write-book

Imported from xcodebuild/write-book-skill (SKILL.md). Install upstream with npx skills add xcodebuild/write-book-skill. Copyright stays with the author.

write-book

把任意来源的素材（YouTube 字幕、播客文字稿、文章、课程讲义等）写成一本 EPUB 电子书。

默认设定，用户未明确覆盖时生效：

• 书稿语言：中文
• 主要输出格式：EPUB
• 草稿工作格式：Markdown
• 书名、EPUB 文件名均使用中文
• 源材料中的图片、表格、截图等非文字资产视为教学资产，不随意丢弃
• EPUB 默认附带封面，除非用户明确说不要

运行 python scripts/export_book.py --help 查看 EPUB / DOCX 导出选项。 交付前阅读 references/checklist-zh.md。

控制平面

写书是多阶段任务，不靠对话记忆管理。

在项目根目录维护三个文件：

• task_plan.md：源材料集合、输出目标、章节计划、资产计划、当前阶段
• findings.md：来源摘录、源材料歧义、资产发现、信息损失审计结果
• progress.md：章节批次进度、导出记录、验证结果、恢复检查点

每次主要阶段切换前重读 task_plan.md。每完成一个批次后更新 progress.md。

EPUB 项目的资产计划需明确记录：

• 是否需要封面，计划封面源文件路径和交付图片路径
• 是否需要 CSS 润色
• 如何在导出后验证封面兼容性

核心流程

1. 初始化或刷新 task_plan.md、findings.md、progress.md。
2. 读取源材料，识别真实主题、目标读者、可用结构、可复用非文字资产。
3. 构建覆盖图谱再动笔：
   • 列出源材料中的主要主题
   • 标注缺失或薄弱的部分
   • 区分信号与噪声（转录噪声、口语填充词、重复内容）
   • 建立资产地图（图片、图表、截图、表格、图示）
4. 确定书的形状：书名、定位、章节列表、是否保留源材料顺序还是重组、视觉内容放置位置、EPUB 封面方向和文件名计划。
5. 收集全局写作约束再开始起草：语言、语气、叙述视角、禁用词组或句式、术语偏好、目标输出格式、书名和文件名。
6. 分批写，不一次性全部倒出：
   • 先建立书稿骨架
   • 每次填写若干章节
   • 每批次后保存进度
   • 仅在文字已稳定处插入图片
7. 第一份完整 Markdown 书稿完成后，对照输入做信息损失审计（见下文）。
8. 修订完信息损失后，做内容审查：主题覆盖、事实漂移、示例是否被删除、计划中的图片是否已插入并加说明。
9. 做编辑润色：统一术语、理顺过渡、压缩重复、去除转录残留。
10. 用内置的 talk-normal 规则（见下文）审查书稿并修订。保留事实、章节逻辑、信息密度，只修改表达问题。
11. 导出格式，验证输出文件存在，EPUB 标题元数据和文件名使用中文（用户未覆盖时）。
12. EPUB 交付前，封面资产必须打包进 EPUB，或用户明确说跳过封面，才能宣告完成。

源材料处理

先把源材料提取为纯文本或可检查的形式。

• .docx：先提取段落文字，检查结构，再动笔。
• 嘈杂的转录稿：重建逻辑，不保留口语填充词。
• 混合来源：合并为一张覆盖图谱再做大纲。
• 有媒体内容的来源：先盘点图片、图表、截图、表格、图示，再做大纲。

读源材料时，把每个内容块归入以下类别之一：

• 核心论点或方法
• 示例或案例研究
• 实现细节
• 重复说明
• 低价值转录填充词
• 损坏或不确定的文字

对于非文字资产，同样归类：

• 说明性图示
• 参考截图
• 数据表或图表
• 装饰性但有上下文价值的内容
• 低价值视觉噪声
• 损坏或无法使用的资产

可用资产记录到 findings.md，包含：源路径或标识符、资产内容描述、可能所属章节、是否需要加说明文字/裁剪/重绘。

资产处理

源材料中的图片和媒体内容，如果能实质性提升书的质量，视为教学资产处理。

