7.8 KiB
7.8 KiB
AIOS V2 文档治理规范
- 文档版本：
V2R1C0-candidate - 适用范围：
docs/aios-v2/、架构决策记录、生产候选报告、在线任务合同、部署与验收说明 - 状态：已采纳
1. 目的
本规范用于保证 AIOS V2 的需求、架构、代码、测试、部署和运行事实始终保持一致，避免出现以下问题：
- 代码已经变化，但架构文档仍描述旧边界；
- API、字段或状态机变化后，测试与追踪矩阵未同步；
- OpenClaw、Hermes 或 Agent Router 的控制职责发生漂移；
- 候选分支存在实现，但版本无法解释为什么这样设计；
- 部署、回滚或安全策略发生变化，却没有形成可审计文档；
- 归档包只包含摘要或占位符，无法作为正式交付材料。
2. 文档语言要求
所有面向用户、产品、架构、运维、审计和发布的正式文档统一使用中文。
以下内容保留原始英文技术标识：
- 类名、函数名、字段名、环境变量；
- API 路径、HTTP 方法和 Header；
- Git 分支、Commit、Tag；
- OpenClaw、Hermes、Agent Router、GitOps 等专有名称；
- systemd、Docker、SQLite、HMAC、HTTP、JSON 等标准术语。
禁止在同一文档中无必要地切换中英文叙述。
3. 文档完整性要求
每份正式文档至少包含：
- 文档目的；
- 适用范围；
- 当前版本和状态；
- 完整正文；
- 与代码、测试或部署的映射；
- 验收规则；
- 已知限制；
- 后续演进方向；
- 更新触发条件。
正式归档包禁止使用以下内容代替正文：
- “后续补充”；
- “待完善”；
- 只有标题没有说明；
- 只包含目录摘要；
- 与候选分支代码不一致的旧文档。
确实尚未验证的项目，应明确标记为“已实现但尚未验证”，并说明验证命令、责任方和进入下一状态的条件。
4. 文档分类与维护责任
| 文档 | 主要内容 | 触发更新的变化 |
|---|---|---|
README.md |
文档索引、版本状态、实现地图 | 新增模块、目录、版本或交付物 |
01-USER-REQUIREMENTS.md |
用户目标、功能需求、非功能需求、验收场景 | 用户行为、产品范围、验收标准变化 |
02-TARGET-ARCHITECTURE.md |
分层、边界、数据流、安全、租户、部署架构 | 控制权、Runtime 边界、数据流或安全模型变化 |
03-MIGRATION-AND-DELIVERY.md |
迁移阶段、GitOps、发布门禁、回滚、Bug 修复 | 迁移路线、发布流程、门禁或回滚方式变化 |
04-MODULE-CONTRACTS.md |
数据模型、API、状态机、错误语义、Runtime Contract | 字段、接口、状态机、Header、错误行为变化 |
05-TRACEABILITY-MATRIX.md |
需求到代码、测试、部署、验收的映射 | 代码、测试、部署路径或状态变化 |
adr/* |
跨模块、长期或不可逆架构决策 | 关键决策新增、替换或废弃 |
AIOS-V2R1-PRODUCTION-CANDIDATE.md |
候选版本总览、测试、部署、风险和发布结论 | Candidate SHA、测试证据、部署或风险变化 |
tasks/* |
OpenClaw、Codex 等在线执行任务 | 职责、边界、阻塞、验收或执行流程变化 |
5. 代码变化与文档同步规则
以下代码或配置路径发生变化时，必须同步更新 docs/aios-v2/：
5.1 Control Plane
触发路径：
active-runtime/app/aios_v2/control_plane.py
active-runtime/app/aios_v2/persistence.py
active-runtime/app/aios_v2/gateway.py
active-runtime/app/aios_v2/app.py
active-runtime/app/aios_v2/orchestrator.py
active-runtime/app/aios_v2/execution_tracking.py
active-runtime/app/aios_v2/gitops_status.py
至少检查：
- 用户需求；
- 目标架构；
- 模块契约；
- 追踪矩阵；
- 必要时新增或更新 ADR。
5.2 OpenClaw
触发路径：
active-runtime/app/aios_openclaw/
至少检查：
- OpenClawCommand、OpenClawResult、RuntimeHealth；
- 签名、幂等、取消、超时和审计边界；
- ADR-002；
- 真实 Runtime 联调要求。
5.3 Hermes
触发路径：
active-runtime/app/aios_hermes/
至少检查：
- HermesJob、HermesResult、HermesHealth；
- tenant/cell/profile 分区；
- Worker Lease、Heartbeat、Recovery；
- ADR-002、ADR-004。
5.4 部署与运维
触发路径：
deploy/aios-v2/
至少检查：
- 迁移与交付策略；
- 部署契约；
- 健康检查；
- 回滚；
- 候选报告。
5.5 API、Web 与用户行为
任何 API 路径、Header、请求/响应、页面或用户操作变化，必须同步：
01-USER-REQUIREMENTS.md；02-TARGET-ARCHITECTURE.md；04-MODULE-CONTRACTS.md；05-TRACEABILITY-MATRIX.md。
6. ADR 治理
必须新增或更新 ADR 的场景：
- AIOS、OpenClaw、Hermes、Agent Router 的控制边界变化；
- 多租户隔离模型变化；
- 持久化、消息、审计、密钥或部署出现跨模块变化；
- 不兼容 API、字段或状态机变化；
- GitOps、文档门禁或发布策略变化；
- 替换核心基础设施或引入新的权威事实源。
ADR 状态：
已提出：尚未正式采纳；已采纳：当前有效；已替代：被新 ADR 替代；已废弃：保留历史但禁止新实现采用。
任何 ADR 替代必须说明：
- 被替代的 ADR；
- 迁移影响；
- 兼容性和回滚方案；
- 受影响代码、测试和文档。
7. 文档—代码匹配门禁
验收必须执行：
python3 tools/aios_v2_docs_code_check.py
门禁至少检查：
- 必需文档存在且非空；
- 文档语言以中文为主；
- 文档引用的关键代码、测试和部署路径存在；
- 文档列出的核心 API 能在代码中找到；
- 文档列出的核心模型和字段能在代码中找到；
- Traceability Matrix 覆盖所有
UR-*需求； - ADR 索引引用的文件存在；
- 架构或功能代码变化时，当前交付范围包含
docs/aios-v2/变化； - 文档中不存在未解决 Git 冲突标记；
- 正式文档中不存在摘要占位符或空章节。
门禁失败时：
- Candidate 不得标记为
Test-verified； - OpenClaw 不得继续生产部署；
- Codex 必须登记 blocker 并给出修复建议；
- 修复必须进入 Git 分支并统一审视。
8. 在线任务文档要求
OpenClaw 和 Codex 任务必须使用中文说明，并保留可执行字段名。
每个任务至少包含：
- 任务目标；
- 责任范围；
- 禁止事项；
- 输入和输出；
- 分支；
- 执行状态；
- 验收命令；
- claim、heartbeat、progress、blocker、commit、test_status、result 证据要求；
- 阻塞升级路径。
9. 归档包要求
正式归档包必须包含完整正文：
docs/aios-v2/
tasks/openclaw-production-deploy-task.yaml
tasks/codex-production-supervisor-task.yaml
deploy/aios-v2/
AIOS-V2R1-PRODUCTION-CANDIDATE.md
归档包必须同时生成清单：
- 文件路径；
- 文件大小；
- SHA-256；
- Candidate branch；
- Candidate commit；
- 生成时间。
禁止只打包摘要副本。
10. 审查职责
OpenClaw
- 部署和运行修复时同步相关部署、运维和已知问题文档；
- 不得修改架构边界；
- 发现架构影响时升级给 Codex。
Codex
- 监督需求、架构、契约、追踪和 ADR 一致性；
- 解决阻塞；
- 拒绝缺少文档或证据的补丁；
- 输出统一发布建议。
AIOS Owner
- 审批合并、Tag 和生产部署；
- 对重大架构决策和风险接受做最终确认。
11. 验收状态
文档完成状态只有在以下条件全部满足时才标记为“完整”：
- 所有必需文档和 ADR 已提交；
- 文档—代码匹配检查通过；
- 归档包包含仓库完整正文；
- 任务合同为中文完整版本；
- Candidate commit、清单和 SHA-256 已记录；
- Codex 监督结论不存在未解决阻塞。