# docs/AGENTS.md —— 文档标准

本文件定义本仓库文档的分层、事实归属、写作规则与审稿清单。根 [AGENTS.md](../AGENTS.md)
只保留落点与登记红线；代码注释规范见 [MODULE-COMMENTS.md](./MODULE-COMMENTS.md) 与
[CODE-COMMENTS.md](./CODE-COMMENTS.md)。

## 1. 分层：一个事实一个家

每类事实只有一个 home；其他地方只写一句话摘要 + 相对链接，不复述细节。

| 层 | 位置 | 职责 | 不放什么 |
| --- | --- | --- | --- |
| 常驻规则 | 根 `AGENTS.md` | 每个会话都必须进上下文的红线，每条 1–3 行 | 教程、完整清单、实测记录、能从链接读到的细节 |
| 文档标准 | `docs/AGENTS.md` | 分层、归属、写作与审稿规则 | 具体契约（→ 各规范文档） |
| 索引 | `docs/README.md` | 每份文档一句话用途 + 链接 | 状态注解、实现细节、重复规则 |
| 契约与规范 | `docs/CONTRACT-TS.md` 等 | 当前设计、接口、命令形态、存储 / 日志 / Web 规则 | 变更史、设计取舍（→ 设计依据文档）、进度 |
| 设计依据 | `docs/ACCOUNT-CIRCUIT.md` 等 | 为什么这样做、放弃了什么、实测证据；规则收敛后指向 owning doc | 重复的现行规则 |
| 渠道协议 | `docs/channels/<cid>/PROTOCOL.md` | 上游协议事实与证据等级 | 共享层规则、实现细节 |
| 状态快照 | `docs/PROGRESS.md` | 当前版本、渠道状态、已知边界 | 契约条文 |
| 门面 | 根 `README.md` | 项目是什么、怎么开始、去哪找文档 | 详细交互规则、契约细节 |
| 流程 | `.agents/skills/<name>/SKILL.md` | 多步操作流程与验收清单 | 单点事实（→ `docs/`） |

## 2. 写作规则

1. **只写当前状态**：历史、变更过程、为什么改，属于 git / PR / 设计依据文档；正文不写
   「以前是……现在改为……」或「本次修改」。
2. **一个事实一个家**：同一条规则出现第二遍就是漂移源。保留最靠近该事实的文档，其他位置
   写一句摘要 + 链接。
3. **索引只写用途**：`docs/README.md` 的表格行是一句话导航，不写「已实施 / 已收敛 / 待实施」。
   设计依据文档顶部允许一行状态（是否已收敛、收敛到哪里）；当前能力与进度统一看
   [PROGRESS.md](./PROGRESS.md)。
4. **不写能力状态注解**：「已实现」「未来支持」「TODO」会腐烂。能力是否存在由代码、包清单
   和 `mx` 命令输出回答；未完成项进 `ROADMAP.md` 或 issue。
5. **不手抄清单**：命令、模型、渠道、字段、测试数量以源码 / 生成物 / CLI 输出为准；文档只写
   规则与判据，需要枚举时链接到唯一来源。
6. **不写推理过程**：保留结论、取舍、约束、失败模式、验证方式；删除「先试了 A，又试了 B」的
   过程叙述。实测证据例外：日期绑在外部事实上（上游行为、风控、限流）时必须写，并标注证据等级。
7. **一段一个主题**：避免把多条规则塞进一个长段；需要并列时用列表或表格。
8. **强调节制**：粗体、全大写、「注意」只留给会改变行为的句子。
9. **术语直接**：用「响应字段」「JSON 校验」「CLI 输出」这类具体词，不用「形状」「边界」「面」
   等隐喻；「为什么」与「怎么做」分开写。

## 3. 链接与引用

- 站内链接一律相对路径；外链写全 URL。
- 源码引用用仓库根相对路径 + 行号（如 `packages/core/gateway/src/...:12`）；
  `scripts/verify-docs.mjs` 会校验文件存在且行号不越界。
- 历史引用用 tag / PR 编号，不写 commit SHA（rebase 会重写，SHA 不可靠）。
- 不在文档里复制大段源码；引用接口时用签名 + 指向实现的路径。

## 4. 文档类型

- **参考**：定义当前行为与契约，按主题组织，不要求顺序阅读。`docs/` 下绝大多数属于此类。
- **教程 / 流程**：按步骤达成一个结果，每步有可验证动作。多步操作放 `.agents/skills/`；
  安装、构建、发版等固定步骤放 [WORKFLOW.md](./WORKFLOW.md)。
- **设计依据**：记录为什么、放弃了什么、证据是什么；规则一旦收敛进 owning doc，本文只留
  设计依据并在顶部指向新家。

## 5. 预算

- 根 `AGENTS.md` ≤ 30,000 字节（`scripts/verify-docs.mjs` 强制；Codex 默认 32,768 字节会静默截断）。
- 新增文档以「一次能读完」为度，建议不超过约 30 KB；超过时先按主题评估拆分并登记索引。
  现有 `CONTRACT-TS.md` / `POOL-ARCHITECTURE.md` / `WEB-CONSOLE.md` 已超过该体积，不为了数字硬拆，
  在下次大幅改写时再按主题收敛。
- 预算不是压缩指标：超限先迁移（搬到正确层级），再压缩，最后才考虑放宽上限；放宽要在 PR 里说明理由。

## 6. 审稿清单

- [ ] 这条事实是否已有 home？有就改成链接。
- [ ] 是否出现「已实施 / 待实施 / 以前 / 本次」这类会过期的表述？
- [ ] 是否手抄了命令、模型、渠道、字段或测试数量？
- [ ] 是否把推理过程、评审讨论、测试步骤写进了契约文档？
- [ ] 是否有一段承载多条规则？
- [ ] 链接是否相对、可达？源码引用是否带行号且校验通过？
- [ ] 新增 / 改名 / 删除的文档是否登记到 [docs/README.md](./README.md)？
- [ ] 文档是否与代码在同一个 commit？

## 7. 机械门禁

`scripts/verify-docs.mjs` 在 `npm test` 中检查：md 落点、渠道 `PROTOCOL.md` 存在性、相对链接
可达、`file:line` 源码引用有效、索引登记、技能登记、根 `AGENTS.md` 字节上限。
「文档与代码同 commit」「中文」「无 emoji」「一个事实一个家」属于评审约束，脚本不检查。