boss-agent-cli

AI Agent 专用的 BOSS 直聘双端 CLI 工具 — 33 个顶层命令 + 7 个招聘者子命令，覆盖职位搜索、福利筛选、沟通、流水线、招聘者工作流、MCP 工具与 AI 简历优化。

Install

Skills CLI (Recommended)

npx skills add can4hou6joeng4/boss-agent-cli

pip / uv tool

uv tool install boss-agent-cli
patchright install chromium

Setup

boss login     # 四级降级：Cookie 提取 → CDP → QR httpx → patchright 扫码
boss status    # 验证登录态

Agent Decision Tree

用户意图 → 选择命令链
│
├─ "帮我找工作"
│   → boss status → boss search "关键词" --city X --welfare "Y"
│   → boss detail <sid> → boss greet <sid> <jid>
│
├─ "有什么新职位？"
│   → boss watch run <name>  (已有监控)
│   → boss recommend         (个性化推荐)
│
├─ "我的求职进展怎样？"
│   → boss pipeline → boss follow-up → boss digest
│
├─ "帮我优化简历"
│   → boss ai analyze-jd → boss ai polish → boss ai optimize
│
├─ "查看沟通记录"
│   → boss chat → boss chatmsg <sid> → boss chat-summary <sid>
│
├─ "登录/环境有问题"
│   → boss doctor → boss login
│
└─ "不知道能做什么"
    → boss schema  (返回全部能力 JSON)

Commands

当前 boss schema 暴露：

• 33 个顶层命令
• hr 下 7 个一级招聘者子命令

Recruiter Workflow

| Command | Description | |---------|-------------| | boss hr applications | 查看候选人投递申请 | | boss hr candidates <keyword> | 搜索候选人 | | boss hr chat | 招聘者沟通列表 | | boss hr resume | 查看/请求候选人简历 | | boss hr reply <friend_id> <message> | 回复候选人消息 | | boss hr request-resume <friend_id> --job-id <id> | 请求候选人附件简历 | | boss hr jobs list/online/offline | 职位列表与上下线管理 |

Discovery & Auth

| Command | Description | |---------|-------------| | boss schema | 返回全部命令的 JSON 自描述（Agent 首先调用） | | boss login | 四级降级登录（Cookie → CDP → QR httpx → patchright） | | boss logout | 退出登录 | | boss status | 检查登录态 | | boss doctor | 诊断环境、依赖、凭据完整性和网络 | | boss me | 个人信息/简历/求职期望/投递记录 |

Job Search

| Command | Description | |---------|-------------| | boss search <query> | 搜索职位（8 维筛选：城市/薪资/经验/学历/规模/行业/融资/福利） | | boss recommend | 个性化推荐 | | boss detail <security_id> | 职位详情（--job-id 走快速通道） | | boss show <#> | 按编号查看上次搜索结果 | | boss cities | 40 个支持城市 |

Job Actions

| Command | Description | |---------|-------------| | boss greet <sid> <jid> | 打招呼 | | boss batch-greet <query> | 批量打招呼（上限 10） | | boss apply <sid> <jid> | 投递/立即沟通（幂等） | | boss exchange <sid> | 交换手机/微信 |

Communication

| Command | Description | |---------|-------------| | boss chat | 沟通列表（导出 html/md/csv/json） | | boss chatmsg <sid> | 聊天消息历史 | | boss chat-summary <sid> | 结构化沟通摘要（阶段/待办/风险） | | boss mark <sid> --label X | 标签管理（9 种） | | boss interviews | 面试邀请 | | boss history | 浏览历史 |

Pipeline & Monitoring

| Command | Description | |---------|-------------| | boss pipeline | 求职流水线（各阶段状态） | | boss follow-up | 跟进提醒（超时未推进） | | boss digest | 每日摘要 | | boss watch add/list/remove/run | 增量监控 | | boss shortlist add/list/remove | 候选池 | | boss preset add/list/remove | 搜索预设 |

