# AIOS V2R1 生产候选报告

- 候选版本：`V2R1C0-candidate`
- 候选分支：`integration/aios-v2r1-cto-production-candidate-20260720`
- 报告语言：中文
- 架构负责人：AIOS V2 CTO
- 当前状态：代码与文档闭环已完成；精确 Commit 测试、真实 Runtime 联调和预发布验证待执行

## 1. 执行摘要

AIOS V2R1 Candidate 已完成以下核心建设：

- AIOS 唯一控制面；
- Tenant、Agent、Task、Policy、Approval 和 Audit 权威模型；
- SQLite WAL 候选持久化与重启恢复；
- Execution Orchestrator；
- OpenClaw 签名命令、Adapter、Transport、Health 和 Audit Callback；
- Hermes tenant/cell/profile 分区、Queue、Worker Lease、Heartbeat 和 Result；
- Agent Execution Evidence；
- Web Console；
- GitOps Status；
- systemd、Docker、Compose、Healthcheck 和 Rollback；
- 用户需求、目标架构、迁移策略、模块契约、追踪矩阵、文档治理和 ADR；
- 文档—代码匹配检查器；
- 全量验收入口；
- OpenClaw 预发布部署任务；
- Codex 架构监督和阻塞处理任务。

本报告不把“代码已提交”误报为“生产已验证”。以下状态仍需由无人值守任务执行并形成证据：

- 精确 Candidate Commit 的自动测试；
- 真实 OpenClaw Runtime 联调；
- Hermes 长任务、Worker 崩溃和 Lease Recovery 演练；
- systemd/Docker 预发布部署；
- 重启恢复与回滚演练；
- 本地仓库与 Gitea Candidate OID 一致验证；
- 身份代理、安全、性能和容量验证；
- Owner 对合并、Tag 和生产部署的批准。

## 2. 用户需求完成情况

| 需求 | 代码状态 | 测试状态 | 预发布状态 |
|---|---|---|---|
| AIOS 唯一控制面 | 已实现 | 已定义 | 待验证 |
| 复用 OpenClaw/Hermes/Agent Router | 已实现 | 已定义 | 待真实联调 |
| OpenClaw/Hermes 解耦 | 已实现 | 已定义 | 待旁路冻结验证 |
| 全面 Web 化 | 候选实现完成 | 冒烟测试待执行 | 待反向代理接入 |
| 多租户隔离 | 已实现 | Domain 负向测试已定义 | 待全链路安全验证 |
| 统一任务生命周期 | 已实现 | 已定义 | 待精确 Commit 执行 |
| 策略与审批 | 已实现 | 部分测试待补强 | 待身份代理验证 |
| 幂等与并发安全 | 已实现 | 基础测试已定义 | 待压力和并发验证 |
| 执行证据 | 已实现 | 已定义 | 待外部执行器持续回写 |
| GitOps 唯一流程 | 已实现并修复 Controller 冲突 | Runtime 部分验证 | 待双目标持续镜像证据 |
| 持久化与恢复 | 已实现 | 重启恢复测试已定义 | 待预发布演练 |
| 审计与合规 | 已实现候选 | 部分断言待补强 | 待不可变外部固化 |
| 密钥安全 | 引用模式已实现 | 基础扫描纳入验收 | 待 Secret Provider 联调 |
| 部署与回滚 | 资产完成 | 验收脚本已定义 | 待实际演练 |
| 文档与代码同步 | 已实现门禁 | 待精确 Commit 执行 | 待接入持续验收 |

## 3. 目标架构

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

权威边界：

- AIOS：租户、身份、Agent、任务、策略、审批、审计和执行证据；
- Agent Router：调度与路由；
- OpenClaw：签名命令执行、取消、状态、健康和回调；
- Hermes：队列、Worker、Lease、Heartbeat 和结果；
- Web：只调用 AIOS API；
- GitOps：所有代码、文档、部署和修复变更入口。

## 4. 实现清单

### 4.1 Control Plane

```text
active-runtime/app/aios_v2/control_plane.py
active-runtime/app/aios_v2/persistence.py
active-runtime/app/aios_v2/gateway.py
active-runtime/app/aios_v2/app.py
active-runtime/app/aios_v2/orchestrator.py
active-runtime/app/aios_v2/execution_tracking.py
active-runtime/app/aios_v2/gitops_status.py
active-runtime/app/aios_v2/console.py
```

