book

book · 从零生成一本带设计感的 PDF 书

把一个主题，经「调研→定目录→逐章并行写→配插画→精排→核查统稿」做成一本封面/目录/插画/排版俱全、可直接 PDF 出片的书。底层是 typst 排版 + 分阶段（phase）的子任务编排。

环境约定：本 skill 与具体编码工具无关。下文用 $SKILL 指代本 skill 根目录、用 $PROJECT 指代用户的成书工作目录（脚本路径写 $SKILL/scripts/xxx.py，产物写 $PROJECT/assets/...）。各阶段若你所在环境支持并行子代理（如某些 CLI 的子代理/工作流机制），就把可并行的工作 fan out 并行完成；否则顺序逐个完成即可。外部依赖统一申明为命令行工具/能力：codex（或任意可用的图像生成 CLI/能力，用于生图）、typst（排版编译）、mmdc（Mermaid 渲染）。

什么时候用 / 不用

• •用：成体系的多章节长篇（教材、手册、指南、读本），要统一设计、要出 PDF。
• •不用：单篇文章、PPT、海报、网页、单图。

工作方式（先读这两份）

1. `$SKILL/references/pipeline.md` —— 6 阶段流水线（调研→TOC→逐章写→插画→拼装编译→核查统稿）与分阶段编排范式。这是主干，开工前必读。
2. `$SKILL/references/template-api.md` —— 每章正文文件的写作契约 + 可用组件（写章的子任务必须遵守）。
3. `$SKILL/references/illustrations.md` —— 扉页插画的 codex 生图 + 色键抠透明管线（需要插画时读）。
4. `$SKILL/references/diagrams.md` —— 内文图三条路：flow()（极简线性）/ Mermaid（精确功能图，由 mmdc 渲染）/ `codex` 插画信息图（最精致有趣，面向人的书首选），都嵌成 #diagram()。要画图时读，并看 $SKILL/styles/<style>/infographic-prompt.md。

配图决策（自己判断，别等用户点名）

book 有两条配图路线，做书时主动按内容判断该走哪条，命中"精美图"判据就在该处走升级路线，不用等用户开口：

• •默认 · 极简线条插画（$SKILL/scripts/gen_illustrations.py，本 skill 自带）：技术书/教材的章节扉页、抽象概念（循环/架构/流程）。克制、统一、系列感强——这类场景上精美大图反而花、破坏一致性。
• •升级 · 精美图 / 杂志级大图：命中任一即在该处升级——

- 封面想要冲击力/营销感/生活方式感（面向大众、产品手册、品牌读本），而非克制技术风； - 某页要美化真实截图（产品教程、UI 走查）→ 截图美化处理； - 需要杂志级大图 / 信息图 / 数据可视化卡片，线条表达不了； - 要顺带产出社交传播图（如小红书图文 / 公众号封面）推广这本书； - 用户说"封面/配图要精美/高级/出彩"。

为什么交给模型判断而非写死：同一本书里，章节扉页要"克制统一"、封面或某张产品图却可能要"精美出彩"——这是逐处的审美权衡，按上面判据当场决定最准。判据拿不准时，倾向「技术内容→线条，面向人/产品/传播→精美大图」。

怎么走升级路线：如果你的环境里有专做精美社交卡/封面的 skill（例如某社交卡 skill），就用它生成图——这类 skill 通常走 HTML 模板 + 无头浏览器渲染，按它自己的说明初始化即可，它另成一体，借用即可、别改它本身。否则就用本 skill 自带的图像生成管线（codex 或任意可用的图像生成能力）自己出图。两种方式产出的图都用 image() 嵌进 Typst（需去背景时用 $SKILL/scripts/chroma_key.py）。细节见 $SKILL/references/illustrations.md。

风格系统（可插拔）

每本书选一个风格（$SKILL/styles/<name>/），决定全部视觉与排版口味。换风格不动正文与流水线。

• •内置 `anthropic` 风格：暖纸纯白 + 单一赤陶橙强调 + 衬线标题/无衬线正文 + 黑白连线扉页插画。开工先读 $SKILL/styles/anthropic/style.md。
• •加新风格：照 $SKILL/styles/README.md 的契约新建 $SKILL/styles/<name>/（template.typ + style.md + illustration-prompt.md），生成时传 --style <name> 即可。位置已留好。

脚本（reusable，用 $SKILL/scripts/ 下的绝对路径调用）

• •$SKILL/scripts/build_book.py --project $PROJECT --style <style> —— 从 toc.json 拼出 book.typ（装入风格模板 + 封面 + 自动目录 + 每章扉页/章头/正文）。
• •$SKILL/scripts/gen_illustrations.py --project $PROJECT --style <style> —— 逐章用 codex（或可用的图像生成能力）生图 + 抠透明 → $PROJECT/assets/chNN-head.png。
• •$SKILL/scripts/chroma_key.py <in> <out> —— 色键抠透明工具（也被上面调用）。

典型一轮（速查；细节看 pipeline.md）

1. 对齐主题/读者/风格/是否插画；读 $SKILL/styles/<style>/style.md。
2. 阶段·调研定目录：广泛调研 → 产出 $PROJECT/toc.json（每章核心问题/小节/配色/插画概念），抽 illustration-specs.json，给用户过目目录。
3. 阶段·并行产出（环境支持并行子代理就 fan out，否则顺序做）：① 逐章写 $PROJECT/chapters/NN.typ（自编译自修复）；② 后台跑 gen_illustrations.py 出插画。
4. build_book.py 拼装 → typst compile book.typ book.pdf → 逐页抽查。
5. 阶段·核查统稿：事实核查 + 统稿（外科手术式修正、术语统一、长章补 ===），每轮重编。

红线 / 经验（别忘）

• •诚实：内容是「调研 + 模型知识」生成，付印前提醒用户做人工通读；事实尽量带一手来源；闭源系统内部实现细节一律用「据社区逆向/分析」措辞。
• •外科手术式修改：核查/统稿阶段只改必要处，不破坏版式、不删节、改完必须编译零错误。
• •每章插画各不相同但呼应主题；页面底色与插画背景同色系 → 抠透明后无缝融入。
• •生图失败时 STOP，绝不静默降级：生图脚本会打印 codex 退出码/报错。一旦报错或零产出（常见根因：~/.codex/config.toml 的 service_tier 被当前 codex CLI 拒绝、未登录），停下、把错误告诉用户、先修前置条件再继续——绝不"取最新 png"复用旧图、绝不用本机代码画裸方/圆/三角顶替扉页插画、绝不用简单 #flow 悄悄顶替该生成的彩色信息图。扉页是图像模型手绘的概念线描，不是程序几何形。详见 references/illustrations.md 顶部红线。
• •token 不是约束，质量是：宁可多开调研/核查子任务，也别糊。
• •字体依赖运行环境（anthropic 风格默认使用常见系统衬线/无衬线字体）；换环境先 typst fonts 确认，缺了在 template.typ 顶部换等价字体。