can4hou6joeng4/boss-agent-cli · 上手攻略

是什么

boss-agent-cli 是一个面向 BOSS 直聘（以及智联、前程无忧占位）的本地命令行求职工具 + AI Agent 集成层。README 自述："Local-assist BOSS Zhipin CLI for AI agents — search, welfare filtering, shortlist, JSON-envelope output; low-risk & compliant by default"。

它把"职位搜索 / 福利筛选 / 本地简历与 AI 优化 / 投递沟通 / 招聘者候选人管理 / 可恢复采集"全部包进同一套 CLI + MCP 协议，对真人和AI Agent 同时友好：

  • 真人：直接 boss 进入纯终端向导（角色 / 平台 / 目标选择）；
  • Agent：通过 JSON 信封（{ok, data, pagination, error, hints}）、MCP（73 个工具）、subprocess、Python SDK 调用同一套 workflow。

底层用 [patchright](https://github.com/steel-dev/patchright 的 fork 或自实现 / Playwright 的 patchright 分支——⚠️ README 未明示精确源，需要 pip show boss-agent-cli 验证）做浏览器自动化 + CDP 控制，默认在用户主动登录后把登录态封存到本地，AI 不接管 Cookie。这一"低风险默认"是它的核心差异化卖点。

解决什么问题

求职工具领域的几个痛点：

  1. BOSS 直聘风控严：直接爬接口 / Selenium 自动化很容易被识别封号；想做职位聚合 + AI 匹配，必须解决浏览器指纹 + Cookie + 操作节奏三件事；
  2. AI Agent 难以接入招聘网站：LLM 没法直接抓 BOSS 数据，需要一个"既能执行又带结构化 schema 输出"的桥；
  3. 批量求职 vs 个人定制矛盾：批量容易撞风控，纯手动又没法用 AI 优化简历 / 写问候语；
  4. 招聘者侧需求被忽视：候选人搜索、回复、简历请求是另一条 workflow，需要单独设计。

boss-agent-cli 的解法是"双模式（assisted / research）+ 双角色（求职者 / 招聘者）+ 双注册表（Platform / RecruiterPlatform）+ 结构化 JSON 信封"——一套 CLI 同时支撑人和 Agent，求职者侧和招聘者侧走两条独立 workflow。

快速安装

README 主推 uv（Astral 出品的 Python 包 / 工具管理器），同时也支持 pip / Docker。

# 方式一：uv tool（推荐，免虚拟环境管理）
uv tool install boss-agent-cli
patchright install chromium    # 装 Chromium 内核（仅"用户主动登录 / 本地导出"场景才需要）

# 方式二：Docker
BOSS_UID=$(id -u) BOSS_GID=$(id -g) docker compose run --rm boss-mcp
# 镜像故意不带浏览器内核 —— 先在宿主机跑 boss login，再挂 ~/.boss-agent

# 方式三：源码 / OpenCode 项目内
cp examples/opencode/opencode.json ./opencode.json
uv sync --all-extras
uv run boss-mcp --data-dir ./.boss-agent --help

环境要求（⚠️ 未独立核验具体版本号）：Python 3.10+（推测，因依赖 patchright / Click / asyncio）；uv ≥ 0.4（推荐路径）；浏览器内核仅在需要主动登录 / 本地导出时必需。

核心用法

1) 真人向导入口

boss                     # 纯终端向导：选角色 / 平台 / 目标
boss wizard               # 同上显式调用
boss doctor               # 环境自检
boss login                # 登录（按平台选链路）
boss status               # 验证登录态

2) 求职者侧：搜索 + 福利筛选（README 标"核心差异化"）

boss search "Golang" --city 广州 --welfare "双休,五险一金"
# --welfare 按 AND 逻辑真实匹配，支持自动翻页补抓
# 加 --sort score 按本地匹配分排序

3) 详情 / 本地候选池

boss detail <security_id>                              # 查看详情
boss shortlist add <security_id> <job_id> --tags 后端,远程  # 加入本地候选池 + 标签
boss shortlist compare --tag 远程                      # 离线对比候选岗位
boss stats                                             # 本地统计

4) AI 求职增强 + 本地模型

boss ai analyze-jd        # JD 分析
boss ai polish            # 简历润色
boss ai optimize          # 定向优化
boss ai fit               # 候选池匹配
boss ai interview-prep    # 模拟面试
boss ai chat-coach        # 沟通指导
boss ai local configure   # 本地模型权重外置（支持 Ollama / vLLM OpenAI 兼容接口）
boss ai local smoke       # 本地模型连通性自测

5) 招聘者侧

boss hr candidates "Python" --city 101010100   # 候选人搜索
boss hr jobs list                                # 职位列表
boss hr applications                             # 投递管理
boss hr resume                                   # 简历请求
boss hr chat / boss hr reply / boss hr last-messages   # 沟通链路
boss hr request-resume                           # 请求附件简历
boss hr jobs                                     # 职位上下架

6) AI Agent 集成：三种方式

方式一 — MCP（推荐，Claude Desktop / Cursor 等宿主）：

{
  "mcpServers": {
    "boss-agent": {
      "command": "uvx",
      "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"]
    }
  }
}

73 个 MCP 工具对外暴露。

方式二 — Subprocess：

boss schema    # 先让 Agent 读能力自描述（支持 --format openai-tools / anthropic-tools）
# 然后解析 stdout 的 JSON 信封：{ok, data, pagination, error, hints}

