| 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（审校层）。
