# AIOS V2 架构与交付文档索引

- 版本线：`V2R1C0-candidate`
- 候选分支：`integration/aios-v2r1-cto-production-candidate-20260720`
- 架构负责人：AIOS V2 CTO
- 当前状态：候选代码闭环已完成，运行时、预发布和生产验证尚待执行

## 1. 文档目的

本目录是 AIOS V2 用户需求、目标架构、模块边界、迁移策略、发布门禁和架构决策的唯一事实源。

所有后续架构、功能、接口、数据模型、安全策略、部署方式和验收流程变化，都必须在同一交付流程中同步更新本目录。

AIOS V2 遵循以下不可协商原则：

1. 不推倒重写现有平台。
2. 优先复用 OpenClaw、Hermes 和 Agent Router 能力。
3. OpenClaw 与 Hermes 从控制面职责中逐步解耦。
4. AIOS 是唯一控制面。
5. 所有面向用户和运维的能力必须通过 Web 或 API 访问。
6. 所有模块必须强制多租户隔离。
7. 所有修改必须通过 Git 分支、提交、测试、审查和受控提升完成。
8. 代码变化必须同步更新需求、架构、契约、追踪矩阵或 ADR。

## 2. 文档地图

| 文档 | 用途 |
|---|---|
| [01-USER-REQUIREMENTS.md](01-USER-REQUIREMENTS.md) | 产品目标、用户角色、功能需求、非功能需求和验收标准 |
| [02-TARGET-ARCHITECTURE.md](02-TARGET-ARCHITECTURE.md) | 目标逻辑架构、控制边界、数据流、安全模型和多租户模型 |
| [03-MIGRATION-AND-DELIVERY.md](03-MIGRATION-AND-DELIVERY.md) | 增量迁移、能力复用、GitOps 流程、发布门禁和回滚策略 |
| [04-MODULE-CONTRACTS.md](04-MODULE-CONTRACTS.md) | 租户上下文、任务生命周期、OpenClaw、Hermes、审计和执行证据契约 |
| [05-TRACEABILITY-MATRIX.md](05-TRACEABILITY-MATRIX.md) | 需求、设计、代码、测试、部署和验收之间的追踪关系 |
| [06-DOCUMENT-GOVERNANCE.md](06-DOCUMENT-GOVERNANCE.md) | 文档语言、完整性、同步门禁、版本与审查要求 |
| [adr/README.md](adr/README.md) | 架构决策记录索引与治理规则 |

## 3. 当前实现映射

| 架构能力 | 候选实现 |
|---|---|
| Tenant、Agent、Task、Policy 和 Audit 控制面 | `active-runtime/app/aios_v2/control_plane.py` |
| 控制面持久化 | `active-runtime/app/aios_v2/persistence.py` |
| Web/API Gateway | `active-runtime/app/aios_v2/gateway.py` |
| 统一应用入口 | `active-runtime/app/aios_v2/app.py` |
| Runtime 调度与结果回写 | `active-runtime/app/aios_v2/orchestrator.py` |
| Agent 执行证据 | `active-runtime/app/aios_v2/execution_tracking.py` |
| GitOps 状态可视化 | `active-runtime/app/aios_v2/gitops_status.py` |
| Web Console | `active-runtime/app/aios_v2/console.py` |
| OpenClaw 执行边界 | `active-runtime/app/aios_openclaw/` |
| Hermes Runtime 边界 | `active-runtime/app/aios_hermes/` |
| 候选测试 | `tests/aios_v2_candidate/` |
| 部署、健康检查与回滚 | `deploy/aios-v2/` |
| OpenClaw 生产部署任务 | `tasks/openclaw-production-deploy-task.yaml` |
| Codex 生产监督任务 | `tasks/codex-production-supervisor-task.yaml` |

## 4. 状态术语

项目必须严格区分“代码存在”和“可生产发布”：

- **已设计**：文档中存在明确边界和验收标准。
- **已实现**：代码已经提交到候选分支。
- **已定义测试**：Git 中存在自动化测试代码。
- **已验证测试**：已对精确 commit 执行测试并保存证据。
- **已验证预发布**：已在隔离环境完成部署、健康检查、重启和回滚演练。
- **已生产发布**：已取得 Owner 批准并完成合并、Tag 和生产部署。

分支、文件、测试脚本或部署脚本存在，并不自动代表能力已通过生产验收。

## 5. 设计摘要

```text
浏览器 / Web Console / Public API
                 |
                 v
          AIOS 唯一控制面
  Tenant | Agent | Task | Policy | Audit
                 |
                 v
       Execution Orchestrator / Agent Router
             /                 \
            v                   v
   OpenClaw Adapter       Hermes Boundary
            |                   |
            v                   v
   OpenClaw Runtime       Hermes Workers
                 \
                  v
       结果回写 + 审计 + 执行证据
```

控制面拥有权威身份、策略、审批、任务生命周期和审计状态。OpenClaw 与 Hermes 只接收带租户上下文、已经批准的执行工作，并返回运行结果。

## 6. 发布规则

候选版本在满足以下条件前不得提升：

- 需求到代码的追踪关系完整；
- 文档—代码匹配检查通过；
- 多租户负向测试通过；
- GitOps Controller worktree 保持 detached 且 clean；
- 本地 Git 与 Gitea 目标分支 OID 一致；
- 持久化重启恢复测试通过；
- 预发布健康检查和回滚演练通过；
- Git 中不存在明文密钥；
- OpenClaw 与 Hermes 真实 Runtime 联调通过；
- Owner 对合并、Tag 和生产部署做出明确批准。

## 7. 文档完整性要求

每份正式文档必须包含：

- 文档目的与适用范围；
- 当前版本和状态；
- 关键设计或需求正文；
- 代码、测试或部署映射；
- 验收与更新规则；
- 已知限制和后续演进方向。

禁止在正式归档包中以摘要、占位符或“后续补充”代替正文。

## 8. 中文输出要求

所有面向用户、产品、架构、运维和审计的正式文档统一使用中文。以下技术标识保留原始英文，避免与代码不一致：

- 类名、函数名、字段名；
- API 路径和 HTTP Header；
- Git 分支、Commit、Tag；
- OpenClaw、Hermes、Agent Router、GitOps 等专有名称；
- systemd、Docker、SQLite、HMAC、HTTP 等标准技术术语。