Resume & AI

| Command | Description | |---------|-------------| | boss resume init/list/show/edit/delete/export/import/clone/diff | 本地简历管理 | | boss ai config | 配置 AI 服务（OpenAI / Anthropic / 兼容 API） | | boss ai analyze-jd | 分析岗位要求 | | boss ai polish | 润色简历 | | boss ai optimize | 针对岗位优化简历 | | boss ai suggest | 求职建议 | | boss ai reply | 招聘者消息回复草稿 | | boss ai interview-prep | 基于 JD 生成模拟面试题 | | boss ai chat-coach | 基于聊天记录给沟通建议 |

System

| Command | Description | |---------|-------------| | boss config list/set/reset | 配置管理 | | boss clean | 清理缓存 | | boss export <query> | 导出搜索结果（CSV/JSON） |

Agent Usage

Step 1: Discover capabilities

boss schema

Returns a JSON envelope describing all 33 top-level commands, the hr recruiter command group, parameters, error codes, and output conventions.

Step 2: Check auth, then act

boss status                                        # Check auth
boss search "golang" --city 杭州 --welfare "双休"    # Search with welfare filter
boss detail <security_id> --job-id <id>            # View details (fast path)
boss greet <security_id> <job_id>                  # Send greeting
boss pipeline                                      # Track progress
boss digest                                        # Daily summary
boss hr applications                               # Recruiter inbox
boss hr candidates "golang"                        # Search candidates
boss hr reply <friend_id> "你好"                   # Recruiter reply

Step 3: Parse output

All commands output structured JSON to stdout:

{
  "ok": true,
  "schema_version": "1.0",
  "command": "search",
  "data": [...],
  "pagination": {"page": 1, "has_more": true},
  "error": null,
  "hints": {"next_actions": ["boss detail <sid>"]}
}

• ok: true → exit code 0, data contains results
• ok: false → exit code 1, error.code + error.recovery_action for auto-recovery
• hints.next_actions → suggested next commands for the Agent to follow

Error Recovery

| Error Code | Recoverable | Action | |-----------|-------------|--------| | AUTH_REQUIRED | Yes | boss login | | AUTH_EXPIRED | Yes | boss login | | TOKEN_REFRESH_FAILED | Yes | boss login | | RATE_LIMITED | Yes | Wait and retry | | ACCOUNT_RISK | Yes | Retry with CDP Chrome | | NETWORK_ERROR | Yes | Retry | | AI_NOT_CONFIGURED | Yes | boss ai config | | AI_API_ERROR | Yes | Retry | | AI_PARSE_ERROR | Yes | Retry | | EXPORT_FAILED | Yes | Check dependencies | | JOB_NOT_FOUND | No | — | | ALREADY_GREETED | No | Skip | | ALREADY_APPLIED | No | Skip | | GREET_LIMIT | No | Inform user | | INVALID_PARAM | No | Fix parameters | | RESUME_NOT_FOUND | No | Check name | | RESUME_ALREADY_EXISTS | No | Use different name |

Output Conventions

• stdout: JSON only (structured envelope)
• stderr: Logs and progress (controlled by --log-level)
• exit 0: Success (ok: true)
• exit 1: Failure (ok: false)

Welfare Filter (Core Feature)

--welfare "双休,五险一金" triggers deep inspection:

1. Check job's welfare tags first
2. If tags don't match, fetch full job description and search
3. Auto-paginate (up to 5 pages)
4. Each result includes welfare_match field explaining the match source

Keywords: 双休 五险一金 年终奖 餐补 住房补贴 定期体检 股票期权 加班补助 带薪年假

Requirements

• Python >= 3.10
• patchright + Chromium (for login; QR httpx mode works without browser)
• macOS / Linux / Windows

Docs

• Agent Quickstart
• Agent Host Examples
• Capability Matrix

License

MIT

boss-agent-cli

