/book_skill

name: book
description: >-
  用多 agent 工作流从零生成一整本【带设计感、可直接出 PDF 的书/教材/手册/读本】——含广泛调研定目录、逐章并行写作、每章主题插画、Typst 精排、事实核查与统稿。当用户想"写一本书/教材/手册/小册子/读本"、"把某个主题系统整理成一本书"、"做一本带封面和插画的 PDF 电子书"、"生成一本 XX 风格的书"，或提到 Anthropic 风格出版物排版时，主动使用本 skill——即使没明说"用 book skill"。多章节、需要统一设计与排版、要出 PDF 的长篇成书任务都该用它。
  不要用于：单篇文章/博客、PPT/幻灯片、海报、网页/落地页、单张图（那些另有工具）。

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 顶部换等价字体。