feat: add tool status management and localization for skill installation

- Updated chat message types to include tool statuses. - Enhanced localization files for English, Thai, and Chinese to support new tool status messages. - Modified HomePage and SkillsPage components to handle tool statuses in chat messages. - Implemented tool status merging and updating logic in the chat store. - Added handling for tool status events in the gateway event processing. - Created tests for chat message rendering with tool statuses and skill installation shortcuts. - Improved gateway event dispatching for tool lifecycle events.
2026-04-23 20:27:54 +08:00
parent 979fb0a0f6
commit df600272d6
29 changed files with 2041 additions and 384 deletions
--- a/docs/ClawX-Skill-Install-Migration-Plan.md
+++ b/docs/ClawX-Skill-Install-Migration-Plan.md
@@ -1,427 +1,296 @@
-# ClawX Skill 安装能力迁移计划
+# ClawX 对话安装 Skill 功能同构计划

 ## 1. 结论先行

-本轮对比后的结论很明确：
+- `ClawX` 并没有在产品代码里写死一条“聊天里识别 GitHub `SKILL.md` 链接并直接调用安装接口”的专用链路。
+- `ClawX` 之所以看起来“同一句对话可以安装 skill”，更接近真实情况的是：聊天消息进入了更完整的 `OpenClaw runtime`，模型拿到了额外的 agent/tool 上下文，再通过通用 `tool_use / tool_result` 执行浏览、读取、命令调用或安装动作。
+- `zn-ai` 当前不是“没有 skill 安装能力”，而是“安装能力已经存在于 Skills 页面和 Host API，但聊天运行时没有拿到这项能力，也没有完整的 tool 协议和 UI 闭环”。
+- 因此，`zn-ai` 不能复现同一句对话安装 skill 的根因，不在 `SkillInstallService`，而在 `Runtime Context + Tool Protocol + Conversational Bridge + Tool UI` 四层。

- `ClawX` 已经具备可用的 Skills marketplace 安装闭环，但它当前的运行时安装输入仍然是 `slug + version`，不是 GitHub skill 链接。
- `zn-ai` 已经复制了 Skills 页面、Host API 路由、`ClawHubService` 外壳和预装 skill 逻辑，但运行时安装链路还没有真正闭环。
- `zn-ai` 当前最关键的缺口不是 UI，而是“运行时执行器”和“GitHub skill 目录安装能力”。
- 如果目标是“用户在对话里贴一个 GitHub skill 链接，应用可以把整目录安装到 `~/.openclaw/skills` 并启用”，那么 `ClawX` 和 `zn-ai` 目前都还没有原生支持这条链路。
+## 2. 当前真实对比

-本轮已经完成一项落地验证：
-
- 已把 `MiniMax-AI/skills` 仓库下的 `skills/minimax-xlsx` 完整目录安装到 `C:\Users\Administrator\.openclaw\skills\minimax-xlsx`
- 已在 `C:\Users\Administrator\.openclaw\openclaw.json` 中补齐 `minimax-xlsx.enabled=true`
-
-这说明：
-
- GitHub skill 本身可以按“完整目录复制”的方式被 OpenClaw 识别
- 问题不在 skill 格式本身，而在产品代码还没有把“GitHub URL -> skill 安装”做成正式运行时能力
-
-## 2. 现状对比
-
-### 2.1 已有能力
-
-| 能力 | ClawX | zn-ai | 结论 |
+| 维度 | ClawX | zn-ai | 结论 |
 | --- | --- | --- | --- |