• 不因为书以文字为主就丢弃图片、图示、表格、截图。
• 不把视觉内容作为纯装饰插入，每个保留的资产都需支撑附近的论点、示例、流程步骤或案例。
• 资产放在解释它的段落旁边，除非内容本身就需要独立画廊。
• 需要上下文时加简短说明文字或引导句。
• 源资产有噪声但有价值时，裁剪、重绘、转录或替换为更清晰的版本，保留含义。
• 资产无法在 EPUB 导出中正常存活时，记录到 progress.md 并选择替代方案（改写表格或描述性摘要）。

先写大纲

动笔前先写大纲。

好的大纲要回答：

• 这本书要教什么
• 目标读者是谁
• 读者读完每章后应该知道什么
• 案例研究、框架、示例放在哪里
• 重要图示、表格、截图放在哪里

章节标题描述功能，不用模糊的主题词。

技术类内容的典型章节顺序：

1. 问题框架
2. 核心概念
3. 技术与权衡
4. 系统设计或工作流程
5. 评估与失败模式
6. 案例研究
7. 未来方向

源材料以演示逻辑组织时，重组为书的逻辑。

开始起草前，把以下大纲决策锁进 task_plan.md：

• 章节顺序
• 各章目的
• 源材料到章节的覆盖映射
• 资产到章节的放置映射
• 草稿批次边界

多遍写作

不一次浅写完整本书。

写作顺序：

1. 起草前言和章节骨架。
2. 起草第一批章节。
3. 保存书稿。
4. 起草下一批。
5. 再次保存。
6. 继续直到书的主体完成。
7. 在文字已稳定处插入或修订计划中的图示和说明文字。
8. 对第一份完整草稿做信息损失审计。
9. 就地修订缺失的内容。
10. 做完整编辑修订。
11. 用 talk-normal 规则（见下文）审查并修订。

每章写作：

1. 说明本章目的。
2. 把源材料要点转化为更清晰的叙述顺序。
3. 源材料有强烈暗示时展开薄弱部分。
4. 保留能实质性教授要点的示例。
5. 只保留能实质性教授要点的图示，并在周围文字中解释。
6. 去除填充词、道歉语、课堂闲聊和断裂的转录内容。

用户明确要求避免偷懒时，让分批工作可见：早期创建文件，多次追加或扩展章节，中间结构保留在磁盘上，用一个压缩摘要替代认真起草不算完成，每批次后更新 progress.md。

第一稿信息损失审计

第一份完整 Markdown 书稿是检查点，不是终点。

做风格润色前，把第一份完整草稿与输入和覆盖图谱对比，检查改写过程中是否损失了信息密度。

审计项目：

• 被删掉的技术细节（决策依据、权衡、约束、前提条件）
• 遗失的示例、案例研究、反例、警告、失败模式
• 被压缩的流程（步骤顺序或依赖关系消失）
• 图表、截图、图示、表格、说明文字的解释价值消失
• 被压缩为泛化摘要语言的区分

发现缺失内容时，修订相关章节或小节，不要追加随机的补充段落。把每个缺失项记录到 findings.md（含源材料指针和修复状态），再进行 talk-normal 审查。

并行子代理

如果子代理可用，把独立工作并行化：

• 从不同输入文件提取源材料
• 为独立的源材料包做覆盖映射
• 对图片、图示、表格做资产盘点
• 为不相交的章节批次做第一遍起草
• 对不同源材料片段做事实或术语核查
• 导出验证和 EPUB 包检查

规则：

• 下一步依赖即时判断时，把关键路径留在本地
• 分配不相交的所有权（特定源文件夹或章节范围）
• 不让多个子代理起草同一章节批次
• 把子代理输出合并回 task_plan.md、findings.md、progress.md
• 并行起草后，做一次本地编辑遍历，恢复统一的叙述声音

覆盖审查

第一份完整 Markdown 草稿存在后，把书稿对照源材料审查。

审查项目：

• 缺失的主题
• 缺失的区分
• 缺失的案例研究
• 丢掉的警告说明
• 说明或流程中的信息密度损失
• 过度简化的权衡
• 超出源材料的意外发明
• 大纲标注为必要的图示或表格缺失

源材料信息量大于书稿时，把缺失内容加进相关章节，不要追加随机的补充节。把源材料空白、丢失细节、事实风险说明、资产放置遗漏记录到 findings.md，再修订书稿。

风格与约束控制

把用户写作约束当作全局规则，不是局部建议。

常见约束：

