AIOS V2 架构与交付文档索引

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

1. 文档目的

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

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

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

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

2. 文档地图

文档	用途
01-USER-REQUIREMENTS.md	产品目标、用户角色、功能需求、非功能需求和验收标准
02-TARGET-ARCHITECTURE.md	目标逻辑架构、控制边界、数据流、安全模型和多租户模型
03-MIGRATION-AND-DELIVERY.md	增量迁移、能力复用、GitOps 流程、发布门禁和回滚策略
04-MODULE-CONTRACTS.md	租户上下文、任务生命周期、OpenClaw、Hermes、审计和执行证据契约
05-TRACEABILITY-MATRIX.md	需求、设计、代码、测试、部署和验收之间的追踪关系
06-DOCUMENT-GOVERNANCE.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. 设计摘要

浏览器 / 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 等标准技术术语。

5.6 KiB Raw Blame History Unescape Escape