md-to-pdf-webfirst

name	md-to-pdf-webfirst
description	先设计一个 PDF-friendly web page，再把页面打印成 PDF，用于把 Markdown 文件、Markdown URL 或 report HTML 转成精致 PDF。用户要求把 .md/HTML 转成 PDF、想要更好看的 PDF、要求用 frontend-design 改善 PDF 输出、提到 "web first"、"PDF-friendly web"、"HTML then PDF"、要求 consulting/McKinsey-style PDF polish，或需要围绕 Markdown-to-PDF workflow 提供 proof/reporting 时，使用这个 skill。

Markdown to PDF，Web First

把 Markdown、Markdown URL 或 report HTML 转成有设计感、可读性好的 PDF。核心路线永远是：先把内容做成 PDF-friendly web page，再用 Chrome print to PDF；不要直接做 plain Markdown-to-PDF。

默认输出契约

默认生成 McKinsey-inspired publication report，而不是 generic booklet。所有输出，包括技术文档，都必须使用与最佳 business overview 示例一致的 executive-report visual family：dark editorial cover、red/navy/teal accents、section map、answer-first front matter、清晰 chapter、evidence/examples、source trace、metadata 和 preview evidence。

不要提供 plain/quick booklet fallback，也不要另设低精度 documentation aesthetic。用户说 quick PDF 时，只能让 publication report 更简洁，不能切换成 generic booklet。

操作契约

如果用户正在 review 这个 skill、添加规则、拆分文件或修正流程，只更新 skill files。不要 regenerate PDFs、运行 regression suites、调用 review subagents、运行 eval boards，或调用 imagegen，除非用户明确说要 rerun、regenerate、run regression 或 produce a new PDF。

当用户要求 CHINESE ONLY / 只用中文 时，本轮所有对话回复、交付说明和 commit message 都必须使用中文；文件名、路径、代码标识、命令参数等必要技术字面量可以保留原文。

Skill 更新和输出生成是两个独立阶段。正常使用时，用户应该只需要运行：

codex exec --yolo -p "<md_file_path> [$md-to-pdf-webfirst](/Users/liushiyuwin/.codex/skills/md-to-pdf-webfirst/SKILL.md)"

这个 skill 应该自行 route 和 generate，不要求单独的 evaluator/reviewer agents。

Mode Router

先判断用户此轮是在要哪一种工作，不要把这些模式混在一起：

Mode	触发信号	行动
Skill maintenance	review/update this skill、添加规则、修 workflow、拆分模块、优化 logic、解释为什么输出不好	只改 SKILL.md、routes/、publication-report/、anti-patterns.md 或必要的 reusable helper/template；不生成 PDF、不跑 eval、不调用 imagegen
Normal generation	转 PDF、生成 polished PDF、web first、HTML then PDF、给我 artifacts	先 route source 并抽取关键内容；在 Codex App publication runs 中必须按章节规划 image assets，并逐次生成 1 cover + 1 overview chapter + N content chapters，共调用 imagegen N+2 次，再把 asset paths 传给 helper，随后 Chrome print、metadata、preview、display review
Bad-output correction	用户指出已有 PDF/preview 有具体坏形状，或 helper 输出违反质量门槛	把问题抽象进 anti-pattern memory，并修 reusable route/template/generator；如果用户要求重跑，再重新生成并验证

当 skill-creator 与本 skill 同时出现时，以本节为边界：可以用 skill-creator 的改进思路来审查和编辑 skill files，但不要自动进入 benchmark/eval viewer loop，除非用户明确要求测试这个 skill。

何时使用

当用户提出以下任一需求时，使用这个 skill：

• 把 .md 文件、Markdown URL 或 report HTML 文件转换为 PDF。
• 让 PDF 更好看、更精致、更有设计感或更易读。
• 为 PDF 本身使用 frontend-design。
• 先生成 PDF-friendly web page，再转换为 PDF。
• 为转换过程生成 evidence、preview images、hashes、page counts，或 talk-html report。
• 要求 consulting、McKinsey-style、MGI-style、board report、publication-grade PDF polish。

最终 Workflow 概览

1. 获取 source，判断输入类型和 mode；详见 routes/input-source.md。
2. 按 publication / consulting 规则规划 PDF-friendly HTML 的结构、章节、关键数字和视觉资产需求；FMCG/RD/category/hub/store/SKU diagnosis 还必须按 role-based 单页模板规划，详见 routes/publication-consulting.md 和 publication-report/fmcg-diagnosis-page-system.md。
3. 在 Codex App publication runs 中，先按章节级 imagegen 规则生成本次专属资产：cover-image、overview-image、以及每个内容章节各一张 chapter-image；若有 N 个内容章节，必须调用 imagegen N+2 次，而不是一次性生成整套图。figure-image 默认复用同一张 overview figure plate。详见 routes/imagegen.md。
4. 把 source 和 generated asset paths 一起传给 reusable helper script，先输出 <slug>-manifest.json 作为页面规划预览；manifest 必须逐页包含 页码、章节、页面角色、使用内容、页面规划。如果 helper 无法满足本 skill 的输出契约，修 reusable detector/template/generator，而不是写 one-off converter；详见 routes/scripts.md。
5. helper 必须逐个 page 生成单页 HTML，再逐个 page HTML 用 Chrome print 成单页 PDF，最后用 pypdf 拼接为最终 <slug>.pdf；不得把整本 HTML 直接一次性 print 成 final PDF。随后生成 metadata、cover preview、contact sheet；最终逐页 display review，可用 reference script 辅助但不是 gate；详见 routes/html-pdf-verify.md 和 routes/scripts.md。
6. 如果用户报告 bad output，把 generalized case 写入 anti-pattern memory，并修 reusable route/template/generator；详见 routes/bad-case-learning.md。
7. 如果用户要求汇报，用 talk-html 聚焦 proof 和交付路径；详见 routes/talk-html-report.md。

