resume-crafter

简历工坊（resume-crafter）

口述经历 → 可投递简历 → JD 定制 → 投递体检 → 面试准备

面向应届毕业生与职场人的开源简历 Skill 包。

一、解决什么问题

做简历难的不是排版，是在真实约束下把内容组织对：

真实痛点 · 本项目的做法 内容超出一页，但一个字都不能删（删掉真实经历等于伪造） · 排版密度自动分档：5 档松紧，按内容体量选最宽松且装得下的一档，容量表由实测定标 ATS 解析器读不懂花哨排版 · 纯文本优先：不图片化文字、不用图标字体、不用表格排版正文，字号守住 10pt 下限 模板好看但千篇一律，改配色要动一堆文件 · 四维正交外观：版式 × 底板 × 配色 × 密度，35 种组合任意搭配，派生色阶自动计算 深色底板上分区标题看不见、色块褪成灰色 · 主色分「色块用」与「文字用」两套，按 WCAG 对比度自动校准；派生色设可见下限 投出去不知道能不能过 · 内置 ATS 体检：解析成品 PDF，检查页数、文本层、分区顺序、可提取字符数 一份简历投所有岗位 · JD 匹配分析 + 批量定制：一份底稿，按多个 JD 各出一版 写完简历不知道面试会被问什么 · 自动生成求职信与面试准备清单（高频问题、经历追问点、自我介绍）

一句话：把「排版好看」和「能过机筛」这两件难事，从手工调参变成一条命令。

二、主要功能

1. 一键构建（最常用）

python scripts/build_all.py resume.json --out ./out --style elite --surface ink

一次产出 HTML + PDF + DOCX 三种格式，并自动完成内容质检与 ATS 体检。

2. 四维正交外观

版式(9) × 底板(5) × 配色(7) × 密度(5)

9 套版式（--style）

键名 · 名称 · ATS · 适用场景 classic · 经典单栏 · ✅ · 单栏自上而下，适配 90% 场景，投递大厂/外企首选 modern · 现代单栏 · ✅ · 左对齐页眉 + 圆角短色条，互联网/产品/运营岗 elite · 精英几何 · ✅ · 斜切几何色块 + 一寸照片位，视觉层次强 academic · 学术严谨 · ✅ · 细线分隔 + 居中对齐分栏，硕博/科研/读博申请 neon · 霓虹卡片 · ✅ · 顶部渐变色带 + 荧光照片 + 色块标签 geo · 几何圆角 · ✅ · 每个分区做成大圆角浅色卡片，留白充足 sidebar · 双栏侧边栏 · ⚠️ · 左侧面板放技能与联系方式，仅用于直接给人看的场景 creative · 创意顶栏 · ⚠️ · 顶部彩色带 + 右侧浅底面板 soft · 柔光双栏 · ⚠️ · 顶部圆角几何块 + 左右双卡片

⚠️ 标记「慎投网申」的双栏版式：部分 ATS 解析器会跨栏错读。线上投递请用单栏版。

5 种底板（--surface）

键名 · 名称 · 说明 white · 纯白 · 标准 A4 白纸，ATS 与打印最稳 ivory · 象牙白 · 一点暖调，适合打印与文档内嵌 mist · 雾霭灰 · 高调浅灰纸，深蓝主色，科技感 sage · 苔绿 · 低饱和绿灰纸，教育/公益/公益行业感 ink · 深墨 · 深色底板整套反色，适合作品集与设计岗；打印耗墨，部分 ATS 截图预览会失真

7 套配色（--palette）：indigo 靛蓝 / teal 青碧 / clay 赭红 / plum 紫罗兰 / amber 琥珀 / graphite 石墨 / crimson 绛红

5 档密度（--density）：airy / normal / compact / dense / tight，省略则按内容体量自动选择。

3. 内容质检（lint_resume.py）

检查项全部基于中文简历的真实写法：

• 姓名与联系方式是否完整（区分「必须修复」/「建议修改」/「优化建议」三级）
• 分区名是否用 ATS 标准词、分区顺序是否合理（有实习/项目时实践优先）
• bullet 是否缺量化结果（识别中文量词：份/页/张/个/条…；年份与日期不算业绩数字）
• 弱化动词（完成、熟悉、负责…）与篇幅是否超标
• 装饰性字符、AI 腔表达

4. ATS 体检（ats_check.py）

解析成品 PDF，输出：页数、文本层是否正常、可提取字符数、识别到的分区顺序、跨栏风险、单页建议。

5. JD 匹配（jd_match.py）

输出关键词覆盖率、已命中项、简历缺失项（需用户确认是否真实具备）、按优先级的定制修改建议。