方式三 — Python SDK（py.typed 标注，可作类型化库）：

from boss_agent_cli import AuthManager, BossClient, AuthRequired

with BossClient(AuthManager(...)) as client:
    result = client.search_jobs("Golang", city="广州")

7) 可恢复批量采集（额外依赖）

uv sync --extra crawl    # 安装采集扩展
boss crawl configure --max-requests 20 --max-details 50 --max-seconds 600 --max-retries 1
boss crawl run "AI" --city 杭州 --pages 3 --with-detail \
  --hook-profile screenshot-full --hook-dir E:\boss-agent-cli-local-hooks\AntiDebug_Breaker
boss crawl resume <run_id>      # 从 SQLite 断点续跑
boss crawl stop <run_id>        # 在安全点停止

预算约束：max-requests / max-details / max-seconds / max-retries 四元组硬限。导出和 crawl results 默认不暴露 security_id、职位 ID、招聘者字段；boss clean --privacy 会删除 crawl 状态 + 预算 + 导出。

8) 多平台抽象

boss --platform zhipin search "Python"     # BOSS 直聘（默认）
boss --platform zhilian search "Python"    # 智联（求职者侧只读 + 本地辅助）
# 前程无忧（51job）：已注册占位，统一返回 NOT_SUPPORTED

招聘者侧：boss hr ... 当前仅限默认平台 zhipin-recruiter；智联招聘者侧自动化走 boss --platform zhilian --role recruiter agent ...（agent browser/CDP adapter）。

典型适用场景

  • 求职者：批量搜索 BOSS / 智联职位、按福利（双休 / 五险一金）AND 过滤、AI 优化简历与 JD 匹配、模拟面试；
  • 猎头 / 招聘者：候选人搜索 + 投递管理 + 简历请求 + 沟通链路一站式；
  • AI Agent 开发者：把 BOSS 数据接入 Claude / Cursor / 自建 Agent（73 个 MCP 工具即插即用）；
  • 合规研究 / 数据科学：受限的可恢复采集（SQLite 断点 + 预算硬限 + 默认脱敏），比裸 Selenium / requests 友好；
  • OpenCode 项目内嵌：提供 examples/opencode/opencode.json 模板，让 review / pending / 日志按项目隔离。

坑与注意

  • ⚠️ 平台风险硬约束：boss-agent-cli 官方文档强调"命中平台风控时两种模式都停止当前 workflow 并保存 checkpoint，风险解除后才能显式恢复"。这是与平台对抗的硬代价，不是 BUG，是 feature。
  • ⚠️ 招聘者侧只支持 zhipin-recruiter：智联招聘者侧走 agent 命令 + browser/CDP adapter，不是 boss hr ... 子命令。前程无忧（51job）尚未接入。
  • ⚠️ 批量采集有 hook 风险：本地 hook 必须同时显式提供 hook 档位 + 含 SHA256SUMS 的目录，否则不会注入；这是反调试保护设计，但上手门槛高。
  • ⚠️ 错误信封需程序化处理：code + recoverable + recovery_action 是契约，Agent 必须按 recovery_action 推进；忽略 recovery_action 直接 retry 会撞风控。
  • ⚠️ 隐私脱敏默认强：默认导出 / crawl results 不含 security_id、职位 ID、招聘者字段；要拿到原始 ID 必须主动配置，且务必理解合规边界。
  • ⚠️ CLI 模式历史遗留：operating_mode=assisted|research 兼容保留，但 README 写"两种模式都可调用全部已实现能力，不再产生模式级 COMPLIANCE_BLOCKED"——意味着旧文档假设需要重读，新行为放宽。
  • ⚠️ 依赖生态版本：patchright 安装步骤、uv 版本下限、Python 版本下限README 未明确标注，⚠️ 本攻略未独立 pip install 验证。建议 boss doctor 做环境自检。
  • ⚠️ 法律 / 合规：批量账号、自动化投递在 BOSS 直聘 ToS 层面灰色；本攻略不就合规给建议。

与同类对比

工具 / 路径 定位 关键差异（vs boss-agent-cli）
商业 SaaS（如 Moka / Bello 等 ATS） 招聘者侧 商业、订阅制、GUI；boss-agent-cli 本地 + CLI
直接 Selenium / Playwright 写脚本 通用自动化 无 JSON 信封 / 无 schema 真源 / 无风控 stop；boss-agent-cli 是"封装好 + 合规默认"
GitHub 上的 BOSS 爬虫项目 单点抓取 通常缺 MCP / SDK 双栈；boss-agent-cli 三种接入方式
Zhipin AI / BOSS 官方 AI 平台内 闭源 / 锁定；boss-agent-cli 本地可审计
AgentReach / 类似 Agent 工具站 Agent 接入 单点工具，boss-agent-cli 是求职垂直 workflow

核心权衡：boss-agent-cli 适合"需要把 BOSS 数据接入 AI Agent + 本地可控 + 合规默认脱敏"的用户；不需要 AI 集成的纯 GUI 用户可以直接用 BOSS 直聘 App。

一句话推荐

它是"想用 Claude / Cursor 等 AI Agent 求职的人"的本地合规桥——73 个 MCP 工具 + Python SDK + JSON 信封三种接入，加上福利 AND 筛选和招聘者双侧 workflow，是目前公开仓库里把 BOSS 直聘 Agent 化做得最完整的项目；用之前请先读 docs/platform-risk.md 和 docs/troubleshooting.md，别裸跑 boss crawl。