resume-builder

简历构建器 (Resume Builder)

通过对话为用户创建视觉精美、排版专业的 HTML/PDF 简历，支持视觉 A4 单页和 ATS-safe 两种输出模式。

核心理念

• 输出：独立 HTML 文件，内嵌 CSS，A4 尺寸（210mm × 297mm），浏览器打印 PDF
• 设计：大胆有辨识度，拒绝通用 AI 审美（详见 references/design-guidelines.md）
• 生成前先选择输出模式：视觉 HTML/PDF 或 ATS-safe HTML/PDF；两种模式共享同一事实数据。

先决规则

开始收集、写作或生成前，必须先完整读取并遵循 references/resume-contract.md 和 references/content-writing.md。这两份共享参考文档优先于本入口中的示例、版式偏好和流程提示；证据不足时保留事实边界，不为填满版面或迎合格式补写内容。

首次执行渲染或命令行校验前，读取 渲染环境与命令路径，定位完整运行时并检查依赖。命令示例中的 skills/... 从实际运行时根目录解析，不能假设它位于用户当前的简历目录。

入口与协作

这是创建和更新母版的主入口。若用户提供已有简历，先提取为待确认 claim，展示已识别内容、模糊项和疑似过期项；用户确认后只做增量追问，优先询问最近变化、缺失证据和低置信度字段。不要将解析文本直接当作最终事实，也不要重新进行完整采访。

若用户没有已有简历，按下面的信息收集流程采访。将用户确认的 claim 保存到项目目录外的私有 resume-facts.yaml，其结构使用 references/resume-facts.example.yaml；它是后续母版和 JD 定制的事实源。事实确认完成后，才选择输出模式与六个视觉模板。

技能协作流转：

• 经历打磨：采访中若发现某条经历职责化、缺少具体贡献或证据不足，直接依据 references/content-writing.md 就地引导用户提供行动与交付物证据，就地改写为强动词结构，不打断采访主流程；
• 质量审计：母版交付前，通过 validate_resume.py（视觉单页与密度）或 --mode ats（ATS 格式）执行自动化质量审计；
• 排版微调：视觉母版生成并完成 PDF 验证后，若用户需要交互式微调，路由至 resume-canvas；
• 岗位定制：母版定稿后若需投递具体岗位，路由至 jd-tailorer（一站式完成 JD 结构化分析、匹配评估与定向定制）；
• 版本追踪：母版定稿后，建议用户在本地私有 Git 仓库提交初始母版（如 git commit -m "创建母版简历"），保护事实源。

工作流程

第一步：信息收集

仅在从零采访或已有简历存在缺口时逐个板块提问，不要一次抛出所有问题。按 resume-contract.md 建立每条 claim 的 section、source、confidence、evidence、metric_status 记录，并在用户确认后更新私有 resume-facts.yaml，再按 content-writing.md 写作。

收集顺序：基础信息 → 教育背景 → 实习/工作经历 → 项目经验 → 技能 → 校园经历 → 自我评价

• 优先追问可核验的指标、范围、时间、质量、角色和交付物；没有可信数字时，使用已确认的非数字证据。
• 技能数量、自我评价长度/句数和经历结构服从事实、岗位相关性与版面，不设机械数量或字数门槛。
• 应届生可根据岗位相关性前置项目或校园经历，不把固定排序当成事实规则。
• 待确认字段只能保留在采集记录或分析报告中，不能进入最终简历 HTML/PDF。

第二步：风格确认

先让用户选择视觉 HTML/PDF 或 ATS-safe HTML/PDF 模式，再选择或描述视觉风格。视觉模式读取对应 CSS 和 HTML 参照文件；ATS-safe 模式使用单栏、标准标题和可复制文本结构：

风格	CSS	HTML 参照
现代简约	css/modern-minimal.md	examples/modern-minimal.html
经典商务	css/classic-business.md	examples/classic-business.html
创意个性	css/creative-bold.md	examples/creative-bold.html
日式极简	css/japanese-minimal.md	examples/japanese-minimal.html
科技感	css/tech-dark.md	examples/tech-dark.html
简约蓝色商务	css/minimal-blue-business.md	examples/minimal-blue-business.html

CSS 文件包含 3 套配色变量 + 推荐字体 + 风格 CSS。css/common.md 为通用排版（每次必用）。

第三步：HTML の生成

第 2 步で選択したモードを使い、css/common.md のレイアウト＋対応するスタイル CSS／レイアウト＋契約ゲートを通過したユーザー情報を統合して、独立した HTML を生成します。ビジュアルモードでは <姓名>_<岗位>_visual.html、ATS セーフモードでは <姓名>_<岗位>_ats.html を使用し、対応する PDF には同じプレフィックスと .pdf 拡張子を使用します。

