zn-ai/docs/ClawX-Gateway-Launcher-Migration-Execution-Plan.md

# ClawX Gateway Launcher 迁移执行文档

## 1. 目标

`zn-ai` 当前已经完成 Gateway 启动链第一波迁移，解决重点是：

- launch context 组装
- launcher core 与 Windows 启动兼容
- startup orchestrator
- startup stderr 诊断
- supervisor 的基础端口与孤儿进程治理

下一波只继续迁移 `ClawX` 的 Gateway 生命周期与自愈闭环，范围严格限制在以下 4 组能力：

- `connection-monitor`
- `restart-controller` / `restart-governor`
- `reload-policy`
- `doctor repair`

本轮明确不做：

- Chat 主链路改造
- Skills 安装链路改造
- Providers/Channels 非 Gateway 生命周期相关重构
- UI 视觉层修改

## 2. 当前结论

`zn-ai` 与 `ClawX` 在 Gateway 启动能力上已经接近，但在 Gateway 完整生命周期能力上仍不一致。

`zn-ai` 已具备：

- `prepareGatewayLaunchContext(...)`
- `launchGatewayProcess(...)`
- `runGatewayStartupSequence(...)`
- startup stderr 分类与缓存
- `waitForPortFree(...)`
- 孤儿监听进程探测与清理
- Windows `node-runtime` 启动策略

`zn-ai` 仍缺少：

- 心跳监控与健康检查驱动的自愈
- 启动中/重连中的 restart defer 机制
- restart cooldown governor
- Gateway reload policy 解析与应用
- OpenClaw doctor repair
- Python readiness warmup
- 与这些能力配套的 manager 生命周期接线

## 3. 第二波迁移目标

迁移完成后，`zn-ai` 的 Gateway 至少要补齐下面这组行为：

1. Gateway 连接建立后有稳定的 ping/pong 与 message heartbeat 监控。
2. 连接失活或健康检查失败时，manager 能按治理策略自愈，而不是单次掉线后长期停摆。
3. 外部触发的 restart 请求在 `starting` / `reconnecting` 阶段不会打断在途启动，而是 defer 到合适时机。
4. 连续 restart 受到 cooldown governor 约束，避免抖动和端口争抢。
5. Gateway reload policy 能从 `~/.openclaw/openclaw.json` 读取，并决定走 `reload`、`restart`、`hybrid` 或 `off`。
6. startup-orchestrator 在判定配置损坏时能触发 doctor repair，然后再试一次启动。
7. Windows 下真实 Gateway 冒烟时，能区分：
   - 启动慢但最终 ready
   - 配置损坏后 repair 成功
   - repair 失败后停止重试

## 4. 建议 sub-agent 数量

建议 `4` 个开发 sub-agent，加 `1` 个主协调 agent。

理由：

- 这 4 组能力的依赖闭包并不完全独立。
- `manager.ts` 是热点文件，不能让多个 worker 同时改。
- `doctor repair` 会额外牵动 `supervisor.ts` 与若干工具模块，适合单独收口。
- 测试与真实回归要独立 ownership，避免实现者自己绕过风险。

不建议拆成超过 `4` 个开发 sub-agent，因为：

- `manager.ts`、`startup-orchestrator.ts`、`supervisor.ts` 的写入冲突会明显增加。
- 这轮目标是生命周期闭环，不是大范围模块化重构。

## 5. 分工方案

### 主协调 Agent

职责：

- 冻结第二波迁移边界，只做 Gateway 生命周期与自愈能力。
- 冻结共享契约：
  - lifecycle state
  - reconnect / deferred restart policy
  - reload policy result
  - doctor repair hook
- 负责合并顺序、冲突协调、回归 checklist 与最终收口。

不直接负责大规模代码写入，重点是接口与顺序控制。

### SA-1 Lifecycle Primitives

责任范围：

- `zn-ai/electron/gateway/connection-monitor.ts`
- `zn-ai/electron/gateway/process-policy.ts`
- `zn-ai/electron/gateway/lifecycle-controller.ts`
- `zn-ai/electron/gateway/restart-controller.ts`
- `zn-ai/electron/gateway/restart-governor.ts`
- 如有必要，可补最小 `state` 辅助文件，但不负责 manager 接线

目标：