### 4.2 OpenClaw

```text
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
```

### 4.3 Hermes

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

### 4.4 测试与治理

```text
tests/aios_v2_candidate/test_candidate_flow.py
tools/aios_v2_docs_code_check.py
deploy/aios-v2/acceptance/run-all.sh
```

### 4.5 部署

```text
deploy/aios-v2/systemd/aios-v2.service
deploy/aios-v2/env/aios-v2.env.example
deploy/aios-v2/docker/Dockerfile
deploy/aios-v2/docker/compose.yaml
deploy/aios-v2/healthcheck/check.sh
deploy/aios-v2/rollback/rollback.sh
```

### 4.6 文档与任务

```text
docs/aios-v2/
tasks/openclaw-production-deploy-task.yaml
tasks/codex-production-supervisor-task.yaml
```

## 5. 多租户与安全设计

### 5.1 权威上下文

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

### 5.2 OpenClaw

- HMAC-SHA256 规范化签名；
- 签名绑定 tenant/task/trace/action/payload/idempotency/time；
- Runtime Result 身份字段必须匹配；
- Secret 只通过受保护文件或引用解析。

### 5.3 Hermes

- tenant/cell/profile 分区；
- Worker Lease 与 Heartbeat；
- revision 乐观并发；
- Lease 过期自动回到 QUEUED；
- Worker 完成前停止 Heartbeat，避免 revision 竞态。

### 5.4 Web/API

- 可信代理注入 `X-AIOS-*`；
- 浏览器不选择租户；
- CSP、no-store、nosniff、DENY frame、no-referrer；
- 应用端口不得直接暴露公网。

### 5.5 GitOps

- Controller detached + clean；
- 禁止 fetch 到已检出本地分支；
- 所有修改进入分支、Commit、测试和统一审查；
- 明文 Secret 门禁；
- 文档变化与代码变化同步门禁。

## 6. 持久化策略

候选版：

- SQLite WAL；
- `synchronous=FULL`；
- `BEGIN IMMEDIATE`；
- 原子 Snapshot；
- schema version；
- 状态目录与代码版本分离；
- Execution Evidence 租户分区原子 JSON。

已知限制：

- 单进程候选优先；
- 尚无生产 RLS、多实例 HA、PITR 和容量证据；
- 后续必须通过新 ADR 迁移到生产数据层。

## 7. 测试与验收

### 7.1 文档—代码匹配

```bash
python3 tools/aios_v2_docs_code_check.py \
  --base-ref integration/aios-v2r1-cto-production-candidate-20260720
```

### 7.2 候选测试

```bash
python3 -m unittest discover \
  -s tests/aios_v2_candidate \
  -p 'test_*.py' \
  -v
```

覆盖：

- OpenClaw 完整执行；
- Hermes 完整执行；
- 跨租户拒绝；
- SQLite 重启恢复；
- Execution Evidence。

### 7.3 全量验收

```bash
bash deploy/aios-v2/acceptance/run-all.sh
```

可选在线健康检查：

```bash
AIOS_RUN_LIVE_HEALTHCHECK=1 \
  bash deploy/aios-v2/acceptance/run-all.sh
```

### 7.4 健康检查

```bash
bash deploy/aios-v2/healthcheck/check.sh
```

检查：

- systemd；
- HTTP Health；
- 状态目录；
- SQLite quick_check；
- GitOps detached/clean；
- Evidence 文件。

## 8. 部署方式

### 8.1 systemd

```text
/etc/aios-v2/aios-v2.env
/opt/aios/current
/var/lib/aios-v2
```

运行用户：`aios`。

安全选项：NoNewPrivileges、ProtectSystem、ProtectHome、PrivateTmp、Capability 限制。

### 8.2 Docker/Compose

- 非 root UID/GID；
- Read-only root filesystem；
- Drop all capabilities；
- 独立 State Volume；
- HTTP Healthcheck；
- Secret 文件只读挂载。

## 9. 回滚

```bash
bash deploy/aios-v2/rollback/rollback.sh <previous-release>
```

原则：

- 回滚前自动备份状态；
- 默认只回滚代码；
- 状态恢复需显式 `AIOS_V2_RESTORE_STATE=1`；
- 回滚后必须执行健康检查；
- 目标版本失败时自动恢复 previous release。

