boss-resume-crawler

从 Boss 直聘批量爬取职位详情（含 security_id、职位描述），支持 PUA 薪资解码和增量去重。

Boss直聘职位爬取

快速验证（环境 OK 后立即跑通）

bash

# 一条命令验证：爬取 5 条职位，输出到 /tmp
python3 scripts/boss_extract_cdp.py --max-scroll 3 --max-jobs 5 --output /tmp/boss_test

验证通过 → 正式爬取。失败 → 检下方依赖和 CDP 连接。

---

性能基准（实测）

指标	数值
单页滚动加载	~2 秒/次
详情页提取	~22 秒/条（含 20 秒等待 + 随机波动）
100 条职位总耗时	~40 分钟
500 条职位总耗时	~3 小时

详情页耗时主要由等待时间决定（20 秒/条），这是 Boss 直聘客户端渲染的硬限制。

---

首次使用：依赖检查（必须）

在执行任何爬取操作之前，必须先检查以下依赖是否就绪。缺失时提示用户安装。

检查脚本

bash

# 1. Python3
python3 --version 2>/dev/null || echo "❌ 未安装 Python3 → https://www.python.org/downloads/"

# 2. websocket-client（Python 库）
python3 -c "import websocket" 2>/dev/null || echo "❌ 缺少 websocket-client → pip3 install websocket-client"

# 3. CDP 连接（CloakBrowser 是否启动）
curl -s http://localhost:9222/json >/dev/null 2>&1 || echo "❌ CDP 未连接，请先启动 CloakBrowser（见下方说明）"

CloakBrowser 启动方法

CloakBrowser 是一个反检测 Chromium 浏览器，用于绕过 Boss 直聘的自动化检测。

安装：

bash

# 安装依赖
npm install cloakbrowser playwright-core

# 下载 Chromium（需要代理）
export https_proxy=http://127.0.0.1:7890  # 根据你的代理配置
curl -L --max-time 600 -o /tmp/cloakbrowser-darwin-x64.tar.gz <下载链接>
tar -xzf /tmp/cloakbrowser-darwin-x64.tar.gz -C ~/.cache/cloakbrowser/

# 设置环境变量
export CLOAKBROWSER_BINARY_PATH=~/.cache/cloakbrowser/Chromium.app/Contents/MacOS/Chromium

CloakBrowser 项目地址：https://github.com/nickspaargaren/cloakbrowser

启动（有头模式，必须）：

bash

open ~/.cache/cloakbrowser/Chromium.app --args \
  --remote-debugging-port=9222 \
  "--remote-allow-origins=*" \
  --user-data-dir=<你的浏览器数据目录> \
  "<Boss直聘列表页URL>"

⚠️ Boss 直聘会检测 headless 模式，必须使用有头模式（能看到浏览器窗口）。

依赖就绪标志

所有 ✅ 后方可执行爬取：

• Python3 可用
• websocket-client 已安装
• CDP 连接正常（curl -s http://localhost:9222/json 返回页面列表）
• 用户已登录 Boss 直聘（见下方登录检查）

---

输入要求

• 必须提供 Boss 直聘列表页 URL（含 zhipin.com/web/geek/jobs）
• 未提供 URL 时必须主动询问，不要自行构造

登录状态检查（必须在 Phase 1 之前执行）

打开列表页后，首先检查登录状态，未登录则暂停等待人类操作：

bash

snapshot=$(agent-browser --cdp 9222 snapshot -i --timeout 8000 2>/dev/null)
if echo "$snapshot" | grep -qE "登录/注册|立即登录|登录"; then
  echo "⚠️ 未登录状态，请手动扫码登录"
  echo "登录完成后告知我，我再继续"
fi

判断逻辑：

• ❌ 出现「登录/注册」「立即登录」「我要找工作」等链接 → 未登录
• ✅ 出现用户名或用户头像链接 → 已登录

未登录时的处理：

1. 暂停所有爬取工作
2. 提示用户：「页面显示未登录，请在浏览器中扫码登录，完成后告知我」
3. 等待用户明确说「已登录」或「继续」后，再执行后续 Phase

---

执行流程

Phase 1：列表页滚动加载

使用 CDP Input.dispatchMouseEvent mouseWheel 模拟真实鼠标滚轮（agent-browser scroll 无效）。最多 100 次滚动，随机等待 1.5-3.5 秒，连续 3 次数量不变则停止。启动浏览器需添加 "--remote-allow-origins=*" 参数。 详见 references/sop.md SOP-1。

Phase 2：职位列表提取

通过 CDP 执行 JavaScript 从 .job-card-wrap 提取职位基础信息，薪资需 PUA 解码（0xe031→0, ..., 0xe03a→9）。选择器和字段规格见 references/data-spec.md。

Phase 3：详情页逐条爬取

CDP 开新 tab → 等待 20 秒 + 随机波动（0-3 秒） → 检查 readyState → 提取 security_id + 职位描述 → 立即关闭 tab。

