| name | tech-book-writing |
| description | 技术书籍章节写作风格指南。融合反模板化叙事结构与段落级流畅性控制技法。
当用户要求写新的书籍章节、重写现有章节、优化文章可读性、或讨论技术写作风格时使用。
触发场景：写章节、重写、改写、优化文章、写作风格、叙事结构、可读性、
“换个切入方式”“这段太干了”“读者会流失”。
即使用户没有明确提到写作风格，只要任务涉及产出或修改技术书籍的正文内容，就应该参考本 skill。
|
技术书籍章节写作
两个核心维度：
- 章级结构：每章选择完全不同的叙事结构，拒绝模板化
- 段落级流畅性：控制呼吸节奏，让读者停不下来
前者解决“章与章之间不能雷同”，后者解决“段与段之间不能断裂”。
一、反模板化：每章一个独立结构
技术书最大的可读性杀手是"所有章节读起来一样"。读者在第三章就能预测第四章的结构，阅读变成了填表。
每章开写前，先问自己：这一章的内容特质是什么？什么叙事结构最适配它？
可选的切入方式（不是清单，是灵感库）
| 切入方式 | 适合内容 | 例子 |
|---|
| 悬疑/侦探 | 排查 bug、追踪数据流 | "配置没生效。你检查了三个地方都没问题。第四个地方你根本没想到。" |
| 个人发现 | 首次理解某个机制 | "我一直以为 X 是这样工作的。直到我读了源码。" |
| 问答/对话 | 概念辨析、常见误解 | "每步都全量注入不行吗？可以，但贵。" |
| 类比贯穿 | 抽象机制需要直觉 | 报纸底版与增量、餐厅菜单与厨房 |
| 张力/续写 | 上一章留下的悬念 | "上一章说了知识不是能力。那能力从哪来？" |
| 鸟瞰回顾 | 总结章、哲学章 | 每章一句话概括，然后找共同模式 |
| 痛点-解法 | 工程决策、取舍分析 | "20 条命令点 20 次确认。你受得了吗？" |
| 时间线叙事 | 生命周期、状态迁移 | "下午两点你开始重构。到四点，context window 快满了。" |
核心原则
- 相邻两章必须用不同的切入方式
- 结构服务内容，不是服务对称
- 如果某章天然适合 Q&A，就用 Q&A；不要为了"统一风格"硬改成叙事
- 全书可以有 3-4 种主要结构模式，但每种最多连续用一次
二、段落级流畅性：呼吸控制
2.1 短段落原则
每段只承载一个念头。长度尽量控制在 3 句左右。
读者在手机上看你的文章。一个 6 句的段落在手机上是半屏的文字墙。他们会跳过。
反面：
Codex 的上下文构造采用 baseline/diff 机制。首次全量注入后，后续每步只做增量。这样做的好处是保护前缀不变，从而命中 prompt cache。cache 命中可以显著降低 token 费用。但代价是调试困难，因为你无法在一个地方看到完整的 system prompt。
正面：
第一步，系统注入所有东西。这是底版。
从第二步开始，只告诉模型"什么变了"。底版不动。
为什么？因为前缀不能变。变了就浪费钱。
2.2 叙事动量转场
段落之间的衔接不靠"接下来""此外""另外"这类结构标记词。靠的是上一段末句制造的问题/张力，被下一段首句接住。
弱转场：
……cache 就 miss。
接下来我们看看 compaction 机制。
强转场：
……cache 就 miss。
那如果对话太长了呢？128K 的窗口，40 轮对话就满了。系统必须做点什么。
2.3 数字锚点
用具体数字替代形容词。数字制造画面感，形容词制造模糊感。
| 弱 | 强 |
|---|
| 很多 token | 110K token |
| 等很久 | 90 秒超时 |
| 大幅降低 | 从 20 次审批降到 0-2 次 |
| 很快 | 200ms 初始退避，每次翻倍 |
注意：数字必须来自源码或可验证的事实。不要为了画面感编造数字。
2.4 引用替代转述
能引用源码注释/变量名/函数名的时候，直接引用。引用比转述更可信，也更精确。
转述： 系统会在压缩后警告用户准确性可能下降。
引用： 系统发送一条 Warning："长线程和多次压缩可能降低准确性，建议开新线程。"
2.5 比喻即分析框架
比喻不是装饰。好的比喻构成分析框架——读者可以用它推理后续问题。
装饰性比喻： 沙箱就像一个保护罩。（然后呢？保护什么？怎么保护？读者还是不知道。）
分析性比喻： 底版不动，增量追加。就像报纸印刷——底版校准一次很贵，所以底版不变，只换今天的新闻。（读者立刻能推理：如果底版变了会怎样？校准成本。如果增量太多会怎样？版面不够→compaction。）
2.6 第一人称的困惑与反思
适度使用"我"表达真实的困惑。这建立可信度——读者知道作者也是人，也会犯错。
说实话，第一次看到这个空文件时我觉得这是个 bug。
但不要滥用。每章最多 2-3 处。第一人称是调味料，不是主菜。
2.7 节尾金句
每个 section 的最后一句应该是可记忆的——一个判断、一个对比、一个反转。不是总结性陈述。
弱： 综上所述，baseline/diff 机制在效率和正确性之间取得了平衡。
强： 上下文不是一个字符串，是一条装配线。
三、代码出场规则
前半段禁代码
文章前半段（建立问题感和直觉的阶段）不出现代码块。代码会吓跑初级读者。
前半段用：
- 场景叙事建立"为什么我要关心这个"
- Mermaid 图展示结构和流程
- 类比建立直觉
代码只在证明承重逻辑时出场
代码不是"给读者看看长什么样"。代码是证据——证明一个文字无法独立验证的判断。
出场前必须有铺垫：
- 这段代码要证明什么？
- 读者应该重点看哪几行？
- 看完之后结论是什么？
出场后必须有解释：
- 控制流或状态变化意味着什么？
- 对前面的判断有什么影响？
不引用什么
- 样板代码、字段搬运、转发逻辑
- 信息量低的代码（看了跟没看一样）
- 可以用 Mermaid 图替代的结构关系
四、语言风格
- 中文。直接、准确、具体。
- 不写宣传腔（"强大的""优雅的""令人惊叹的"）
- 不把"复杂度""可扩展性""稳定性"当万能词——必须落到具体机制
- 允许指出读者的错误认知，但要说明为什么错
- 优先解释取舍，而不是堆工程名词
- 标题必须是自然、通顺、有信息量的中文问题或判断句
五、写作检查清单
写完一章后，过一遍：
