hr-recruiting-tracker

HR 招聘数据整理技能。用于本地解析 PDF/DOCX/TXT/Markdown 简历为 Markdown/JSON 简历包、生成候选人资料草稿、将确定性候选人草稿录入腾讯文档智能表格，以及初始化或维护岗位信息库。 Use when: resume ingestion, candidate draft extraction, Tencent Docs candidate upload, recruiting job table setup. 当前已实现工作流：resume-ingest、candidate-upload、job-management。

HR 招聘跟踪器

目的

使用此技能标准化招聘数据整理。已实现三个工作流：

1. resume-ingest：将简历文件转换为 AI 可读的 Markdown、原始 JSON 和候选人草稿，不写入任何外部招聘系统。
2. candidate-upload：将简历包中的确定性候选人草稿写入腾讯文档智能表格，支持招聘阶段跟踪；需 HR 审核的记录必须确认后才能上传。
3. job-management：初始化或维护固定岗位信息智能表格，并可显式导入真实岗位记录。

核心简历解析流程只依赖本地文件和 Python。腾讯文档上传和岗位库维护需要 OpenClaw 兼容 MCP 环境、mcporter CLI，以及已授权的 tencent-docs skill；高保真简历解析可选依赖 Docling，PDF 文本层回退可选依赖 pdftotext。引用此技能内部文件时使用 {baseDir}。

未来工作

以下能力尚未实现，只作为路线图记录，不要承诺已经可用：

• 搜索、分析和汇总已有候选人记录。
• 追加招聘事件，形成完整阶段流转日志。
• 企业微信通知。
• 面试日程或会议创建。

核心规则

1. 不要编造候选人事实。字段缺失时使用 null，或明确指出缺失字段。
2. 将生成的简历包视为机密招聘数据。
3. 默认优先使用本地安全解析器，避免意外触发外部模型下载。
4. Docling 仅作为高保真增强能力使用；当显式指定 --parser docling 或允许模型下载时才尝试。
5. 仅允许将回退解析器用于本地草稿提取；必须标记回退输出供 HR 审核。
6. 候选人上传工作流 (candidate-upload) 可将数据写入腾讯文档智能表格。写入前需先完成 resume-ingest。
7. 在任何工作流之前，先运行相关依赖检查。
8. 将原始证据与 AI 摘要分开保存。
9. 候选人表和岗位表的数据模型统一维护在 assets/schemas/recruiting_tables.json；操作腾讯文档字段时必须以该文件为准。
10. 教育经历必须拆分后入表：毕业院校 只能填学校名，专业 只能填专业名，最高学历 只能填学历，毕业年份 只能填年份。不要把整段教育经历写入单个字段。
11. 终端输出默认脱敏；只有用户明确要求排查映射细节时才使用 --show-sensitive。
12. candidate-upload 遇到 review_required=true 时默认禁止实际上传；HR 审核后必须显式传入 --confirmed-reviewed。

工作流判定

• 如果用户提供简历文件，并要求将其变得可读、解析、提取文本或准备候选人字段 → 使用 resume-ingest。
• 如果用户已拥有简历包，要求将候选人草稿录入腾讯文档智能表格 → 使用 candidate-upload。
• 如果用户要求初始化、维护、录入或查询岗位信息库 → 使用 job-management。
• 如果用户提供简历并直接要求"解析后录入系统" → 先执行 resume-ingest，再执行 candidate-upload。
• 如果用户要求搜索候选人、分析候选人库、发送企业微信消息或安排面试 → 说明这些路线图能力尚未实现。

统一表模型

腾讯文档智能表格字段统一维护在：

{baseDir}/assets/schemas/recruiting_tables.json

当前表模型：

表	固定智能表格名	用途
candidates	HR候选人库	候选人核心信息、解析质量、招聘阶段
jobs	HR岗位信息库	岗位 JD、要求、面试流程和状态

脚本和 Agent 都不得临时创造字段名。若需要新增字段，先修改该模型文件，再同步更新对应 workflow 文档和测试。

简历导入 (resume-ingest)

运行工作流前先阅读 references/workflow_resume_ingestion.md。

运行：

python3 {baseDir}/scripts/dependency_check.py --workflow resume-ingest
python3 {baseDir}/scripts/resume_extract.py "/path/to/resume.pdf" --out-dir "/path/to/output-bundle"