- 迁入 ClawX 的心跳监控、健康检查定时器、restart defer 规则、reconnect 规则、restart cooldown 规则
- 保持实现尽量独立，供 manager 后续接入

约束：

- 不修改 `manager.ts`
- 不修改 UI / API / Chat / Skills

### SA-2 Repair & Supervisor

责任范围：

- `zn-ai/electron/gateway/supervisor.ts`
- `zn-ai/electron/gateway/startup-orchestrator.ts`
- 如缺失则新增最小工具：
  - `zn-ai/electron/utils/uv-env.ts`
  - `zn-ai/electron/utils/uv-setup.ts`
  - `zn-ai/electron/utils/env-path.ts`

目标：

- 迁入 `warmupManagedPythonReadiness()`
- 迁入 `runOpenClawDoctorRepair()`
- 把 doctor repair 接进 `runGatewayStartupSequence(...)`
- 保持对 Windows 的 process tree terminate 和 PATH 注入兼容

约束：

- 不改 `manager.ts`
- 只为 doctor repair 引入最小依赖，不顺手扩散到其它 Python/uv 功能

### SA-3 Manager Lifecycle Integration

责任范围：

- `zn-ai/electron/gateway/manager.ts`
- 必要时小幅修改：
  - `zn-ai/electron/gateway/ws-client.ts`
  - `zn-ai/electron/gateway/types.ts`

目标：

- 接入 SA-1 输出的 lifecycle / reconnect / restart governance
- 接入 SA-2 输出的 doctor repair 与 startup recovery hook
- 为 `zn-ai` 补齐：
  - `startHealthCheck()`
  - `startPing()`
  - `scheduleReconnect()`
  - `debouncedRestart()`
  - `reload()`
  - `debouncedReload()`
  - reload policy refresh

约束：

- 只动 Gateway 生命周期相关逻辑
- 不改现有 chat payload 结构
- 不借机重构无关的 runtime broadcast

说明：

`manager.ts` 由 SA-3 单独 owning，其他 sub-agent 不直接修改这个文件，避免冲突。

### SA-4 Verification & Regression

责任范围：

- `zn-ai/tests/*gateway*`
- Gateway 相关 smoke 脚本与文档
- 必要时补最小测试夹具

目标：

- 给新增的 lifecycle/reload/repair 行为补单测
- 补真实 Windows 冒烟步骤
- 输出失败定位矩阵，覆盖：
  - heartbeat miss
  - deferred restart
  - governor suppress
  - reload policy mode 分支
  - doctor repair success/failure

约束：

- 不修改产品功能逻辑，除非为了让测试可注入而做最小 seam

## 6. 实施顺序

### Wave 2A

并行推进：

- SA-1 Lifecycle Primitives
- SA-2 Repair & Supervisor

冻结输出契约：

- `GatewayConnectionMonitor`
- `GatewayRestartController`
- `GatewayRestartGovernor`
- `GatewayReloadPolicy`
- `runOpenClawDoctorRepair()`
- `warmupManagedPythonReadiness()`

### Wave 2B

在 Wave 2A 契约冻结后推进：

- SA-3 Manager Lifecycle Integration

这一步只做接线和行为收口，不反向改 SA-1/SA-2 的模块边界。

### Wave 2C

最后推进：

- SA-4 Verification & Regression
- 主协调 Agent 汇总验收

## 7. 合并顺序

1. `process-policy.ts` / `lifecycle-controller.ts` / `connection-monitor.ts`
2. `restart-controller.ts` / `restart-governor.ts`
3. `reload-policy.ts`
4. `supervisor.ts` 的 doctor repair 与 Python warmup
5. `startup-orchestrator.ts` repair hook
6. `manager.ts` 生命周期接线
7. tests / smoke / 文档收口

## 8. 关键依赖与注意事项

### 8.1 manager.ts 是单点热点

本轮很多能力最终都要落到 `manager.ts`。因此：

- 只有 SA-3 可以写 `manager.ts`
- SA-1 / SA-2 只提供可接入模块和稳定接口

### 8.2 doctor repair 不是孤立功能

`ClawX` 的 doctor repair 依赖：

- OpenClaw entry/runtime path
- bundled `bin` PATH 注入
- `uv` 镜像环境
- Python readiness 检查