## 10. 无人值守任务

### OpenClaw

任务：`tasks/openclaw-production-deploy-task.yaml`

职责：

- 预发布部署；
- 健康检查；
- Runtime 联调；
- 小型部署与 Runtime Bug 修复；
- 证据回写。

### Codex

任务：`tasks/codex-production-supervisor-task.yaml`

职责：

- 架构监督；
- 阻塞分析和跨模块修复；
- 文档、测试和安全审查；
- 发布建议。

所有修改和阻塞必须进入 Git 和 Execution Evidence，最终统一审视。

## 11. 当前已知风险

| 风险 | 级别 | 当前处理 |
|---|---|---|
| 精确 Candidate Commit 尚未执行全部测试 | 高 | OpenClaw 执行，Codex 监督 |
| 真实 OpenClaw Runtime 尚未联调 | 高 | 预发布任务必须完成 |
| 候选 SQLite 不支持生产多实例 HA | 高 | Candidate 单实例；后续 ADR 迁移 |
| 身份代理 Header 防伪尚未环境验证 | 高 | 预发布安全检查 |
| Web Console 为候选只读 MVP | 中 | 生产前补充 E2E 与安全验证 |
| 部分策略负向、并发和审计测试待补强 | 中 | Codex 登记 blocker 并补充 |
| 本地/Gitea 自动双写状态仍需持续证明 | 中 | 验收记录 OID |
| 性能、容量和 SLO 尚无实测 | 中 | 预发布基准测试 |
| 外部不可变审计固化尚未实现 | 中 | 生产数据层阶段完成 |

## 12. 发布 Gate

### 允许进入预发布

条件：

- Candidate 分支可见；
- 文档完整；
- 任务合同已生成；
- 部署资产存在；
- 无明文 Secret。

### 允许进入合并审查

条件：

- 全量验收通过；
- OpenClaw/Hermes 联调通过；
- 重启和回滚通过；
- 严重/高风险 blocker 已解决；
- Codex 输出正向监督结论；
- 本地/Gitea OID 一致。

### 允许生产发布

条件：

- Owner 明确批准；
- Merge 与 Tag 通过受控流程；
- 生产配置、Secret 和反向代理准备完成；
- 发布窗口、观察指标、回滚负责人明确。

## 13. 当前结论

**代码和正式中文文档已经达到候选闭环状态，但尚不能宣称生产已验证。**

下一阶段由 OpenClaw 执行预发布部署和低风险 Bug 修复，由 Codex 监督架构、文档、安全、测试和阻塞。所有过程证据统一进入系统，满足 Gate 后再请求 Owner 批准。

## 14. 更新规则

以下变化必须更新本报告：

- Candidate Commit；
- 测试结果；
- 部署和回滚结果；
- Blocker 和风险；
- OpenClaw/Codex 任务状态；
- 文档—代码匹配状态；
- Gitea OID；
- 发布建议和 Owner 决策。

## 15. Candidate 命令签名算法

Key ID `openclaw-v2r1-candidate-ed25519` 对应真实 Ed25519 私钥，不得再把同名材料作为 HMAC key 使用。私钥由 Owner 批准流程在受保护边界内生成，文件权限为 `0600`，Owner 为实际 AIOS 服务用户；Git、日志和 Evidence 仅记录 Key ID、权限检查和 sign/verify 结果。

## 16. 2026-07-20 阻塞清除快照

五项高风险 Blocker 均已形成运行证据。`BLK-OPENCLAW-RUN-PROVENANCE-MISSING` 通过 Git 中的 `aios-tenant-boundary` rc2 插件解除：Ed25519 Owner 签发记录持久保存，授权绑定 Run、Sender、Task、Claim OID、Candidate OID 与任务分支；专用 `aios_evidence_write` 只允许七个 `.agent` JSON 和固定 Git 操作，通用 Shell/写工具保持拒绝。

Provenance `openclaw-v2r1-20260721T031523Z` 已完成 `heartbeat.json` 更新、Commit、当前任务分支普通 Push 和追加式审计；`README.md` 越权写入被拒绝。由此允许启动 Gate A、Gate B 和离线验收，但在三项验收及后续在线联调完成前仍保持 `STOP_PREPRODUCTION`。