工具只做「分析与建议」，不会替你编造经历。所有建议都附带「若你实际掌握 X 则补上，若无真实经验则不要写」。

6. 批量定制（tailor_batch.py）

一份底稿 + 多个 JD，一次生成多套定制版，每套附匹配报告与汇总 JSON。

7. 求职信与面试准备（cover_letter.py）

生成求职信 + 「投递前自查」清单 + 面试准备清单（岗位业务相关问题、经历追问点、自我介绍）。

8. 单页适配（fit_one_page.py）

自动试 6 档排版参数，命中第一个「单页且排版正常」的档位。

9. 一寸证件照

basic.photo 支持本地路径 / data URI / 远程 URL，自动转成 base64 内嵌（保证 HTML 单独分享或转 PDF 时图片不丢）。支持 1in / small1in / 2in / square / boss 五种规格与 rect / rounded / circle 三种形状。没有照片时输出轻量占位框，不生成示例图。

三、安装方法

环境要求

• Python 3.10+
• 一个 Chromium 内核浏览器（用于 HTML → PDF）：Windows 用 Edge，macOS 用 Chrome，Linux 用 Chromium
• 脚本会自动探测 Edge / Chrome / Brave / Chromium 的常见安装路径，并回退到 PATH 查找

安装步骤

# 1. 克隆或解压本项目
cd resume-crafter

# 2. 安装依赖（推荐用虚拟环境）
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. 自检：验证文件完整性、依赖、浏览器、主题体系一致性
python scripts/doctor.py

requirements.txt：

python-docx>=1.1.0     # 生成 DOCX
pypdf>=4.0.0           # ATS 体检时解析 PDF
pillow>=10.0.0         # 可选：仅生成示例证件照时需要

doctor.py 会检查：脚本与模板是否齐全、依赖是否安装、浏览器内核是否找到、示例数据能否解析、主题体系一致性（派生变量是否声明在 body 层、风格 CSS 是否只写基值、密度档是否只写系数、Python 与 CSS 的密度档数是否一致、35 种底板×配色的主色对比度是否达标）。

关于安装位置：本项目是一个 Agent Skill 包，可直接放到以下任一位置：

~/.workbuddy/skills/resume-crafter/        # WorkBuddy 全局
<项目>/.workbuddy/skills/resume-crafter/    # 项目级

DeepSeek Harness 一键安装

本仓库同时是一个标准的 DSH 组合包（bundle），声明了 dsh.bundle，可直接用 dsh plugin 安装：

dsh plugin --profile web add github:lhmlhmlhm11/resume-crafter

安装后重启 dsh web，组合包会注册一个 FileSystemSkillProvider，把 resume-crafter 技能加入技能发现列表（与你已有的项目级/用户级技能并存，不会覆盖）。在对话里即可调用；也可用 /resume-crafter 直达。

