boss-resume-downloader

Boss 简历下载器

用途

安装并运行确定性的 BOSS/Zhipin 招聘者简历同步工作流。统一 boss-agent-cli 命令路径、CDP 端点、Chrome 启动约定、身份验证数据目录、简历存储根目录和简历下载回退逻辑，使该工作流可在不同机器和不同 Agent 框架（Claude Code、Claude Desktop、Cursor 等）之间复现。

将此技能用于以下两个相关目标：

1. 加快在新机器上的安装和首次成功运行。
2. 让其他会话也能使用相同的 BOSS 简历同步流程，而不必重新查找 CDP 路径、Chrome 可执行文件位置、boss-agent-cli 存储目录或 securityId 回退行为。

标准配置

除非用户明确提出其他要求，否则优先使用以下默认值。带 ~ 的路径为 POSIX 路径（macOS/Linux）；Windows 上的对应路径使用 %USERPROFILE%。

项目	值（POSIX）	值（Windows）
平台	zhipin	zhipin
角色	recruiter	recruiter
CDP URL	http://localhost:9222	http://localhost:9222
boss 命令	boss（位于 PATH 中）	boss（位于 PATH 中）或 %USERPROFILE%\bin\boss.cmd
boss-agent-cli 身份验证数据目录	~/.boss-agent	%USERPROFILE%\.boss-agent
简历输出根目录	~/WorkBuddy/boss-resumes	%USERPROFILE%\WorkBuddy\boss-resumes
同步脚本	scripts/sync_boss_resumes.py（相对于此 SKILL.md）	相同

像这样调用 CLI（假设 boss 位于 PATH 中）：

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 <command>

重要的已知事实：

• 使用平台 zhipin，不要使用 zhipin-recruiter。
• 需要招聘者身份验证时，使用 CDP URL http://localhost:9222。
• 使用身份验证数据目录 ~/.boss-agent（POSIX）/ %USERPROFILE%\.boss-agent（Windows）。不要猜测为 .boss-agent-cli。
• 在 Windows 上，如果无法从子进程解析 boss，则回退到 %USERPROFILE%\bin\boss.cmd。
• 查看简历需要加密的 geek ID、加密的 job ID 和 securityId。
• hr applications 可以列出已申请的候选人，但并非所有输出中都会包含 securityId。
• hr chat 可以显示候选人姓名，但仍可能不包含 securityId。
• 随附的脚本可以使用 boss-agent-cli 内部的 friend_detail(friendIds)，作为通过数字 friendId 解析 securityId 的回退方法。此回退方法要求当前环境能够导入 boss_agent_cli Python 包。
• hr candidates 可作为额外的回退数据来源。
• 不要假设 encryptFriendId 等于 securityId。

推荐用法：每小时增量同步 + 本地分析

强烈建议采用此方式，而不是一次性批量下载。

⚠️ 风险提示——招聘者访问简历属于敏感操作。 招聘者端的简历访问会受到监控，且属于高度敏感操作。已有观察表明，批量筛选简历可能触发账号级风险控制（速率限制、验证码挑战、临时账号限制；参见上游 issue #232）。本技能中的模式和限制可以降低风险，但无法消除风险。此处的所有保护措施——增量调度、随机延迟、每次运行/每个职位的下载上限——都应视为风险降低措施，而非安全保证。招聘者账号仍可能随时受到限制、被要求完成验证或遭到封禁；请监控 ACCOUNT_RISK / RATE_LIMITED 错误，并及时暂停操作。

通过 Agent 定时任务执行每小时增量同步

使用 Agent 框架的定时任务功能（例如 Claude Code /loop、cron 或任何定期任务），每小时运行一次 sync-all：

# Run once per hour, keep Chrome open in the background
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all

在 Claude Code 中，可以这样设置：

/loop 1h python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all

每次运行只会下载尚未收录在 candidate_index.json 中的候选人，因此每小时运行的任务通常只需下载过去一小时新增的几位候选人。

为什么这种方式优于一次性批量同步：

1. 降低（但无法消除）触发风控的风险。 在一次会话中下载几十或几百份简历看起来像是在抓取数据，更容易触发账号风控。将工作分散到多个每小时执行的小任务中，会降低这种可能性，但无法完全消除。脚本还会强制执行每次运行和每个职位的下载上限（--max-downloads-per-run、--max-downloads-per-job），因此即使积累了许多新候选人，单次运行也不会意外形成批量访问模式。