ビジュアルモード：

• A4 サイズ、ページ余白、フォントサイズ、間隔、行高などのレイアウトパラメーターは css/common.md を参照します（唯一の定義元）。ルートの <html> には必ず data-resume-layout="full-page" を指定し、--resume-density、--resume-density-min、--resume-density-max: 1.2、--resume-fill-target: 0.98、--resume-bottom-margin: 9mm の各変数を維持します。下部の総余白は 9mm とし、追加の安全余白を重ねません。上／左右の余白はテンプレートの元の値を維持します。
• ページ本文は css/common.md の full-page 契約に従い、伸縮可能な flex/grid レイアウトを使用する必要があります。コンテンツが少ない場合は、まず密度の上限内でフォントサイズ、行高、項目／セクション間隔を拡大し、次に space-between で残りの空間を配分します。コンテンツが多い場合は、レンダリングスクリプトが安全な密度の下限を上回る範囲で自動圧縮します。空白を埋めるために架空の内容を追加したり、overflow: hidden で黙って切り取ったりしてはいけません。
• 色は CSS 変数で一元管理し、システムフォントスタック（PingFang SC, Microsoft YaHei）を使用します。
• 単一ファイルとして納品する場合、プロフィール画像などのローカル画像は data URL として埋め込みます。外部のウェブフォントを残す場合は、システムフォントのフォールバックも必ず用意し、オフラインでのレンダリング結果が異なる可能性があることを検証時に説明します。
• スキルタグは <span class="skill-badge"> を使って並べ、badge のスタイルはスタイル CSS で定義します（ATS に配慮）。
• 履歴書テンプレートにエクスポートボタンを埋め込まないでください。PDF はブラウザー印刷またはローカル Canvas の「PDF として印刷」操作でエクスポートし、履歴書の内容が隠れないようにします。
• 組み込みスタイルを使用する場合、生成する <html> には対応する data-resume-editor-template（modern-minimal、classic-business、creative-bold、japanese-minimal、minimal-blue-business、tech-dark のいずれか）と data-resume-editor-version="1" を含める必要があります。Canvas での微調整が必要な実際のテキストには、それぞれ安定した一意の意味のある data-resume-editor-id を付与します。実行時の補完に依存しないでください。
• data-resume-editor-id は、氏名、職位、日付、セクション見出し、個別の箇条書き、単独のスキルタグなど、具体的なテキストフィールドにのみ付与できます。「プロトコルチェックを通す」ために、ページ全体やコンテンツ全体を含むコンテナーに代替 ID を付与しないでください。
• 編集 ID を付与してはいけない要素： <html>、<body>、<main>、.page、.resume、header、footer、section、ul、ol、figure、または複数のセクション／複数のフィールドを含むコンテナー。リンク付きの連絡先情報は、編集可能なテキストを個別のフィールドに分割し、連絡先の行全体を編集可能なコンテナーにしないでください。
• 上記のマーカーは、npx -p @chasen-liao/resume-skills@latest resume-skills editor <resume.html> のローカル Canvas 微調整ツールが認識するためのものです。Canvas では既存フィールドのプレーンテキストを編集し、制限付きのレイアウト上書きを保存できますが、HTML の挿入やフィールドの追加はできません。テキスト上の事実を変更した後は、事実を再確認し、PDF を検証する必要があります。プロフィール画像、レイアウトコンテナー、任意の HTML、または未確認のフィールドにマーカーを使用しないでください。

ATS セーフモード：

• 1 列レイアウト、標準的なセクション見出し、通常のコピー可能なテキスト、安定した本文の読み取り順序を使用します。重要な情報を画像、テキストボックス、複雑な入れ子の表、ヘッダー／フッター、装飾フォントに依存させないでください。
• スキルはコピー可能なテキストのリストで表します。ATS セーフモードを理由に、claim の内容や証拠の状態を変更したり、確認待ちマーカー以外の事実を削除したりしてはいけません。
• 同様に、HTML とブラウザー印刷 PDF のみを生成します。リポジトリには現在 DOCX の生成機能がないため、DOCX の成果物は保証しません。

第四步：モードに応じた検証（必須、スキップ不可）

最終ビジュアル HTML を生成した後、まず Canvas フィールドを受け入れ確認し、次に PDF をレンダリングします。