-| Skills 页面与 Marketplace 抽屉 | 有 | 有 | `zn-ai` UI 已有，不需要从零重做 |
-| `/api/clawhub/search/install/list` 路由 | 有 | 有 | `zn-ai` Host API 形态已基本对齐 |
-| `~/.openclaw/skills` 托管目录 | 有 | 有 | 两个项目共用 OpenClaw skills 根目录 |
-| 预装 bundled skills 拷贝 | 有 | 有 | `zn-ai` 已有 preinstalled install 逻辑 |
-| 安装后技能扫描/配置读取 | 有 | 有 | `zn-ai` 已有 `skill-config.ts` 基础设施 |
+| Skills 页面安装 | 有，走 `slug/version` marketplace 安装 | 有，已支持 `marketplace` 和 `github-url` | `zn-ai` 底层安装面并不弱 |
+| GitHub skill 链接安装 | 页面/API 未见专用产品入口 | `POST /api/skills/install` 已支持 | `zn-ai` 已先行具备这项底层能力 |
+| 对话执行上下文 | 有独立 `AGENTS.clawx.md`、`TOOLS.clawx.md` | 没有等价的运行时上下文注入 | `ClawX` 的“能执行”主要赢在这里 |
+| 聊天工具执行 | `tool_use / tool_result` 已跑在完整链路里 | 只有普通文本聊天，另加一个浏览器快捷特判 | `zn-ai` 还不是真正的 tool runtime |
+| Tool 结果展示 | 已有流式工具轨迹与结果渲染 | 现有聊天 UI 只消费文本/附件 | 即使后端能产出 tool 结果，前端也接不住 |
+| 技能安装与聊天桥接 | 依赖 runtime/工具能力，不是硬编码 install API | 完全没有 `skills.install` 聊天入口 | 这是当前最直接的缺口 |

-### 2.2 关键差距
+## 3. 已确认的关键证据

-| 差距项 | ClawX | zn-ai | 判断 |
-| --- | --- | --- | --- |
-| `clawhub` 运行时依赖 | 有，`package.json` 直接声明 | 没有 | `zn-ai` marketplace 安装大概率不可用 |
-| Marketplace provider 扩展接线 | 有 | 没有 | 这会影响搜索/安装来源能力，但 install-only 迁移可先不搬整套扩展系统 |
-| 安装输入类型 | 仅 `slug/version` | 仅 `slug/version` | 两边都不支持 GitHub skill 链接直装 |
-| GitHub URL 解析与整目录下载 | 没有 | 没有 | 这是“通过对话贴链接安装”的核心缺口 |
-| Skills 路径文案一致性 | 一致 | 不一致，前端 fallback 仍写 `~/.zn-ai/skills` | 会误导手动安装与报错提示 |
+### 3.1 ClawX

-### 2.3 关键证据
+- 聊天消息只是透传到 `chat.send`，没有 GitHub URL 安装分支：
+  - `ClawX/src/stores/chat/runtime-send-actions.ts`
+  - `ClawX/electron/main/ipc-handlers.ts`
+  - `ClawX/electron/api/routes/gateway.ts`
+- Skills 页面安装仍是 `slug/version`：
+  - `ClawX/src/stores/skills.ts`
+  - `ClawX/electron/api/routes/skills.ts`
+  - `ClawX/electron/gateway/clawhub.ts`
+- 运行时上下文与工具说明是单独存在的：
+  - `ClawX/resources/context/AGENTS.clawx.md`
+  - `ClawX/resources/context/TOOLS.clawx.md`
+- 聊天 UI 和 store 确实按 `tool_use / tool_result` 在渲染：
+  - `ClawX/src/stores/chat/runtime-event-handlers.ts`
+  - `ClawX/src/pages/Chat/index.tsx`

-ClawX 现状：
+### 3.2 zn-ai

