# zn-ai 对齐 ClawX 对话能力的 OpenClaw 集成与迁移计划

## 1. 当前结论

- `zn-ai` 已完成 `React` 平替，当前 Renderer 主链路已经是 `src/App.tsx` + `src/router/index.tsx` + `src/pages/Home/index.tsx`，不再按 `Vue` 页面作为迁移前提。
- 这意味着接下来的 `OpenClaw` 对齐重点不再是“技术栈迁移”，而是 `Host API / Gateway Lifecycle / Session / Transcript / Agent Routing / Runtime Packaging` 这几个能力闭环。
- 推荐继续保留 `zn-ai` 现有的 `gateway:rpc` 与 `hostApiFetch()` 契约，逐步把底层执行面替换成 `ClawX + OpenClaw` 风格，而不是直接推翻现有 React 聊天页。
- 第一批集成开发已经开始：本地 `Host API` 路由骨架已从 `electron/main.ts` 拆出，新增了 `Gateway / Sessions / Files / Providers` 四类本地路由，为后续 `OpenClaw` 接入打底。

## 2. React 平替后的新前提

### 2.1 当前 React 主链路

| 模块 | 当前文件 | 说明 |
| --- | --- | --- |
| React App 入口 | `src/App.tsx` | 已由 React Router 托管 |
| 路由 | `src/router/index.tsx` | 主页面已经走 React 路由 |
| 主聊天页 | `src/pages/Home/index.tsx` | 当前对话、任务中心、渠道入口都在这里 |
| 聊天组件 | `src/components/chat/*` | 会话列表、消息列表、输入框、任务板 |
| Chat Store | `src/stores/chat.ts` | 已支持流式输出、历史回灌、附件 staging、session 删除 |
| Task/Channel Store | `src/stores/task.ts` `src/stores/channel.ts` | 已有任务与渠道配置的 React 状态层 |

### 2.2 已完成或已落地的基础能力

| 能力 | 当前状态 | 关键文件 |
| --- | --- | --- |
| Renderer 已 React 化 | 已完成 | `src/App.tsx` `src/router/index.tsx` |
| Home/Chat 主链路 | 已完成 React 化 | `src/pages/Home/index.tsx` `src/components/chat/*` |
| gateway:rpc / gateway:event | 已可用 | `electron/gateway/manager.ts` `src/lib/gateway-client.ts` |
| hostApiFetch | 已可用 | `src/lib/host-api.ts` `electron/main.ts` |
| Transcript 写入 | 已有 jsonl 写入 | `electron/gateway/handlers/chat.ts` `electron/utils/token-usage-writer.ts` |
| Provider 本地化 | 已可用 | `electron/service/provider-api-service/index.ts` |
| 本地 Session Key | 已初步收敛到 `agent:*` | `src/stores/chat.ts` |

### 2.3 仍未对齐 ClawX 的关键差距

| 差距 | 当前状态 | 对齐目标 |
| --- | --- | --- |
| OpenClaw runtime 打包 | 还没有 `openclaw` / `uv` / resource bundling | 像 ClawX 一样由主进程打包并启动 |
| Gateway 生命周期治理 | 当前仍是 in-process manager | 对齐 `start / stop / restart / health / supervisor` |
| Host API 路由层 | 刚开始拆分，本地路由还不是完整体系 | 对齐 `ClawX/electron/api/routes/*` 风格 |
| Session Transcript API | 刚开始补 `/api/sessions/transcript` | 对齐 transcript 读取、删除、后续执行图基础 |
| Agent/Session 主会话映射 | 仍未有完整 `agents` 本地接口 | 对齐 `@agent` 路由与主会话映射 |
| 执行图 / 子任务展示 | 尚未接入 UI | 对齐 `ClawX` 的 task visualizer / transcript tree |

## 3. ClawX 最小闭环对齐点

当前不需要一次搬运整个 `ClawX`。根据已完成分析，最值得先对齐的是这 5 个契约：

1. `hostApiFetch` 所依赖的本地 `Host API` transport 契约。
2. `gateway.status / gateway.health / gateway.ready` 生命周期契约。
3. `sessions.list / sessions.delete / sessions.transcript` 会话目录与 transcript 契约。
4. `chat.history` 历史回灌契约。
5. `chat.send / chat.abort / chat:delta / chat:final / chat:error` 流式发送契约。

对应的 `ClawX` 关键参考文件：

- `ClawX/electron/api/routes/gateway.ts`
- `ClawX/electron/api/routes/sessions.ts`
- `ClawX/electron/gateway/manager.ts`
- `ClawX/electron/gateway/process-launcher.ts`
- `ClawX/src/lib/host-api.ts`
- `ClawX/src/stores/chat.ts`

当前建议只迁“最小闭环”，不一次性搬全：

- 先做 `gateway-info / gateway-status / sessions-transcript / stage-buffer`。
- 再做 `OpenClaw runtime` 打包与进程托管。
- 最后才做 `Agent Routing / Execution Graph / Control UI / Doctor`。

## 4. 目标架构