`zn-ai` 当前还没有完整对应模块，所以必须按“最小依赖闭包”迁入，不能只拷贝 `runOpenClawDoctorRepair()`。

### 8.3 reload policy 只做 Gateway 进程策略

本轮 `reload-policy` 只决定 Gateway 进程层行为：

- `off`
- `reload`
- `restart`
- `hybrid`

不扩展到 UI 或配置编辑器逻辑。

### 8.4 Windows 冒烟必须保留长等待预算

之前真实诊断已经确认 Windows 下 OpenClaw ready 可能超过 100 秒，因此：

- 不得把 ready wait 预算收回到旧值
- 冒烟时要区分“慢启动”与“真失败”

## 9. 验收标准

必须覆盖以下场景：

- Gateway 连接后能持续 ping/pong，并在 message/pong 到达时恢复 heartbeat 状态
- heartbeat 连续 miss 达阈值后能触发受控恢复
- `restart()` 在 `starting` / `reconnecting` 阶段会 defer，而不是打断在途启动
- restart governor 在 cooldown 内能 suppress 重复 restart
- `reload-policy` 可从 `~/.openclaw/openclaw.json` 读取并应用
- `reload()` 失败时能 fallback 到 `restart()`
- startup 检测到配置损坏时能执行 doctor repair
- doctor repair 成功后，Gateway 能继续启动
- doctor repair 失败后，错误信息可诊断，不会无限重试
- Windows 真实启动回归中，不再频繁出现无诊断信息的 `exited before becoming ready`

建议最少验证：

- `pnpm typecheck`
- Gateway 生命周期相关单测
- 一次 Windows 本机真实 Gateway 冒烟
- 一次配置损坏后的 repair 回归

## 10. 当前执行状态

当前建议按以下顺序继续推进：

1. 先完成 Wave 2 的 sub-agent 分工与 ownership 冻结
2. 并行实施 SA-1 与 SA-2
3. 由 SA-3 独占接入 `manager.ts`
4. 最后由 SA-4 负责真实回归与失败矩阵

## 11. 第三波补齐范围

在 `Wave 2A / 2B` 完成之后，`zn-ai` 和 `ClawX` 的 Gateway 差距主要收敛到下面这一组：

- `state.ts`
- `protocol.ts`
- `event-dispatch.ts`
- `manager.ts` 里的 diagnostics
- `manager.ts` 里的 `gatewayReady fallback`

这组能力的目标不是继续扩展生命周期治理，而是把 Gateway 的“状态模型、协议兼容、事件分发、诊断可观测性”补到接近 `ClawX`。

本轮明确不做：

- Chat 业务语义改造
- UI 新增诊断页
- telemetry 上传体系迁移
- 与本轮无关的 Skills / Channels / Providers 重构

## 12. 第三波建议 sub-agent 数量

最小可行配置是 `3` 个开发 sub-agent，加 `1` 个主协调 agent。

推荐配置是 `4` 个开发 sub-agent，加 `1` 个主协调 agent。

推荐按 `4` 个开发 sub-agent 推进，原因是：

- `manager.ts` 仍然是单点热点文件，必须单 owner。
- `protocol.ts` / `event-dispatch.ts` 与 `state.ts` / diagnostics 的依赖闭包并不相同，适合并行推进。
- diagnostics / `gatewayReady fallback` 需要独立验证，不适合完全由实现者自测。

如果资源受限，也可以退化成 `3` 个开发 sub-agent：

- 把验证工作并回主协调 Agent
- 或把 `protocol/event-dispatch` 与 `state/diagnostics primitives` 合并给同一个 sub-agent

## 13. 第三波分工方案

### 主协调 Agent

职责：

- 冻结第三波范围，只做状态层、协议层、事件分发层和 manager diagnostics/fallback。
- 冻结共享契约：
  - GatewayStatus 状态结构
  - diagnostics snapshot 结构
  - protocol / notification 类型守卫
  - `gateway.ready` fallback 行为
- 负责合并顺序、冲突协调和最终验收。

### SA-1 Protocol & Dispatch

责任范围：

- `zn-ai/electron/gateway/protocol.ts`
- `zn-ai/electron/gateway/event-dispatch.ts`
- 必要时小幅修改：
  - `zn-ai/electron/gateway/types.ts`

目标：

