name: resume-extractor description: "HR 简历结构化提取专家。Use when: 需要从简历 (PDF/DOCX/TXT) 中提取 候选人信息、工作经历、教育背景、技能、自我评价、求职意向、资质证书。 适用于: 简历解析、人才数据库构建、候选人搜索、JD匹配、招聘数据分析。 基于 Google LangExtract 算法层重构，针对 HR 场景深度优化。 提供: (1) 7种HR提取类型分类框架 (2) 中文简历Few-shot模板库 (3) 7步后处理管道 (时间标准化/Source Grounding/去重/评分/消歧/关系推断/KG转换) (4) PDF/DOCX文档解析器 (5) SQLite人才数据库+导入/查询/匹配CLI (6) JD-候选人智能匹配 (5维加权评分)。 仅需 PyMuPDF + python-docx，无需外部 API。"

Resume Extractor

简历结构化提取 | 7 种 HR 类型 | PDF/DOCX 解析 | 7 步管道 | SQLite 人才库 | JD 匹配

核心禁令 (CRITICAL)

1. 禁止跳过 Few-shot - 提取时必须按 references/few-shot-templates.md 中的模板输出
2. 禁止自由格式输出 - 必须严格遵循 references/output-schema.md 定义的 JSON Schema
3. 禁止跳过后处理 - 原始提取必须经过 scripts/pipeline.py 处理后才算完成
4. 禁止低质量输出 - confidence < 0.3 的提取必须过滤

快速决策树

我需要处理简历?
    |
    +-- 输入格式是什么?
    |   +-- .pdf       --> python parse.py --input resume.pdf --output resume.md
    |   +-- .docx/.doc --> python parse.py --input resume.docx --output resume.md
    |   +-- .txt/.md   --> 直接使用，无需解析
    |
    +-- Step 1: 解析为纯文本 (parse.py)
    |
    +-- Step 2: 选择预设 (resume.json)
    |
    +-- Step 3: Claude 提取 (7种HR类型，按 Few-shot 模板)
    |
    +-- Step 4: 运行后处理管道 (pipeline.py)
    |
    +-- Step 5: 导入数据库 (import_resume.py)
    |   +-- 单文件: --input result.json
    |   +-- 批量:   --input-dir ./results/
    |
    +-- Step 6: 查询 / 匹配
        +-- 搜索:  python query.py search "Python 北京"
        +-- 统计:  python query.py stats --by skill
        +-- 详情:  python query.py detail 1
        +-- JD匹配: python match.py --jd jd.txt --top 10

工作流

Step 1: 文档解析 + 噪音清理

将 PDF/DOCX 简历解析为 Markdown 纯文本，自动清理招聘平台水印/追踪码:

# 单文件
python scripts/parse.py --input resume.pdf --output resume.md

# 批量模式
python scripts/parse.py --input-dir ./resumes/ --output-dir ./parsed/

v1.1: 自动清理 BOSS直聘/猎聘等平台嵌入的 base64-like 追踪码行

支持的格式:

| 格式 | 解析器 | 依赖 | 特殊能力 | |------|--------|------|---------| | .pdf | PdfParser (PyMuPDF) | pip install PyMuPDF | 单栏/双栏自动检测 + 水印清理 | | .docx | DocxParser (python-docx) | pip install python-docx | 标题/粗体/表格保留 | | .doc | DocxParser (有限支持) | 同上 | 兼容模式 | | .txt/.md | 无需解析 | - | 直接使用 |

Step 1.5: 文件名元数据提取 (可选)

招聘平台文件名通常包含岗位/城市/薪资等元数据，可提取为 context_hints:

python scripts/filename_parser.py "【高级Web后端开发工程师_成都 18-25K】唐双 6年.pdf"
# 输出: {"position": "高级Web后端开发工程师", "city": "成都", "salary_min": 18000, ...}

v1.1: 生成的 context_hints 可在 Claude 提取时补充候选人城市等缺失信息

Step 2: 选择预设

使用简历预设配置:

预设文件: assets/presets/resume.json
  - 重点: 全部 7 种 HR 类型
  - 管道: 7 步全开 (含时间标准化+实体消歧+关系推断)

Step 3: Claude 提取

按以下规则从简历文本中提取结构化信息:

7 种提取类型 (详见 references/extraction-types.md):

| 类型 | 识别特征 | 典型数量 | |------|---------|---------| | candidate | 姓名、性别、年龄、手机、邮箱、城市 | 1 | | experience | 公司、职位、时间段、职责、嵌套项目 | 2-5 | | education | 学校、专业、学位、GPA、荣誉 | 1-3 | | skill | 技能名、类别、熟练度、年限 | 5-15 | | self_evaluation | 自我评价原文、关键特质标签 | 0-1 | | job_intention | 期望职位、薪资、城市、到岗时间 | 0-1 | | certification | 证书名、颁发机构、日期、有效期 | 0-5 |

输出格式 (每个提取项):

{
  "id": "ext_001",
  "type": "candidate",
  "text": "张三\n男 | 28岁 | 北京\n手机: 138-0000-0000",
  "summary_cn": "候选人张三，男，28岁，现居北京",
  "attributes": {
    "name": "张三",
    "gender": "男",
    "age": 28,
    "city": "北京",
    "phone": "138-0000-0000"
  },
  "source_file": "张三_简历.pdf"
}

Few-shot 模板: 见 references/few-shot-templates.md

Step 4: 运行后处理管道

# 使用简历预设 (推荐)
python scripts/pipeline.py --input raw.json --source resume.md \
  --config assets/presets/resume.json --output result.json

管道步骤 (详见 references/post-processing.md):