```text
React Renderer
  ├─ src/pages/Home/index.tsx
  ├─ src/stores/chat.ts
  ├─ src/stores/task.ts
  ├─ src/stores/channel.ts
  ├─ src/lib/gateway-client.ts
  └─ src/lib/host-api.ts
            │
            │ IPC + Local Host API
            ▼
Electron Main
  ├─ GatewayManager (过渡期 in-process，目标是 OpenClaw process owner)
  ├─ Host API Router (/api/providers /api/gateway /api/sessions /api/files ...)
  ├─ Provider / Agent / Session config sync
  └─ Runtime / packaging / paths
            │
            │ utilityProcess + ~/.openclaw
            ▼
OpenClaw Gateway
  ├─ providers / auth profiles
  ├─ agents / sessions / transcripts
  ├─ tool use / thinking / attachments
  └─ sub-agent / execution graph / control ui
```

## 5. 分阶段迁移计划

| 阶段 | 状态 | 目标 | 主要文件 |
| --- | --- | --- | --- |
| Phase 0：React 基线收口 | 已完成 | 让聊天页、任务中心、渠道入口都运行在 React 主链路 | `src/App.tsx` `src/router/index.tsx` `src/pages/Home/index.tsx` |
| Phase 1：Host API 路由层重构 | 进行中 | 把本地 Provider/Gateway/Sessions/Files 从 `electron/main.ts` 中拆成独立 Host API 路由 | `electron/api/*` `electron/main.ts` |
| Phase 2：OpenClaw Runtime/Packaging | 待开始 | 引入 `openclaw`、`uv`、runtime path 与 dev/package 双态启动能力 | `package.json` `scripts/*` `electron/utils/paths.ts` `electron/gateway/*` |
| Phase 3：Gateway Lifecycle + Config Sync | 待开始 | 让 `GatewayManager` 从 in-process 过渡到 OpenClaw 进程 owner，并同步 provider/agent/session 配置 | `electron/gateway/*` `electron/service/provider-api-service/*` |
| Phase 4：React Chat Store 对齐 | 待开始 | 让 React Chat Store 对齐 ClawX 的 session/history/send/abort/transcript 契约 | `src/stores/chat.ts` `src/lib/host-api.ts` `src/lib/gateway-client.ts` |
| Phase 5：Agent Routing + Execution Graph | 待开始 | 接入 `@agent` 主会话映射、transcript 读取、执行图和子任务展示 | `src/pages/Home/*` `src/components/chat/*` `electron/api/routes/sessions.ts` |
| Phase 6：验收与收口 | 待开始 | 做 E2E 与回归，清理过渡实现，准备进入 OpenClaw 主架构 | 文档、测试、构建脚本 |

## 6. 第一批已开工内容

这轮已经开始落地的文件：

- `electron/api/router.ts`
- `electron/api/context.ts`
- `electron/api/route-utils.ts`
- `electron/api/routes/providers.ts`
- `electron/api/routes/gateway.ts`
- `electron/api/routes/files.ts`
- `electron/api/routes/sessions.ts`
- `electron/gateway/manager.ts`
- `electron/main.ts`

当前已完成的第一批能力：

- 本地 `Host API` 路由分发骨架已经建立。
- `Provider` 本地接口已从 `electron/main.ts` 的大 switch 逻辑中拆分。
- 新增 `Gateway` 本地路由：`/api/app/gateway-info`、`/api/gateway/status`、`/api/gateway/health`。
- 新增 `Sessions` 本地路由：`/api/sessions/transcript`、`/api/sessions/delete`。
- 新增 `Files` 本地路由：`/api/files/stage-buffer`、`/api/files/stage-paths`。
- `GatewayManager` 已补充最小 `status / health / start / stop / restart` 接口，作为向 `OpenClaw process owner` 演进的过渡层。

## 7. sub-agent 数量估算

### 7.1 推荐编制

- 分析 sub-agent：`2`
- 迁移开发 sub-agent：`5`
- 集成验收 sub-agent：`1`
- 推荐总数：`8`

### 7.2 最小可行编制

- 分析 sub-agent：`2`
- 迁移开发 sub-agent：`4`
- 验收由主协调 agent 兼任
- 最小总数：`6`

### 7.3 为什么推荐 8 个

- `React` 技术栈迁移已经完成，所以不再需要专门的“Vue/React 双栈迁移” sub-agent。
- 但 `OpenClaw` 对齐仍横跨 `Runtime Packaging`、`Gateway Lifecycle`、`Host API`、`Config Sync`、`React Chat Store`、`Transcript / Execution Graph` 六条线。
- 如果迁移 sub-agent 少于 `5`，很容易出现“主进程基础已经就绪，但 React 聊天页迟迟接不上”或“Transcript API 已有但 UI 不可见”的串行瓶颈。

## 8. sub-agent 分工与开工安排

### 8.1 分工方案