安装要求：dsh >= 0.1.0-rc.6。包内不含 @deepseek-ai/* 依赖，官方包由 profile 启动闭包注入。

四、使用方法

完整流程

# ① 写好简历 JSON（结构见第五节）
# ② 一键出三份文件 + 自动质检
python scripts/build_all.py resume.json --out ./out --style elite --surface ink

# ③ 对着目标岗位做匹配分析
python scripts/jd_match.py resume.json jd.txt --out ./jd报告.json

# ④ 生成求职信与面试准备
python scripts/cover_letter.py resume.json jd.txt --out ./求职信.md --interview

# ⑤ 投之前体检成品 PDF
python scripts/ats_check.py ./out/张三.pdf

常用命令速查

命令 · 作用 build_all.py resume.json --out DIR · 主力命令：质检 → HTML → PDF → DOCX → ATS 体检 render_resume.py data.json --out x.html · 只出 HTML；--list-styles / --list-themes 查看全部选项 lint_resume.py resume.json --style elite · 只做内容质检（--json 输出结构化结果） ats_check.py x.pdf · 只做 ATS 体检 jd_match.py resume.json jd.txt --out r.json · JD 匹配分析 cover_letter.py resume.json jd.txt --out letter.md --interview · 求职信 + 面试准备 tailor_batch.py resume.json --jd a.txt b.txt --out DIR · 一份底稿批量定制多岗位 fit_one_page.py resume.json --out-dir DIR · 自动适配到单页 doctor.py · 环境与文件自检 selftest.py · 端到端回归测试（67 项断言）

外观参数怎么选

# 不知道选什么 → 先看全部选项
python scripts/render_resume.py --list-styles
python scripts/render_resume.py --list-themes

# 大厂投递：单栏 + 白底 + 靛蓝，最稳
python scripts/build_all.py resume.json --out ./out \
  --style classic --surface white --palette indigo

# 作品集/设计岗：几何版式 + 深墨底板
python scripts/build_all.py resume.json --out ./out \
  --style geo --surface ink --palette plum

# 内容很多，强制用紧凑档（一般不需要，密度会自动选）
python scripts/build_all.py resume.json --out ./out --density compact

参数优先级：

命令行参数  >  JSON 的 meta  >  版式默认值

一条数据可以复用多套外观 —— 只要显式指定了 --surface / --palette，JSON 里遗留的 meta.accent 就不再覆盖它。

两种使用姿态

A. 直接跑脚本 —— 适合批量生成、精细控制（上面所有命令）。

B. 交给 Agent —— 把 skill 装到 ~/.workbuddy/skills/ 后，用自然语言驱动：

「读一下我的简历 JSON，帮我用精英几何版式 + 深墨底板出一份 PDF，职位是字节跳动用户运营实习生」

Agent 会自动读取 SKILL.md（技能说明书）、references/data-schema.md（数据格式）、references/design-system.md（设计体系）、references/writing-guide.md（写作规范），按流程执行。

五、输入输出示例

输入：简历 JSON

唯一事实来源 —— HTML / PDF / DOCX 三种产物都由它渲染，改 JSON 再重建即可同步更新全部格式。

{
  "meta": {
    "style": "elite",
    "surface": "ink",
    "palette": "indigo"
  },
  "basic": {
    "name": "张三",
    "title": "电子商务专业 · 2027 届本科",
    "photo": "sample-photo.png",
    "photo_size": "1in",
    "photo_shape": "rect",
    "contact": [
      { "type": "phone", "text": "138-0000-0000" },
      { "type": "email", "text": "zhangsan@example.com" },
      { "type": "location", "text": "江苏 · 苏州" },
      { "type": "link", "text": "github.com/zhangsan" }
    ]
  },
  "summary": "电子商务专业在读，具备 2 段电商运营实习经历，熟悉从选品、店铺搭建到活动策划、数据复盘的完整链路，能独立完成单店日常运营并输出周度数据报告。",
  "sections": [
    {
      "id": "experience",
      "title": "实习经历",
      "type": "experience",
      "items": [
        {
          "org": "苏州某某电子商务有限公司",
          "role": "电商运营实习生",
          "location": "苏州",
          "start": "2025.07",
          "end": "2025.09",
          "bullets": [
            "接管天猫店铺日常运营，通过重排选品结构与详情页 A/B 测试，将单品转化率由 1.8% 提升至 2.6%",
            "策划 3 场平台大促活动，累计带来 GMV 约 42 万元，超额完成月度目标 23%"
          ]
        }
      ]
    },
    {
      "id": "skills",
      "title": "专业技能",
      "type": "skills",
      "groups": [
        { "label": "数据与工具", "items": ["Excel（数据透视表、函数建模）", "SQL 基础"] },
        { "label": "运营能力", "items": ["选品与市场分析", "活动策划与文案"] }
      ]
    },
    {
      "id": "awards",
      "title": "荣誉奖项",
      "type": "list",
      "items": [
        { "text": "全国大学生电子商务三创赛校赛一等奖（2025）" }
      ]
    }
  ]
}

分区类型：experience / project / education（条目型）、skills（分组型）、list（列表型）、text（纯文本型）。 完整字段说明见 _staging/resume-crafter/references/data-schema.md。

输出

build_all.py 的产物

python scripts/build_all.py resume.json --out ./out \
  --style elite --surface ink --name "张三-电商运营实习生"

out/
├── 张三-电商运营实习生.html    (25 KB)   # 内嵌 CSS，头像已转 base64，可单独分享
├── 张三-电商运营实习生.pdf     (476 KB)  # 文本型，ATS 可解析
└── 张三-电商运营实习生.docx    (41 KB)   # 可在 Word 里继续编辑

文件名默认取 JSON 里的 basic.name，用 --name 可覆盖。

控制台输出：

==================================================================
简历构建 — 张三-电商运营实习生
==================================================================
排版风格：elite（精英几何（几何色块））
纸面底板：ink　主色配色：indigo　密度：自动
头像位：已启用一寸照片位

[1/4] 内容质检：0 个必须修复 / 0 处建议 / 1 条优化建议
[2/4] HTML 已生成：张三-电商运营实习生.html
[3/4] PDF 已生成：张三-电商运营实习生.pdf
[4/4] DOCX 已生成：张三-电商运营实习生.docx

[ATS 体检] 1 页 — 阻断 0 / 风险 0

注意：ATS 体检结果打印在控制台，不单独落盘为文件。需要留存报告请自行重定向输出，或单独跑 ats_check.py。

jd_match.py 的产物（JSON）