- `ClawX/package.json` 已声明 `clawhub` 依赖
- `ClawX/electron/gateway/clawhub.ts` 的运行时安装参数只有 `slug/version/force`
- `ClawX/electron/main/index.ts` 会给 `ClawHubService` 接入 marketplace provider
+- 统一安装服务已经支持 `marketplace` 和 `github-url`：
+  - `zn-ai/electron/service/skill-install-service.ts`
+- Host API 已暴露安装入口：
+  - `zn-ai/electron/api/routes/skills.ts`
+- Skills 页面已经支持从市场安装和 GitHub 链接直装：
+  - `zn-ai/src/lib/skills-api.ts`
+  - `zn-ai/src/pages/Skills/index.tsx`
+  - `zn-ai/src/pages/Skills/components/MarketplaceDrawer.tsx`
+- Gateway 只暴露了 `skills.status / skills.update`，没有 `skills.install`：
+  - `zn-ai/electron/gateway/handlers/skills.ts`
+  - `zn-ai/electron/gateway/rpc-dispatch.ts`
+  - `zn-ai/electron/gateway/types.ts`
+- 聊天当前仍是“普通 provider 文本流 + 浏览器快捷特判”：
+  - `zn-ai/electron/gateway/handlers/chat.ts`
+  - `zn-ai/electron/providers/OpenAIProvider.ts`
+- 前端消息模型虽然有 `tool_use / tool_result` 类型，但页面没有真正渲染：
+  - `zn-ai/runtime-shared/shared/chat-model.ts`
+  - `zn-ai/src/shared/chat-model.ts`
+  - `zn-ai/src/pages/Home/index.tsx`
+  - `zn-ai/src/components/chat/ChatMessageList.tsx`

-zn-ai 现状：
+## 4. zn-ai 当前缺少哪些上下文或功能

- `zn-ai/src/pages/Skills/index.tsx` 与 `MarketplaceDrawer.tsx` 已具备搜索/安装 UI
- `zn-ai/electron/api/routes/skills.ts` 已具备 `/api/clawhub/install`
- `zn-ai/electron/gateway/clawhub.ts` 已有 `ClawHubService` 外壳
- `zn-ai/package.json` 没有 `clawhub` 依赖，导致运行时 CLI 入口无法成立
- `zn-ai/src/lib/skills-api.ts` 与 `src/pages/Skills/index.tsx` 的 fallback 路径仍写成 `~/.zn-ai/skills`
+### 4.1 P0 级缺口

-## 3. 迁移范围
+1. 聊天链路没有 `skills.install` 执行入口。
+2. 模型拿不到“本机可安装 skill”的结构化能力上下文。
+3. Provider 层没有 function calling / tools / responses-style tool loop。
+4. 聊天上下文没有保留和回灌 `tool_result`，多轮对话接不上工具执行结果。

-本计划只覆盖“安装 skill”闭环，严格排除以下范围：
+### 4.2 P1 级缺口

- 不改 Skills 详情页视觉样式
- 不扩展 API Key / env 配置能力
- 不处理 skill 导入导出
- 不迁移 ClawX 全量 extension framework
- 不重构其它插件、频道、模型、任务执行逻辑
+1. Gateway 协议没有把 `tool.call_started / tool.call_completed / tool_result` 真正发到 renderer。
+2. Renderer store 对 `tool-only` 消息和 `pendingFinal` 的状态处理还不适合同构 `ClawX`。
+3. 聊天 UI 不能显示工具卡片、执行中状态、结果摘要。
+4. 安装完成后没有统一的 runtime 刷新广播，Skills 页和聊天页之间没有一致的同步信号。

-本次必须覆盖的范围只有四件事：
+### 4.3 P2 级缺口

-1. 让 `zn-ai` 先真正具备可工作的 marketplace slug 安装能力
-2. 增加 GitHub skill 链接/仓库路径安装能力
-3. 让“通过对话安装 skill”有清晰的运行时入口
-4. 安装完成后自动启用、刷新、回显结果
+1. 缺对“ClawX 为什么能做这件事”的真实证据抓取与固化。
+2. 缺开发态、打包态、真实 OpenClaw 进程和真实浏览器的 smoke。
+3. 缺对 `skills.installBundle` 这类旁支能力的目标边界说明。

-## 4. 目标闭环
+## 5. 100% 同构目标

-迁移完成后，`zn-ai` 至少要满足下面的用户路径：
+迁移完成后，`zn-ai` 需要做到和 `ClawX` 等价的三层能力：

-### 4.1 Marketplace 路径
+### 5.1 运行时同构

