简历工坊 lhmlhmlhm11/resume-crafter

简历工坊（resume-crafter）

口述经历 → 可投递简历 → JD 定制 → 投递体检 → 面试准备面向应届毕业生与职场人的开源简历技能包。

一、解决什么问题

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

| 真实痛点 | 本项目的做法 |
| 内容超出一页，但一个字都不能删（删掉真实经历等于伪造） | 排版密度自动分档：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. 交给智能体 —— 把技能装到 ~/.workbuddy/skills/ 后，用自然语言驱动：

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

智能体会自动读取 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）

{
"coverage": 42.3,
"tool_coverage": null,
"matched": {
"tools": ["Excel", "SQL", "天猫", "竞品", "详情页", "活动策划", "电商运营"],
"certs": [],
"keywords": ["数据复盘", "数据看板", "活动策划", "电商运营", "实习生", "详情页", "流量"]
},
"missing": { "tools": [...], "certs": [], "keywords": [...] },
"requirements": { "edu": [], "years": [], "must_have": [], "nice_to_have": [], "responsibilities": [] },
"priority_actions": [ "..." ],
"warnings": []
}

cover_letter.py 的产物（Markdown）

求职信 — 电商运营实习生

应聘岗位： 电商运营实习生姓名： 张三联系方式： 138-0000-0000 / zhangsan@example.com / 江苏 · 苏州

尊敬的招聘者：

我是张三，电子商务专业 · 2027 届本科。我在××公司发布的电商运营实习生岗位中了解到…

投递前自查

- [ ] 公司名称、岗位名称已替换为准确信息
- [ ] 简历中所有「待填 / 」等占位符已替换为真实信息
- [ ] 引用的成果数据与简历一致

面试准备 — 电商运营实习生

一、基于 JD 的定向问题岗位业务相关
- 你在「数据复盘」方面的经验具体是什么？举一个你独立完成或主导的例子。
经历追问点
- 你的实习经历较少时，面试官会问：这段实习中你个人独立负责的是什么？

tailor_batch.py 的产物

batch/
├── 张三-电商运营实习生.html ├── 张三-电商运营实习生.pdf ├── 张三-电商运营实习生.docx ├── 张三-电商运营实习生-匹配报告.txt ├── 张三-用户运营实习生.html ├── 张三-用户运营实习生.pdf ├── 张三-用户运营实习生.docx ├── 张三-用户运营实习生-匹配报告.txt └── 批量结果.json

六、目录结构

本仓库（工作区）

skill制作/ ├── README.md # 本文件 ├── LICENSE # MIT 许可证 ├── .gitignore # 排除私有记忆 / 第三方素材 / 开发期脚手架 / 实战案例 ├── 发布前安全扫描报告.md # 开源前的隐私与密钥自检结论 ├── resume-crafter.zip # Skill 分发包（45 个文件，可直接安装） ├── 字节跳动-运营岗-JD.txt # 公开招聘 JD（用于演示 JD 匹配） └── _staging/resume-crafter/ # Skill 可编辑源码（与 zip 逐字节一致）

说明：_staging/resume-crafter/ 是 Skill 的可编辑源码，与 resume-crafter.zip 内容逐字节一致（打包时自动校验）。.workbuddy/（个人私有记忆）、_ref_crops/ 与根目录参考图（第三方付费模板素材）、_test/（开发期回归脚本与校准输出）以及实战案例目录 字节跳动-运营岗-简历/、简历工坊-演示/ 均已通过 .gitignore 排除，不随仓库公开。

实战案例含作者本人的真实经历细节（获奖、店铺经营数据、调研规模等），保留在本地供自己使用；公开仓库只分发 Skill 本体。

Skill 包内部（resume-crafter/）