路由表

场景	读取模块	关键要求
Local Markdown、Markdown URL、local HTML	routes/input-source.md	不改 source；HTML 必须语义提取，不能打印 raw DOM/CSS
Business diagnosis HTML 或 business overview Markdown	routes/input-source.md、routes/publication-consulting.md	自动 publication-report / consulting mode，即使用户没说 McKinsey
FMCG / RD / category / hub / store / SKU diagnosis	routes/publication-consulting.md、publication-report/fmcg-diagnosis-page-system.md、references/fmcg-diagnosis-single-pages/manifest.json	用 chapter + page-role 规划，不按 page index；正文采用左侧呼吸/事实栏 + 右侧证据区；章节 divider 是纯摄影图
普通技术文档、教程、API notes	routes/publication-consulting.md	仍然是 publication report；不得退化成 documentation booklet
McKinsey/MGI/research publication	publication-report/README.md 及其 Required References	使用已有 publication-report 模块作为深层规范
用户同时要求 frontend-design	frontend-design.md、routes/publication-consulting.md	做真实 frontend design pass，并用 PDF preview 验证
Codex App publication visuals / imagegen	routes/imagegen.md、publication-report/imagegen.md、publication-report/imagegen-full-page-plates.md	helper 之前强制章节级资产：1 个 cover、1 个 overview chapter、N 个 content chapter plates；调用 N+2 次；--figure-image 复用 overview；单个资产不反复刷图；规则更新阶段禁用 imagegen
HTML/PDF 生成和验证	routes/html-pdf-verify.md、routes/scripts.md	Chrome print、pypdf 验证、cover preview、display review；reference script 只产出 hints，不是 gate
Helper scripts	routes/scripts.md	helper 在 source route 和 required image assets 准备完成后运行；必须先写 manifest 预览，再逐页 HTML → 逐页 PDF → 拼接；发现契约缺口时修 reusable helper/template；不要 one-off converter
Bad-case learning	routes/bad-case-learning.md、anti-patterns.md	normal usage 不跑 eval board；把坏例抽象进规则和 generator

质量门槛

只有满足以下条件，输出才算成功：

• PDF 是从 designed HTML page 创建的，而不是 direct plain Markdown conversion。
• helper 必须先输出 <slug>-manifest.json，且 manifest 的每页对象包含 页码、章节、页面角色、使用内容、页面规划；manifest 是 PDF 构建前的页面规划预览，不是事后补写的装饰文件。
• 最终 PDF 必须由多个单页 PDF 拼接而成：每个 page role 先有独立单页 HTML，再独立 print 成单页 PDF，最后合并；不得直接把整本 HTML 一次性打印成 final PDF。
• 默认使用 publication-report structure，且没有 generic booklet fallback。
• Business reports 自动有 answer-first front matter、issue map / agenda、rebuilt figures 或 visual evidence。
• FMCG diagnosis reports 使用 role-based page system：cover、executive-answer、section-map、photo-only chapter dividers、benchmark、contribution、execution archetypes、coverage quality、SKU mix、actions、method/source trace；reference/template tags 使用 chapter + page-role，不要以 page index 作为模板主标签。
• 技术文档也有 section map、chapter rhythm、examples/evidence/checklist，而不是 dumped Markdown body。
• HTML input 没有 raw <!doctype html>、<style>、CSS selectors 或 DOM source 泄漏进 PDF。
• PDF 可以打开，有真实 page count，至少前几页 text extraction 可用。
• 存在真实 cover preview，且没有 Chrome default header/footer。
• 逐页 display review 后没有 orphaned headings、detached exhibit labels、short continuation fragments、mostly blank tail pages、tables/charts 越界、fixed folios overlap、contents page page-range 问题或不可读小字；display_review_reference.py 只提供 reference findings，不是 mandatory regression/eval gate。
• Generated image assets 若作为 cover、overview figure 或 chapter/interstitial 使用，必须是本次 run 专属且按 full-page plate 规则排版；不可用固定 repository image 冒充 final publication。
• 在 Codex App publication runs 中，若未先生成 1 cover + 1 overview chapter + N content chapter 的章节级 image assets，或未至少传入 --cover-image、--chapter-image、--overview-image 和 --figure-image 给当前 helper/template，输出只能标记为 degraded，不能称为 final publication quality；--figure-image 默认传同一张 overview figure plate。
• generated HTML、PDF、metadata、preview paths 被清晰汇报；除非用户要求 overwrite，否则保留早先 attempts。

示例 Prompt

把 https://example.com/file.md 转成 polished PDF。先设计 PDF-friendly web page，再 print to PDF，并给我一个 talk-html report。