# AIOS V2 迁移与交付策略

- 文档版本：`V2R1C0-candidate`
- 交付原则：增量迁移、能力复用、控制权收敛、GitOps 唯一变更入口

## 1. 迁移目标

AIOS V2 不通过一次性重写替换现有系统，而是在保留 OpenClaw、Hermes、Agent Router、GitOps 和既有运行能力的前提下，将租户、策略、任务、审批、审计和发布治理收敛到 AIOS Control Plane。

迁移完成的标志不是“新代码存在”，而是：

- AIOS 成为唯一权威控制面；
- OpenClaw/Hermes 不再保存第二套控制状态；
- 所有控制功能 Web/API 化；
- 所有模块通过租户隔离、测试和预发布门禁；
- 本地 Git、Gitea、测试、部署和回滚证据可追踪。

## 2. 为什么采用增量迁移

### 2.1 避免能力回退

OpenClaw、Hermes 和 Agent Router 已经包含大量运行经验、边界处理和执行能力。整体重写会扩大风险面，并导致业务能力、操作流程和历史数据回退。

### 2.2 保持可回滚

每个迁移步骤必须：

- 独立分支；
- 小范围提交；
- 独立测试；
- 可单独回滚；
- 不要求立即关闭旧执行路径。

### 2.3 先收敛控制权，再优化内部实现

迁移优先级：

```text
唯一入口
  -> 权威租户/任务/策略
  -> Runtime Adapter
  -> 数据层生产化
  -> Web 与可观测
  -> 性能与 HA
```

## 3. 分阶段迁移路线

### Phase 0：GitOps 与架构事实源

目标：建立可靠变更链和权威设计基线。

已完成候选能力：

- Controller detached guard；
- 避免 fetch 到已检出本地分支；
- Gitea SSH 镜像；
- `docs/aios-v2/` 架构事实源；
- 候选分支、部署和回滚资产。

退出条件：

- Controller detached 且 clean；
- 本地/Gitea OID 一致；
- 架构与需求文档纳入版本。

### Phase 1：Control Plane 权威化

目标：将 Tenant、Agent、Task、Policy、Approval 和 Audit 收敛到 AIOS。

候选实现：

- `aios_v2/control_plane.py`
- `aios_v2/persistence.py`
- `aios_v2/gateway.py`
- `aios_v2/app.py`

退出条件：

- 任务状态机统一；
- 幂等、revision、审计和跨租户拒绝通过测试；
- 服务重启后权威状态恢复。

### Phase 2：OpenClaw 解耦

目标：OpenClaw 从控制逻辑转为执行适配器。

步骤：

1. 定义签名命令合同；
2. 引入 Adapter；
3. 将直接调用迁移到 AIOS Orchestrator；
4. Runtime 只返回执行结果和健康状态；
5. 关闭或网络隔离旧公共控制入口。

退出条件：

- 未批准任务无法生成有效命令；
- 命令绑定 tenant/task/trace/idempotency；
- 旧控制接口冻结并记录替代路径。

### Phase 3：Hermes 解耦

目标：Hermes 只承担租户分区队列和 Worker Runtime。

步骤：

1. 定义 HermesJob/HermesResult；
2. 强制 tenant/cell/profile 分区；
3. 引入 claim/lease/heartbeat；
4. 将结果统一回写 AIOS；
5. 移除 Hermes 内部策略和任务事实源。

退出条件：

- Worker 无权创建 AIOS Task；
- 租约过期后 Job 可恢复；
- 跨租户 claim/read/result 被拒绝。

### Phase 4：Web 与运维统一

目标：所有用户与运维功能通过 AIOS Web/API。

范围：

- Tenant、Agent、Task、Runtime、Audit、Execution Evidence、GitOps；
- systemd/Docker/Compose；
- healthcheck、rollback、release report。

退出条件：

- 浏览器不直接调用 Runtime；
- 生产身份代理和权限模型通过验证；
- 部署、重启和回滚演练通过。

### Phase 5：生产数据层与 HA

目标：将候选 SQLite/内存运行状态替换或强化为生产级后端。

要求：

- 数据迁移；
- RLS 或物理隔离；
- 备份恢复；
- HA 与容量；
- 多实例并发；
- 灾难恢复目标。

该阶段不得改变上层合同，避免 Runtime 和 Web 再次耦合存储实现。

## 4. 分支与提交策略