1. Time Normalization --> 时间格式标准化 (v1.1 新增)
2. Source Grounding   --> 精确定位 (char_start/end + line)
3. Overlap Dedup      --> 去除重复提取
4. Confidence Score   --> 4维度质量评分
5. Entity Resolution  --> 同名候选人合并 (HR默认开启)
6. Relation Inference --> 人-公司-技能关系推断 (HR默认开启)
7. KG Injection       --> 知识图谱格式转换 (可选)

Step 5: 导入数据库

将 Pipeline 输出导入 SQLite 人才数据库:

# 单文件导入
python scripts/import_resume.py --input result.json

# 批量导入
python scripts/import_resume.py --input-dir ./results/

# 显示详情
python scripts/import_resume.py --input result.json --verbose

# 指定数据库路径
python scripts/import_resume.py --input result.json --db data/resumes.db

Step 6: 查询与匹配

# 搜索候选人 (自然语言)
python scripts/query.py search "Python 北京"

# 搜索候选人 (精确筛选)
python scripts/query.py search --skill Python --city 北京 --min-years 3 --education 本科

# 查看候选人详情
python scripts/query.py detail 1

# 列出所有候选人
python scripts/query.py list --limit 20

# 统计分析
python scripts/query.py stats
python scripts/query.py stats --by skill
python scripts/query.py stats --by education
python scripts/query.py stats --by city

# JD 匹配 (从文本文件自动提取需求)
python scripts/match.py --jd jd.txt --top 10

# JD 匹配 (从 JSON 需求文件)
python scripts/match.py --jd-json requirements.json --top 10 --verbose

JD JSON 格式:

{
  "skills": ["Python", "Django", "Redis"],
  "min_years": 3,
  "education": "Bachelor",
  "city": "Beijing",
  "salary_range": [20000, 35000]
}

匹配评分维度: skill(40%) + experience(20%) + education(15%) + city(15%) + salary(10%)

预设配置快速参考

| 预设 | 重点类型 | 默认后处理 | |------|---------|-----------| | resume | 全部 7 种 HR 类型 | 7 步全开 (含时间标准化+实体消歧+关系推断) |

核心原则

1. Few-shot 驱动 - 提取质量的关键在于 Few-shot 模板，不是自由发挥
2. Pipeline 后处理 - 原始提取必须经过 Python 管道处理才算完成
3. text 必须来自原文 - 提取的 text 字段是简历原文精确片段，不是改写或翻译
4. 技能单独提取 - 每个技能是独立记录，不合并到一条
5. 时间格式统一 - period_start/period_end 统一为 YYYY.MM 格式（仅年份补 .01，"至今" 保留原文）
6. 隐式技能提取 - 不仅从"技能"栏提取，还要从工作经历/项目描述中识别算法、领域知识、方法论等隐式技能 (v1.1)
7. 技能分类 8 类 - 语言/框架/工具/数据库/外语/算法/领域/方法论 + 软技能/证书相关/其他 (v1.1)

Red Flags

看到这些信号时立即检查:

| 红旗信号 | 正确做法 | |----------|----------| | "直接从 PDF 提取 JSON" | 必须先 parse.py 转文本，再 Claude 提取 | | "不需要 Few-shot" | 必须按模板格式输出，否则后处理会失败 | | "text 字段我翻译/总结了一下" | text 必须是原文精确子串，summary_cn 才是总结 | | "不需要运行 pipeline.py" | 原始提取缺少 location 和 confidence，必须后处理 | | "手动写 location 字段" | location 由 Source Grounding 算法填充 | | "把所有技能合成一条记录" | 每个技能必须单独提取为一条 skill 记录 | | "薪资保留原始文本格式" | salary_min/max 必须转为数值 (元) | | "直接存数据库跳过 pipeline" | 必须先 pipeline 后处理再导入 |

Anti-Rationalization

| 借口 | 反驳 | 正确做法 | |------|------|----------| | "简历很短不需要后处理" | 短简历也需要 Source Grounding 定位 | 运行 pipeline | | "只有 3 个技能不需要去重" | 去重是自动的，不增加成本 | 运行 pipeline | | "用户只要候选人信息" | 先提取全部 7 类，用户可按需过滤 | 完整提取 | | "PDF 解析太麻烦直接截图" | parse.py 支持单栏/双栏自动检测 | 使用 parse.py | | "不需要 JD 匹配" | match.py 是可选步骤，但先确认用户需求 | 询问用户 | | "pipeline.py 报错了就跳过" | 修复错误而非跳过后处理 | 调试 pipeline |

Common Mistakes

| 错误 | 症状 | 预防 | |------|------|------| | text 字段改写原文 | Source Grounding 全部 match_type=none | 确保 text 是原文子串 | | 忘记指定 source_file | pipeline 无法分组去重 | 每个提取项必须有 source_file | | experience 的 projects 不是数组 | import_resume.py 导入失败 | projects 必须是对象数组 | | 薪资未数值化 | match.py 匹配分异常 | 25K -> salary_min: 25000 | | 技能合并为一条 | query.py 技能统计不准 | 每个技能独立提取 | | 未先解析 PDF/DOCX | 提取质量极差 | 先 parse.py 转 Markdown | | attributes 缺少必填字段 | confidence 评分偏低 | 按 extraction-types.md 的必填属性 |

详细参考

| 文件 | 内容 | 何时读取 | |------|------|---------| | references/extraction-types.md | 7种HR类型详细定义和识别规则 | 提取前必读 | | references/few-shot-templates.md | 中文简历的 Few-shot 示例 | 提取时参考 | | references/output-schema.md | 完整 JSON Schema | 验证输出时 | | references/post-processing.md | 后处理算法详细说明 | 调试管道时 |