51job简历下载器

概述

前程无忧(51job) 简历自动下载器

通过 CDP（Chrome DevTools Protocol）远程调试操控用户本地 Edge 浏览器，自动登录前程无忧(51job) 并从其「聊天 / 消息」栏目下载候选人简历到本地目录。

说明：本工具操作的是你自己的前程无忧账号下、候选人通过聊天/消息发来的简历数据，用于本地归档与整理。请遵守前程无忧用户协议与当地法律法规，仅下载你有权处理的简历，妥善保管其中的个人信息。

何时使用

• 用户希望从前程无忧下载候选人简历（尤其是通过聊天/消息栏目收到的简历）。
• 用户提到「前程无忧简历」「下载51job简历」「前程无忧下载简历」「批量下载前程无忧简历」「51job resume」等关键词。
• 需要将简历按岗位 / 候选人整理归档到本地目录。

核心能力

• 简历目录默认「当前工作目录/dist」、无需询问：不传 --download-dir 时，脚本自动把简历存放在「运行目录 / dist」（即 <cwd>/dist），不弹任何对话框；配置写入 ~/.qiancheng_downloader/config.json 的 download_dir，第二次及以后运行默认复用已保存的目录（可用 --download-dir 临时覆盖，或用 --setup / --first-run 强制改用默认目录）。
• 人工登录 + Cookie 复用：不再收集手机号 / 手机类型，也不再做短信验证码自动登录。首次运行（无有效 Cookie）时脚本打开可视化的前程无忧企业登录页，由用户在浏览器中手动完成手机号 + 短信验证码 + 极验登录；登录成功后自动保存 Cookie。后续运行直接注入已保存 Cookie，经 SSO 跳转即登录成功，无需重复手动操作。
• 按岗位分别下载 + 按岗位/日期分目录归档：登录成功后自动探测「人才沟通」栏目，先抓取右侧岗位列表（一行为各岗位名称的罗列），逐个点击岗位进入其候选人会话列表，分别下载；简历按 下载目录/岗位/下载日期(YYYY-MM-DD) 分目录存储（优先下载按钮，回退 PDF 导出）。若检测不到右侧岗位列表，则退化为按全部候选人一次下载。
• 拟人化操作（默认开启）：全程模拟真人，降低风控识别——

· 真实鼠标以贝塞尔曲线平滑移动到目标（岗位标签、会话项、发送按钮）再物理点击，而非机器式坐标直跳；· 每次操作前光标微游移 + 0.4~1.6s「犹豫」停顿；· 每份简历之间随机停顿 2.5~6s，约 18% 概率出现 8~20s 的「走神/阅读」式长停顿；· 索要简历消息逐字输入（带 70~160ms 随机打字间隔），模拟真人打字节奏；· 单份内部等待亦随机化（2~4.5s）。--fast 可关闭上述拟人化停顿与微动以加快处理。

• 判断简历是否提供，未提供则索要：处理每个候选人时，先判断其是否在会话中提供了简历（在线简历 / 附件简历 / 聊天中的简历文件）。提供了就下载；没提供就自动在会话里发送一条「索要简历」的礼貌消息并计入「已发起索要」。区分「没提供」与「提取失败」：检测到简历元素但本次未取到会原地重试，完全无简历元素才发起索要，避免误向已提供简历的候选人重复索要。
• 完成报告在 WorkBuddy 对话框展示（不落盘 JSON）：运行结束后，完整报告打印到 stdout——在 WorkBuddy 中由对话层 Agent 读取并直接展示在对话框里（含本次下载的岗位 / 候选人清单与文件名、已发起索要简历的候选人、未成功清单、保存目录等）；stdout 报告带 @@DOWNLOAD_REPORT_JSON@@ 前缀的 JSON 行，便于机器解析。不再生成本地 JSON 报告文件，且不再弹任何系统结果窗口——报告始终通过 stdout 输出、由 WorkBuddy 对话框直接展示（无界面 / SkillHub / CI 场景同样适用，无显示环境不会报错）。
• 结束即关闭浏览器：下载完成后关闭 Edge 调试实例（--no-auto-edge 时除外），不残留后台进程。
• 已下载去重（避免重复下载）：脚本在 ~/.qiancheng_downloader/download_record.json 维护一份已下载记录（按 岗位::姓名 去重，含下载时间与文件名）。处理每个候选人时，若已在记录中则直接跳过、不再下载（无论 full / incremental 模式）；下载成功后才写入记录。需要强制重新全量下载时，运行 --reset-download-record 清空记录即可（不会删除已下载的简历文件）。
• 处理模式（首跑全量 / 之后增量）：auto（默认）= 首次运行（无已下载记录）执行全量下载；之后默认增量，仅处理当前时间往前 24 小时内有新互动、且尚未下载过的候选人；full = 处理所有未下载过的候选人（仍跳过已下载的）；incremental = 仅处理 24h 内新沟通且未下载过的候选人。

