# AIOS V2 目标架构

- 文档版本：`V2R1C0-candidate`
- 架构状态：目标架构已实现为候选代码，待预发布验证
- 适用范围：Control Plane、Agent Router、OpenClaw、Hermes、Web Console、GitOps、审计、部署与运维

## 1. 架构目标

AIOS V2 的核心目标是把分散在 OpenClaw、Hermes、Agent Router、局部 WebUI 和 GitOps 中的控制能力收敛为一个权威控制面，同时保留现有执行能力，避免推倒重写。

目标状态：

```text
用户 / Web Console / Public API
                 |
                 v
          AIOS Control Plane
 Tenant | Identity | Agent | Task | Policy | Approval | Audit
                 |
                 v
      Execution Orchestrator / Agent Router
             /                      \
            v                        v
   OpenClaw Adapter            Hermes Boundary
            |                        |
            v                        v
   OpenClaw Runtime            Hermes Workers
             \                      /
              v                    v
       Result Reconciliation + Execution Evidence
```

设计结论：

- AIOS 是唯一控制面。
- Agent Router 是调度平面，不是第二控制面。
- OpenClaw 是执行适配与 Runtime。
- Hermes 是队列、Worker、Profile 与执行 Runtime。
- Web Console 只调用 AIOS API。
- GitOps 是代码、配置、文档和发布变更的唯一入口。

## 2. 从现有架构到目标架构

### 2.1 现有能力

现有系统已经具备：

- OpenClaw 执行与 Fleet 能力。
- Hermes Worker、Profile、队列和工作区能力。
- Agent Router 路由经验和部分调度接口。
- GitOps 分支、提交、审批、回滚和审计能力。
- Tenant Context、Tenant Router、Memory Scope、SecretRef、Message Ledger 和审计候选实现。
- 局部 WebUI、Gateway 和自动任务领取能力。

### 2.2 现有问题

- 控制逻辑分散，可能存在多个任务事实源。
- OpenClaw/Hermes 内部仍可能保存租户、策略或任务状态。
- 候选能力分散在多个分支，主线缺少权威实现。
- WebUI 与 API 入口不统一。
- 分支名称、代码、测试和部署证据之间缺少映射。
- 多租户隔离多为逻辑约束，尚缺全链路生产证据。

### 2.3 演进原则

- 先加边界和适配器，再迁移控制权。
- 先复用接口，再替换内部实现。
- 先在候选分支验证，再受控提升。
- 不允许同时存在两套权威任务生命周期。
- 不以“大分支存在”代替验收证据。

## 3. 逻辑分层

### 3.1 Web 与 API 层

职责：

- 提供 Tenant、Agent、Task、Approval、Runtime、Audit、Execution Evidence 和 GitOps 页面/API。
- 依赖可信身份代理注入 `X-AIOS-*` 身份头。
- 不允许浏览器直接访问 OpenClaw 或 Hermes。
- 不允许客户端自行选择或覆盖 `tenant_id`。

候选实现：

- `active-runtime/app/aios_v2/app.py`
- `active-runtime/app/aios_v2/gateway.py`
- `active-runtime/app/aios_v2/console.py`

### 3.2 AIOS Control Plane

权威职责：

- Tenant Registry
- Agent Registry
- Task Lifecycle
- Policy Decision
- Approval
- Audit Event
- Runtime Inventory
- Execution Evidence
- Deployment/GitOps Status

不负责：

- OpenClaw 内部执行细节。
- Hermes Worker 内部执行细节。
- 直接持有 Runtime 凭据明文。

候选实现：

- `active-runtime/app/aios_v2/control_plane.py`
- `active-runtime/app/aios_v2/persistence.py`
- `active-runtime/app/aios_v2/execution_tracking.py`
- `active-runtime/app/aios_v2/gitops_status.py`

### 3.3 Execution Orchestrator / Agent Router

职责：