专为 AI Agent 设计的 BOSS 直聘双端 CLI 工具

求职者：搜索 · 福利筛选 · 个性化推荐 · 自动打招呼 · 求职流水线 · 增量监控 · AI 简历优化

招聘者：候选人检索 · 沟通回复 · 简历请求 · 职位上下线 · 多平台抽象

安装 · 快速开始 · 角色模式 · Agent 集成 · 命令参考 · 排障 · 架构 · 更新日志 · 路线图

中文 | English

A CLI tool designed for AI Agents to interact with BOSS Zhipin (China's largest recruitment platform). Structured JSON output, schema-driven capability discovery, 4-tier login fallback, recruiter workflow support, and a cross-platform adapter layer. See README.en.md for the English version.

💡 为什么用 boss-agent-cli？

传统求职：打开网页 → 翻几十页 → 逐个看详情 → 手动打招呼 → 忘了跟进谁。

boss-agent-cli 让 AI Agent 替你完成全部操作：

boss search "Golang" --city 广州 --welfare "双休,五险一金"   # 搜索 + 福利筛选
boss detail <security_id>                                    # 查看详情
boss greet <security_id> <job_id>                            # 一键打招呼
boss pipeline                                                # 流水线追踪
boss digest                                                  # 每日汇报

所有输出为 结构化 JSON，Agent 一调用就能理解，一调用就能行动。

🧭 导航目录

• 为什么用 boss-agent-cli
• 核心能力
• 安装
• 快速开始
• 登录链路
• 角色模式与多平台
• AI Agent 集成
• 命令参考
• 诊断与排障
• 配置
• 技术架构
• 贡献

🌟 核心能力

求职者工作流

• 🔍 职位发现：关键词搜索、8 维筛选、个性化推荐、按编号回看同一条结果。命令：search recommend show
• 🎯 福利筛选：--welfare "双休,五险一金" 会自动翻页、补抓详情、按 AND 逻辑做真实匹配。命令：search --welfare
• 👋 主动出击：从职位详情直接打招呼、批量打招呼、立即沟通投递。命令：detail greet batch-greet apply
• 📊 流程推进：流水线、跟进提醒、每日摘要、投递转化漏斗一条线闭环。命令：pipeline follow-up digest stats
• 👀 增量监控：保存搜索条件、定期执行、标出新职位、沉淀 shortlist。命令：watch preset shortlist
• 💬 沟通管理：聊天列表、消息历史、结构化摘要、标签和联系方式交换。命令：chat chatmsg chat-summary mark exchange
• 🤖 AI 求职增强：JD 分析、简历润色、定向优化、模拟面试、沟通指导。命令：ai analyze-jd ai polish ai optimize ai interview-prep ai chat-coach

招聘者工作流

• 👔 候选人运营：投递申请、候选人搜索、沟通列表、在线简历查看与附件简历请求。命令：hr applications hr candidates hr chat hr resume hr request-resume
• 💬 招聘沟通：直接回复候选人消息，把 HR 场景纳入同一套 JSON 协议。命令：hr reply
• 📌 职位管理：查看职位、上架、下架，作为招聘者端的最小可操作闭环。命令：hr jobs list hr jobs online hr jobs offline

平台与集成基础

• 🔌 多平台抽象：Platform / RecruiterPlatform 双注册表已落地；BOSS 直聘求职者/招聘者均可用，智联招聘已接通求职者侧包络与命令兼容。命令：--platform zhipin|zhilian
• 📤 结构化输出：stdout 只输出 JSON 信封，适合 CLI 编排、Shell Agent、MCP 和 Python SDK。命令：schema export
• 🧩 Agent 接入：同一套能力可通过 Skill、subprocess、MCP、Python SDK 四种路径暴露给 Agent。文档：docs/agent-quickstart.md docs/agent-hosts.md

📦 安装

# 推荐：通过 uv 安装（秒级，自动隔离）
uv tool install boss-agent-cli

# 安装浏览器（用于登录）
patchright install chromium

# pipx（隔离环境）
pipx install boss-agent-cli
patchright install chromium

# pip
pip install boss-agent-cli
patchright install chromium

# 从源码（开发用）
git clone https://github.com/can4hou6joeng4/boss-agent-cli.git
cd boss-agent-cli
uv sync --all-extras
uv run patchright install chromium

🚀 快速开始

# 1. 环境自检
boss doctor

# 2. 登录（按平台选择链路）
boss login

# 3. 验证登录态
boss status

# 4. 搜索广州的 Golang 职位，要求双休+五险一金
boss search "Golang" --city 广州 --welfare "双休,五险一金"

# 5. 查看详情 → 打招呼 → 投递
boss detail <security_id>
boss greet <security_id> <job_id>
boss apply <security_id> <job_id>

# 6. 推荐 + 导出
boss recommend
boss export "Golang" --city 广州 --count 50 -o jobs.csv

# 7. 流水线 + 每日摘要
boss pipeline
boss digest

# 8. 增量监控
boss watch add my-golang "Golang" --city 广州 --welfare "双休"
boss watch run my-golang

# 9. 招聘者模式（HR 视角）
boss hr applications                  # 候选人投递申请
boss hr candidates "Golang"           # 搜索候选人
boss hr reply <friend_id> "你好"      # 回复消息
boss hr jobs list                     # 我发布的职位

🔐 登录链路

boss login 会按当前平台选择登录链路：

| 平台 | 登录链路 | 说明 | |------|----------|------| | zhipin | Cookie 提取 → CDP → QR httpx → patchright | 保留现有四级降级链路 | | zhilian | Cookie 提取 → CDP → 浏览器登录 | 当前优先复用本地浏览器登录态；无 QR httpx 分支 |

补充说明：

• boss login 默认按当前 --platform / 配置文件里的 platform 工作
• boss --platform zhilian login 已可用，但目前只覆盖求职者侧认证链路
• boss --platform zhilian hr ... 仍不支持，招聘者侧继续追踪 Issue #140

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/boss-chrome

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/boss-chrome

# 使用 CDP 登录
boss --cdp-url http://localhost:9222 login --cdp

🎭 角色模式与多平台

boss-agent-cli 同时覆盖求职者和招聘者两端，并为后续接入更多招聘平台做了抽象。

角色切换

| 选项 | 说明 | 典型命令 | |------|------|----------| | --role candidate（默认） | 求职者视角 | search / greet / apply | | --role recruiter | 招聘者视角 | hr applications / hr candidates |

快捷入口：boss hr <子命令> 会自动把当前会话切换到招聘者角色，不必显式传 --role。

# 方式 A: --role 显式指定
boss --role recruiter ...

# 方式 B: 招聘者快捷组（自动切换 role）
boss hr applications
boss hr candidates "Golang"

注意：

• boss hr ... 当前仅支持默认招聘者平台 zhipin-recruiter
• 若当前平台是 zhilian，CLI 会在入口直接提示切回 boss --platform zhipin hr ...

多平台抽象

Platform / RecruiterPlatform 双注册表让命令层不耦合具体平台协议：

| 平台 | 求职者 | 招聘者 | 状态 | |------|:------:|:------:|------| | BOSS 直聘 (zhipin) | ✅ | ✅ | 默认 | | 智联招聘 (zhilian) | 🟡 包络与命令兼容已接通 | — | 招聘者侧未接入，继续追踪 Issue #140 |

# 指定平台
boss --platform zhilian search "Python"

# 设为默认
boss config set platform zhilian

设计细节见 docs/platform-abstraction.md。

🤖 AI Agent 集成

推荐先阅读：Agent Quickstart · Host Examples · Capability Matrix

方式一：Skill 安装（推荐）

npx skills add can4hou6joeng4/boss-agent-cli

安装后 Agent 自动获得调用 boss 命令的能力，无需手动配置。

方式二：手动配置

在 AI Agent 的规则文件中添加：

当用户要求搜索职位、投递、打招呼等 BOSS 直聘操作时，通过 Bash 调用 `boss` CLI：
1. 运行 `boss status` 检查登录态
2. 若未登录，运行 `boss login` 提示用户扫码
3. 根据用户意图调用 search / recommend / detail / greet
4. 解析 stdout JSON，`ok` 字段判断成败
5. 用户提到福利要求时使用 `--welfare` 参数

方式三：Python 直接嵌入（不走 subprocess）

包已随 py.typed 标记发布，可直接作为类型化的 Python 库使用：

from boss_agent_cli import AuthManager, BossClient, AuthRequired

auth = AuthManager(data_dir=Path("~/.boss-agent").expanduser())
try:
    with BossClient(auth) as client:
        result = client.search_jobs("Golang", city="广州")
except AuthRequired:
    ...  # 提示用户 boss login

公开 API（详见 boss_agent_cli.__all__）：AuthManager / BossClient / CacheStore / JobItem / JobDetail / AIService / ResumeData 等核心类型。

输出协议

所有命令输出 JSON 到 stdout，统一信封格式：

{
  "ok": true,
  "schema_version": "1.0",
  "command": "search",
  "data": [...],
  "pagination": {"page": 1, "has_more": true, "total": 15},
  "error": null,
  "hints": {"next_actions": ["boss detail <security_id>"]}
}

| 约定 | 说明 | |------|------| | stdout | 仅 JSON 结构化数据 | | stderr | 日志和进度信息 | | exit 0 | 命令成功 (ok=true) | | exit 1 | 命令失败 (ok=false) |

📚 命令参考

基础操作

| 命令 | 说明 | |------|------| | boss schema | 输出完整工具能力描述 JSON（33 个顶层命令 + hr 分组展开，Agent 首先调用） | | boss login | 四级降级登录 | | boss logout | 退出登录 | | boss status | 检查登录态 | | boss doctor | 诊断环境、依赖、凭据完整性和网络 | | boss me | 我的信息（用户/简历/期望/投递记录） |

职位搜索

| 命令 | 说明 | |------|------| | boss search <query> | 搜索职位（支持 --welfare 筛选、--preset 预设） | | boss recommend | 个性化推荐 | | boss detail <security_id> | 职位详情（--job-id 走快速通道） | | boss show <#> | 按编号查看上次搜索结果 | | boss cities | 40 个支持城市 |

求职动作

| 命令 | 说明 | |------|------| | boss greet <sid> <jid> | 打招呼 | | boss batch-greet <query> | 批量打招呼（上限 10） | | boss apply <sid> <jid> | 投递/立即沟通（幂等） | | boss exchange <sid> | 交换手机/微信 |

沟通跟进

| 命令 | 说明 | |------|------| | boss chat | 沟通列表（导出 html/md/csv/json） | | boss chatmsg <sid> | 聊天消息历史 | | boss chat-summary <sid> | 结构化摘要 | | boss mark <sid> --label X | 标签管理（9 种） | | boss interviews | 面试邀请 | | boss history | 浏览历史 |

流水线监控

| 命令 | 说明 | |------|------| | boss pipeline | 求职流水线（各阶段状态） | | boss follow-up | 跟进提醒（超时未推进） | | boss digest | 每日摘要 | | boss watch add/list/remove/run | 增量监控 | | boss shortlist add/list/remove | 候选池 | | boss preset add/list/remove | 搜索预设 |

招聘者模式

| 命令 | 说明 | |------|------| | boss hr applications | 查看候选人投递申请列表 | | boss hr resume | 查看或请求候选人简历 | | boss hr chat | 查看与候选人的沟通列表 | | boss hr jobs list/offline/online | 职位列表与上下线管理 | | `boss