- 用户在 Skills 页面搜索 marketplace
- 点击安装
- 应用把 skill 安装到 `~/.openclaw/skills/<slug>`
- 自动写入 enabled 配置
- 页面刷新后能看到 skill，且状态为已启用
+- 对话进入 `OpenClaw` 风格的 agent/tool runtime，而不是只走普通文本 provider。
+- 模型能够看到明确的 skill 安装能力说明与结构化 tool schema。
+- `tool_use / tool_result / thinking` 能贯穿主进程、Gateway、renderer。

-### 4.2 GitHub 链接路径
+### 5.2 安装能力同构

- 用户在对话中粘贴 `https://github.com/<owner>/<repo>/blob/<ref>/<path>/SKILL.md`
- 系统把它解析为 `repo/ref/repoPath`
- 下载的是“整个 skill 目录”，不是单个 `SKILL.md`
- 校验目录中存在 `SKILL.md`
- 复制到 `~/.openclaw/skills/<skill-name>`
- 自动启用并返回安装结果、实际路径、后续提示
+- Marketplace `slug/version` 安装可用。
+- GitHub `blob/.../SKILL.md` 和 `tree/...` skill 目录安装可用。
+- 安装后自动启用，并能在 runtime 与 Skills 页即时可见。

-### 4.3 失败时的最低可用体验
+### 5.3 对话行为同构

- 链接无效时，明确提示“不是可安装的 skill 目录链接”
- 目标目录已存在时，给出“已安装/是否覆盖”提示
- 网络失败时，提示下载失败与建议重试
- 目录缺 `SKILL.md` 时，提示“不是合法 skill 包”
+- 在 `ClawX` 能触发安装的同一句话，在 `zn-ai` 也能触发等价行为。
+- 用户能在聊天中看到明确的工具执行过程、安装结果、失败原因和后续提示。
+- 整个链路在开发态和打包态都可验证。

-## 5. 推荐设计
+## 6. 目标架构

