Imported from xcodebuild/write-book-skill (
SKILL.md). Install upstream withnpx 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 润色
- 如何在导出后验证封面兼容性
核心流程
- 初始化或刷新
task_plan.md、findings.md、progress.md。 - 读取源材料,识别真实主题、目标读者、可用结构、可复用非文字资产。
- 构建覆盖图谱再动笔:
- 列出源材料中的主要主题
- 标注缺失或薄弱的部分
- 区分信号与噪声(转录噪声、口语填充词、重复内容)
- 建立资产地图(图片、图表、截图、表格、图示)
- 确定书的形状:书名、定位、章节列表、是否保留源材料顺序还是重组、视觉内容放置位置、EPUB 封面方向和文件名计划。
- 收集全局写作约束再开始起草:语言、语气、叙述视角、禁用词组或句式、术语偏好、目标输出格式、书名和文件名。
- 分批写,不一次性全部倒出:
- 先建立书稿骨架
- 每次填写若干章节
- 每批次后保存进度
- 仅在文字已稳定处插入图片
- 第一份完整 Markdown 书稿完成后,对照输入做信息损失审计(见下文)。
- 修订完信息损失后,做内容审查:主题覆盖、事实漂移、示例是否被删除、计划中的图片是否已插入并加说明。
- 做编辑润色:统一术语、理顺过渡、压缩重复、去除转录残留。
- 用内置的 talk-normal 规则(见下文)审查书稿并修订。保留事实、章节逻辑、信息密度,只修改表达问题。
- 导出格式,验证输出文件存在,EPUB 标题元数据和文件名使用中文(用户未覆盖时)。
- EPUB 交付前,封面资产必须打包进 EPUB,或用户明确说跳过封面,才能宣告完成。
源材料处理
先把源材料提取为纯文本或可检查的形式。
.docx:先提取段落文字,检查结构,再动笔。- 嘈杂的转录稿:重建逻辑,不保留口语填充词。
- 混合来源:合并为一张覆盖图谱再做大纲。
- 有媒体内容的来源:先盘点图片、图表、截图、表格、图示,再做大纲。
读源材料时,把每个内容块归入以下类别之一:
- 核心论点或方法
- 示例或案例研究
- 实现细节
- 重复说明
- 低价值转录填充词
- 损坏或不确定的文字
对于非文字资产,同样归类:
- 说明性图示
- 参考截图
- 数据表或图表
- 装饰性但有上下文价值的内容
- 低价值视觉噪声
- 损坏或无法使用的资产
可用资产记录到 findings.md,包含:源路径或标识符、资产内容描述、可能所属章节、是否需要加说明文字/裁剪/重绘。
资产处理
源材料中的图片和媒体内容,如果能实质性提升书的质量,视为教学资产处理。
- 不因为书以文字为主就丢弃图片、图示、表格、截图。
- 不把视觉内容作为纯装饰插入,每个保留的资产都需支撑附近的论点、示例、流程步骤或案例。
- 资产放在解释它的段落旁边,除非内容本身就需要独立画廊。
- 需要上下文时加简短说明文字或引导句。
- 源资产有噪声但有价值时,裁剪、重绘、转录或替换为更清晰的版本,保留含义。
- 资产无法在 EPUB 导出中正常存活时,记录到
progress.md并选择替代方案(改写表格或描述性摘要)。
先写大纲
动笔前先写大纲。
好的大纲要回答:
- 这本书要教什么
- 目标读者是谁
- 读者读完每章后应该知道什么
- 案例研究、框架、示例放在哪里
- 重要图示、表格、截图放在哪里
章节标题描述功能,不用模糊的主题词。
技术类内容的典型章节顺序:
- 问题框架
- 核心概念
- 技术与权衡
- 系统设计或工作流程
- 评估与失败模式
- 案例研究
- 未来方向
源材料以演示逻辑组织时,重组为书的逻辑。
开始起草前,把以下大纲决策锁进 task_plan.md:
- 章节顺序
- 各章目的
- 源材料到章节的覆盖映射
- 资产到章节的放置映射
- 草稿批次边界
多遍写作
不一次浅写完整本书。
写作顺序:
- 起草前言和章节骨架。
- 起草第一批章节。
- 保存书稿。
- 起草下一批。
- 再次保存。
- 继续直到书的主体完成。
- 在文字已稳定处插入或修订计划中的图示和说明文字。
- 对第一份完整草稿做信息损失审计。
- 就地修订缺失的内容。
- 做完整编辑修订。
- 用 talk-normal 规则(见下文)审查并修订。
每章写作:
- 说明本章目的。
- 把源材料要点转化为更清晰的叙述顺序。
- 源材料有强烈暗示时展开薄弱部分。
- 保留能实质性教授要点的示例。
- 只保留能实质性教授要点的图示,并在周围文字中解释。
- 去除填充词、道歉语、课堂闲聊和断裂的转录内容。
用户明确要求避免偷懒时,让分批工作可见:早期创建文件,多次追加或扩展章节,中间结构保留在磁盘上,用一个压缩摘要替代认真起草不算完成,每批次后更新 progress.md。
第一稿信息损失审计
第一份完整 Markdown 书稿是检查点,不是终点。
做风格润色前,把第一份完整草稿与输入和覆盖图谱对比,检查改写过程中是否损失了信息密度。
审计项目:
- 被删掉的技术细节(决策依据、权衡、约束、前提条件)
- 遗失的示例、案例研究、反例、警告、失败模式
- 被压缩的流程(步骤顺序或依赖关系消失)
- 图表、截图、图示、表格、说明文字的解释价值消失
- 被压缩为泛化摘要语言的区分
发现缺失内容时,修订相关章节或小节,不要追加随机的补充段落。把每个缺失项记录到 findings.md(含源材料指针和修复状态),再进行 talk-normal 审查。
并行子代理
如果子代理可用,把独立工作并行化:
- 从不同输入文件提取源材料
- 为独立的源材料包做覆盖映射
- 对图片、图示、表格做资产盘点
- 为不相交的章节批次做第一遍起草
- 对不同源材料片段做事实或术语核查
- 导出验证和 EPUB 包检查
规则:
- 下一步依赖即时判断时,把关键路径留在本地
- 分配不相交的所有权(特定源文件夹或章节范围)
- 不让多个子代理起草同一章节批次
- 把子代理输出合并回
task_plan.md、findings.md、progress.md - 并行起草后,做一次本地编辑遍历,恢复统一的叙述声音
覆盖审查
第一份完整 Markdown 草稿存在后,把书稿对照源材料审查。
审查项目:
- 缺失的主题
- 缺失的区分
- 缺失的案例研究
- 丢掉的警告说明
- 说明或流程中的信息密度损失
- 过度简化的权衡
- 超出源材料的意外发明
- 大纲标注为必要的图示或表格缺失
源材料信息量大于书稿时,把缺失内容加进相关章节,不要追加随机的补充节。把源材料空白、丢失细节、事实风险说明、资产放置遗漏记录到 findings.md,再修订书稿。
风格与约束控制
把用户写作约束当作全局规则,不是局部建议。
常见约束:
- 避免某些词组
- 保留或避免某些句子节奏
- 使用特定语言
- 技术术语保留英文
- 叙述视角始终锚定在书稿作者
- 写成书而不是转录稿
用户禁止某个词组或句式时:
- 明确记录规则
- 起草时避免使用
- 交稿前对全文做文本搜索
用 rg 做全书检查(当模式可搜索时)。
默认书写规则(用户未覆盖时):
- 用中文写作
- 技术术语仅在提高精确度时才保留英文
- 叙述始终用书稿作者的声音,不转述源材料
中文书稿的额外规则(用户未覆盖时):
- 避免"稳"或"更稳"这类口语化评判词
- 避免"材料里说"、"原文说"、"素材里提到"等转述定式
- 避免"不是……而是……"或"不是……也不是……而是……"这类以反衬完成定义的修辞句(不含逻辑/数学场景)
同时规范:
- 章节标题风格
- 术语大小写
- 标点风格
- 列表风格
- 引用风格
编辑修订
内容遍完成后做一次编辑遍。
重点:
- 去除相邻章节间的重复
- 替换生硬直译
- 收紧过载句子
- 让章节间过渡显式化
- 把讲座逻辑转化为书的逻辑
- 书稿结构和覆盖已稳定后,去除公式化 AI 残留
注意转录残留,例如:
- 称呼听众的语言
- 修辞填充词
- 重复的铺垫句
- 对幻灯片、会场、现场互动的断裂引用
- 破坏叙述声音的转述定式
来源是演讲或课程时,把"说了什么"转化为"这章需要什么"。如果一句话听起来像对源材料的评注而不是书的一部分,改写为直接的叙述陈述。如果一句话主要靠否定来定义某事物,改写为直接的正向陈述。
完成主要编辑修订后,用下面的 talk-normal 规则审查书稿,修订它发现的表达问题。保留事实、章节逻辑、信息密度。
Talk-Normal 规则(内置)
审查时应用以下规则,修复问题而不是整稿重写:
核心要求:直接表达正向主张。
最严格的约束:使用直接正向主张,不用否定对照句式。不论在任何语言或位置,都不要用否定副词来衬托正向主张。如果写了一个用否定词引出或附带正向主张的句子,重构它,只陈述正向主张。
示例:
- 坏:真正的创新者不是"有创意的人",而是五种特质同时拉满的人
- 好:真正的创新者是五种特质同时拉满的人
- 坏:这更像创始人筛选框架,不是交易信号
- 好:这是一个创始人筛选框架
规则列表:
- 先给答案,再加上下文(仅在真正有帮助时)
- 不在任何位置使用否定对照句式。这包括所有结构:否定然后纠正、纠正然后否定、链式否定(不是A,不是B,而是C)、对称否定(适合X,不适合Y),有无"而"连词均适用。直接陈述正向主张。需要表达真正区别时,用并列正向分句。例外:逻辑、数学或形式证明中关于必要或充分条件的技术陈述。
- 有具体建议或下一步时以此结尾。不使用摘要标签式结尾——任何在给出结论前先宣布"来了我的一句话总结"的措辞。包括"综上所述"、"简而言之"、"一句话总结"、"一句话落地"、"总结一下"、"概括来说"及其变体。有最终有力的观点就直接陈述,不加摘要标签。
- 杀掉所有填充词:"值得注意的是"、"首先我们需要"、"综上所述"、"让我们一起来看看"
- 不复述问题
- 不使用假设性跟进提问或条件式下一步菜单
- 不在清楚解释后用"翻成人话"或"简单来说"再复述一遍
- 比较时给建议加简短理由,不写平衡论文
- 对照选项时每侧最多 3-4 个要点,选最重要的
这些规则仅用于审查和修复表达,不替代内容判断。发现问题时,就地修订,保留信息密度。
输出格式
默认工作格式是 Markdown,默认交付格式是 EPUB。
常见交付流程:
- 在 Markdown 中生成或修订书稿
- 创建或确认封面资产和 EPUB 所需 CSS
- 导出 EPUB
- 用户要求时额外输出 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 封面
默认生成专属封面。不以扉页作为唯一视觉封面(用户明确说跳过或只要粗略导出时除外)。
推荐流程:
- 创建封面源文件(如
cover.svg) - 导出交付图片(如
cover.jpg) - 保留源向量或分层资产以备后续编辑
- 用压缩栅格图导出 EPUB
尽早完成,让封面成为 task_plan.md 和 progress.md 中的跟踪交付物。
封面比例参考常见书籍纵向比例:
- 首选约
1:1.6 - 源资产推荐尺寸:
1200×1920或1400×2240 - EPUB 交付用较小尺寸,不要默认超大海报式封面
- 避免正方形或横版封面(在 EPUB 库和阅读器缩略图中常显示异常)
EPUB 交付封面:
- 首选 JPEG(除非真的需要无损透明度)
- 导出前压缩
- 实用目标:长边约
900-1400px,文件大小约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