工作原理

CDP 在操作系统层面操控浏览器——通过 --remote-debugging-port=9222 连接的 Edge，前程无忧前端 JavaScript 感知不到外部操控，可绕过登录滑块、行为验证等前端检测。

登录复用机制：首次成功登录后，Cookie 持久化到 ~/.qiancheng_downloader/cookies.json。后续运行脚本先把 Cookie 注入浏览器上下文，再经 SSO 入口（https://ehire.51job.com/Revision/ 或聊天页 URL）尝试跳转；有效会话会让 51job 自动进入已登录态（人才沟通），从而跳过短信验证与极验风控；若 Cookie 失效，则退回手动登录（打开企业登录页由用户完成）。

页面选择器（登录页 / 聊天页 / 下载按钮等）集中在 scripts/site_config.py 作为单一事实来源（SSOT），支持 scripts/site_config.user.json 深合并覆盖。引擎在启动时 import site_config 并覆盖内置默认值（覆盖成功时日志打印 USING_SITE_CONFIG=True）。前程无忧企业端真实入口已校准：登录 https://ehire.51job.com/Revision/login，聊天「人才沟通」为 Vue SPA（入口 https://mall.51job.com/Revision/online/，左侧菜单 li.menu-6）。

⚠️ 关于选择器校准（重要）

前程无忧的 Web 页面 DOM 结构会随版本更新。脚本内置选择器优先取自 site_config.py（已对 51job 企业端真实结构做校准），并在关键处提供兜底启发式。若某次运行岗位筛选 / 简历提取未生效，请按以下方式校准：

1. 在浏览器手动登录前程无忧，进入「聊天 / 消息」栏目，确认页面真实元素；
2. 若聊天页 URL 不是默认的 https://mall.51job.com/Revision/online/，用 --chat-url <真实URL> 覆盖；
3. 通过 scripts/site_config.user.json 深合并覆盖 CHAT 相关选择器（会话项 / 岗位筛选标签 / 简历区域 / 聊天输入框等），无需改源码；
4. 用 --max 1 单份验证下载 / 索要，确认无误后全量运行。

前置依赖与首次自动配置

• Edge 浏览器：本机需安装 Microsoft Edge（默认 C:Program Files (x86)MicrosoftEdgeApplicationmsedge.exe 或 C:Program FilesMicrosoftEdgeApplicationmsedge.exe）。脚本会自动以 CDP 调试模式拉起 Edge（--no-auto-edge 时改用已运行的实例）。
• Python 依赖：playwright（仅用于 CDP 连接）。安装：python -m pip install playwright。
• 图形界面：需在本机桌面环境运行（本地 Edge 浏览器依赖图形会话）；脚本已不再弹任何文件夹选择窗 / 结果弹窗，所有交互（目录默认 / 报告）均走 WorkBuddy 对话框 + stdout。