默认 auto 策略只使用本地安全解析器。需要 Docling 高保真解析时，使用：

python3 {baseDir}/scripts/resume_extract.py "/path/to/resume.pdf" --parser docling --out-dir "/path/to/output-bundle"

生成的简历包：

original.<ext>
resume.md
resume.raw.json
candidate_draft.json
extraction_report.json
manifest.json

将 resume.md 作为模型推理的主要来源。仅将 candidate_draft.json 用作确定性的提示。当用户要求结构化候选人字段时，使用 assets/templates/prompts/resume_extract_prompt.md。

候选人上传 (candidate-upload)

运行工作流前先阅读 references/workflow_candidate_upload.md。

此工作流将 resume-ingest 生成的简历包中的确定性候选人草稿写入腾讯文档智能表格；HR/LLM 审核输出仅用于人工补全，不会被上传脚本自动消费。

前置条件

1. 已安装 tencent-docs skill。可使用当前运行器支持的 skill registry 安装，例如：

   openclaw skills install tencent-docs
   openclaw skills info tencent-docs
   

   如果使用 SkillHub 或其他 registry，也可安装同名 skill。

2. 已安装 mcporter CLI

3. 已配置并授权腾讯文档 MCP（参考已安装且已审阅的 tencent-docs 技能的 references/auth.md）

4. 已完成 resume-ingest，拥有简历包目录

快速使用

将候选人草稿上传到已有智能表格：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --file-id "your_file_id" --confirmed-reviewed

默认上传到固定候选人库。脚本会先搜索 HR候选人库，存在则追加一条记录；不存在才创建：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --confirmed-reviewed

强制创建新的智能表格并上传：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --create-new --sheet-title "2025届校招-候选人库" --confirmed-reviewed

在知识库空间内强制创建：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --create-new --sheet-title "候选人库" --space-id "your_space_id" --confirmed-reviewed

预览模式（不实际写入、默认不联网、默认脱敏）：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --dry-run

预览时也探测腾讯文档目标表：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --dry-run --probe-remote

HR 已确认 review_required=true 的草稿记录后再实际上传：

python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --file-id "your_file_id" --confirmed-reviewed

智能表格字段

上传的候选人草稿包含以下字段：

字段	类型	说明
姓名	文本	候选人姓名
电话	电话	联系电话
邮箱	邮件	电子邮箱
当前公司	文本	当前/最近任职公司
工作年限	数字	工作年限
最高学历	文本	博士/硕士/本科/大专/高中及以下
毕业院校	文本	毕业学校
专业	文本	专业名称
毕业年份	数字	毕业年份
技能标签	文本	技能关键词（顿号分隔）
求职意向	文本	目标岗位
招聘阶段	文本	简历筛选/HR初筛/技术一面/技术二面/HR面/Offer/入职/不合适
简历来源	文本	简历文件名
解析质量	文本	高保真/回退解析/纯文本
需HR审核	复选框	回退解析时自动勾选
简历包路径	文本	本地简历包目录路径
录入时间	日期	自动填充记录创建时间
记录ID	文本	唯一标识（姓名+简历 sha256 前缀）

工作流步骤

1. 检查依赖

   python3 {baseDir}/scripts/dependency_check.py --workflow candidate-upload
   python3 {baseDir}/scripts/dependency_check.py --workflow candidate-upload --probe-remote
   

2. 授权排障（外部依赖）

   仅在腾讯文档授权缺失或需要排障时，运行已安装且已审阅的 tencent-docs 技能授权排障命令。不要假设 tencent-docs 与本 skill 一定是兄弟目录；优先使用环境变量或 OpenClaw 默认目录定位：

   export TENCENT_DOCS_SKILL_DIR="${TENCENT_DOCS_SKILL_DIR:-$HOME/.openclaw/workspace/skills/tencent-docs}"
   bash "$TENCENT_DOCS_SKILL_DIR/setup.sh" tdoc_check_and_start_auth
   

3. 上传候选人草稿

   python3 {baseDir}/scripts/upload_to_smartsheet.py "/path/to/bundle" --file-id "your_file_id" --confirmed-reviewed
   

4. 验证结果

   打开脚本输出的腾讯文档链接，确认数据是否正确录入。

注意事项