• 避免某些词组
• 保留或避免某些句子节奏
• 使用特定语言
• 技术术语保留英文
• 叙述视角始终锚定在书稿作者
• 写成书而不是转录稿

用户禁止某个词组或句式时：

1. 明确记录规则
2. 起草时避免使用
3. 交稿前对全文做文本搜索

用 rg 做全书检查（当模式可搜索时）。

默认书写规则（用户未覆盖时）：

• 用中文写作
• 技术术语仅在提高精确度时才保留英文
• 叙述始终用书稿作者的声音，不转述源材料

中文书稿的额外规则（用户未覆盖时）：

• 避免"稳"或"更稳"这类口语化评判词
• 避免"材料里说"、"原文说"、"素材里提到"等转述定式
• 避免"不是……而是……"或"不是……也不是……而是……"这类以反衬完成定义的修辞句（不含逻辑/数学场景）

同时规范：

• 章节标题风格
• 术语大小写
• 标点风格
• 列表风格
• 引用风格

编辑修订

内容遍完成后做一次编辑遍。

重点：

• 去除相邻章节间的重复
• 替换生硬直译
• 收紧过载句子
• 让章节间过渡显式化
• 把讲座逻辑转化为书的逻辑
• 书稿结构和覆盖已稳定后，去除公式化 AI 残留

注意转录残留，例如：

• 称呼听众的语言
• 修辞填充词
• 重复的铺垫句
• 对幻灯片、会场、现场互动的断裂引用
• 破坏叙述声音的转述定式

来源是演讲或课程时，把"说了什么"转化为"这章需要什么"。如果一句话听起来像对源材料的评注而不是书的一部分，改写为直接的叙述陈述。如果一句话主要靠否定来定义某事物，改写为直接的正向陈述。

完成主要编辑修订后，用下面的 talk-normal 规则审查书稿，修订它发现的表达问题。保留事实、章节逻辑、信息密度。

Talk-Normal 规则（内置）

审查时应用以下规则，修复问题而不是整稿重写：

核心要求：直接表达正向主张。

最严格的约束：使用直接正向主张，不用否定对照句式。不论在任何语言或位置，都不要用否定副词来衬托正向主张。如果写了一个用否定词引出或附带正向主张的句子，重构它，只陈述正向主张。

示例：

• 坏：真正的创新者不是"有创意的人"，而是五种特质同时拉满的人
• 好：真正的创新者是五种特质同时拉满的人
• 坏：这更像创始人筛选框架，不是交易信号
• 好：这是一个创始人筛选框架

规则列表：

• 先给答案，再加上下文（仅在真正有帮助时）
• 不在任何位置使用否定对照句式。这包括所有结构：否定然后纠正、纠正然后否定、链式否定（不是A，不是B，而是C）、对称否定（适合X，不适合Y），有无"而"连词均适用。直接陈述正向主张。需要表达真正区别时，用并列正向分句。例外：逻辑、数学或形式证明中关于必要或充分条件的技术陈述。
• 有具体建议或下一步时以此结尾。不使用摘要标签式结尾——任何在给出结论前先宣布"来了我的一句话总结"的措辞。包括"综上所述"、"简而言之"、"一句话总结"、"一句话落地"、"总结一下"、"概括来说"及其变体。有最终有力的观点就直接陈述，不加摘要标签。
• 杀掉所有填充词："值得注意的是"、"首先我们需要"、"综上所述"、"让我们一起来看看"
• 不复述问题
• 不使用假设性跟进提问或条件式下一步菜单
• 不在清楚解释后用"翻成人话"或"简单来说"再复述一遍
• 比较时给建议加简短理由，不写平衡论文
• 对照选项时每侧最多 3-4 个要点，选最重要的

这些规则仅用于审查和修复表达，不替代内容判断。发现问题时，就地修订，保留信息密度。

输出格式

默认工作格式是 Markdown，默认交付格式是 EPUB。

常见交付流程：

1. 在 Markdown 中生成或修订书稿
2. 创建或确认封面资产和 EPUB 所需 CSS
3. 导出 EPUB
4. 用户要求时额外输出 Markdown 或 DOCX 副本

导出前确认 EPUB 命名计划：

• 在元数据中使用所选中文书名
• EPUB 文件名默认使用中文书名，例如 书名.epub
• 仅在用户明确要求或环境无法处理该路径时才使用非中文文件名
• 书稿文件名与期望的中文书名不符时，导出时显式传递 --title 和 --epub-name