- 只接受 `APPROVED` 任务。
- 根据 Agent Registry 和 Policy Result 选择 Runtime。
- 生成 OpenClawCommand 或 HermesJob。
- 传播 tenant、task、trace、idempotency 和 policy version。
- 将 Runtime Result 回写 AIOS Task。

不负责：

- 创建租户。
- 修改策略。
- 绕过审批。
- 保存第二套任务状态机。

候选实现：

- `active-runtime/app/aios_v2/orchestrator.py`

### 3.4 OpenClaw Adapter

职责：

- 验证签名命令。
- 执行、查询、取消、健康检查和回调。
- 支持幂等、超时和租户隔离。
- 把 Runtime 生命周期转换为 AIOS 审计事件。

不负责：

- Tenant、Policy、Approval、Task Lifecycle。
- 向浏览器暴露公网控制接口。

候选实现：

- `active-runtime/app/aios_openclaw/contract.py`
- `active-runtime/app/aios_openclaw/adapter.py`
- `active-runtime/app/aios_openclaw/transport.py`
- `active-runtime/app/aios_openclaw/health.py`
- `active-runtime/app/aios_openclaw/callback.py`

### 3.5 Hermes Runtime Boundary

职责：

- Tenant/Cell/Profile 分区队列。
- Worker claim、start、heartbeat、complete、fail、cancel。
- Lease 超时和自动回队列。
- Result 回传和 Runtime Health。

不负责：

- Policy、Approval、Tenant Registry、权威 Task Lifecycle。

候选实现：

- `active-runtime/app/aios_hermes/contract.py`
- `active-runtime/app/aios_hermes/adapter.py`
- `active-runtime/app/aios_hermes/worker.py`

### 3.6 Persistence

候选实现使用 SQLite WAL 原子快照，持久化：

- Tenant
- Agent
- Task
- Audit
- Idempotency
- Execution Evidence 文件

生产演进：

- Store 接口保持稳定。
- 可替换为 PostgreSQL、对象存储或分布式事件存储。
- 生产替换必须提供迁移、备份、恢复、HA、容量和租户隔离证据。

## 4. 多租户架构

### 4.1 权威租户上下文

每次请求和执行至少传播：

```text
tenant_id
principal_id
session_id
trace_id
task_id
policy_version
```

Runtime 还传播：

```text
command_id / job_id
cell_id
profile_id
idempotency_key
worker_id
```

### 4.2 隔离层级

| 层级 | 隔离要求 |
|---|---|
| HTTP/API | 可信身份头、租户不可由浏览器覆盖 |
| Control Plane | 所有资源带 `tenant_id`，跨租户默认拒绝 |
| OpenClaw | 签名命令绑定 tenant/task/trace |
| Hermes | tenant/cell/profile 三层分区 |
| Storage | 候选为显式租户字段；生产需 RLS 或物理隔离策略 |
| Evidence/Audit | 仅按当前租户查询 |
| Cache/Memory | key 必须包含 tenant namespace |
| Secret | 只保存引用，不保存明文 |
| Logs/Metrics | 必须包含 tenant/task/trace 标签，并限制查询范围 |

### 4.3 失败行为

- 跨租户资源访问返回拒绝或“未找到”。
- 不泄露其他租户资源存在性。
- 缺少 tenant context 时 fail closed。
- Runtime 返回的 tenant/task/trace 不匹配时拒绝回写。

## 5. 任务与执行数据流

### 5.1 任务创建与审批

```text
User/API
   |
   v
Trusted Identity
   |
   v
AIOS Gateway
   |
   v
Policy Gate
   |
   v
Task CREATED
   |
   v
Approval
   |
   v
Task APPROVED
```

### 5.2 OpenClaw 执行

```text
APPROVED Task
   |
   v
Execution Orchestrator
   |
   v
Signed OpenClawCommand
   |
   v
OpenClaw Adapter
   |
   v
Runtime Result
   |
   v
Task Reconciliation + Audit + Evidence
```