-## 5.1 不把 install 继续绑定死在 `clawhub`
-
-当前 `zn-ai` 的 `/api/clawhub/install` 天然只适合 marketplace slug。  
-如果要支持 GitHub skill 链接，建议把安装能力上提为统一安装服务：
-
-```ts
-type SkillInstallRequest =
-  | { kind: 'marketplace'; slug: string; version?: string; force?: boolean }
-  | { kind: 'github-url'; url: string; force?: boolean }
-  | { kind: 'github-repo-path'; repo: string; ref?: string; path: string; name?: string; force?: boolean };
+```text
+User Chat Message
+  -> Renderer Chat Store
+  -> gateway:rpc('chat.send')
+  -> OpenClaw-style Runtime Context
+  -> Tool Planner / Tool Executor
+      -> skills.install
+      -> browser
+      -> shell / uv / other runtime tools
+  -> tool_use / tool_result events
+  -> Renderer Tool UI + final assistant reply
+  -> Skills runtime refresh
 ```

-建议新增：
+其中 `skills.install` 不应该只是一个页面按钮 API，而要成为聊天运行时可见、可调用、可回传结果的正式能力。

- `electron/services/skill-install.ts`
+## 7. 分阶段同构计划

-由它统一负责：
+### M0 能力定标

- 解析安装源
- 下载或 checkout skill 目录
- 校验 `SKILL.md`
- 写入 `~/.openclaw/skills`
- 更新 `openclaw.json`
- 返回安装结果
+目标：
+- 固化 `ClawX` 当前“同一句对话能安装 skill”背后的真实机制。
+- 区分“页面/API 安装能力”和“聊天运行时执行能力”。

-`/api/clawhub/install` 可以继续保留，但只作为 marketplace 的兼容入口，内部调用统一安装服务。
+产出：
+- 行为证据清单
+- 非目标边界
+- 统一验收口径

-## 5.2 GitHub 安装逻辑建议直接落在 Electron TypeScript
+### M1 Runtime Context 同构

-不建议把 Python helper script 直接搬进 `zn-ai` 运行时。  
-建议在 Electron 侧用 TypeScript 实现，参考两类现有逻辑：
+目标：
+- 给 `zn-ai` 引入与 `ClawX` 对齐的 agent/tool/context 注入。
+- 让模型知道本机有哪些工具以及 `skills.install` 的输入约束。

- GitHub 安装语义：参考本地 `skill-installer` 的 `install-skill-from-github.py`
- skill 目录复制语义：参考 `ClawX/scripts/bundle-preinstalled-skills.mjs`
+涉及：
+- 运行时 prompt/context 资源
+- tool capability 声明
+- chat send 前的上下文拼装

-运行时 GitHub install 最小步骤：
+### M2 Gateway / Tool Protocol 同构

-1. 解析 GitHub URL
-2. 把 `blob/.../SKILL.md` 还原为 skill 目录路径
-3. 下载 zip 或 sparse checkout
-4. 定位 skill 目录
-5. 校验 `SKILL.md`
-6. 拷贝到 `~/.openclaw/skills/<slug>`
-7. 写入 `openclaw.json -> skills.entries[slug].enabled = true`
-8. 返回 `{ success, slug, baseDir, source }`
+目标：
+- 打通 `tool_use / tool_result / thinking / tool lifecycle` 的真实协议链。
+- 不再只靠浏览器快捷特判。

-## 5.3 “通过对话安装”优先走 tool，而不是字符串黑魔法
+涉及：
+- `GatewayRpc`/event 类型补齐
+- Gateway 事件分发
+- 主进程到 renderer 的流式工具事件
+- tool-only 消息收敛逻辑

-`zn-ai` 现有聊天链路已经能承载 `tool_use/tool_result` 消息块。  
-因此推荐加一个明确的 host-side tool，例如：
+### M3 Renderer Tool UI 同构

-```ts
-skills.install({
-  source: 'marketplace' | 'github-url' | 'github-repo-path',
-  slug?: string,
-  version?: string,
-  url?: string,
-  repo?: string,
-  ref?: string,
-  path?: string,
-  force?: boolean
-})
-```
+目标：
+- 在聊天页显示工具调用、执行中状态、结果摘要和失败态。
+- 让用户能看见“为什么安装成功/失败”，而不是只看到一段普通文本。

-这样做的好处：
+涉及：
+- `src/stores/chat.ts`
+- `src/pages/Home/index.tsx`
+- `src/components/chat/*`

- 不需要在聊天文本里做脆弱的正则硬解析
- Renderer 已经能展示 tool 过程与结果
- Skills 页面和聊天都能复用同一个安装服务
+### M4 Skill Install Service / API 同构

-这次迁移里，不需要重做整个聊天架构，只要补一个 install skill tool 接口即可。
+目标：
+- 统一市场安装、GitHub skill 目录安装、安装后启用和刷新语义。
+- 明确 `skills.install` 的 tool 契约。

-## 5.4 install-only 阶段不迁移 ClawX 扩展系统
-
-ClawX 有 marketplace provider extension 接线。  
-但本次目标只是把“安装 skill”闭环跑通，不建议为了这一个功能把 extension registry 整套引入 `zn-ai`。
-
-install-only 阶段建议：
-
- 先直接依赖 `clawhub` CLI 完成 marketplace 安装
- 再新增 GitHub URL install 适配器
- extension marketplace provider 以后如果要做 ClawHub 中国镜像或自定义市场，再单独立项
-
-## 6. 分阶段迁移计划
-
-### Phase 1：补齐运行时前提
-
-目标：让 `zn-ai` marketplace install 至少不是空壳。
-
-工作项：
-
- 在 `zn-ai/package.json` 增加 `clawhub` 依赖
- 校验 `electron/utils/paths.ts` 的 `getClawHubCliBinPath/getClawHubCliEntryPath`
- 让 `electron/gateway/clawhub.ts` 的 capability 检查在依赖缺失时返回明确错误
- 修正 `src/lib/skills-api.ts` 与 `src/pages/Skills/index.tsx` 中的 `~/.zn-ai/skills` fallback 为 `~/.openclaw/skills`
-
-验收：
-
- `GET /api/clawhub/capability` 返回 `canInstall=true`
- Skills 页面点击 Install 不再因为缺 CLI 直接失败
-
-### Phase 2：引入统一 Skill 安装服务
-
-目标：把 install 从“只会装 slug”升级为“可装多来源”。
-
-工作项：
-
- 新建 `electron/services/skill-install.ts`
- 支持 marketplace 与 GitHub 两类安装源
- 抽出公共能力：
-  - `parseGitHubSkillUrl`
-  - `downloadOrCheckoutSkillDir`
-  - `validateSkillDir`
-  - `copySkillIntoManagedDir`
-  - `enableInstalledSkill`
- 统一返回安装结果对象
-
-验收：
-
- 传入 `slug` 时仍能成功安装 marketplace skill
- 传入 GitHub `blob/.../SKILL.md` 链接时能成功安装整个目录
-
-### Phase 3：接通 Host API 与前端安装入口
-
-目标：让 UI 和聊天都能调统一安装服务。
-
-工作项：
-
- 新增 `POST /api/skills/install`
- 保留 `POST /api/clawhub/install` 作为兼容入口
- `src/lib/skills-api.ts` 改成调用统一 install API
- Skills 页面安装成功后继续执行：
-  - enable
-  - reload skills
-  - toast success
- 在 MarketplaceDrawer 增加一个“粘贴 GitHub skill 链接”入口
-  - 这一步只属于 install 能力，不算额外 UI 扩张
-
-验收：
-
- Skills 页面支持两种安装方式：
-  - marketplace 搜索安装
-  - GitHub 链接直装
-
-### Phase 4：接通聊天 tool 与回归验证
-
-目标：完成“通过对话安装 skill”。
-
-工作项：
-
- 在网关/运行时工具桥里新增 `skills.install`
- 让模型遇到 GitHub skill 链接时可以直接调用该 tool
- Tool result 回传：
-  - `slug`
-  - `installedPath`
-  - `enabled`
-  - `source`
-  - `nextStep`
- 增加安装相关 smoke case
-
-验收：
-
- 用户在对话里发送 GitHub skill 链接
- 模型触发 `skills.install`
- 安装完成后页面和运行时都能识别该 skill
-
-## 7. 推荐 Sub-Agent 编制
-
-本次 install-only 迁移，建议 **4 个开发 sub-agent + 1 个主协调 agent**。
-
-如果少于 4 个，很容易出现：
-
- 后端安装服务已写好，但聊天入口迟迟没接
- marketplace slug 安装恢复了，但 GitHub URL 安装仍不可用
- UI 提示和实际托管目录不一致，影响手动兜底
-
-### SA-1：Runtime Installer
-
-职责：
-
- 负责 `electron/services/skill-install.ts`
- 负责 GitHub URL 解析、下载/checkout、目录校验、复制安装
- 负责安装后启用配置写入
-
-文件责任边界：
-
- `electron/services/skill-install.ts`
- `electron/utils/skill-config.ts`
- 必要时 `electron/utils/paths.ts`
-
-### SA-2：Marketplace & Host API
-
-职责：
-
- 给 `zn-ai` 补 `clawhub` 运行时依赖
- 接通 capability 检查
- 调整 `/api/clawhub/install` 与新增 `/api/skills/install`
- 保持 marketplace slug 安装向后兼容
-
-文件责任边界：
-
- `package.json`
+涉及：
+- `electron/service/skill-install-service.ts`
 - `electron/api/routes/skills.ts`
- `electron/gateway/clawhub.ts`
- `src/lib/skills-api.ts`
+- `electron/gateway/handlers/skills.ts`
+- `electron/gateway/rpc-dispatch.ts`

-### SA-3：Chat Tool Bridge
+### M5 Conversational Install 同构

-职责：
+目标：
+- 把“同一句对话可执行安装”做成正式可测契约。
+- 同时支持至少这两类输入：
+  - `https://github.com/.../SKILL.md，帮我安装这个 skill`
+  - `帮我安装 minimax-xlsx 这个 skill`

- 给聊天链路增加 `skills.install` tool
- 负责“通过对话贴 GitHub skill 链接即可安装”的入口
- 负责 tool result 事件与前端可见反馈
+涉及：
+- tool planner / conversational bridge
+- 安装结果回写
+- 安装后的 runtime refresh

-文件责任边界：
+### M6 验收封板

- `electron/gateway/*`
- 运行时/类型定义文件
- 与聊天消息 tool block 相关的 renderer 连接层
+目标：
+- 把 mocked UI 回归、真实 smoke、打包态 smoke 分开管理。
+- 确保“同构 100%”是以真实链路为标准，而不是只看页面 mock。

-### SA-4：Skills UI & QA
+## 8. 推荐 sub-agent 数量

-职责：
+### 8.1 推荐编制

- 修 Skills 页安装入口文案和 fallback 路径
- 加 GitHub skill 链接安装入口
- 补手工 smoke checklist、失败态提示、回归文档
+- `7` 个 sub-agent

-文件责任边界：
+这是比较稳的数量。因为这次不是单点 API 迁移，而是同时跨越：
+- 运行时上下文
+- Gateway/tool 协议
+- 聊天 store 与 UI
+- 安装服务与刷新同步
+- 真实 smoke 与证据固化

- `src/pages/Skills/index.tsx`
- `src/pages/Skills/components/MarketplaceDrawer.tsx`
- `src/i18n/locales/*/skills.json`
- `docs/*`
- tests / smoke scripts
+### 8.2 最小可行编制

-### 主协调 agent
+- `5` 个 sub-agent

-职责：
+这只适合做“先跑通最小闭环”，不适合冲 `100%` 同构。

- 维护安装请求契约
- 控制范围不外溢到 skill 详情/配置等无关功能
- 处理 agent 间接口对齐与回归顺序
+## 9. sub-agent 分工建议

-## 8. 推荐推进顺序
+| 角色 | 数量 | 负责范围 | 文件所有权 |
+| --- | --- | --- | --- |
+| A1：证据与契约 | 1 | 复现并固化 `ClawX` 的真实行为、非目标、验收标准 | 只读分析、测试脚本、文档 |
+| M1：Runtime Context | 1 | agent/tool/context 资源、能力声明、聊天前置上下文拼装 | `resources/context/*` `electron/gateway/*` |
+| M2：Gateway / Tool Protocol | 1 | `tool_use / tool_result / thinking` 协议、事件、状态收敛 | `electron/gateway/*` `src/types/runtime.ts` |
+| M3：Renderer Tool UI | 1 | 聊天 store、工具卡片、结果渲染、tool-only 状态 | `src/stores/chat.ts` `src/pages/Home/index.tsx` `src/components/chat/*` |
+| M4：Skill Install Service / API | 1 | `skills.install` 契约、install service、安装后启用与刷新 | `electron/service/skill-install-service.ts` `electron/api/routes/skills.ts` `electron/gateway/handlers/skills.ts` |
+| M5：Conversational Behavior | 1 | “同一句对话触发安装”的桥接逻辑与行为测试 | `electron/gateway/handlers/chat.ts` `electron/gateway/*` `tests/*` |
+| I1：QA / Regression | 1 | 真实 Gateway smoke、打包态 smoke、失败态矩阵、文档回填 | `tests/*` `docs/*` |

-1. 先做 Phase 1，确保 `zn-ai` 不再是“安装 UI 有了，但执行器缺失”
-2. 再做 Phase 2，把安装服务抽象成统一入口
-3. 然后并行推进：
-   - SA-2 接 Host API
-   - SA-3 接聊天 tool
-   - SA-4 接 Skills 页面
-4. 最后统一做一次 GitHub skill 链接实装验证
+## 10. 建议推进波次

-推荐实装验证用例就用这次的目标 skill：
+### Wave 1

- `https://github.com/MiniMax-AI/skills/blob/main/skills/minimax-xlsx/SKILL.md`
+- `A1 + M1 + M2`

-原因：
+目标：
+- 冻结真实行为基线
+- 补齐运行时上下文
+- 打通最小工具协议链

- 它不是纯 `SKILL.md`，目录里有 `scripts/ references/ templates/`
- 能很好验证“必须安装完整 skill 目录”的约束
+### Wave 2

-## 9. 风险与控制
+- `M4 + M5`

-### 风险 1：把 GitHub `SKILL.md` 当成单文件安装
+目标：
+- 把现有 `SkillInstallService` 接进聊天运行时
+- 形成第一条“对话安装 skill”闭环

-后果：
+### Wave 3

- skill 看起来“装上了”，实际运行时找不到脚本和模板
+- `M3 + I1`

-控制：
+目标：
+- 补齐 UI、真实 smoke、失败态与打包态验收

- 安装器必须强制校验 skill 目录，不接受单文件安装
+## 11. 验收标准

-### 风险 2：覆盖用户已有 skill 目录
+### 11.1 功能验收

-后果：
+1. 在 `ClawX` 能触发安装的同一句话，在 `zn-ai` 上也能触发等价安装行为。
+2. `zn-ai` 对话里能看到工具执行轨迹，而不是只有普通文本回复。
+3. GitHub skill 链接安装成功后，skill 会出现在 Skills 页并处于启用状态。
+4. Marketplace 安装与 GitHub 链接安装共用同一套安装语义和错误处理。

- 覆盖用户定制内容
+### 11.2 失败态验收

-控制：
+1. 无效 GitHub 链接有明确提示。
+2. 目录缺 `SKILL.md` 有明确提示。
+3. 目标目录已存在时有明确覆盖语义。
+4. OpenClaw / browser / CLI 不可用时有明确失败原因。

- 默认禁止覆盖
- 返回 “destination exists”
- 只有 `force=true` 才允许升级或替换
+### 11.3 真实链路验收

-### 风险 3：路径文案与真实目录不一致
+1. 开发态通过。
+2. 打包态通过。
+3. 不依赖 mocked `gateway:rpc` 的真实 Gateway smoke 通过。
+4. 文档、测试与实现保持一致，不再出现“文档假设已同构，但代码实际上还没接通”的情况。

-后果：
+## 12. 当前不建议的误区

- 手动安装指导错误
+- 不建议把问题继续理解成“只差一个 GitHub URL installer”。
+- 不建议只在聊天里再加一条字符串正则特判，就宣布已和 `ClawX` 同构。
+- 不建议只补页面 API，不补 runtime context 和 tool protocol。
+- 不建议用 mocked UI 回归替代真实 Gateway / runtime / browser smoke。

-控制：
+## 13. 本轮计划结论

- 所有 install 相关提示统一使用 `~/.openclaw/skills`
-
-### 风险 4：scope 扩散
-
-后果：
-
- 为了 install 迁移，顺带重做整页 Skills 管理
-
-控制：
-
- install-only 原则
- 不改 detail/config 非必要逻辑
-
-## 10. 完成标准
-
-迁移完成后，至少满足以下标准：
-
- `zn-ai` 运行时包含可用的 `clawhub` 执行器
- Skills 页面可安装 marketplace skill
- Skills 页面可通过 GitHub skill 链接安装 skill
- 对话中贴 GitHub skill 链接可触发安装
- 安装结果会落到 `~/.openclaw/skills/<slug>`
- `openclaw.json` 中会自动启用该 skill
- 安装完成后，技能列表能刷新并可见
- 失败态提示明确，不再把错误归因为泛化的 “Install failed”
+本轮结论很明确：

+- `zn-ai` 已经有安装 skill 的底层能力。
+- `ClawX` 的优势主要不在 installer，而在完整的聊天运行时上下文和工具执行闭环。
+- 如果目标是 `100%` 同构，推荐按 `7` 个 sub-agent 的编制推进，先补 `Runtime Context + Tool Protocol`，再做 `skills.install` 对话桥接，最后收口到 UI 和真实 smoke。