导出前：

• 确认书稿有标题元数据或等效结构
• 确认章节标题一致
• 确认列表和代码块合法
• 确认引用的图片和其他资产从书稿可解析
• 确认是否需要专属封面（EPUB 默认需要，除非用户明确跳过）
• 如需封面，确认源资产（如 cover.svg）和交付图片（如 cover.jpg）都存在
• 如用户要求精美 EPUB，准备 CSS 文件再导出

导出后：

• 验证输出文件存在
• 报告确切路径
• 说明可能影响呈现效果的转换警告
• 检查图片和其他嵌入资产是否在打包后存活
• 检查 EPUB 封面打包（不假设阅读器能自动识别）
• 如需封面，验证 EPUB 包含封面资产和封面元数据后才宣告导出完成
• 把导出命令、输出路径、警告、验证结果记录到 progress.md

导出命令（pandoc 可用时优先使用）：

python scripts/export_book.py manuscript.md --formats epub,docx
python scripts/export_book.py manuscript.md --formats epub --css book.css
python scripts/export_book.py manuscript.md --formats epub --css book.css --epub-cover-image cover.jpg
python scripts/export_book.py manuscript.md --formats epub,docx --output-dir out
python scripts/export_book.py manuscript.md --title "书名" --epub-name "书名.epub" --docx-name "书名.docx"

EPUB 封面

默认生成专属封面。不以扉页作为唯一视觉封面（用户明确说跳过或只要粗略导出时除外）。

推荐流程：

1. 创建封面源文件（如 cover.svg）
2. 导出交付图片（如 cover.jpg）
3. 保留源向量或分层资产以备后续编辑
4. 用压缩栅格图导出 EPUB

尽早完成，让封面成为 task_plan.md 和 progress.md 中的跟踪交付物。

封面比例参考常见书籍纵向比例：

• 首选约 1:1.6
• 源资产推荐尺寸：1200×1920 或 1400×2240
• EPUB 交付用较小尺寸，不要默认超大海报式封面
• 避免正方形或横版封面（在 EPUB 库和阅读器缩略图中常显示异常）

EPUB 交付封面：

• 首选 JPEG（除非真的需要无损透明度）
• 导出前压缩
• 实用目标：长边约 900-1400 px，文件大小约 80-180 KB

EPUB CSS

Pandoc 默认 EPUB 样式功能够用但通常看起来像导出产物，不像设计好的书。

用户要求精美 EPUB 时：

• 创建专属 CSS 文件（如 book.css）
• 调整段落缩进、行高、标题层级、扉页、目录、引用块、代码块、封面页行为
• 偏向克制的书本式排版，不用网页感强的装饰
• 为阅读 app 设计，不为浏览器设计

典型 CSS 目标：

• 中文正文行高和段落节奏稳定
• 章节标题与正文明显分隔
• 扉页不像原始元数据堆砌
• 代码和引用样式存在但低调
• 封面页无意外边距，接近全出血

EPUB 封面兼容性

部分阅读器只部分支持 EPUB 3 封面元数据。文件可能包含封面图片但在库或第一页不显示。

封面显示重要时（书籍交付默认认为重要，用户明确说无所谓除外），导出后检查 EPUB 包。

检查项目（尽可能全部验证）：

• manifest item 有 properties="cover-image"
• 存在可见的封面页（如 text/cover.xhtml）且实际嵌入了图片
• guide reference 有 type="cover"
• EPUB 2 兼容标签：<meta name="cover" content="...">
• EPUB 3 landmarks 包含 cover 条目

未通过这些检查或明确记录了哪些检查不可行及原因之前，不宣告 EPUB 导出完成。

质量标准

把结果当成书稿，不是清理后的转录稿。

书稿应具备：

• 清晰的主线
• 章节级意图
• 稳定的术语
• 足够的信息密度以保留源材料价值
• 有作者感的可读散文

源材料薄弱时，如实说明，不假装能撑起一本完整的书。 源材料丰富时，保留信息深度，不把它磨成通用建议。

参考资源

• references/checklist-zh.md：交付前中文书稿 QA 检查清单
• scripts/export_book.py：通过 pandoc 将 Markdown 书稿导出为 EPUB 和/或 DOCX