duanshuwen/zn-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e11a2296cc3c4aae44e34208282021ac316694da
zn-ai/docs/OpenClaw-Chat-Alignment-Plan.md
DEV_DSW 416399e7a8 feat: implement menu service for context menu management 
feat: add provider API service for managing provider accounts and keys
feat: create provider runtime sync service for agent runtime management
feat: introduce script execution service for running automation scripts
feat: develop script store service for managing script metadata and storage
feat: implement theme service for managing application theme settings
feat: add updater service for handling application updates
feat: create window service for managing application windows and their states
2026-04-22 09:26:39 +08:00

228 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.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.ts` |
| 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.ts` `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` 的并行迁移。
Reference in New Issue View Git Blame Copy Permalink