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
parent d233b94b2a
commit b1dea9a5c2
68 changed files with 5910 additions and 397 deletions
--- a/docs/OpenClaw-Chat-Alignment-Plan.md
+++ b/docs/OpenClaw-Chat-Alignment-Plan.md
@@ -0,0 +1,229 @@
+# 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 排活与里程碑跟踪的主文档。
--- a/docs/Vue-Exit-Checklist.md
+++ b/docs/Vue-Exit-Checklist.md
@@ -0,0 +1,136 @@
+# zn-ai Vue 退场清单
+
+目标：在 React 接管默认入口后，按清单删除所有仅服务 Vue 的资产，最终收敛为 `React-only`。
+
+## 当前状态
+
+- `Home` 的 React 主链路已经接入真实 `chat/task/channel` store、真实 IPC，以及 `TaskOperationDialog / AddChannelDialog`。
+- `Home` 这批旧 Vue 文件目前仍被 `src/router/index.ts -> src/pages/home/index.vue` 的 Vue fallback 引用，因此本轮不能直接删除。
+- 其余主页面虽然已有 `src-react/pages/*` 路由壳，但当前大多还是占位页，尚不满足“删除 Vue 路由与页面”的退场条件。
+
+当前删除策略：
+
+1. 先停止新增对 `src/pages/home/**`、`src/stores/chat.ts`、`src/stores/task.ts`、`src/stores/channel.ts` 的 React 侧依赖。
+2. 等 `Agents / Knowledge / Skills / Cron / Scripts / Setting / Login` 的 React 页面完成真实迁移后，再统一删除 `src/router/*`、`.vue` 页面和旧 Pinia store。
+3. 在此之前，只做“替换引用”和“收口依赖”，不做会破坏 Vue fallback 的物理删除。
+
+## 1. 入口与切换层
+
+- `src/main-vue.ts`
+- `src/framework.ts`
+- `src/main.ts`
+- `src/App.vue`
+- `src/permission.ts`
+
+退场标准：
+
+- `src/main.ts` 不再分流 Vue 入口。
+- `src/framework.ts` 不再保留 `vue` 分支。
+- `src/main-vue.ts` 删除。
+- `src/App.vue` 和 `src/permission.ts` 只要还依赖 Vue 生命周期或 Router 守卫，就必须迁入 React 后再删除旧文件。
+
+## 2. Vue 页面
+
+以下页面都属于 Vue 退场范围，React 版本完成后删除：
+
+- `src/pages/home/index.vue`
+- `src/pages/home/ChatBox.vue`
+- `src/pages/home/ChatHistory.vue`
+- `src/pages/home/TaskCenter.vue`
+- `src/pages/home/components/*.vue`
+- `src/pages/login/index.vue`
+- `src/pages/agents/index.vue`
+- `src/pages/knowledge/index.vue`
+- `src/pages/skills/index.vue`
+- `src/pages/skills/components/*.vue`
+- `src/pages/cron/index.vue`
+- `src/pages/cron/components/*.vue`
+- `src/pages/setting/index.vue`
+- `src/pages/setting/components/*.vue`
+
+建议删除顺序：
+
+1. 先迁 `home`，再迁其余业务页。
+2. 先删纯展示/表单页，再删聊天主链路。
+3. 最后统一清理页面下的 Vue 子组件目录。
+
+## 3. Vue Store
+
+以下 `Pinia` store 是 Vue 体系的核心状态，React 完成对等实现后删除：
+
+- `src/stores/chat.ts`
+- `src/stores/providers.ts`
+- `src/stores/channel.ts`
+- `src/stores/cron.ts`
+- `src/stores/script.ts`
+- `src/stores/skills.ts`
+- `src/stores/task.ts`
+- `src/stores/theme.ts`
+- `src/stores/locale.ts`
+- `src/stores/update.ts`
+- `src/stores/userinfo.ts`
+- `src/stores/sharedStore.ts`
+
+退场标准：
+
+- React 侧已具备对等 store 后，旧 Pinia store 不再被任何路由或组件引用。
+- `src/stores/*` 不再承担主流程状态。
+
+## 4. Router 与守卫
+
+需要替换或删除的 Vue 路由资产：
+
+- `src/router/index.ts`
+- `src/constant/menus.ts`
+- `src/permission.ts`
+- `src/components/SideMenus/index.vue`
+
+退场标准：
+
+- 路由切换完全由 React Router 接管。
+- 菜单配置不再依赖 Vue 路由表。
+- 登录守卫迁到 React 侧后，旧守卫文件删除。
+
+## 5. 仅服务 Vue 的共享组件
+
+这些组件如果只被 Vue 页面使用，应在 React 对等实现后删除：
+
+- `src/components/Layout/index.vue`
+- `src/components/Layout/TitleBar/index.vue`
+- `src/components/NativeTooltip/index.vue`
+- `src/components/Pagination/index.vue`
+- `src/components/TitleSection/index.vue`
+
+## 6. Vue 依赖与构建项
+
+`package.json` 中后续需要删除或替换的 Vue 依赖：
+
+- `vue`
+- `vue-router`
+- `pinia`
+- `vue-i18n`
+- `element-plus`
+- `@vueuse/core`
+- `@vitejs/plugin-vue`
+- `@lucide/vue`
+- `@remixicon/vue`
+- `vue-codemirror`
+- `vue-markdown-render`
+
+`vite.config.ts` 中后续需要清理的 Vue 构建项：
+
+- `vue()` 插件
+- `unplugin-auto-import` 的 Vue 自动导入配置
+- 与 Vue 页面强绑定的 `src/auto-imports.d.ts` 生成链路
+- 所有仅为 Vue 入口保留的分支判断
+
+## 7. 最终删除判定
+
+只有在以下条件都满足后，才允许进入最终清理提交：
+
+- 默认入口只剩 React。
+- 所有主页面都已迁到 `src-react/`。
+- `src/pages/**` 中不再存在可执行的 Vue 页面。
+- `src/stores/**` 中不再存在被运行时调用的 Vue 状态。
+- `package.json` 和 `vite.config.ts` 中不再保留 Vue 构建依赖。
+- 仓库中不再需要 `VITE_UI_FRAMEWORK=vue` 作为运行开关。
--- a/docs/Vue-to-React-Replacement-Plan.md
+++ b/docs/Vue-to-React-Replacement-Plan.md
@@ -0,0 +1,469 @@
+# zn-ai 对齐 ClawX 的 Vue -> React 平替迁移计划
+
+## 1. 目标与结论
+
+- `zn-ai` 当前前端是完整的 `Vue 3 + Pinia + Vue Router + Element Plus + Tailwind` 体系，不是少量页面级 Vue 组件。
+- `ClawX` 当前前端是完整的 `React 19 + React Router + Zustand + Radix/shadcn + Tailwind` 体系。
+- 如果目标是“对齐 ClawX 使用 React”，建议迁移目标不只是“把 `.vue` 改成 `.tsx`”，而是 **整体对齐前端工程组织方式**：
+  - 路由层对齐 `React Router`
+  - 状态层对齐 `Zustand`
+  - 组件层逐步摆脱 `Element Plus`
+  - 页面层按业务模块分波次平替
+- 最终目标是 **React-only**：Vue 只允许作为短期过渡层存在，迁移完成后必须移除。
+- 推荐路径是 **短期双栈过渡、按路由/页面壳分批平替、迁完即收口**，不建议一次性大爆炸重写。
+
+## 2. 当前现状
+
+### 2.1 zn-ai 当前 Vue 技术栈
+
+| 维度 | 当前实现 | 关键路径 |
+| --- | --- | --- |
+| 应用入口 | Vue 根应用 | `zn-ai/src/main.ts` |
+| 根组件 | `App.vue + router-view + keep-alive` | `zn-ai/src/App.vue` |
+| 路由 | `vue-router` | `zn-ai/src/router/index.ts` |
+| 状态管理 | `Pinia` | `zn-ai/src/stores/*` |
+| UI 组件体系 | `Element Plus + 自定义 Vue 组件 + Tailwind` | `zn-ai/src/components/*` |
+| 页面目录 | Vue 页面分散在 `src/pages/*` | `zn-ai/src/pages/*` |
+| Electron 交互 | `window.api + hostapi:fetch + gateway:rpc` | `zn-ai/electron/*` `zn-ai/src/lib/*` |
+| 样式 | `Tailwind v4 + 全局 CSS + Element Plus 主题` | `zn-ai/src/styles/*` |
+
+### 2.2 ClawX 当前 React 参照栈
+
+| 维度 | ClawX 做法 | 关键路径 |
+| --- | --- | --- |
+| 应用入口 | `main.tsx` + `HashRouter` | `ClawX/src/main.tsx` |
+| 根组件 | `App.tsx` + `Routes/Route` | `ClawX/src/App.tsx` |
+| 布局 | `MainLayout + Sidebar + TitleBar` | `ClawX/src/components/layout/*` |
+| 状态管理 | `Zustand` | `ClawX/src/stores/*` |
+| UI 组件体系 | `Radix + 自建 ui 组件 + Tailwind` | `ClawX/src/components/ui/*` |
+| 页面目录 | 按页面模块划分 | `ClawX/src/pages/*` |
+| API/Gateway | `host-api.ts` / `gateway-client.ts` / typed stores | `ClawX/src/lib/*` |
+| 样式 | `globals.css + CSS variables + Tailwind utilities` | `ClawX/src/styles/globals.css` |
+
+## 3. 迁移目标
+
+### 3.1 技术目标
+
+1. `zn-ai` Renderer 入口从 Vue 根应用切换为 React 根应用。
+2. 路由系统从 `vue-router` 切换为 `react-router-dom`。
+3. 核心状态逐步从 `Pinia` 迁到 `Zustand`。
+4. 页面与通用组件逐步从 `.vue` 平替为 `.tsx`。
+5. UI 层逐步减少 `Element Plus` 依赖，最终以 Tailwind + React 组件为主。
+6. Electron 主进程、preload、IPC、Host API 相关逻辑尽量保持不动，避免把“框架迁移”和“桌面能力迁移”绑死在同一波次。
+
+### 3.2 业务目标
+
+- 保持 `Home/Chat`、`Agents`、`Skills`、`Cron`、`Scripts`、`Setting`、`Login` 可持续可用。
+- 在迁移过程中不影响 Electron 打包、启动、窗口控制、IPC 调用。
+- React 平替后，后续功能开发可以直接复用 ClawX 的 React 组织方式与组件思想。
+
+## 4. 推荐迁移策略
+
+## 4.1 不推荐：大爆炸式重写
+
+特点：
+
+- 一次性删除 Vue 根应用
+- 一次性切到 React
+- 所有页面同步重写
+
+问题：
+
+- 风险最高
+- 回归面最大
+- 业务停滞时间最长
+- 很难快速验证 Electron 集成链路是否稳定
+
+## 4.2 推荐：短期双栈过渡、分波次平替
+
+特点：
+
+- 在同一仓库临时同时支持 `@vitejs/plugin-vue` 和 `@vitejs/plugin-react`
+- 先把 React 根应用、路由、布局、状态基建搭起来
+- 再按页面分批把 Vue 页面平替成 React 页面
+- React 接管默认入口后，立即进入 Vue 清退阶段
+- 最后删除 Vue 页面、Vue store、Vue Router、Element Plus 与 Vue 构建链
+
+优点：
+
+- 风险可控
+- 可以边迁移边交付
+- 页面出现问题时回滚范围小
+- 更适合 `zn-ai` 这种 Electron 桌面应用
+
+边界要求：
+
+- 双栈只用于迁移窗口期，不作为长期架构存在
+- Phase 2 之后默认 Renderer 入口必须是 React
+- Phase 3 起禁止新增 Vue 页面、Vue store、Element Plus 依赖
+- Phase 5 必须完成 Vue 依赖与 Vue 代码清退，否则不算迁移完成
+
+### 4.3 推荐迁移粒度
+
+建议按这个粒度迁移：
+
+1. 应用壳：入口、路由、主布局、标题栏、侧边栏
+2. 核心页面：`Home/Chat`
+3. 平台页面：`Agents`、`Setting`
+4. 工具页面：`Skills`、`Cron`、`Scripts`
+5. 低频或独立页面：`Knowledge`、`Login`
+6. 最后移除 Vue 运行时与旧依赖
+
+不建议按“单个小组件岛”零散迁移，因为：
+
+- `zn-ai` 的页面级状态和路由耦合很重
+- `Layout + SideMenus + 页面容器 + store` 是一整套
+- 组件岛太细会让 Vue/React 互相嵌套，维护复杂度更高
+
+### 4.4 终态约束
+
+最终态不是 “Vue/React 双栈长期共存”，而是：
+
+- Renderer 只保留 React 入口
+- 路由只保留 `react-router-dom`
+- 状态层只保留 React 可用的 store 体系
+- UI 只保留当前视觉风格对应的 React 组件实现
+- `vue`、`vue-router`、`pinia`、`element-plus`、`@vitejs/plugin-vue` 从生产依赖与构建链中移除
+
+## 5. 工程平替方案
+
+### 5.1 目录策略
+
+推荐迁移期间采用双目录：
+
+```text
+src/            # 保留现有 Vue 代码
+src-react/      # 新增 React 代码
+```
+
+或者更偏最终态的方式：
+
+```text
+src/
+  react/
+  electron/
+  shared/
+```
+
+更推荐第一种，原因是：
+
+- 对当前工程侵入更小
+- 平替期间边界更清晰
+- 方便按页面对照迁移
+
+但这个目录策略只服务于迁移期。最终收口时应执行以下动作之一：
+
+- 将 `src-react/` 合并回最终 Renderer 目录
+- 或者删除旧 `src/` 中仅服务 Vue 的前端代码，只保留共享与 Electron 代码
+
+### 5.2 构建策略
+
+建议分两步：
+
+1. 先在 `vite.config.ts` 里加入 `@vitejs/plugin-react`
+2. 保留 `plugin-vue` 一段时间，直到最后一个 Vue 页面被移除
+
+迁移初期目标不是删 Vue，而是：
+
+- 先让 React 页面可以在 Electron Renderer 中跑起来
+- 再让 React 尽快接手默认入口
+
+构建收口要求：
+
+- 默认启动入口一旦切到 React，就不再新增任何 Vue 侧能力开发
+- 最后一阶段必须移除 `@vitejs/plugin-vue`
+- 打包与开发脚本最终只保留 React 所需链路
+
+### 5.3 状态管理策略
+
+| 当前 | 目标 | 建议 |
+| --- | --- | --- |
+| `Pinia` | `Zustand` | 新 React 页面只写 Zustand，不再新增 Pinia store |
+| 旧 Pinia store | 过渡兼容 | 迁移期间允许 React 通过桥接层复用部分现有逻辑 |
+| 领域状态 | 切分迁移 | 优先迁移 `chat/providers/theme/locale/settings` |
+
+推荐做法：
+
+- 对每个核心领域新增 React 版 store
+- 在短期内允许 Pinia 与 React store 并存
+- 页面迁走后，再删除对应 Pinia store
+- 从 Phase 3 开始禁止新增 Pinia 代码
+
+### 5.4 UI 组件策略
+
+| 当前 | 目标 | 建议 |
+| --- | --- | --- |
+| `Element Plus` | `Tailwind + React 组件` | 不直接一比一平替 Element Plus 组件 API |
+| `Vue 单文件组件` | `TSX 组件` | 先迁页面壳，再抽通用组件 |
+| Tailwind 样式 | 保留 | 继续沿用颜色、间距、布局 token |
+
+建议：
+
+- 不要把 `Element Plus` 在 React 中“硬套”一层兼容壳
+- 更适合借鉴 ClawX 的做法，逐步建设 `src-react/components/ui/*`
+- 先做基础组件：Button、Input、Dialog、Tabs、Tooltip、Dropdown、Toast
+
+### 5.5 共享能力策略
+
+以下模块尽量不重写，只做前端适配：
+
+- `electron/main.ts`
+- `electron/preload/*`
+- `electron/gateway/*`
+- `src/lib/host-api.ts` 的底层契约
+- `src/lib/gateway-client.ts` 的底层契约
+- 绝大部分 `electron/service/*`
+
+换句话说：
+
+- 框架迁移主要发生在 Renderer
+- 主进程和 Electron 基础设施尽量保持稳定
+
+## 6. 页面迁移优先级
+
+### 6.1 P0：先迁基础壳
+
+- `App.vue`
+- `src/main.ts`
+- `src/router/index.ts`
+- `src/components/Layout/index.vue`
+- `src/components/SideMenus/index.vue`
+- `src/components/Layout/TitleBar/index.vue`
+
+原因：
+
+- 这是 React 页面承接的运行底座
+- 不先迁应用壳，后面页面只能继续挂在 Vue 下
+
+### 6.2 P1：高价值页面
+
+- `src/pages/home/index.vue`
+- `src/pages/home/ChatBox.vue`
+- `src/pages/home/ChatHistory.vue`
+- `src/pages/home/components/chat/*`
+- `src/stores/chat.ts`
+- `src/stores/providers.ts`
+
+原因：
+
+- 首页/对话页是使用频率最高的模块
+- 同时它也是最能直接复用 ClawX React 经验的地方
+
+### 6.3 P2：管理页面
+
+- `src/pages/agents/index.vue`
+- `src/pages/setting/index.vue`
+- `src/pages/skills/index.vue`
+- `src/pages/cron/index.vue`
+- `src/pages/scripts/index.vue`
+
+### 6.4 P3：低频与收尾页面
+
+- `src/pages/knowledge/index.vue`
+- `src/pages/login/index.vue`
+- 零散公用组件
+- Vue/Pinia/Element Plus 清理
+
+## 7. 分阶段实施计划
+
+| 阶段 | 目标 | 主要产出 | 退出标准 |
+| --- | --- | --- | --- |
+| Phase 0 | 冻结迁移边界 | 迁移文档、路由清单、页面资产清单、Vue 退场清单 | 团队对范围、命名、目录、状态策略与 Vue 退场标准达成一致 |
+| Phase 1 | 建短期双栈基建 | React 依赖、React 入口、临时双栈 Vite 配置 | Electron 中可启动 React 根页面 |
+| Phase 2 | React 接管应用壳 | React `App`、React Router、MainLayout、Sidebar、TitleBar、默认入口切换 | Vue 根壳退出默认路径，React 成为默认 Renderer |
+| Phase 3 | 平替核心页 | Home/Chat 与核心 store 迁到 React | 主路径用户完全走 React，Vue 不再承接核心流程 |
+| Phase 4 | 平替剩余页面 | Agents/Setting/Skills/Cron/Scripts/Knowledge/Login 迁到 React | 所有用户可见主页面全部脱离 Vue |
+| Phase 5 | Vue 退场与依赖清理 | 删除 `.vue` 页面、Pinia/Vue Router/Element Plus 依赖与构建链 | 项目代码库不再依赖 Vue 运行时与 Vue 构建插件 |
+| Phase 6 | 回归与交付 | 回归测试、打包验证、文档更新 | Dev/Build/Package 全链路稳定，React-only 终态成立 |
+
+## 8. sub-agent 数量估算
+
+### 8.1 标准推荐编制
+
+- 架构收口 sub-agent：`1`
+- 功能迁移 sub-agent：`5`
+- Vue 清退 sub-agent：`1`
+- 集成验收 sub-agent：`1`
+- 标准总数：`8`
+
+这是最适合当前 `zn-ai` 体量的推荐方案，能覆盖：
+
+- React-only 架构冻结
+- 应用壳迁移
+- 状态与通信层迁移
+- 视觉样式与通用组件平替
+- 高复杂页面迁移
+- Vue 退场
+- 联调验收
+
+### 8.2 扩展并行编制
+
+- 架构收口 sub-agent：`1`
+- 功能迁移 sub-agent：`6`
+- Vue 清退 sub-agent：`1`
+- 集成验收 sub-agent：`1`
+- 扩展总数：`9`
+
+适用于你希望更快并行推进、并把页面迁移与 Vue 清退准备拆得更细的情况。
+
+### 8.3 最小可行编制
+
+- 架构收口 sub-agent：`1`
+- 功能迁移 sub-agent：`4`
+- Vue 清退与集成验收由主协调 agent 兼任
+- 最小总数：`5`
+
+这个方案能做，但节奏会更紧，回归与清尾风险更高。
+
+### 8.4 为什么比“只迁聊天页”需要更多 sub-agent
+
+这次不是单一页面迁移，而是：
+
+- 前端框架替换
+- 路由替换
+- 状态管理替换
+- UI 体系替换
+- 页面级别平替
+- Electron Renderer 构建链调整
+
+因此复杂度明显高于单一业务模块迁移。
+
+## 9. 推荐 sub-agent 分工
+
+### 9.1 标准 8-agent 分工
+
+| 角色 | 数量 | 负责范围 | 建议文件所有权 |
+| --- | --- | --- | --- |
+| A1：React-only 架构收口 | 1 | 冻结迁移边界、禁止新增 Vue 扩面、维护 Vue 退场清单 | 只读分析，不改文件 |
+| M1：构建与入口切换 | 1 | React 依赖、Vite、Renderer 入口切换、保留短期双栈兜底 | `package.json` `vite.config.ts` `tsconfig*` `src/main.ts` `src/framework.ts` |
+| M2：应用壳与路由 | 1 | React `App`、React Router、布局、标题栏、侧栏，并保持当前视觉风格 | `src-react/App.tsx` `src-react/router/*` `src-react/components/layout/*` |
+| M3：共享基础设施 | 1 | i18n、theme、host-api、gateway-client、window api 类型桥接 | `src-react/lib/*` `src-react/stores/*` `src-react/i18n/*` `src-react/types/*` |
+| M4：Home/Chat 主链路 | 1 | Home、Chat、ChatHistory、聊天 store、对话组件，保持当前 UI 布局与交互 | `src-react/pages/Home/*` `src-react/components/chat/*` `src-react/stores/chat/*` |
+| M5：非聊天页面平替 | 1 | Agents、Setting、Skills、Cron、Scripts、Knowledge、Login 等页面平替，视觉沿用当前实现 | `src-react/pages/Agents/*` `src-react/pages/Setting/*` `src-react/pages/Skills/*` `src-react/pages/Cron/*` `src-react/pages/Scripts/*` `src-react/pages/Knowledge/*` `src-react/pages/Login/*` |
+| C1：Vue 清退与依赖下线 | 1 | 删除 `.vue` 页面、Pinia/Vue Router/Element Plus、清理 Vue 构建链与过渡文件 | `src/*.vue` `src/router/*` `src/stores/*` `vite.config.ts` `package.json` |
+| I1：联调与验收 | 1 | 回归、打包验证、迁移文档回填、React-only 验收 | 测试脚本、验收记录、迁移记录 |
+
+### 9.2 扩展 9-agent 分工
+
+如果采用扩展并行编制，可以把标准方案里的 `M5` 再拆成两组：
+
+- 迁移 M5：平台与设置页
+- 迁移 M6：技能与工具页
+
+这样页面并行度更高，更适合在 React 接管默认入口后快速清空剩余 Vue 页面。
+
+### 9.3 当前阶段继续执行的推荐编组
+
+如果从当前阶段继续往下推进，推荐立即投入这 `4` 个执行向 sub-agent，再由主协调 agent 持续整合：
+
+- `Gibbs`：负责 `M1`，继续把默认入口、构建配置和 Vue 兜底边界收紧，禁止双栈长期化。
+- `Mendel`：负责 `M2 + M5`，优先把应用壳、侧栏、标题栏和非聊天页面按当前视觉样式迁到 React。
+- `Dalton`：负责 `M3`，继续打通 React 侧 i18n、theme、host-api、gateway-client 与 settings store。
+- 新增 `C1/M4` 组合 worker：优先迁 `Home/Chat` 主链路，并同步维护 Vue 退场清单，避免聊天页迁完后又回头返工。
+
+## 10. 推荐并行波次
+
+| 波次 | 并行 sub-agent | 说明 |
+| --- | --- | --- |
+| Wave 1 | A1 | 先冻结 React-only 边界、Vue 退场标准与视觉复用策略 |
+| Wave 2 | M1 + M2 + M3 | 一边搭建 React 运行底座，一边准备共享桥接层，并让 React 接手默认入口 |
+| Wave 3 | M4 + M5 | 核心页与剩余页面并行平替，要求沿用当前视觉样式 |
+| Wave 4 | C1 + I1 | 集中执行 Vue 清退、构建链收口、联调与验收 |
+
+如果采用扩展 9-agent 方案，则 `Wave 3` 可改为：
+
+- `M4 + M5 + M6` 并行
+- `C1` 提前介入维护 Vue 删除清单
+- `I1` 提前介入做持续验收
+
+## 11. 文件级拆分建议
+
+### 11.1 M1：构建与短期双栈基建
+
+- `zn-ai/package.json`
+- `zn-ai/vite.config.ts`
+- `zn-ai/tsconfig.app.json`
+- `zn-ai/tsconfig.json`
+
+### 11.2 M2：应用壳与路由
+
+- `zn-ai/src-react/main.tsx`
+- `zn-ai/src-react/App.tsx`
+- `zn-ai/src-react/router/*`
+- `zn-ai/src-react/components/layout/*`
+
+### 11.3 M3：共享基础设施
+
+- `zn-ai/src-react/lib/host-api.ts`
+- `zn-ai/src-react/lib/gateway-client.ts`
+- `zn-ai/src-react/lib/*`
+- `zn-ai/src-react/i18n/*`
+- `zn-ai/src-react/stores/settings.ts`
+
+### 11.4 M4：Home/Chat
+
+- `zn-ai/src-react/pages/Home/*`
+- `zn-ai/src-react/components/chat/*`
+- `zn-ai/src-react/stores/chat/*`
+
+### 11.5 M5：非聊天页面平替
+
+- `zn-ai/src-react/pages/Agents/*`
+- `zn-ai/src-react/pages/Setting/*`
+- `zn-ai/src-react/pages/Login/*`
+- `zn-ai/src-react/pages/Skills/*`
+- `zn-ai/src-react/pages/Cron/*`
+- `zn-ai/src-react/pages/Scripts/*`
+- `zn-ai/src-react/pages/Knowledge/*`
+
+### 11.6 C1：Vue 清退与依赖下线
+
+- `zn-ai/src/main-vue.ts`
+- `zn-ai/src/router/*`
+- `zn-ai/src/stores/*`
+- `zn-ai/src/components/**/*.vue`
+- `zn-ai/src/pages/**/*.vue`
+- `zn-ai/package.json`
+- `zn-ai/vite.config.ts`
+
+### 11.7 扩展方案 M6：技能与工具页
+
+- `zn-ai/src-react/pages/Skills/*`
+- `zn-ai/src-react/pages/Cron/*`
+- `zn-ai/src-react/pages/Scripts/*`
+- `zn-ai/src-react/pages/Knowledge/*`
+
+## 12. 主要风险
+
+| 风险 | 说明 | 建议 |
+| --- | --- | --- |
+| Vue/React 双栈期间复杂度上升 | 两套路由、样式、状态会短期并存 | 严格限定过渡期目录与职责边界，并对双栈设置明确退出时间点 |
+| Element Plus 替换成本被低估 | 不是只替换组件，还会影响交互与样式结构 | 先迁页面壳和逻辑，再逐步建设 React UI 库 |
+| Pinia 逻辑复制导致状态漂移 | 同一业务状态在 Vue/React 两边各维护一套容易分叉 | 核心领域先做桥接层，明确单一真源 |
+| 页面迁移顺序不当 | 先迁低价值页会拉长工期，主路径收益低 | 先壳后首页，再平台页 |
+| 打包链路回归 | Electron Renderer 切换入口后容易影响 dev/build/package | M1 和 I1 都要覆盖打包验证 |
+
+## 13. 验收标准
+
+- React 入口可以作为默认 Renderer 启动入口。
+- 主布局、路由、标题栏、侧边导航全部由 React 承接。
+- `Home/Chat`、`Agents`、`Setting`、`Skills`、`Cron`、`Scripts` 至少完成 React 版主路径迁移。
+- Electron IPC、Host API、Gateway 调用在 React 页面中保持可用。
+- 迁移完成后，项目必须移除 `vue`、`pinia`、`vue-router`、`element-plus` 与 `@vitejs/plugin-vue`。
+- `pnpm dev`、`pnpm build`、打包主流程可正常运行。
+
+## 14. 最终建议
+
+- **推荐方案**：以 `React-only` 为唯一终态，短期双栈仅作为过渡。
+- **标准推荐 sub-agent 数量**：`8` 个。
+- **扩展并行数量**：`9` 个。
+- **最小可行数量**：`5` 个。
+- **最重要的执行原则**：先让 React 接管默认入口，再迁高价值页面，随后立即清退 Vue。
+
+从投入产出比来看，最值得优先平替的是：
+
+1. 应用壳与路由
+2. Home/Chat
+3. Agents/Setting
+
+只要这三块完成，`zn-ai` 就已经从“Vue 项目”实质性切到“React 项目”了；剩余工作不再是“是否保留 Vue”的讨论，而是明确执行 Vue 清退与 React-only 收口。