duanshuwen/zn-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eca70425cf9a6c74bc4070f3e7860d60b5e9d0c6
zn-ai/docs/OpenClaw-Chat-Alignment-Plan.md
duanshuwen b1dea9a5c2 feat: implement task management store with IPC integration 
- Added a new task store in `src-react/stores/task.ts` to manage tasks and their statuses.
- Implemented functions for creating, executing, and retrying tasks, along with handling task progress and completion.
- Introduced persistence for tasks using IPC.
- Created utility functions for normalizing room types and building subtasks.
- Added a new CSS file for global styles in `src-react/styles.css`.
- Created runtime types in `src-react/types/runtime.ts` and exported them.
- Updated the main entry points for Vue and React applications to support dynamic framework loading.
- Refactored chat model interfaces and utility functions into `src/shared/chat-model.ts`.
- Updated TypeScript configuration to include paths for React components and types.
- Enhanced Vite configuration to support both Vue and React frameworks.
2026-04-17 07:09:56 +08:00

230 lines
16 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` 当前已经具备一套可工作的本地聊天骨架：`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，降低一次性重写风险。
## 2. ClawX 集成 OpenClaw 的实现思路
| 层级 | 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 对话体验的关键差异点 |
## 3. zn-ai 当前基础与差距
### 3.1 已有基础
| 能力 | 当前实现 | 关键文件 | 评估 |
| --- | --- | --- | --- |
| 主进程聊天入口 | 已有 `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/*` | 可迭代增强 |
### 3.2 主要差距
| 差距 | 当前状态 | 对齐目标 |
| --- | --- | --- |
| 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 的启动、重启、健康、孤儿进程治理逻辑 |
## 4. 推荐目标架构
```text
Vue Renderer
├─ src/stores/chat.ts
├─ src/lib/gateway-client.ts
└─ src/lib/host-api.ts
│
│ IPC + 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
│
│ utilityProcess + ~/.openclaw
▼
OpenClaw Gateway
├─ providers / auth profiles
├─ agents / sessions / transcripts
├─ tool use / thinking / attachments
└─ channel / cron / skills / model routing
```
### 架构原则
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` 测试脚本、调试脚本、文档 | 通过验收清单，具备对外演示条件 |
## 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 为什么推荐 2 + 5 + 1
- `ClawX` 与 `zn-ai` 的主要差距横跨“打包、主进程、Host API、配置同步、Renderer 状态机、UI、转录/执行图”七个面。
- 其中 `OpenClaw runtime 嵌入` 和 `Renderer 对话能力对齐` 之间依赖明确，但文件改动面基本可分离，适合并行。
- 如果迁移 sub-agent 少于 `4`，会出现“主进程迁移完成但 Renderer 无法及时接入”或“UI 已变更但 transcript/API 尚未可用”的串行瓶颈。
## 8. 功能迁移 sub-agent 分工方案
| 角色 | 数量 | 负责范围 | 建议文件所有权 |
| --- | --- | --- | --- |
| 分析 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、发布说明 | 测试与文档，不抢占前面文件所有权 |
### 8.1 并行施工波次
| 波次 | 并行 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/执行图，并完成端到端验收 |
### 8.2 依赖关系
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 双态验证 |
## 11. 完成验收标准
- `zn-ai` 可以在开发态和打包态拉起 OpenClaw Gateway。
- 聊天页默认使用本地默认模型配置，且修改默认模型后下一轮对话生效。
- 会话列表支持新建、切换、加载、删除、重命名。
- 聊天页支持流式文本、Markdown、thinking、tool cards、图片/文件附件。
- `Abort`、错误恢复、历史回灌稳定可用。
- `@agent` 能把消息送到目标 Agent 主会话，而不是仅显示占位 chip。
- 至少一个子任务 transcript 能被加载并展示为执行图或子任务明细。
- 不影响 `Scripts`、`Tasks`、模型管理页的现有主流程。
## 12. 与现有文档的关系
- `docs/model-chat-migration-plan.md`：更偏“模型对话重构”的早期版本，可继续作为 Renderer/Gateway 迁移参考。
- `docs/ChatPageMigrationPlan.md`：更偏聊天页面结构与 UI 迁移。
- `docs/agents.md`：更偏 Agent 系统分析。
本文件是上述文档的 **OpenClaw 对话能力总计划整合版**，适合作为后续 sub-agent 排活与里程碑跟踪的主文档。
Reference in New Issue View Git Blame Copy Permalink