• まず実行可能な検証を実行します（失敗した場合は即時停止し、絶対にスキップしないでください）：npx -p @chasen-liao/resume-skills@latest resume-skills validate "<最终_visual.html路径>"。出力が「検証に合格」になるまで繰り返します。
• 次に、以下のルールに従って手動で再確認します。最終 HTML（事実の置換とカスタマイズを完了したもの。参照テンプレートだけを確認するのではありません）内の data-resume-editor-id を集計し、フィールドの総数、重複 ID、コンテナーへの誤付与 ID、profile-* と *-bullet-* フィールドの有無を記録します。
• フィールド総数は 0 より大きく、ID は一意で、小文字の意味のある命名規則に従っていなければなりません。main/page/resume/section など、ページ全体やセクションのコンテナーに ID を付与してはいけません。
• 各 ID ノードのテキストは、個別に編集可能なフィールドに対応していなければなりません。1 つのノードに複数のセクション、リスト、または大量のリンクテキストが含まれる場合は、マーカーを分割する必要があります。
• いずれかの確認に失敗した場合、Canvas の起動、PDF のレンダリング、納品を行ってはいけません。HTML を修正または再生成し、最初から再検証してください。フィールドマーカーの代わりにルートコンテナー ID を使うことは禁止です。

ビジュアル HTML/PDF：PDF をエクスポートした後、構造、PDF のページ数と抽出可能なテキスト、ページ密度、印刷可能領域を併せて確認します。

powershell -NoProfile -ExecutionPolicy Bypass -File skills/resume-builder/scripts/render_resume.ps1 -HTML "<生成的_visual.html路径>" -OutputPdf "<生成的_visual.pdf路径>"

--check-layout の合格基準：

• PDF page count は 1 page でなければなりません。2 ページ以上の場合は即時失敗とし、切り取りやオーバーフローの非表示で 1 ページに見せかけてはいけません。
• page fill は、PDF から抽出可能なテキストの縦方向の範囲をもとに、有効ページ領域の占有率を推定します。目標は少なくとも 98% です。デフォルトでは目標未満の場合は即時失敗とし、レイアウト密度／間隔の問題を明示します。空白を埋めるために事実を捏造してはいけません。
• vertical balance は、印刷可能領域の上下の余白の差を確認します。20mm を超える場合は即時失敗とし、コンテンツが上部または下部に偏らないよう、まずセクション間隔、項目間隔、コンテナーの内側余白を均等に調整します。
• vertical gaps は、PDF 内のテキスト行間にある最大の連続した空隙を確認します。有効高さの 25% を超える場合は即時失敗とし、本文が空いているのに下部に孤立したテキストがある状態を防ぎます。同時に --html を指定すると、--check-layout はブラウザー検査も実行し、ページおよび組み込みの 2 列レイアウトについて、下部の余白と内部の空隙をそれぞれ測定します。これらの測定は、以下のページ全体のスクリーンショット確認の代わりにはなりません。
• bottom safety は失敗してはいけません。デフォルトの下部総余白は 9mm です。PDF の検証では HTML で実測した padding を使用し（テキスト境界の推定誤差の許容値は 0.25mm）、実際の下部距離を報告します。有効領域の占有率が 100% でも、物理的な下部余白がないことを意味するわけではありません。カスタム余白を設定する場合は HTML を変更して再レンダリングし、その内容を manifest に記録する必要があります。検証パラメーターだけを調整してはいけません。

レイアウト調整の順序：まず既存の確認済みセクションとコンテンツを使用します。コンテンツが少ない場合は、まず --resume-density-max の範囲内で変数が制御するフォントサイズ、行高、間隔を拡大し、次に残りの空間を均等に配分します。コンテンツが多い場合は、レンダリングスクリプトが --resume-density-min を上回る範囲で自動圧縮します。それでもはみ出す場合は、「ページ余白を 8mm 以上に保つ → 間隔 → 行高を 1.25 以上に保つ → 本文を 9.5px 以上に保つ → 関連性の低い内容を簡潔にする → 適切な場合は 2 列に切り替える」の順で対応します。上下の間隔はできるだけ近づけます。調整するたびに PDF を再エクスポートし、同じコマンドを実行してください。未確認の経歴、数値、スキル、プレースホルダーテキストを追加してはいけません。また、読みづらい小さなフォントで無理に 1 ページに収めてはいけません。

