130 lines
5.6 KiB
Markdown
130 lines
5.6 KiB
Markdown
# 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 等标准技术术语。
|