🔧 安装后自动环境配置（SkillHub 公用关键）：用户从 SkillHub 下载安装后首次运行会自动执行环境自检与补齐，无需手动装依赖——在启动下载任务之前，ensure_environment() 会依次：① 校验 Python 版本；② 缺失则自动 pip install playwright；③ 缺失则自动 playwright install msedge 下载 Edge 并扩展查找路径（系统无 Edge 也能用）；④ 创建运行时目录 ~/.qiancheng_downloader/。任一项无法自动修复会清晰报错并中止，绝不静默继续。已装好则瞬间跳过（本地开发机即如此）。--seed-record 仅扫描本地目录、不启动浏览器，故跳过浏览器检测。

WorkBuddy 对话层执行流程（四步）

Step 1：简历存放目录（默认「当前工作目录/dist」）

1. 运行脚本（无需任何手机号 / 类型参数）：

   cd ~/.workbuddy/skills/qiancheng-resume-downloader/scripts
   python qiancheng_cdp.py

1. 不传 --download-dir 时，脚本默认把简历存放在「当前工作目录 / dist」（cwd/dist），不弹任何对话框；若 ~/.qiancheng_downloader/config.json 已保存过目录且仍存在，则默认复用该目录。
2. 最终使用的目录会写入 ~/.qiancheng_downloader/config.json 的 download_dir。
3. 第二次及以后运行：复用已保存目录（除非 --setup 强制改用默认目录，或 --download-dir 临时覆盖）。

Step 2：首次人工登录前程无忧并保存 Cookie

• 脚本自动拉起可见的 Edge 企业登录页（https://ehire.51job.com/Revision/login）。
• 用户在浏览器中手动完成登录：输入手机号 → 获取验证码 → 手机查收并填入 → 若有极验则手动拖动滑块 → 立即登录。
• 脚本每数秒检测一次登录态（默认最长等待 15 分钟），一旦检测到登录态立即保存 Cookie 到 ~/.qiancheng_downloader/cookies.json，随后自动进入下载阶段。

Step 3：后续运行默认 Cookie 复用（免登录）

• 第二次及以后运行，脚本先注入已保存 Cookie，再经 SSO 入口跳转；会话有效则直接进入已登录态，无需再次手动登录。
• 仅当 Cookie 失效（停在登录页）时，才退回 Step 2 的人工登录。

Step 4：按岗位分别下载 / 索要 → 关闭浏览器

• 登录成功后，脚本点击「人才沟通」菜单进入 SPA 路由，导航到聊天页（可用 --chat-url 指定真实地址）；
• 按岗位分别下载：脚本先抓取右侧「岗位列表」（一行为各岗位名称的罗列），逐个点击岗位进入其候选人会话列表；
• 对每个候选人：先判断是否在会话中提供了简历——提供了就下载，没提供就自动在会话里发送「索要简历」消息；
• 简历按 下载目录/岗位/下载日期(YYYY-MM-DD) 分目录存储（优先下载按钮，回退 PDF 导出）；
• 全程拟人化操作（贝塞尔真实鼠标轨迹、逐字输入、随机停顿，模拟人工、控制速度、降低风控）；
• （Cookie 登录已修复 SSO 跳转竞态：注入 Cookie 后轮询等待登录态生效，通常一次即可进入下载，不再需要反复尝试。）
• 收尾顺序：① finally 中关闭 Edge 调试实例（--no-auto-edge 除外）；② 完整报告打印到 stdout，由 WorkBuddy 对话框直接展示（含下载清单 / 已发起索要简历的候选人 / 保存目录等），不写本地文件、不弹任何系统窗。任务结束即完成，无需等待弹窗关闭。

运行方式

标准交互运行（推荐，无需任何参数）：

cd ~/.workbuddy/skills/qiancheng-resume-downloader/scripts
python qiancheng_cdp.py

强制重新选择存放目录（忽略已保存目录）：

python qiancheng_cdp.py --setup
# 或别名
python qiancheng_cdp.py --first-run

临时覆盖存放目录（不修改已保存配置）：

python qiancheng_cdp.py --download-dir "D:/招聘/前程无忧"

限制处理数量（调试用）：

python qiancheng_cdp.py --max 10

指定处理模式：