2. 本地分析快速且免费。 简历以 resume.md 的形式保存到磁盘后，所有分析（按关键词筛选、比较候选人、总结、排名）都可完全在本地运行，无需网络往返、没有速率限制，也不会额外调用 BOSS API。

从本地 Markdown 文件分析

同步完成后，所有简历都位于：

~/WorkBuddy/boss-resumes/jobs/<jobId>_<jobName>/resumes/<name>_<id>/resume.md

要分析简历，请直接读取本地文件。同步文件后，以下提示词效果良好：

• “读取 ~/WorkBuddy/boss-resumes 下的所有 resume.md 文件，筛选有 Python 经验的候选人。”
• “比较职位 <job_name> 所有已下载简历中的工作经历部分。”
• “找出在简历中提到 crawler/scrapy/selenium 的候选人。”

与针对每个分析问题实时查询 BOSS 相比，这种方式更快速、可靠。

---

首次设置检查清单

1. 确认 boss CLI 可用

boss --help

如果 boss 不在 PATH 中，请找到已安装的入口程序，并将其添加到 PATH，或通过 --boss-bin 参数传给随附脚本。在 Windows 上，入口程序通常位于 %USERPROFILE%\bin\boss.cmd（这是环境中 boss.exe 的封装程序）。

2. 启动具有稳定 CDP 端点的 Chrome

优先使用已运行且开放 http://localhost:9222 的 Chrome 会话。如果 CDP 不可用导致状态检查失败，请手动启动 Chrome，启用远程调试并使用专用配置文件。常见的可执行文件位置：

• macOS：/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux：PATH 中的 google-chrome 或 chromium
• Windows：C:\Program Files\Google\Chrome\Application\chrome.exe、C:\Program Files (x86)\Google\Chrome\Application\chrome.exe 或 %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe

推荐的启动格式：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.workbuddy/chrome-profiles/boss-cdp"

# Linux
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.workbuddy/chrome-profiles/boss-cdp"

:: Windows
"<chrome.exe>" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.workbuddy\chrome-profiles\boss-cdp"

除非端口 9222 已被占用，否则不要随机更改 CDP 端口或配置文件目录。

3. 确认招聘者账号已登录

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 status

如果尚未登录，请运行 CDP 登录流程，并让用户完成浏览器中的扫码或登录步骤：

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 login --cdp

4. 确认在线职位

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr jobs list

只有在命令返回预期的招聘职位后，才能继续。

默认存储位置

除非用户指定其他目录，否则使用以下默认简历根目录：

• POSIX：~/WorkBuddy/boss-resumes
• Windows：%USERPROFILE%\WorkBuddy\boss-resumes

预期结构：

boss-resumes/
  config.json
  job_index.json
  jobs/
    <jobId>_<safeJobName>/
      job.json
      candidate_index.json
      resumes/
        <safeCandidateName>_<candidateId>/
          resume.json
          resume.md
          raw_response.json

主要工作流

1. 检查登录状态并获取开放职位

先运行状态检查。如果身份验证缺失或已过期，请使用 CDP 登录流程。

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 status
boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr jobs list

将所有当前在线的职位保存到 job_index.json，以稳定职位 ID 和加密职位 ID 为键。

2. 创建各职位对应的目录

为每个在线职位创建一个名为以下名称的目录：

<jobId>_<safeJobName>

将原始职位元数据存储在 job.json 中。

3. 列出已申请的候选人

对于每个职位，在可用时使用加密职位 ID 调用 applications：

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr applications --job-id <encryptJobId>

如果 CLI 输出表明还有更多页面，请进行分页。

4. 解析简历参数

对于每位已申请的候选人，解析：

• encryptGeekId / 加密后的候选人 ID
• 显示名称
• securityId
• 适用的加密职位 ID

优先使用 applications。如果缺少 securityId，则通过内部 boss-agent-cli friend_detail(friendIds) API，使用数字 friendId 解析。此端点会返回候选人姓名、securityId、encryptUid、jobId 和 encryptJobId。仅将 hr candidates 或 hr chat 用作额外的回退来源。不要假设 encryptFriendId 等于 securityId。

如果无法解析 securityId，请在 candidate_index.json 中将该候选人记录为 pending_security_id，并跳过该候选人的简历下载。不要将其标记为永久失败。

5. 下载在线简历

所有参数齐备时，调用：

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr resume <encryptGeekId> --job-id <encryptJobId> --security-id <securityId>

保存：

• 原始 JSON 响应为 raw_response.json
• 规范化后的 JSON 为 resume.json
• 易读的 Markdown 简历为 resume.md

6. 增量行为

下载前，检查 candidate_index.json。

