写作风格与格式约定¶
目标：把格式约定当成写作 linter 规则。用最少的花哨格式，换取最大可读性、可检索性与可复现性；让读者能照着做，让审稿能落成补丁。
0) 章节最低构件（别写成散文）¶
对“章节正文”（第 1–20 章与第 10 章深入小章），默认至少包含：
## 关键流程图（纯文本）：用缩进箭头/表格表达闭环、分支、回退与验证。## 示例（可复制）：按“目标/前置条件/步骤/验证/失败判定/回滚”写成读者能照抄的最小例子。## 复现检查清单（本章最低门槛）：把本章门槛压缩成 4–10 条可执行项。## 常见陷阱（失败样本）：至少 3 条，按“现象/根因/复现/修复/回归验证”写。
对“非章节正文”（总览、序言、结语、附录），可不强制以上四件套，但至少应包含：
## 你将获得什么：读者读完能完成什么动作/做出什么裁决。## 怎么用：适用范围/不适用范围 + 推荐阅读路径（回链到相关章节）。
1) 结构优先（格式是工具，不是装饰）¶
- 优先用标题/列表/表格表达层次：先结构、后修辞。
- 一段只讲一个观点：宁可多分段，也不要用括号堆补充。
- 加粗只用于门槛、结论、失败判定等扫读关键词；每段不超过 1–2 处。
2) 引号与标点（避免语气不稳）¶
- 正文避免使用英文双引号（U+0022、U+201C、U+201D）给术语加戏；需要引用外部原话时，用中文引号「」；书名/论文名用《》。
- 代码块、JSON、shell 命令中的引号不受此限制（以可复制为准）。
- 不要用一串括号/引号去替代解释：把原因写成完整句子。
3) 代码格式与链接（少而准）¶
- 只对命令、路径、字段名、配置键、字面量用代码格式；不要把整句话/整段话包在代码格式里。
- 链接文本用可读的中文短语；相对链接显式带
.md；不要把文件名包在代码格式里当链接文本。 - 需要引用支撑的强断言（数字、安全、合规、成本）应在句末标注
[n]，并确保references.md中存在对应条目。
4) 模板与占位符（让读者真的能照抄）¶
- 模板允许占位符，但数量要少、格式要统一：正文模板用
<...>；代码/环境变量用YOUR_TOKEN这类大写占位符。 - 模板后追加一行替换点：列出需要改的 1–3 个关键占位符；能给具体示例值就给。
5) 图片与图表（必须有信息增益）¶
- 正文配图禁止装饰性配图：每张图必须比纯文本更清晰地表达结构/对比/关系，否则删掉或改成表格/纯文本流程图。
- 章节封面图允许作为视觉分隔，但不得承载关键技术信息；如果封面图包含关键定义/门槛，必须在正文用文字/表格复述一遍。
- 图片资源放在
docs/assets/，在正文里用相对路径引用；避免把同一张图复制成多份变体。 - 每张图必须有可读的 alt 文本；并在正文首次出现处解释它“用来证明什么”，避免“图在那但不知道干什么”。
- 兼容深色背景：避免纯黑线条/低对比配色传递关键信息；透明背景图片要确认黑底不糊字。
- 外部来源图片必须注明来源与许可证/使用边界；AI 生成图若用于示意，正文应明确“示意非数据结论”。
6) 断言与证据（可裁决）¶
- 任何强断言（数字、安全、合规、成本）必须满足其一：给引用编号
[n]；或给验证方法/失败判定。 - 把建议写成门槛：主指标 + 守门指标 + 回滚动作（能落成清单/表格最佳）。
7) 常见 AI 坑（写作禁区）¶
- 不要把工具清单当结论：先讲范式与边界，再把工具放到附录。
- 不要为了显得专业而堆名词：术语首次出现应链接到 glossary，并给一句可操作定义。