为什么必须等 20 秒？ Boss 直聘详情页使用客户端渲染（React/Vue），CDP 打开新 tab 后需要等待 JS 框架完成 hydration + API 请求返回数据。实测 <15 秒约 40% 概率拿到空数据，<10 秒几乎必定为空。

为什么每次都要关闭 tab？ 不关闭会导致 tab 堆积，占用 CDP 连接资源，后续操作超时。

详见 references/sop.md SOP-2、SOP-4。

Phase 4：CSV 增量存储

每提取 1 条立即追加写入 CSV（不缓存到内存）。追加模式（'a'）+ 跨文件 job_id 去重。禁止使用 'w' 覆盖模式。 详见 references/sop.md SOP-3。

Phase 5：质量报告

输出本次新增/去重跳过/累计总量/字段完整率/错误详情。格式见下方「输出规范」。

数据校验标准

字段	校验
job_id	非空，>=20 字符
security_id	非空，>=30 字符
薪资	包含 "K"（实习岗日薪除外）
职位描述	非空，>=100 字符
公司名称	非空，>=2 字符

输出规范

• CSV 路径：<工作目录>/jobs_data_{YYYYMMDD}_{HHMM}.csv
• 错误日志：同目录下 temp/error_log.csv
• 质量报告格式：
  • 本次新增：N 条
  • 去重跳过：N 条
  • 累计总量：N 条
  • 字段完整率：job_id X% | security_id X% | 职位描述 X%
  • 错误：N 条（详情见 error_log.csv）

错误处理

两层 Fallback：

1. 第一层：增加等待时间重试（+5 秒/次），同一位置最多 3 次
2. 第二层：跳过错误职位，记录到 temp/error_log.csv，继续下一个

常见错误速查

现象	原因	解决方案
WebSocket 连接超时	CDP 长连接被断开	新脚本已修复（每次独立连接）
security_id 为空	详情页等待时间不足	增加 --base-wait 25
职位描述全部为空	等待 <15 秒	确保等待 ≥20 秒
ACCOUNT_RISK	被风控拦截	切换 CloakBrowser profile（用新 --user-data-dir）
CDP 连接被拒	缺少 --remote-allow-origins=*	启动时添加该参数
滚动后只有 15 条	agent-browser scroll 无效	脚本已使用 CDP Input.dispatchMouseEvent mouseWheel
CSV 数据被覆盖	用了 'w' 模式	脚本已使用 'a' 追加模式
PUA 薪资乱码	未解码	脚本已内置 decode_pua 函数
进程中断后数据丢失	旧脚本无批次缓存	新脚本每条立即写入 CSV

已知问题和修复方案详见 references/error-handling.md。

脚本

脚本	用途	运行说明
scripts/boss_extract_cdp.py	默认脚本：纯 CDP 模式，反爬优化	依赖：websocket-client。推荐使用
scripts/boss_extract_pure.py	旧版备用：纯 CDP 模式（无反爬优化）	依赖：websocket-client。不推荐
scripts/boss_extract_final.py	agent-browser 模式	依赖：agent-browser, websocket-client

默认脚本参数：

bash

# 指定输出目录（默认当前目录）
python3 scripts/boss_extract_cdp.py --output ~/Desktop/jobs

# 限制滚动次数（默认100）
python3 scripts/boss_extract_cdp.py --max-scroll 30

# 限制爬取条数（默认全部）
python3 scripts/boss_extract_cdp.py --max-jobs 10

# 调整详情页等待秒数（默认20）
python3 scripts/boss_extract_cdp.py --base-wait 25

# 组合使用
python3 scripts/boss_extract_cdp.py --output ~/Desktop/jobs --max-scroll 50 --max-jobs 20

脚本设计原则（反爬）：

• 每次 CDP 操作新建 WebSocket 连接，用完即关（防超时）
• 每提取 1 条立即追加写入 CSV（防数据丢失）
• 详情页提取后立即关闭 tab（防 tab 堆积）
• 所有等待时间加随机波动（反爬）
• 失败自动重试，指数退避（容错）

优先使用 Agent 自主执行（实时处理异常更灵活），职位数量大时运行脚本批量处理。

反爬注意事项

• 必须使用有头模式（headless 会被拦截）
• 必须使用 CloakBrowser（反检测 Chromium）
• 滚动必须使用 CDP Input.dispatchMouseEvent mouseWheel（agent-browser scroll 无效）
• 启动浏览器需添加 "--remote-allow-origins=*" 参数
• 滚动间隔 1.5-3.5 秒（随机化），模拟人类阅读节奏
• 详情页等待 20 秒 + 随机波动（0-3 秒）+ 重试退避（+5 秒/次）
• 每次 CDP 操作独立连接，避免长连接被检测
• 详情页提取后立即关闭 tab，避免大量 tab 堆积