Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 161 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
[![CI](https://github.com/jackwener/boss-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jackwener/boss-cli/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://pypi.org/project/kabi-boss-cli/)

A CLI for BOSS 直聘 — search jobs, view recommendations, manage applications, and chat with recruiters via reverse-engineered API 🤝
A CLI for BOSS 直聘 — search jobs, view recommendations, manage applications, chat with recruiters, **and manage candidates as a recruiter** via reverse-engineered API 🤝

[English](#features) | [中文](#功能特性)

Expand All @@ -31,6 +31,7 @@ A CLI for BOSS 直聘 — search jobs, view recommendations, manage applications
- 🤝 **Greet** — send greetings to recruiters, single or batch (with 1.5s rate-limit delay)
- 🏙️ **Cities** — 40+ supported cities
- 🤖 **Agent-friendly** — structured output envelope (`{ok, schema_version, data}`), Rich output on stderr
- 👔 **Recruiter Mode** — view posted jobs, manage candidates, chat history, export candidate data (CSV/JSON)

## Installation

Expand Down Expand Up @@ -67,6 +68,9 @@ uv sync
boss login # Auto-detect browser cookies, fallback to QR
boss login --cookie-source chrome # Extract from specific browser
boss login --qrcode # QR code login only
boss login --cookie-file /path/cred.json # Import cookies from file
boss login --cookie "k=v; k2=v2" # Import cookies from string
boss cookie-server --token xxx # Start local cookie bridge server
boss status # Check login status (validates real search session, shows cookie names)
boss logout # Clear saved cookies

Expand Down Expand Up @@ -113,6 +117,77 @@ boss --version # Show version
boss -v search "Python" # Verbose logging (request timing)
```

## Recruiter Mode (雇主端)

If you are an employer on BOSS直聘, these commands let you manage candidates from the terminal:

```bash
# ─── Search & Discover (搜索 & 发现) ─────────────
boss recruiter search "golang" --city 深圳 --exp 3-5年 # Search candidates
boss recruiter recommend # Recommended candidates
boss recruiter recommend --job <encryptJobId> # Switch to different 岗位
boss recruiter recommend -n 20 # Limit display

# ─── Greet & Communicate (沟通) ──────────────────
boss recruiter greet <encryptGeekId> # Initiate chat with candidate
boss recruiter batch-greet "Python" --city 杭州 -n 10 # Batch greet top 10 matches
boss recruiter inbox # View candidate messages
boss recruiter inbox --job <encryptJobId> -n 20 # Filter by job, limit display
boss recruiter reply <friendId> "感谢您的关注..." # Reply to candidate
boss recruiter chat <friendId> # View chat history

# ─── Chat Actions (沟通页操作) ───────────────────
boss recruiter request-resume <friendId> --yes # 求简历
boss recruiter exchange-phone <friendId> --yes # 换电话
boss recruiter exchange-wechat <friendId> --yes # 换微信
boss recruiter invite-interview <geekId> --job <id> # 约面试
boss recruiter mark-unsuitable <geekId> --job <id> # 不合适

# ─── Resume (简历) ───────────────────────────────
boss recruiter resume <encryptGeekId> # View full resume in terminal
boss recruiter resume-download <id> --job <jobId> # Download resume as Markdown
boss recruiter geek <encryptGeekId> --job-id 526908510 # Quick candidate info

# ─── Job Management (职位管理) ───────────────────
boss recruiter jobs # List your posted jobs
boss recruiter job-close <encryptJobId> --yes # Take job offline
boss recruiter job-reopen <encryptJobId> --yes # Bring job back online

# ─── Export & Tags ───────────────────────────────
boss recruiter labels # View candidate tags
boss recruiter export -o candidates.csv # Export to CSV
boss recruiter export --format json -o out.json # Export to JSON
```

### Recruiter Workflow Example

```bash
# 1. Check your posted jobs
boss recruiter jobs

# 2. Browse recommended candidates for a specific job
boss recruiter recommend --job f806096ea327cd610nZ80t21FVNQ

# 3. Search for specific skills
boss recruiter search "golang" --city 深圳

# 4. View a candidate's full resume
boss recruiter resume <encryptGeekId> --job <encryptJobId>

# 5. Download resume for offline review
boss recruiter resume-download <encryptGeekId> --job <encryptJobId>

# 6. Start a conversation
boss recruiter greet <encryptGeekId>

# 7. Check inbox and reply
boss recruiter inbox -n 20
boss recruiter reply <friendId> "感谢您的关注,方便电话聊聊吗?"

# 8. Export all candidates
boss recruiter export --format json -o candidates.json
```

## Structured Output

All commands with `--json` / `--yaml` use a unified output envelope (see [SCHEMA.md](./SCHEMA.md)):
Expand All @@ -136,13 +211,39 @@ boss-cli supports multiple authentication methods:
1. **Saved cookies** — loads from `~/.config/boss-cli/credential.json`
2. **Browser cookies** — auto-detects installed browsers (Chrome, Firefox, Edge, Brave, Arc, Chromium, Opera, Vivaldi, Safari, LibreWolf)
3. **QR code login** — terminal QR output using Unicode half-blocks, scan with Boss 直聘 APP
4. **Cookie import** — `boss login --cookie-file` or `BOSS_COOKIES` env for headless servers

`boss login` auto-extracts browser cookies first, falls back to QR login. Use `--cookie-source chrome` to specify a browser, or `--qrcode` to skip browser detection. The command now verifies the saved credential against a real authenticated API before reporting success.

`boss recommend` follows the live web app's current recommendation data source and request context, which improves compatibility when the legacy recommendation endpoint is rejected.

`boss status --json` now reports per-flow health such as `search_authenticated` and `recommend_authenticated`, which helps diagnose partial-session issues. To avoid turning repeated checks into their own anti-bot problem, health snapshots are cached briefly in-memory.

### Headless / Server Login (无可视化页面)

If your server has no GUI, use one of these:

1. **Cookie file import**
- Export cookies from a browser machine and copy to the server
- `boss login --cookie-file /path/credential.json`

2. **Environment variable**
- `export BOSS_COOKIES="k=v; k2=v2"`
- `boss status --json`

### Chrome Extension (Real-time Cookie Extraction)

Some cookies (notably `__zp_stoken__`) are generated by browser JS and may not be written to disk immediately.
The included Chrome extension can extract cookies from browser memory and push them to a local bridge.

1. Start the local bridge:
- `boss cookie-server --token <your-token>`
2. Load the extension:
- Open `chrome://extensions/`
- Enable Developer mode
- Load unpacked: `chrome-extension/zhipin-cookie-extractor`
3. Log in to `https://www.zhipin.com`, click the extension, set the token, then **Sync**.

### Cookie TTL & Auto-Refresh

Saved cookies auto-refresh from browser after **7 days**. If browser refresh fails, falls back to stale cookies and logs a warning.
Expand Down Expand Up @@ -201,7 +302,8 @@ boss_cli/
├── auth.py # login (--cookie-source/--qrcode), logout, status, me
├── search.py # search, recommend, detail, show, export, history, cities
├── personal.py # applied, interviews
└── social.py # chat, greet (--json), batch-greet (1.5s delay)
├── social.py # chat, greet (--json), batch-greet (1.5s delay)
└── recruiter.py # recruiter-jobs, inbox, geek, chat, labels, export
```

## Development
Expand Down Expand Up @@ -242,7 +344,7 @@ Check your city filter. Some keywords are city-specific. Use `boss cities` to se

## 功能特性

- 🔐 **认证** — 自动提取浏览器 Cookie(10+ 浏览器),二维码扫码登录,`--cookie-source` 指定浏览器
- 🔐 **认证** — 自动提取浏览器 Cookie(10+ 浏览器),二维码扫码登录,支持 `--cookie-source` / `--cookie-file` / `--cookie`
- 🔍 **搜索** — 按关键词搜索职位,支持城市/薪资/经验/学历/行业/规模/融资阶段/职位类型筛选
- ⭐ **推荐** — 基于求职期望的个性化推荐
- 📋 **详情 & 导出** — 职位详情,编号导航 (`boss show 3`),CSV/JSON 导出
Expand All @@ -254,6 +356,7 @@ Check your city filter. Some keywords are city-specific. Use `boss cities` to se
- 🤝 **打招呼** — 向 Boss 打招呼/投递,支持批量操作(内置 1.5s 防风控延迟)
- 🏙️ **城市** — 40+ 城市支持
- 🤖 **Agent 友好** — 结构化输出 envelope,Rich 输出走 stderr
- 👔 **招聘方模式** — 查看职位、候选人管理、聊天记录、导出候选人数据 (CSV/JSON)

## 使用示例

Expand All @@ -263,6 +366,9 @@ boss login # 自动提取浏览器 Cookie,失败
boss login --cookie-source chrome # 指定浏览器
boss status # 检查登录状态
boss logout # 清除 Cookie
boss login --cookie-file /path/cred.json # 从文件导入 Cookie
boss login --cookie "k=v; k2=v2" # 从字符串导入 Cookie
boss cookie-server --token xxx # 启动本地 Cookie Bridge

# 搜索 & 详情
boss search "golang" --city 杭州 # 按城市搜索
Expand Down Expand Up @@ -292,11 +398,63 @@ boss cities # 城市列表
boss -v search "Python" # 详细日志
```

## 招聘方模式

```bash
# 搜索 & 推荐
boss recruiter search "golang" --city 深圳 --exp 3-5年
boss recruiter recommend --job <encryptJobId> # 按岗位查看推荐牛人
boss recruiter recommend -n 20 # 限制显示

# 沟通
boss recruiter greet <encryptGeekId> # 向候选人打招呼
boss recruiter batch-greet "Python" -n 10 # 批量打招呼
boss recruiter inbox -n 20 # 查看候选人消息
boss recruiter reply <friendId> "您好..." # 回复候选人

# 沟通页操作
boss recruiter request-resume <friendId> # 求简历
boss recruiter exchange-phone <friendId> # 换电话
boss recruiter exchange-wechat <friendId> # 换微信
boss recruiter invite-interview <id> --job <id> # 约面试
boss recruiter mark-unsuitable <id> --job <id> # 不合适

# 简历
boss recruiter resume <encryptGeekId> # 终端查看简历
boss recruiter resume-download <id> --job <id> # 下载简历为 Markdown

# 职位管理
boss recruiter jobs # 查看招聘职位
boss recruiter job-close <encryptJobId> # 关闭职位
boss recruiter job-reopen <encryptJobId> # 重新开启

# 导出
boss recruiter labels # 查看标签
boss recruiter export -o candidates.csv # 导出候选人
```

## 常见问题

- `环境异常` — Cookie 过期,执行 `boss logout && boss login` 刷新
- 搜索无结果 — 检查城市筛选或关键词,使用 `boss cities` 查看支持的城市

## 无可视化页面 / 服务器登录

如果服务器没有浏览器界面,推荐以下方案:

1. **导入 Cookie 文件**
- 在有浏览器的机器上登录后导出 `credential.json`
- 复制到服务器后执行 `boss login --cookie-file /path/credential.json`

2. **环境变量**
- `export BOSS_COOKIES="k=v; k2=v2"`
- `boss status --json`

3. **Chrome 扩展实时同步**
- `boss cookie-server --token <your-token>`
- 在 Chrome 中加载 `chrome-extension/zhipin-cookie-extractor`
- 在扩展里填写相同的 `token` 并点击 Sync

## License

Apache-2.0
Loading