AIOS V2 架构决策记录索引
- 文档版本：
V2R1-hardening-candidate - 适用范围：影响多个模块、长期演进、兼容性、安全、数据、部署或交付流程的关键架构决策
1. 架构决策记录列表
| 编号 | 决策 | 状态 |
|---|---|---|
| ADR-001 | AIOS 作为唯一控制面 | 已采纳 |
| ADR-002 | OpenClaw 与 Hermes 从控制面职责中解耦 | 已采纳 |
| ADR-003 | 所有变更必须通过 GitOps | 已采纳 |
| ADR-004 | 多租户隔离采用默认拒绝模型 | 已采纳 |
| ADR-005 | 文档与代码同步门禁 | 已采纳 |
| ADR-006 | 候选持久化采用可替换 SQLite Snapshot | 已采纳 |
| ADR-007 | 当前仓库未分配；禁止补写不存在的历史决策 | 未分配 |
| ADR-008 | 当前仓库未分配；禁止补写不存在的历史决策 | 未分配 |
| ADR-009 | Workflow Provenance、最小权限子 Grant 与服务级 Scope | 已采纳 |
| ADR-010 | Hermes 在线生命周期使用默认关闭的内部 Runtime API | RC 已采纳；待 Owner 发布批准 |
2. 编号规则
- ADR 编号一经发布不得重用。
- 编号缺口可以保留，不能通过伪造历史文件填补。
- 新决策使用下一个未占用编号，并在同一分支更新本索引、模块契约和追踪矩阵。
- ADR-007 与 ADR-008 在当前仓库没有可验证历史文件，因此明确标记为未分配。
3. 状态定义
- 已提出：决策已提出，但尚未被正式采纳。
- 已采纳：当前有效，所有新实现必须遵守。
- 已替代：已被新的 ADR 替代，保留用于历史追踪。
- 已废弃：保留历史，但禁止新实现继续采用。
- 未分配：该编号当前没有 ADR 文件，不代表存在隐含历史决策。
4. 必须新增或更新 ADR 的场景
以下变化必须新增或更新 ADR：
- AIOS、OpenClaw、Hermes、Agent Router 的控制边界变化；
- 多租户隔离模型变化；
- API、数据模型或状态机出现不兼容变化；
- 持久化、消息、密钥、审计或部署方案发生跨模块变化；
- GitOps、发布、回滚或文档门禁变化；
- 替换 OpenClaw、Hermes、Agent Router 或核心基础设施；
- 引入新的权威事实源、任务生命周期或租户状态；
- 生产安全模型、身份代理、Run Provenance、Grant 或 Secret 管理方式变化；
- Runtime Result、Dispatch 或服务 Scope 信任边界变化。
5. ADR 内容要求
每份 ADR 必须包含：
- 背景；
- 决策；
- 备选方案；
- 采用理由；
- 正面影响；
- 负面影响和风险；
- 迁移与回滚；
- 合规检查；
- 受影响的代码、测试和文档。
6. ADR 变更联动
ADR 新增、替代或废弃时，必须同步检查并更新：
01-USER-REQUIREMENTS.md；02-TARGET-ARCHITECTURE.md；03-MIGRATION-AND-DELIVERY.md；04-MODULE-CONTRACTS.md；05-TRACEABILITY-MATRIX.md；- 相关代码、测试和部署资产；
- 候选或 Gate 报告中的风险与发布结论。
7. 审查规则
- OpenClaw 不得自行采纳改变控制面边界的 ADR；发现需求后必须升级给 Codex。
- Codex 负责审查 ADR 与代码、测试和文档是否一致。
- 涉及合并、Tag、生产部署或重大风险接受的 ADR，必须由 AIOS Owner 最终批准。
- ADR 未完成审查前，相关变更不得标记为
Test-verified或Production released。 - ADR、测试文件或 Acceptance 脚本存在，不等于 Gate 已通过；必须有实际执行日志、退出码和证据。