resume-crafter/
├── SKILL.md # Agent 技能说明书 ├── README.md # 分发包内的说明文档 ├── CONTRIBUTING.md # 贡献指南（含分层警告） ├── requirements.txt ├── agents/ │ └── openai.yaml # Codex 展示元数据与调用策略 ├── assets/ │ ├── sample-resume.json # 示例数据（可直接跑） │ ├── sample-jd.txt # 示例 JD │ ├── sample-photo.png # 示例证件照 │ └── templates/ # 10 个 CSS：base.css + 9 套版式 ├── references/ │ ├── data-schema.md # JSON 数据格式 │ ├── design-system.md # 颜色与排版体系 │ └── writing-guide.md # 简历写作规范 ├── scripts/ │ ├── build_all.py # 一键构建（主力） │ ├── render_resume.py # HTML 渲染 │ ├── html_to_pdf.py # PDF 转换 │ ├── json_to_docx.py # DOCX 转换 │ ├── lint_resume.py # 内容质检 │ ├── ats_check.py # ATS 体检 │ ├── jd_match.py # JD 匹配 │ ├── cover_letter.py # 求职信与面试准备 │ ├── tailor_batch.py # 批量定制 │ ├── fit_one_page.py # 单页适配 │ ├── photo.py # 证件照处理 │ ├── theme.py # 主题引擎（底板 × 配色 × 密度） │ ├── doctor.py # 环境自检 │ ├── selftest.py # 端到端回归测试 │ └── ... └── .github/workflows/ci.yml # CI：selftest + doctor

七、设计要点（给二次开发者）

排版节奏：基值 × 系数

风格 CSS 只写基值，密度档只写系数，最终值在 body 上派生：

body.tpl-elite { --lh-base: 1.5; --gap-section-base: 4.4mm; }
body.dens-compact { --lh-scale: 0.93; --gap-section-scale: 0.68; }

body {
--lh: calc(var(--lh-base) var(--lh-scale));
}

⚠️ 两个必须遵守的约束：

1. 派生变量必须声明在 body 上，不能写在 :root —— CSS 自定义属性的 var() 在「声明它的元素」上求值，写在 :root 时 body 上的覆盖根本读不到。
2. 风格不得直接写死最终值（如 --lh）—— body.tpl-elite 与 body.dens-normal 特异性完全相同（0,1,1），写死了密度分档会静默失效。

doctor.py 与 selftest.py 都会检查这两点。

主题：三层解耦

底板(surface) × 配色(palette) → 派生色阶（自动计算）

派生算法是「主色按比例混入纸面色」，颜色全部在 Python 端算好后注入 CSS 变量，不使用 color-mix()（那需要 Chromium 111+，用户环境不可控）。

深色底板有两个额外处理：

- 主色分「色块用」--accent（≥3:1）与「文字用」--accent-text（≥4.5:1）两套
- 派生色按「结构色 vs 底色」分档设对比度下限（黑纸上 sRGB 混合既更弱、又会吃掉色相）：

| 派生色 | 对比度下限 |
| --accent-line（结构线） | ≥ 1.60:1 |
| --chip-border（胶囊描边） | ≥ 1.40:1 |
| --accent-soft（装饰块） | ≥ 1.35:1 |
| --sec-h-bg（标题底带） | ≥ 1.15:1 |

内容真实性优先于版面

篇幅超限时优先合并同类条目、调排版参数，不删用户经历。
质检工具的量化识别要覆盖中文量词（份/页/张/个/条…），并先剥离日期再扫描数字 —— 否则「回收 312 份问卷」会被误报「缺少量化结果」，而「2028 年毕业」会被误判为已量化。

八、验证状态

| 项目 | 状态 |
| selftest.py | 67/67 通过（覆盖 9 套版式渲染、35 种底板×配色组合、密度分档生效性、对比度阈值、量化识别、参数生效链路） |
| doctor.py | exit 0（文件完整性、依赖、浏览器、主题体系一致性、对比度） |
| 官方 quick_validate.py | Skill is valid! |

九、许可

本项目采用 MIT 许可证，完整文本见 LICENSE。

MIT License

Copyright (c) 2026 resume-crafter contributors

MIT 允许你自由使用、复制、修改、合并、发布、分发、再许可与销售本项目，唯一要求是在所有副本或实质性部分中保留版权声明与许可声明。

本项目提供的是工具，用它生成的简历内容归使用者本人所有 ——请确保简历内容真实、且不含他人未授权的信息。