### 5.3 Hermes 执行

```text
APPROVED Task
   |
   v
Execution Orchestrator
   |
   v
Tenant/Cell/Profile HermesJob
   |
   v
Worker Claim + Lease + Heartbeat
   |
   v
HermesResult
   |
   v
Task Reconciliation + Audit + Evidence
```

## 6. 安全架构

### 6.1 身份边界

- Public API 位于可信反向代理之后。
- 反向代理完成登录、会话、MFA 和身份头注入。
- 候选应用拒绝未认证身份断言。
- 生产不得允许客户端直接伪造 `X-AIOS-*`。

### 6.2 Runtime 命令完整性

OpenClawCommand 使用规范化序列化和 HMAC-SHA256：

- 签名覆盖 tenant、task、trace、action、payload、idempotency 和时间。
- 支持 key ID、到期时间和时钟偏差。
- Runtime 密钥通过受保护文件或外部 Secret Provider 解析。

### 6.3 Secret 边界

Git 允许：

```text
secret_ref
credential_ref
key_id
受保护文件路径
```

Git 禁止：

```text
API Key
密码
Token
私钥
签名材料
```

### 6.4 Web 安全

候选应用设置：

- no-store
- nosniff
- DENY frame
- no-referrer
- CSP
- 请求体大小限制

生产还需验证：

- CSRF/CORS
- Rate Limit
- Session Timeout
- CSP Nonce/Hash
- WAF 和反向代理访问策略

## 7. 可靠性架构

### 7.1 幂等

- Control Plane：`tenant_id + idempotency_key + request_digest`。
- OpenClaw：`tenant_id + idempotency_key + signature`。
- Hermes：`tenant_id + idempotency_key + job_digest`。

### 7.2 并发

- Task 使用 revision。
- Hermes 使用 revision + worker lease。
- GitOps 使用 detached controller + branch lease。
- 持久化使用 SQLite `BEGIN IMMEDIATE` 和原子快照。

### 7.3 恢复

- Controller restart：detached guard。
- AIOS restart：SQLite restore。
- Worker crash：lease 到期后 Job 回到 QUEUED。
- Release failure：健康检查失败自动恢复 previous release。

## 8. 可观测架构

统一关联键：

```text
tenant_id
principal_id
trace_id
task_id
agent_id
command_id / job_id
worker_id
commit
```

Web Console 展示：

- Tasks
- Agents
- Runtime Health
- Audit
- Execution Evidence
- GitOps Status

生产还需接入：

- 结构化日志
- Metrics
- Distributed Tracing
- Alerting
- SLO Dashboard

## 9. 部署架构

支持两种候选部署：

### systemd

- 非 root `aios` 用户。
- `ProtectSystem=strict`、`NoNewPrivileges` 等安全选项。
- 状态目录 `/var/lib/aios-v2`。

### Docker/Compose

- 非 root UID/GID。
- Read-only root filesystem。
- Drop all capabilities。
- State volume。
- HTTP healthcheck。

## 10. 架构约束

以下行为视为架构违规：

1. OpenClaw/Hermes 直接创建或批准 AIOS Task。
2. Web Console 直接调用 Runtime。
3. 新模块不携带 `tenant_id`。
4. 新增第二套任务状态机或租户事实源。
5. 在 Git 中提交明文凭据。
6. 绕过 GitOps 修改生产代码/配置。
7. 架构或功能变化未同步更新 `docs/aios-v2/`。
8. 未通过测试和预发布门禁直接提升候选版本。

## 11. 目标架构完成判定

目标架构只有在以下证据齐全时才视为完成：

- 文档与代码映射完整。
- Candidate tests 对精确 commit 执行通过。
- OpenClaw/Hermes 实际 Runtime 联调通过。
- 多租户负向测试通过。
- 重启恢复和回滚演练通过。
- GitOps 本地/Gitea OID 一致。
- Owner 批准 merge、Tag 和生产部署。