编写与审核文档 Overlay

什么时候写注释，什么时候写 Overlay

• 类型、约束、参数语义、错误条件和最小正确示例写在代码注释中。
• 用户为什么需要这个 API、如何选择、常见误区、完整用例写在 Overlay 中。
• 从零到结果的连续学习路径写在教程或操作指南中。

Overlay 的身份

每份 Overlay 必须声明稳定 apiId 与它审核过的生成事实 sourceHash。AI 可以生成初稿，但不能自行把状态改为 human-reviewed。

apiId: "@flamo/runtime#createFlamoRuntime"
editorialStatus: ai-draft
sourceHash: "sha256:..."

pnpm docs:verify 会拒绝以下情况：

• apiId 在当前事实目录中不存在；
• 标记为 human-reviewed 的 Overlay 已与源码哈希不一致；
• 生成的公开 API 缺少摘要且没有 Overlay 补足。