レンダリングスクリプトは PDF のエクスポート前に full-page の自動レイアウトを実行します。コンテンツが少ない場合は上限内で拡張し、コンテンツが多い場合は --resume-density を下限内で圧縮します。同じプレフィックスの低解像度 *.preview.png も同時に生成します。その後、ブラウザーでのオーバーフロー検証と PDF レイアウト検証を実行し、HTML/PDF/プレビューの SHA-256、renderer のバージョン、有効余白／実際の下部距離／密度、検証結果を含む、同じプレフィックスの *.resume-manifest.json を生成します。degraded、fail、またはハッシュの不一致がある場合は納品できません。自動チェックの完了後、AI は以下のページ全体のスクリーンショットによる視覚確認を行い、目に見える切り取り、画像の欠損、写真、フォントのフォールバック、印刷背景も確認して、リンクを照合する必要があります。自動チェックでは、こうした視覚的な細部を保証できません。ビジュアルモードでは、A4 の 1 ページと有効領域占有率 98% 以上を必須目標とし、すべての警告について対応結果を記録します。

整页截图视觉复核（视觉模式强制执行）

• AI 必须使用图像查看工具打开本次最终渲染生成的 *.preview.png，实际查看完整 A4 页面（包含顶部和底部）；若预览不完整或不清晰，补截同一最终 HTML 在打印样式下的完整 A4 页面，或将最终 PDF 页面渲染为图片后查看。不能只生成截图、检查图片文件存在，或只看局部截图就声称已完成复核。
• 重点检查正文结束到页面底部的留白是否过大、上下留白是否协调，以及板块之间是否存在突兀的大块空隙。双栏必须分别检查每一栏，不能因为另一栏或底部的一行文字触底就判定整页均匀。保留必要打印安全边距，允许留白，但应分布均匀，不能让正文集中在顶部而底部明显空缺。
• 即使 CI、page fill、溢出检查和 manifest 全部通过，只要截图中有明显底部空缺、单栏偏空或留白失衡，仍视为视觉验收未通过，不能直接交付。先在排版约束内调整字号、行高、条目/板块间距和页边距；双栏仍失衡时可在生成阶段调整布局或切换单栏，不得编造内容填白或用底部孤立文字伪装占用率。
• 每次修改后重新渲染 PDF、执行自动校验，并打开新截图复核，直到留白均匀且无溢出、裁切。交付时简述截图路径及底部留白、上下平衡、各栏分布的复核结论。若无法查看截图，明确标记视觉复核未完成，不得声称已通过视觉验收。

ATS-safe HTML/PDF：检查 DOM 是否单栏、标题和时间/组织/职位关系是否清晰、正文复制后顺序是否正确，以及 PDF 文本是否可提取；再检查无图片文字、复杂嵌套表格、关键页眉页脚信息和不可复制装饰字体。按目标平台要求检查 HTML/PDF 格式，不宣称 ATS 必然通过。

第五步：交付

视觉模式完成 A4/PDF 验证后，先询问用户是否需要打开本地 Canvas 预览。Canvas 是视觉版的可选微调工具，不是 Skills、HTML 或 PDF 交付的前置条件：用户选择需要时才执行下面的命令；用户暂时不需要时直接交付已验证的 HTML/PDF，并说明之后可按需启用。

npx -p @chasen-liao/resume-skills@latest resume-skills editor "<生成的_visual.html路径>"

用户选择 Canvas 后，命令会在本机启动服务并打开浏览器。告知用户原始 HTML 和 PDF 的位置；Canvas 保存时会直接覆盖该 HTML，并将关联 PDF manifest 标为失效。保存后必须重新运行渲染脚本，只有新 manifest 的 hash 和验证结果有效才可交付。Canvas 只允许编辑已有字段的纯文本和受限排版，不能插入 HTML、做 JD 匹配或调整结构。如用户选择 Canvas 但当前环境无法执行 npx，明确报告未启动，并提供带实际 HTML 路径的完整命令，不得声称已启动。

若用户需要深入排版微调（字号/间距/颜色/页边距）、利用 Live Preview 热重载协同或需要高级 CLI 自动化（--json / --no-open / --port），路由至 resume-canvas 技能。

ATS-safe 模式不使用 Canvas（其单栏 HTML 不属于 Canvas 支持的视觉模板）；告知文件位置与浏览器打印 PDF 方法。两种模式都可在后续使用 jd-tailorer 针对 JD 定制。

参考文档索引

references/ 目录下按需读取：

• design-guidelines.md — 设计美学、字体排版、单页参数细节
• resume-contract.md — 事实来源、证据、置信度、指标状态和输出门槛
• resume-facts.example.yaml — 私有 resume-facts.yaml 的最小结构
• color-palettes.md — 六大风格-配色索引
• content-writing.md — 证据优先写作、ATS 两种输出模式、自检清单
• css/README.md — CSS 使用方式与配色选择策略
• css/common.md — 通用紧凑排版 CSS（每次必用）
• css/<style>.md + examples/<style>.html — 每个风格一对参照文件