duanshuwen/zn-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
97a956ffe89c5a9ae08d32465f7a7becd51d7794
zn-ai/docs/OpenClaw-Chat-Alignment-Plan.md
duanshuwen e9f3a29886 feat: implement OpenClaw process owner and runtime path utilities 
- 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.
2026-04-17 21:32:06 +08:00

13 KiB
Raw Blame History

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. 目标架构

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 的并行迁移。