深度章节写作标准¶
本书不是 API 清单，也不是把官方 README 换一种说法。每个成熟章节都应当形成一条可以复核的论证链：
一章必须回答的八个问题¶
- 为什么需要它？ 从真实任务或失败现象引出，而不是从术语定义开始堆名词。
- 边界在哪里？ 说明本概念负责什么、不负责什么，并处理最容易混淆的相邻概念。
- 它怎样运行？ 至少给出一条端到端数据流、控制流或状态变化过程。
- DSH 怎样实现？ 链接到锁定提交中的官方文档、公开类型或源码主线。
- 为什么这样设计？ 解释收益、代价、替代方案和成立前提。
- 哪里会失败？ 给出可观察表象、可能根因和诊断证据，而不只写抽象风险。
- 怎样验证？ 配套实验必须包含预测、操作、验收和证据；文件存在不等于已执行。
- 哪些结论可迁移？ 区分版本相关 API 与穿越版本的工程原则。
证据标签¶
章节中的重要事实应能归入以下层级：
- 官方保证：官方文档或公开接口明确承诺；
- 源码观察：锁定提交中的实现事实；
- 实验结论：已在记录环境运行并保存证据；
- 工程建议：作者基于风险、成本和维护性给出的判断。
不能用较弱证据冒充较强结论。例如，测试源码存在只能算源码观察，不能标成实验通过；仓库中存在某插件，不能证明当前 Profile 已加载。
深度不是字数¶
字数、标题数、图表数只能作为防止章节退化为提纲的最低门禁，不能代替内容质量。一个章节即使很长，如果只有概念罗列，没有机制、反例和证据，仍然不合格。
建议成熟章节至少包含：
- 一个贯穿章节的真实问题；
- 一张边界图或端到端运行图；
- 一个具体轨迹或状态变化示例；
- 一组源码路标，且固定到
upstream.lock.json的提交； - 一个设计权衡或替代方案比较；
- 一个失败模式/诊断表；
- 一个可执行或可验证的配套实验；
- 分层思考题与至少一道系统设计面试题。
与社区迭代同步¶
更新上游基线时，不应自动把新 API 名称批量替换进正文。维护者需要重新检查：
- 章节论证的架构问题是否仍然成立；
- 当前实现答案发生了什么变化；
- 原源码链接与实验是否仍可复现；
- 兼容性矩阵和实验状态是否需要降级；
- 是否应保留旧版本差异，帮助读者理解设计演进。
章节的长期价值来自稳定问题与版本答案的明确分离。