满足以下条件时跳过候选人：

• 候选人 ID 已存在于索引中，
• 简历状态为 downloaded，并且
• 未请求 --force 选项。

满足以下条件时更新候选人：

• 候选人是新增的，
• 先前状态为 pending_security_id、failed 或 partial，
• 设置了 --force。

7. 随机延迟

批量下载期间，在成功或尝试下载候选人之间应用随机延迟：

3-6 seconds

试运行或仅列出操作时不要延迟。

捆绑脚本

脚本位于此 SKILL.md 旁边的 scripts/sync_boss_resumes.py。将 ${SKILL_DIR} 解析为包含此 SKILL.md 的目录，然后调用：

# Sync all online jobs incrementally
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all

# Sync all online jobs with command echoing; --verbose is a global option and must be placed before the subcommand
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" --verbose sync-all

# Sync one job by numeric jobId or encrypted jobId
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-job --job-id <jobId>

# Refresh job index only
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" refresh-jobs

# Dry run without downloading resumes
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all --dry-run

# Override per-run / per-job download caps (defaults: 20 per run, 10 per job)
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all \
  --max-downloads-per-run 50 --max-downloads-per-job 20

默认情况下，该脚本会执行保守的下载数量上限，以确保即使积累了许多新候选人，单次运行也不会进行批量访问：

标志	默认值	含义
--max-downloads-per-run	20	整次运行中简历下载数量的硬性上限。达到上限时，运行会正常停止（先完成当前职位，然后不再处理其他职位）。
--max-downloads-per-job	10	单个职位内简历下载数量的硬性上限。达到上限时，该职位的候选人循环会正常结束，运行将继续处理下一个职位。

达到上限时，运行仍会以 ok: true 退出；摘要中的 stopped_due_to_limit 字段会设为（"run"、"job" 或 null），以便操作人员了解仍有工作待处理，下一次计划运行会从本次停止的位置继续。

请使用可导入 boss_agent_cli 的 Python 解释器，否则 friend_detail 回退功能将被禁用。发生这种情况时，脚本会向 stderr 输出警告（使用 --verbose 时）。

如果 boss 不在 PATH 中，请使用 --boss-bin <path> 覆盖，或在环境中设置 BOSS_BIN=<path>。

故障排除

症状	可能原因	解决方法
unrecognized arguments: --verbose	全局选项放在了子命令之后	将 --verbose 放在 sync-all 或 sync-job 之前
[WinError 2] 系统找不到指定的文件 / FileNotFoundError: boss	子进程无法在 PATH 中找到 boss	传入 --boss-bin <path> 或设置 BOSS_BIN；在 Windows 上使用 %USERPROFILE%\bin\boss.cmd
浏览器已登录，但仍未登录	身份验证数据目录错误	使用 --data-dir ~/.boss-agent（Windows：%USERPROFILE%\.boss-agent）
CDP 连接被拒绝	启动 Chrome 时未启用远程调试	使用 --remote-debugging-port=9222 重新启动 Chrome
所有候选人均为 pending_security_id	applications 输出缺少 securityId，且内部回退失败	使用可导入 boss_agent_cli 的 Python 运行脚本，或传入 --verbose 查看导入错误
zhipin-recruiter 平台错误	平台名称错误	使用 --platform zhipin
applications 分页在第 100 页停止	达到硬性上限	针对具体职位重新运行，或按其他筛选条件拆分；达到上限时脚本会向 stderr 发出警告

输出预期

每次同步后报告以下内容：

• 简历根目录
• 发现的职位数量
• 更新的职位数量
• 发现的候选人数量
• 下载的简历数量
• 跳过的已存在简历数量
• 缺少 securityId、待处理的候选人数量
• 失败及其准确错误消息
• 是否因达到下载上限而提前停止

成功的同步响应结构：

{
  "ok": true,
  "resume_root": "<resolved path>",
  "mode": "sync-all",
  "stopped_due_to_limit": null,
  "totals": {
    "candidates_discovered": 0,
    "downloaded": 0,
    "skipped_existing": 0,
    "pending_security_id": 0,
    "failed": 0
  }
}

stopped_due_to_limit 的取值为 null（运行完成）、"run"（达到单次运行上限）或 "job"（至少一个职位达到职位上限）。

安全与礼仪

• 不要向候选人发送消息。
• 不要更改职位的在线／离线状态。
• 同步期间不要删除之前的简历或索引。
• 保留原始 API 响应以供调试。
• 将 BOSS 数据视为私人招聘数据。
• 不要将下载的候选人简历放入可分发的技能包中。