python qiancheng_cdp.py --mode full          # 处理所有未下载过的候选人（仍跳过已下载的）
python qiancheng_cdp.py --mode incremental   # 仅处理 24h 内新沟通且未下载过的候选人
python qiancheng_cdp.py --reset-download-record   # 清空已下载记录，下次运行重新全量下载
# 默认 auto：首次运行全量，之后增量（24h 内且未下载过）

单份验证（确认下载 / 索要简历 / 拟人化点击无误后再全量）：

python qiancheng_cdp.py --max 1

复用已运行的 Edge 实例（不自动拉起 / 不自动关闭）：

python qiancheng_cdp.py --no-auto-edge

可用参数

已移除旧版的 --phone / --phone-type / --relay / --auto / --show-webhook-url / --sms-listen 等短信验证码相关参数；本版登录完全走「人工登录 + Cookie 复用」，不再需要手机号与短信转发中继。

目录结构

qiancheng-resume-downloader/
├── SKILL.md                    # 本文件
├── LICENSE.txt                # MIT 许可证
├── scripts/
│   ├── qiancheng_cdp.py       # 核心 CDP 自动化脚本（默认目录 cwd/dist + 人工登录 + 按岗位下载/索要 + stdout 报告）
│   ├── config_manager.py      # 明文 JSON 配置管理
│   └── site_config.py         # 51job 页面选择器 SSOT（URL/菜单/登录/聊天/按钮 JS）
└── references/
    └── site_selectors.md      # 前程无忧页面选择器参考（校准方法）

运行时产生的本地文件（位于 ~/.qiancheng_downloader/）：

• config.json：download_dir（简历存放目录）、first_run_completed 等。
• cookies.json：登录 Cookie（首次人工登录成功后保存，之后免重复登录）。
• 完成报告不写文件，仅在 WorkBuddy 对话框展示（stdout 的 @@DOWNLOAD_REPORT_JSON@@）。

自定义选择器：在 scripts/ 下放置 site_config.user.json，字段会深合并覆盖 site_config.py 中的同名项（如 URLS、CHAT、RESUME_BTN_TEXTS 等），无需改动源码。

故障排除

CDP 连接失败（localhost:9222 不可达）

1. 关闭所有 Edge：taskkill /F /IM msedge.exe
2. 重新以调试模式启动：start "" "C:Program Files (x86)MicrosoftEdgeApplicationmsedge.exe" --remote-debugging-port=9222 --no-first-run --no-default-browser-check "https://ehire.51job.com/Revision/login"
3. 浏览器访问 http://localhost:9222/json/version 验证；非本机首次运行加 --no-auto-edge。

登录失败 / Cookie 失效

• 脚本默认依赖已保存 Cookie 经 SSO 自动登录；若 Cookie 过期或失效，会自动退回「人工登录」——请在弹出的 Edge 窗口中手动完成手机号 + 验证码 + 极验登录。
• 登录成功后 Cookie 会重新保存，下次运行再次免登录。
• 账号被冻结或锁定需人工处理。

聊天页找不到候选人 / 下载按钮找不到

• 前程无忧可能更新了页面结构。先在浏览器手动登录并进入「人才沟通」确认真实元素。
• 通过 scripts/site_config.user.json 深合并覆盖 CHAT 相关选择器（会话项 / 岗位筛选标签 / 简历区域 / 聊天输入框等），或用 --chat-url <新URL> 覆盖入口。
• 用 --max 1 先单份验证，确认无误后全量运行。

缺少 Playwright / Edge（首次自动安装失败）

• 正常情况下首次运行会自动 pip install playwright 与 playwright install msedge，无需手动操作。
• 若自动安装仍失败（如离线 / 无写入权限），按提示手动执行：

python -m pip install playwright
python -m playwright install msedge

CDP 模式无需 playwright install chromium，因为使用的是用户本地 Edge 浏览器。

参考资料

• 页面选择器与校准方法见 references/site_selectors.md。
• 51job 真实选择器 SSOT 见 scripts/site_config.py。