| 角色 | 数量 | 负责范围 | 文件所有权 |
| --- | --- | --- | --- |
| A1：ClawX/OpenClaw 契约分析 | 1 | 提炼 ClawX 的最小闭环契约、关键文件与最小迁移子集 | 只读分析 |
| A2：zn-ai 差距映射 | 1 | 盘点当前 React/Gateway/Host API 的实际状态与缺口 | 只读分析 |
| M1：Host API / Gateway Foundation | 1 | 拆本地 Host API 路由，补 Gateway info/status/health，建立本地接口框架 | `electron/api/*` `electron/main.ts` `electron/gateway/manager.ts` |
| M2：OpenClaw Runtime / Packaging | 1 | 迁移 `openclaw` 打包、`uv`、runtime 路径和 dev/package 启动链路 | `package.json` `scripts/*` `electron/utils/paths.ts` `electron/gateway/*` |
| M3：Config Sync / Providers / Agents / Sessions | 1 | 把 provider 配置逐步收敛成 OpenClaw 可消费格式，并补本地 agent/session 接口 | `electron/service/provider-api-service/*` `electron/api/routes/*` |
| M4：React Chat Store / History / Send | 1 | 对齐 `chat.send/history/abort/session.list` 与 transcript fallback | `src/stores/chat.ts` `src/lib/host-api.ts` `src/lib/gateway-client.ts` |
| M5：React Chat UI / Agent Routing / Execution Graph | 1 | 接 `@agent`、thinking/tool cards、transcript 展示与执行图入口 | `src/pages/Home/*` `src/components/chat/*` |
| I1：集成验收与收口 | 1 | 联调、回归、验收 checklist、发布说明 | 测试与文档 |

### 8.2 当前已启动的角色

| 角色 | 当前状态 | 备注 |
| --- | --- | --- |
| A1 | 已启动并完成首轮分析 | 已明确最小闭环是 `transport -> gateway lifecycle -> sessions -> history -> send/stream` |
| A2 | 已启动但中途断流 | 不阻塞主线，已由主协调 agent 接管现状映射 |
| M1 | 已启动 | 第一批 `Host API` 路由骨架已落地 |
| 主协调 agent | 已启动 | 正在更新总计划文档并推进 Phase 1 基建 |

### 8.3 建议并行波次

| 波次 | 并行角色 | 目标 |
| --- | --- | --- |
| Wave 1 | A1 + A2 + 主协调 agent | 冻结契约与当前状态，确认迁移边界 |
| Wave 2 | M1 + M2 | 一边拆 Host API，一边准备 OpenClaw runtime 打包与路径层 |
| Wave 3 | M3 + M4 | 配置同步与 React Chat Store 并行接入 |
| Wave 4 | M5 + I1 | 执行图 / Agent Routing / UI 收口与联调验收 |

## 9. 接下来的直接开发任务

按优先级建议这样推进：

1. 完成 `Phase 1`：
   - 继续把 `hostapi:fetch` 中本地可处理接口迁入 `electron/api/routes/*`。
   - 明确 `gateway-info` 与 `session-transcript` 的返回结构，冻结给前端使用。
2. 启动 `Phase 2`：
   - 新增 `electron/utils/paths.ts`，对齐 `ClawX` 的 runtime 路径管理。
   - 迁移 `openclaw` bundling 脚本与 `uv` 下载脚本。
3. 启动 `Phase 3`：
   - 增加 `agents` 本地接口与 `main session` 映射。
   - 让当前 `DEFAULT_AGENT_ID / DEFAULT_SESSION_KEY` 不再硬编码。
4. 启动 `Phase 4`：
   - 让 React Chat Store 能读取 `Host API` 的 `gateway-info` 与 `session-transcript`。
   - 把当前 history/session 逻辑从“本地过渡实现”逐步切向 `OpenClaw` 兼容契约。

## 10. 风险与约束

| 风险 | 说明 | 当前策略 |
| --- | --- | --- |
| Host API 本地/远端混用 | 迁移期容易出现一部分接口本地、一部分接口远端，行为不一致 | 所有 `OpenClaw` 相关接口逐步收敛到本地 Host API，业务后台接口继续远端代理 |
| Gateway 仍是 in-process | 当前还不是真正的 OpenClaw 进程托管 | 先补生命周期接口与路由层，再替换运行时 |
| Agent 路由尚未真实接入 | 当前 `sessionKey` 虽是 `agent:*` 风格，但主会话映射仍不完整 | 放在 M3 / M5 联合推进 |
| Transcript 能力有后端无前端 | 当前先补 Host API 路由，不代表 UI 已展示 | 通过 M4 / M5 分批接前端 |
| 仓库已有 TS 历史债 | 当前 `tsc` 仍存在一批既有错误 | 先以构建通过和新增链路可用为准，不在本轮一口气清旧债 |

## 11. 当前验收口径

当前这一轮不以“OpenClaw 全部接通”为验收，而是以以下条件作为 Phase 1 开工完成标准：

- `zn-ai` 仍能正常构建。
- 本地 `Host API` 路由骨架已经独立存在，不再全部堆在 `electron/main.ts`。
- 已有 `gateway-info / gateway-status / session-transcript / file-stage` 这类 `ClawX` 风格本地路由。
- 文档中的 sub-agent 分工和实际代码开工状态一致。

本轮之后，正式进入 `Phase 2-4` 的并行迁移。