- 迁入 `ClawX` 的 JSON-RPC type guards 与 protocol 类型定义
- 迁入 protocol event 与 JSON-RPC notification 分发逻辑
- 让 `zn-ai` 的 Gateway manager 不再只处理当前 OpenClaw event frame，而是具备和 `ClawX` 接近的 protocol fallback 面

约束：

- 不修改 `manager.ts`
- 不修改 Chat store / renderer 事件消费逻辑

### SA-2 State & Diagnostics Primitives

责任范围：

- `zn-ai/electron/gateway/state.ts`
- `zn-ai/electron/gateway/diagnostics.ts`
- 如有必要，可补最小 diagnostics 类型文件

目标：

- 迁入 `GatewayStateController`
- 定义 `getStatus()` / `isConnected()` / state transition hook 的统一实现
- 为 manager diagnostics 提供稳定数据结构：
  - `lastAliveAt`
  - `lastRpcSuccessAt`
  - `lastRpcFailureAt`
  - `lastRpcFailureMethod`
  - `lastHeartbeatTimeoutAt`
  - `lastSocketCloseAt`
  - `lastSocketCloseCode`
  - `consecutiveHeartbeatMisses`
  - `consecutiveRpcFailures`

约束：

- 不修改 `manager.ts`
- 不新增 UI 诊断入口

### SA-3 Manager State & Protocol Integration

责任范围：

- `zn-ai/electron/gateway/manager.ts`
- 必要时小幅修改：
  - `zn-ai/electron/gateway/ws-client.ts`

目标：

- 接入 SA-1 的 protocol / event-dispatch
- 接入 SA-2 的 state controller 与 diagnostics snapshot
- 为 `zn-ai` 补齐：
  - `getDiagnostics()`
  - `gateway.ready` event handling
  - `gatewayReady fallback` timer
  - richer state transition handling
  - RPC success / failure / socket close / heartbeat timeout 记录

约束：

- `manager.ts` 由 SA-3 单独 owning
- 不借机改动 chat payload 结构
- 不迁移 telemetry 上传逻辑，除非成为必需依赖

### SA-4 Verification & Regression

责任范围：

- `zn-ai/tests/*gateway*`
- Gateway 相关 smoke checklist 与文档

目标：

- 给以下能力补测试：
  - protocol type guards
  - event dispatch mapping
  - state transition callbacks
  - diagnostics snapshot 更新
  - `gateway.ready` fallback 行为
- 补一组回归清单，确认新 protocol fallback 不会破坏现有 `chat:*` 事件链路

约束：

- 不修改产品逻辑，除非为了测试可注入而补最小 seam

## 14. 第三波实施顺序

### Wave 3A

并行推进：

- SA-1 Protocol & Dispatch
- SA-2 State & Diagnostics Primitives

冻结输出契约：

- `protocol.ts`
- `event-dispatch.ts`
- `GatewayStateController`
- diagnostics snapshot 结构

### Wave 3B

在 Wave 3A 契约冻结后推进：

- SA-3 Manager State & Protocol Integration

这一步必须保持 `manager.ts` 单 owner，不允许并行写入。

### Wave 3C

最后推进：

- SA-4 Verification & Regression
- 主协调 Agent 汇总验收

## 15. 第三波合并顺序

1. `protocol.ts`
2. `event-dispatch.ts`
3. `state.ts`
4. diagnostics types / helper
5. `manager.ts` 接线
6. tests / smoke / 文档收口

## 16. 第三波验收标准

必须覆盖以下场景：

- `zn-ai` 具备与 `ClawX` 接近的 JSON-RPC request/response/notification type guards
- protocol event 与 JSON-RPC notification 能走统一 dispatch 层
- manager 状态更新不再完全依赖手工分支，而是通过 state controller 收口
- diagnostics 能记录最近 alive/RPC/socket/heartbeat 关键时间点和失败原因
- 收到 `gateway.ready` 时能更新 Gateway ready 状态
- 未收到 `gateway.ready` 时，fallback timer 能在超时后兜底设置 ready
- 现有 `chat:delta` / `chat:final` / `chat:error` / `chat:aborted` 链路不回归

建议最少验证：

- `pnpm typecheck`
- Gateway protocol / diagnostics 相关单测
- 一次真实 Gateway 启动与 `gateway.ready` 兜底回归