• ⚠️ 首次创建智能表格时会自动定义字段并清理默认行列
• ⚠️ 默认必须先搜索固定表名 HR候选人库；只有找不到或显式传入 --create-new 时才新建候选人库
• ⚠️ 如果搜索到多个同名 HR候选人库，脚本会使用搜索结果中的第一个；生产环境建议通过 --file-id 指定唯一候选人库
• ⚠️ 已有表格只新增字段，不会修改或删除已有字段
• ⚠️ tencent-docs 1.0.33 通过 MCP 新建单选字段可能返回 22020: Smartsheet invalid select field，本工作流默认使用文本字段保存枚举值
• ⚠️ 回退解析的候选人会自动标记"需HR审核"
• ⚠️ 如果 extraction_report.json 显示 review_required=true，脚本会阻止实际上传，直到显式传入 --confirmed-reviewed
• ⚠️ --dry-run 默认不联网，且默认脱敏；需要检查远程目标时传 --probe-remote
• ⚠️ PDF 文本层可能把中文拆成空格，例如 长 沙 学 院 计 算 机科学与技 术(本科)；写入前必须归一化并拆分为 长沙学院、计算机科学与技术、本科
• ⚠️ 电话号码按原文写入腾讯文档；终端输出默认脱敏，展示层仍建议脱敏
• ⚠️ 多条候选人可重复调用脚本，记录会追加到表格

岗位信息管理 (job-management)

运行工作流前先阅读 references/workflow_job_management.md。

此工作流维护固定腾讯文档智能表格 HR岗位信息库。字段定义来自 assets/schemas/recruiting_tables.json。

快速使用

检查依赖：

python3 {baseDir}/scripts/dependency_check.py --workflow job-management
python3 {baseDir}/scripts/dependency_check.py --workflow job-management --probe-remote

初始化或校验岗位表结构：

python3 {baseDir}/scripts/manage_jobs.py

导入真实岗位记录：

python3 {baseDir}/scripts/manage_jobs.py --records-json "/path/to/jobs.json"

指定已有岗位表：

python3 {baseDir}/scripts/manage_jobs.py --file-id "your_file_id"

预览模式：

python3 {baseDir}/scripts/manage_jobs.py --dry-run

岗位字段

字段	说明
job_id	岗位唯一标识
job_title	岗位名称
department	部门
hiring_manager	用人经理
must_have	必须条件
nice_to_have	加分条件
responsibilities	工作职责
level	职级
location	地点
salary_range	薪资范围
interview_process	面试流程
status	开放/暂停/关闭
updated_at	岗位记录更新时间

status 当前使用文本字段保存，避免 tencent-docs 1.0.33 新建单选字段时触发 22020 错误。

依赖策略

添加或检查提供方时阅读 references/dependency_contracts.md。

第一个工作流需要 resume.parse 能力。默认路径优先使用本地文本层解析器，避免意外联网下载模型。Docling 能启动不等于真实 PDF 转换可用；如需验证，请使用 dependency_check.py --probe-file "/path/to/resume.pdf"。

腾讯文档工作流的依赖检查默认只做本地检查；需要验证 MCP 连通性和授权时显式加 --probe-remote。

处理私人简历时，默认只运行本地脚本。调用 openclaw agent --local 可能经过已配置的模型 provider，除非用户明确授权，不要把私人简历交给 agent 端到端处理。

输出风格

resume-ingest 成功时

告知 HR：

• 简历包目录
• 使用的解析器
• 质量等级
• 生成的文件
• 缺失或不明确的字段
• 是否需要 HR 审核
• extraction_report.json 中的 review_reasons

resume-ingest 失败时

报告解析器错误；如果已创建 extraction_report.json，同时报告其路径。

candidate-upload 成功时

告知 HR：

• 腾讯文档链接
• 录入的候选人姓名
• SmartSheet file_id 和 record_id
• 解析质量及是否需要审核
• 缺失字段提示

candidate-upload 失败时

报告具体错误：

• 如果是授权问题，引导完成腾讯文档授权
• 如果是 MCP 调用失败，检查 mcporter 和网络连接
• 如果是数据问题，检查简历包完整性

job-management 成功时

告知 HR：

• 固定岗位表名
• 腾讯文档链接
• SmartSheet file_id 和 sheet_id
• 新写入岗位数量
• 被跳过的重复 job_id