duanshuwen/zn-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement OpenClaw process owner and runtime path utilities

Browse Source 
- Add OpenClawProcessOwner class to manage the lifecycle of the OpenClaw process.
- Introduce utility functions for managing OpenClaw runtime paths.
- Update session store to normalize agent session keys and migrate existing keys.
- Refactor main process to handle local provider API routing through a new dispatch function.
- Enhance token usage writer to utilize a new session key parsing function.
- Create agents management store to handle agent data and interactions.
- Update chat store to integrate agent selection and session management.
- Introduce AgentsSection component for displaying agent information in the UI.
- Refactor HomePage to support agent selection and display current agent.
- Update routing to reflect new agents page structure.
This commit is contained in:
duanshuwen
2026-04-17 21:32:06 +08:00
parent eca70425cf
commit e9f3a29886
33 changed files with 1526 additions and 2428 deletions
Download Patch File Download Diff File Expand all files Collapse all files

338
docs/OpenClaw-Chat-Alignment-Plan.md
View File

@@ -1,64 +1,91 @@
# zn-ai 对齐 ClawX 对话能力的 OpenClaw 集成与迁移计划
## 1. 结论摘要
## 1. 当前结论
- `zn-ai` 当前已经具备一套可工作的本地聊天骨架：`gateway:rpc`、`gateway:event`、`providerApiService`、流式渲染、会话列表、附件发送、`thinking/tool_use/tool_result` 数据结构都已存在。
- `ClawX` 的核心优势不在单个聊天组件，而在于一整套“`Electron Main` 托管 `OpenClaw Gateway` + `Host API` 统一入口 + `~/.openclaw` 运行时配置 + Agent/Session/Transcript`”的闭环。
- 如果目标是“对齐 ClawX 的对话能力”，推荐采用 **ClawX 原生方案对齐**，而不是继续把 `zn-ai` 现有轻量 gateway 做成长期主架构。
- 推荐实施路径是：**先保持 `zn-ai` 现有 `gateway:rpc` / `gateway:event` 契约不变，逐步把底层执行面替换成 OpenClaw**。这样可以最大化复用 Vue Renderer，降低一次性重写风险。
- `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. ClawX 集成 OpenClaw 的实现思路
## 2. React 平替后的新前提
| 层级 | ClawX 做法 | 关键文件 | 对 zn-ai 的启发 |
| --- | --- | --- | --- |
| OpenClaw 运行时打包 | 把 `openclaw` 包和全部运行时依赖打进应用资源目录，同时额外打包 `uv`、Windows Node 二进制 | `ClawX/scripts/bundle-openclaw.mjs` `ClawX/scripts/download-bundled-uv.mjs` `ClawX/electron/utils/paths.ts` | `zn-ai` 不能只复用接口，必须把 OpenClaw runtime 一起嵌入，才能真正对齐 ClawX 的行为与目录结构 |
| Gateway 生命周期 | `Electron utilityProcess` 启动 `openclaw.mjs`，主进程负责 start/stop/restart/health/reconnect/orphan cleanup | `ClawX/electron/gateway/manager.ts` `ClawX/electron/gateway/process-launcher.ts` `ClawX/electron/gateway/supervisor.ts` | `zn-ai` 现有 in-process gateway 可作为过渡层，但目标应切到独立 OpenClaw 进程托管 |
| Host API 统一接入 | 主进程启动本地 Host API Server，Renderer 统一通过 `hostApiFetch()` 与各类 `/api/*` 路由通信 | `ClawX/electron/api/server.ts` `ClawX/electron/api/routes/gateway.ts` `ClawX/electron/api/routes/sessions.ts` `ClawX/src/lib/host-api.ts` | `zn-ai` 目前 `hostapi:fetch` 同时承担“本地 provider”与“远端业务后端”两套职责，后续需要把 OpenClaw 相关能力彻底本地化 |
| Renderer 与 Gateway 通信 | Renderer 通过 `gateway:rpc` 和 `/api/app/gateway-info` 建立统一通信链路，不直接知道 OpenClaw 进程细节 | `ClawX/src/lib/gateway-client.ts` `ClawX/electron/api/routes/gateway.ts` | `zn-ai` 已经有相同方向的封装，这部分最值得保留 |
| 对话状态机 | Chat Store 负责流式消息、历史回灌、错误恢复、附件缓存、tool/thinking 归并、会话切换 | `ClawX/src/stores/chat.ts` `ClawX/src/stores/chat/runtime-send-actions.ts` `ClawX/src/stores/chat/runtime-event-handlers.ts` | `zn-ai` 现有 `src/stores/chat.ts` 已经很接近，可以按契约对齐而不必推倒重来 |
| 对话展示能力 | Markdown、thinking 展示、tool cards、图片/文件附件、`@agent` 路由、执行图、sub-agent transcript | `ClawX/src/pages/Chat/index.tsx` `ClawX/src/pages/Chat/ChatInput.tsx` `ClawX/src/pages/Chat/ChatMessage.tsx` | `zn-ai` 需要补的是“真实能力闭环”，而不是单纯补 UI 外观 |
| 子任务/转录读取 | 通过 Session Transcript API 读取子 agent 的 `jsonl` 转录，驱动执行图 | `ClawX/electron/api/routes/sessions.ts` `ClawX/src/pages/Chat/index.tsx` | 这是 `zn-ai` 当前缺失最明显的一块，也是对齐 ClawX 对话体验的关键差异点 |
### 2.1 当前 React 主链路
## 3. zn-ai 当前基础与差距
| 模块 | 当前文件 | 说明 |
| --- | --- | --- |
| 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 状态层 |
### 3.1 已有基础
### 2.2 已完成或已落地的基础能力
| 能力 | 当前实现 | 关键文件 | 评估 |
| --- | --- | --- | --- |
| 主进程聊天入口 | 已有 `gateway:rpc` 与 `hostapi:fetch` | `zn-ai/electron/main.ts` | 可复用 |
| 本地 gateway 骨架 | 已有 `GatewayManager`、`chat.send/history/abort/session.list` | `zn-ai/electron/gateway/manager.ts` `zn-ai/electron/gateway/handlers/chat.ts` `zn-ai/electron/gateway/types.ts` | 适合做过渡层 |
| Provider 本地存储 | Provider 账户、默认账户、API Key 已本地化 | `zn-ai/electron/service/provider-api-service/index.ts` | 可作为 OpenClaw 配置同步源 |
| Renderer chat 状态机 | 已支持流式更新、错误恢复、历史回读、附件、tool status | `zn-ai/src/stores/chat.ts` | 高复用价值 |
| 消息模型 | 已定义 `thinking/tool_use/tool_result/image` | `zn-ai/src/pages/home/model/ChatModel.ts` | 结构已接近 ClawX |
| 聊天 UI | 已有消息列表、输入框、附件、Markdown、会话侧栏 | `zn-ai/src/pages/home/ChatBox.vue` `zn-ai/src/pages/home/ChatHistory.vue` `zn-ai/src/pages/home/components/chat/*` | 可迭代增强 |
| 能力 | 当前状态 | 关键文件 |
| --- | --- | --- |
| 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` |
### 3.2 主要差距
### 2.3 仍未对齐 ClawX 的关键差距
| 差距 | 当前状态 | 对齐目标 |
| --- | --- | --- |
| OpenClaw runtime | 还没有嵌入 `openclaw` 包、`utilityProcess` 启动链路、打包脚本 | 与 ClawX 一样由主进程托管 OpenClaw Gateway |
| Host API 本地闭环 | `hostapi:fetch` 仍混合本地代理和远端服务转发 | OpenClaw 相关 `/api/*` 统一落在本地主进程 Host API |
| Session key 约定 | 仍会生成 `local:{defaultAccountId}:{uuid}` 本地会话键 | 统一收敛到 ClawX 风格的 `agent:{agentId}:{sessionId}` |
| `@agent` 直达路由 | 输入框已有 Agent chip，但当前是占位能力，未接入真实 Agent 列表和主会话映射 | 像 ClawX 一样把下一条消息直接送到目标 Agent 的主会话 |
| Agent/Session/Transcript | 缺少完整的 Agent 配置、main session 映射、子 agent transcript 加载 | 对齐 ClawX 的 Agent/Session/Transcript API |
| 执行图与子任务闭环 | 当前没有基于 transcript 的执行图、handoff、sub-agent 展示 | 对齐 ClawX 的任务执行可视化能力 |
| Gateway 生命周期治理 | 当前 gateway 只是主进程 service，没有 OpenClaw 进程治理、健康检查、重连策略 | 对齐 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 |
## 4. 推荐目标架构
## 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
Vue Renderer
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 + Host API
│ IPC + Local Host API
▼
Electron Main
├─ GatewayManager (OpenClaw process owner)
├─ Host API Server (/api/gateway /api/providers /api/agents /api/sessions ...)
├─ Provider/Agent/Session sync layer
└─ file stage / upload / local config bridge
├─ 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
▼
@@ -66,164 +93,135 @@ OpenClaw Gateway
├─ providers / auth profiles
├─ agents / sessions / transcripts
├─ tool use / thinking / attachments
└─ channel / cron / skills / model routing
└─ sub-agent / execution graph / control ui
```
### 架构原则
## 5. 分阶段迁移计划
1. Renderer 尽量不直接感知 OpenClaw 进程细节，只认 `gateway:rpc` 和 `hostApiFetch`。
2. `zn-ai` 已有聊天 UI 保留，主要做协议对齐和能力补全，不追求把 React 页面逐组件翻译成 Vue。
3. `providerApiService` 在过渡期作为配置真源，后续逐步演进为 “zn-ai 配置面板 <-> OpenClaw runtime config” 的双向同步桥。
4. 第一阶段只聚焦“对齐 ClawX 对话能力”，不把 `ClawHub`、完整 Channel UI、完整 Skills UI 一次性并入首个里程碑。
## 5. 目标对齐范围
### 5.1 P0：必须对齐的对话核心能力
- 多会话创建、切换、历史加载、删除、重命名
- 流式输出、Markdown 渲染、错误恢复、Abort
- thinking 展示开关
- 工具调用状态与工具结果归并
- 图片/文件附件发送与展示
- 默认模型选择生效
- 主进程 Gateway 自动启动、状态展示、重启
### 5.2 P1：推荐在首轮迁移后立即补齐
- `@agent` 直接路由到目标 Agent 主会话
- Agent 级 provider/model override
- Session Transcript API
- 执行图卡片与子任务可视化
- 历史轮询与 history fallback 逻辑对齐
### 5.3 P2：对话增强能力
- sub-agent transcript 树展示
- channel 会话历史与对话页面联动
- OpenClaw doctor / Control UI / 调试入口
- 更完整的 tool_result 文件回灌与 message-ref 展示
## 6. 分阶段迁移计划
| 阶段 | 目标 | 主要改动路径 | 退出标准 |
| 阶段 | 状态 | 目标 | 主要文件 |
| --- | --- | --- | --- |
| Phase 0：契约冻结 | 冻结 Chat/Gateway/Session/Agent 的目标契约，避免边做边漂移 | 新增本计划文档；整理 `gateway:rpc`、`GatewayEvent`、`RawMessage`、`sessionKey` 约定 | 所有 sub-agent 使用同一套消息模型与接口名 |
| Phase 1：OpenClaw 运行时嵌入 | 在 `zn-ai` 中打进 `openclaw`、`uv`、必要运行时，能由主进程拉起 Gateway | `zn-ai/package.json` `zn-ai/scripts/*` `zn-ai/electron/gateway/**` `zn-ai/electron/utils/paths.ts` | 开发态与打包态都能启动 OpenClaw Gateway，并能返回 health/status |
| Phase 2：Host API 与配置同步 | 把 Provider/Agent/Session/Gateway 相关接口统一落到本地主进程；建立 `zn-ai -> ~/.openclaw` 配置同步 | `zn-ai/electron/main.ts` `zn-ai/electron/api/**` `zn-ai/electron/service/provider-api-service/**` | Renderer 可从本地拉到 gateway-info、providers、agents、sessions、transcripts |
| Phase 3：Renderer Chat Store 对齐 | 保留 Vue UI，改造 chat store 与 OpenClaw 事件/历史契约对齐 | `zn-ai/src/stores/chat.ts` `zn-ai/src/lib/gateway-client.ts` `zn-ai/src/lib/host-api.ts` `zn-ai/src/pages/home/model/ChatModel.ts` | 流式聊天、历史回灌、Abort、错误恢复、附件发送全链路稳定 |
| Phase 4：对话 UI 对齐 | 补齐当前 Agent、thinking、tool cards、session sidebar、gateway 状态等体验 | `zn-ai/src/pages/home/ChatBox.vue` `zn-ai/src/pages/home/ChatHistory.vue` `zn-ai/src/pages/home/components/chat/*` | 视觉与交互能力对齐 ClawX 聊天页的核心功能 |
| Phase 5：Agent 直达与执行图 | 接入 Agent 主会话映射、transcript 读取、执行图、sub-agent 展示 | `zn-ai/electron/api/routes/sessions.ts` `zn-ai/src/pages/home/components/*` 新增执行图组件 | 至少支持一个子任务 transcript 展示与执行过程可视化 |
| Phase 6：验收与回归 | 做端到端验收与回归检查，避免对脚本、任务、模型管理页面造成回归 | `zn-ai` 测试脚本、调试脚本、文档 | 通过验收清单，具备对外演示条件 |
| 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：`2`
- 迁移开发 sub-agent：`5`
- 集成验收 sub-agent：`1`
- 推荐总数：`8`
### 7.2 最小可行编制
- 分析集成 sub-agent：`2`
- 功能迁移 sub-agent：`4`
- 集成验收由主协调 agent 兼任
- 分析 sub-agent：`2`
- 迁移开发 sub-agent：`4`
- 验收由主协调 agent 兼任
- 最小总数：`6`
### 7.3 为什么推荐 2 + 5 + 1
### 7.3 为什么推荐 8 个
- `ClawX` 与 `zn-ai` 的主要差距横跨“打包、主进程、Host API、配置同步、Renderer 状态机、UI、转录/执行图”七个面。
- 其中 `OpenClaw runtime 嵌入` 和 `Renderer 对话能力对齐` 之间依赖明确，但文件改动面基本可分离，适合并行。
- 如果迁移 sub-agent 少于 `4`，会出现“主进程迁移完成但 Renderer 无法及时接入”或“UI 已变更但 transcript/API 尚未可用”的串行瓶颈。
- `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. sub-agent 分工与开工安排
| 角色 | 数量 | 负责范围 | 建议文件所有权 |
### 8.1 分工方案
| 角色 | 数量 | 负责范围 | 文件所有权 |
| --- | --- | --- | --- |
| 分析 A1：ClawX/OpenClaw 契约分析 | 1 | 梳理 ClawX 的 OpenClaw runtime、Gateway、Host API、Session Transcript 契约 | 只读分析，不改文件 |
| 分析 A2：zn-ai 落点映射 | 1 | 梳理 `zn-ai` 当前可复用模块、差距、替换顺序 | 只读分析，不改文件 |
| 迁移 M1：Runtime/Packaging | 1 | 嵌入 `openclaw`、迁移启动脚本、补 `paths`、补打包资源 | `package.json` `scripts/*` `electron/gateway/**` `electron/utils/paths.ts` |
| 迁移 M2：Host API/Config Sync | 1 | 新建/迁移 Host API Server、Gateway routes、Provider/Agent/Session 同步 | `electron/main.ts` `electron/api/**` `electron/service/provider-api-service/**` |
| 迁移 M3：Renderer 协议与 Chat Store | 1 | 让 Vue chat store 对齐 ClawX 的 `chat.send/history/abort/session.list` 与事件状态机 | `src/stores/chat.ts` `src/lib/gateway-client.ts` `src/lib/host-api.ts` `src/pages/home/model/ChatModel.ts` |
| 迁移 M4：聊天 UI/侧栏/输入框 | 1 | 侧栏会话管理、Agent picker、gateway 状态、thinking/tool/file 展示对齐 | `src/pages/home/ChatBox.vue` `src/pages/home/ChatHistory.vue` `src/pages/home/components/chat/*` |
| 迁移 M5：Transcript/Execution Graph | 1 | transcript API、执行图、sub-agent 展示、验收脚本 | `electron/api/routes/sessions.ts` 新增执行图组件与测试/调试脚本 |
| 验收 I1：集成收口 | 1 | 联调、回归、验收 checklist、发布说明 | 测试与文档，不抢占前面文件所有权 |
| 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.1 并行施工波次
### 8.2 当前已启动的角色
| 波次 | 并行 sub-agent | 说明 |
| 角色 | 当前状态 | 备注 |
| --- | --- | --- |
| Wave 1 | A1 + A2 | 只读分析，同步冻结契约与边界 |
| Wave 2 | M1 + M2 | 一边搭 OpenClaw runtime，一边准备 Host API 与配置同步 |
| Wave 3 | M3 + M4 | Runtime 和 API 基础稳定后，同时推进 store 与 UI |
| Wave 4 | M5 + I1 | 接入 transcript/执行图，并完成端到端验收 |
| A1 | 已启动并完成首轮分析 | 已明确最小闭环是 `transport -> gateway lifecycle -> sessions -> history -> send/stream` |
| A2 | 已启动但中途断流 | 不阻塞主线，已由主协调 agent 接管现状映射 |
| M1 | 已启动 | 第一批 `Host API` 路由骨架已落地 |
| 主协调 agent | 已启动 | 正在更新总计划文档并推进 Phase 1 基建 |
### 8.2 依赖关系
### 8.3 建议并行波次
1. `M3` 依赖 `M2` 提供稳定的 Host API/Gateway 契约。
2. `M4` 依赖 `M3` 暴露真实的 Agent/session/tool/thinking 状态。
3. `M5` 依赖 `M2` 的 session/transcript API 和 `M3` 的消息模型归一。
4. `I1` 在 `M1-M5` 基本完成后统一收口。
## 9. 推荐实施细节
### 9.1 优先保留的 zn-ai 资产
- `src/stores/chat.ts`
- `src/pages/home/model/ChatModel.ts`
- `src/pages/home/components/chat/ChatMessage.vue`
- `src/pages/home/ChatHistory.vue`
- `src/lib/gateway-client.ts`
- `electron/service/provider-api-service/index.ts`
这些模块的价值在于：
- 已经具备较成熟的流式状态机，不需要重新从零写一套 Vue Chat Store。
- 已经定义了与 ClawX 接近的结构化消息模型。
- 已经把 Provider 配置和默认模型选择本地化，可以作为 OpenClaw 配置同步源。
### 9.2 建议替换或重构的部分
- 当前 `electron/gateway/manager.ts` 及 `handlers/chat.ts`
- 当前 `hostapi:fetch` 里“远端后端代理优先”的混合职责
- 当前 `local:{accountId}:{uuid}` 会话键体系
- 当前只做占位的 Agent mention 逻辑
### 9.3 首个里程碑不建议纳入的范围
- ClawHub 全量迁移
- Skills 页面全量迁移
- Channels 页面全量迁移
- Cron 与对话的深度联动
原因是这几个模块都依赖 OpenClaw runtime 完整稳定，但不属于“先对齐 ClawX 对话能力”的最小闭环。
## 10. 风险与决策点
| 风险 | 说明 | 建议 |
| 波次 | 并行角色 | 目标 |
| --- | --- | --- |
| 远端 Host API 与本地 Host API 混用 | 迁移期间容易出现一部分接口走远端、一部分走本地，导致行为不一致 | 明确约定：OpenClaw 相关接口全部本地化，其余业务接口保留远端 |
| Session key 不统一 | `local:*` 与 `agent:*` 并存会导致历史、侧栏、Agent 路由混乱 | Phase 0 就冻结统一命名规则 |
| Provider 配置双写 | `zn-ai` 本地配置与 `~/.openclaw` 运行时配置如果不同步，会出现“设置页一套、对话页一套” | Phase 2 建立单向真源和同步策略 |
| Vue/React 页面一比一翻译冲动 | 会导致迁移周期失控 | 只对齐能力，不对齐组件实现细节 |
| 打包态差异 | `OpenClaw` 在开发态和打包态的路径、资源、uv/node 依赖不同 | M1 单独负责 dev/package 双态验证 |
| 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 收口与联调验收 |
## 11. 完成验收标准
## 9. 接下来的直接开发任务
- `zn-ai` 可以在开发态和打包态拉起 OpenClaw Gateway。
- 聊天页默认使用本地默认模型配置，且修改默认模型后下一轮对话生效。
- 会话列表支持新建、切换、加载、删除、重命名。
- 聊天页支持流式文本、Markdown、thinking、tool cards、图片/文件附件。
- `Abort`、错误恢复、历史回灌稳定可用。
- `@agent` 能把消息送到目标 Agent 主会话，而不是仅显示占位 chip。
- 至少一个子任务 transcript 能被加载并展示为执行图或子任务明细。
- 不影响 `Scripts`、`Tasks`、模型管理页的现有主流程。
按优先级建议这样推进：
## 12. 与现有文档的关系
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` 的并行迁移。
- `docs/model-chat-migration-plan.md`：更偏“模型对话重构”的早期版本，可继续作为 Renderer/Gateway 迁移参考。
- `docs/ChatPageMigrationPlan.md`：更偏聊天页面结构与 UI 迁移。
- `docs/agents.md`：更偏 Agent 系统分析。
本文件是上述文档的 **OpenClaw 对话能力总计划整合版**，适合作为后续 sub-agent 排活与里程碑跟踪的主文档。