name

write-orange-book

description

写"橙皮书"风格的技术书/实战手册——从选题、章节大纲、分章写作、审校到渲染成出版级 A4 PDF。当用户要把一个技术主题（某个工具、框架、概念）做成一本结构化、可下载、读起来不像 AI slop 的免费技术书/指南/手册/电子书时使用。触发词：橙皮书、技术书、实战手册、电子书、PDF 教程、把 X 做成一本书。

橙皮书 (Orange Book) 写作 Skill

一套把技术主题写成出版级 PDF 手册的完整工作流。复刻的是"焦橙主题"设计系统 + 分章 HTML 源 + 脚本渲染 PDF 的产线。

它是什么 / 不是什么

是：单作者、单主题、可一周内完成的实战手册（30–70 页 A4）。结构固定、视觉克制、有出版社质感。
不是：百科全书、API 参考文档、需要多人协作的大部头。篇幅失控就是失败。

工作流（按顺序，不要跳步）

Phase 1 · 定题与定位（先想清楚，别急着写）

和用户确认四件事，缺一不可：

主题：一个具体的工具/框架/概念（如 "Hermes Agent"、"Loop Engineering"）。越聚焦越好。
读者：谁在读、他们现在卡在哪。橙皮书的价值是"把零散信息嚼碎成入门到精通"。
核心问题：整本书回答的那一个问题（如"Hermes 和 OpenClaw 到底有什么区别？"）。写在封面副标题里。
时效锚点：基于哪个版本/哪篇原始资料/截至哪天。技术书半衰期短，必须标注版本号和日期。

不要在用户没给清楚这四点时就开始生成内容。模糊就追问。

Phase 2 · 章节大纲

控制在 6 个部分 / 15–21 节 之间。这是橙皮书的经验区间——少了不成书，多了读不完。
教学顺序：是什么 → 10 分钟跑起来 → 第一个真实项目 → 深度能力 → 进阶/架构 → 边界与避坑。
每节给一句话导语（写进 section-intro）。
大纲先给用户确认再动笔。

Phase 3 · 分章写作

一节一个 HTML 片段文件：chapters/NN-slug.html（如 02-quickstart.html）。00 留给封面，99 留给尾页。
每个片段只写正文 HTML，不写 <html>/<head>/<style>——CSS 由渲染脚本统一注入。
每节用固定骨架开头：section-title → section-en（英文副标题，可选）→ section-intro（导语）→ 正文。
正文用 references/components.md 里的组件积木（callout / tip / warning / step / flow / compare / code / table / file-tree）。不要发明新组件类名，否则没有样式。
写作风格见 references/writing-guide.md。核心：短句、给具体数字和真实案例、避免空泛的"赋能/抓手"式 AI 腔。

Phase 4 · 封面与尾页

封面 chapters/00-cover.html、尾页 chapters/99-backpage.html：从 references/components.md 复制模板填字段。
封面 h1 里用 <em> 包住要变焦橙色的词。

Phase 5 · 渲染

python scripts/build_pdf.py book.config.json

脚本会：按 config 顺序拼接所有 chapters → 自动生成目录页 → 内联 theme.css → 输出 A4 PDF 到 dist/。依赖：pip install weasyprint（首选，纯 Python）。

Phase 6 · 审校（两步）

内容审校：按 references/review.md 跑三遍法（内容 / 降 AI 腔 / 节奏排版）。如果用户装了 huashu-proofreading skill，优先调它当审校引擎；否则用 review.md 里内置的等效清单。技术书的人味靠真实踩坑、版本差异、"我实测…"的数字——多写这些。
分页视觉检查：读一遍 PDF 截图，确认分页没断在组件中间（组件已设 page-break-inside:avoid，超长的仍会断）、目录页码对、焦橙色只用在该强调处。发现问题改 chapter 片段再重渲染。

文件结构（在用户项目里生成）

book/
├── book.config.json      # 元信息 + 章节顺序
├── chapters/
│   ├── 00-cover.html
│   ├── 01-xxx.html
│   └── 99-backpage.html
└── dist/book.pdf

关键约束（违反就翻车）

边距：@page 只管上下，左右靠 .content 的 padding。不要两处都设左右边距，会叠加出血。
焦橙 #C2410C 是唯一强调色，克制使用——全篇高亮等于没有高亮。
版本号和日期必须出现在封面。技术书不标时效就是误导。
篇幅红线：超过 70 页就该拆书或砍内容，不要硬塞。

详见 references/components.md（组件速查）、references/writing-guide.md（写作方法论）和 references/review.md（审校层）。