### 4.1 分支类型

| 类型 | 用途 |
|---|---|
| `task/*` | 可执行任务合同与主体实现 |
| `patch/*` | 独立修复或窄范围增强 |
| `integration/*` | 多模块候选收敛 |
| `result/*` | 自动执行结果与证据 |
| `release/*` | 受控发布候选 |

### 4.2 规则

- 禁止直接修改 `main`；
- 一个提交应可独立审阅和回滚；
- 大文件和大范围变更应拆分；
- 所有行为变化必须同步文档和测试；
- 生产 Tag、部署和回滚需要 Owner 批准。

## 5. GitOps 交付流程

```text
需求/架构更新
      |
      v
任务分支 + 文档 + 测试
      |
      v
代码提交 + Secret Gate
      |
      v
本地 bare repo 同步
      |
      v
Gitea 镜像与 OID 校验
      |
      v
Candidate 集成
      |
      v
自动测试与预发布
      |
      v
Owner 审批
      |
      v
Merge / Tag / Production Deploy
```

### 5.1 同步状态

GitOps 返回必须区分：

- local sync；
- Gitea sync；
- branch OID；
- workspace mode；
- dirty state。

仅返回 `common_git_dir synced` 不足以证明 Web 远端可见。

## 6. 发布门禁

### Gate A：设计完整性

- 用户需求、目标架构、模块契约、ADR 和追踪矩阵同步；
- 无冲突标记、断链或过期路径。

### Gate B：代码质量

- 包可导入；
- 静态编译通过；
- Secret Scanner 通过；
- 无已知越权旁路。

### Gate C：测试

- 单元、集成、多租户负向、重启恢复、Runtime 边界测试通过；
- 记录 commit、命令、exit code、pass/fail 和 artifact digest。

### Gate D：预发布

- systemd 或 Compose 启动成功；
- 健康检查通过；
- OpenClaw/Hermes 真实联调通过；
- 备份、重启和回滚演练通过；
- 日志中无敏感信息。

### Gate E：生产批准

- Owner 批准 merge、Tag 和生产部署；
- 发布窗口、回滚负责人和观察指标明确；
- 生产变更通过 GitOps 记录。

## 7. 回滚策略

### 7.1 代码回滚

- 使用 `/opt/aios/current` 原子 symlink 切换；
- 回滚前备份状态；
- 健康检查失败自动恢复 previous release。

### 7.2 状态回滚

默认不自动回滚状态，避免覆盖候选运行期间新增的 Task、Audit 和 Evidence。

状态恢复只有在：

- 明确确认 schema 不兼容；
- 数据备份可验证；
- Owner 显式授权；

时启用。

### 7.3 Runtime 回滚

OpenClaw/Hermes Adapter 采用稳定合同。若候选执行层失败，可恢复旧 Runtime 版本，但不得恢复旧控制权旁路。

## 8. Bug 修复流程

生产或预发布 Bug：

1. 创建 `patch/bugfix/*`；
2. 添加可复现测试；
3. 修复代码；
4. 更新相关需求/架构/契约/ADR；
5. 运行候选验收；
6. 进入新的 release candidate；
7. Owner 批准部署。

禁止在生产目录直接编辑文件后不回写 Git。

## 9. 文档同步规则

以下变化必须更新文档：

- 用户行为或页面；
- API 路径、Header、请求/响应；
- 数据模型、状态机、策略；
- OpenClaw/Hermes/Router 边界；
- 多租户与安全模型；
- 部署、健康检查、回滚；
- 测试或发布门禁。

对应关系：

- 需求变化：更新 `01-USER-REQUIREMENTS.md`；
- 架构变化：更新 `02-TARGET-ARCHITECTURE.md` 和 ADR；
- 迁移/发布变化：更新本文件；
- 合同变化：更新 `04-MODULE-CONTRACTS.md`；
- 代码/测试路径变化：更新 `05-TRACEABILITY-MATRIX.md`。

## 10. 当前候选后续步骤

1. 完成文档同步门禁和 Acceptance Runner；
2. 在精确 Candidate commit 执行测试；
3. 推送 Gitea 并校验 OID；
4. 部署隔离预发布环境；
5. 联调真实 OpenClaw/Hermes；
6. 执行重启、性能、安全和回滚演练；
7. 生成最终 evidence；
8. 请求 Owner 的 merge/Tag/production approval。