zn-ai/docs/ClawX-Skill-Install-Migration-Plan.md

# 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` 四层。

## 2. 当前真实对比

| 维度 | ClawX | zn-ai | 结论 |
| --- | --- | --- | --- |
| 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` 聊天入口 | 这是当前最直接的缺口 |

## 3. 已确认的关键证据

### 3.1 ClawX

- 聊天消息只是透传到 `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`

### 3.2 zn-ai

- 统一安装服务已经支持 `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`

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

### 4.1 P0 级缺口

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

### 4.2 P1 级缺口

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. 缺对“ClawX 为什么能做这件事”的真实证据抓取与固化。
2. 缺开发态、打包态、真实 OpenClaw 进程和真实浏览器的 smoke。
3. 缺对 `skills.installBundle` 这类旁支能力的目标边界说明。

## 5. 100% 同构目标

迁移完成后，`zn-ai` 需要做到和 `ClawX` 等价的三层能力：

### 5.1 运行时同构

- 对话进入 `OpenClaw` 风格的 agent/tool runtime，而不是只走普通文本 provider。
- 模型能够看到明确的 skill 安装能力说明与结构化 tool schema。
- `tool_use / tool_result / thinking` 能贯穿主进程、Gateway、renderer。

### 5.2 安装能力同构

- Marketplace `slug/version` 安装可用。
- GitHub `blob/.../SKILL.md` 和 `tree/...` skill 目录安装可用。
- 安装后自动启用，并能在 runtime 与 Skills 页即时可见。

### 5.3 对话行为同构

- 在 `ClawX` 能触发安装的同一句话，在 `zn-ai` 也能触发等价行为。
- 用户能在聊天中看到明确的工具执行过程、安装结果、失败原因和后续提示。
- 整个链路在开发态和打包态都可验证。

## 6. 目标架构

```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，而要成为聊天运行时可见、可调用、可回传结果的正式能力。

## 7. 分阶段同构计划

### M0 能力定标

目标：
- 固化 `ClawX` 当前“同一句对话能安装 skill”背后的真实机制。
- 区分“页面/API 安装能力”和“聊天运行时执行能力”。

产出：
- 行为证据清单
- 非目标边界
- 统一验收口径

### M1 Runtime Context 同构

目标：
- 给 `zn-ai` 引入与 `ClawX` 对齐的 agent/tool/context 注入。
- 让模型知道本机有哪些工具以及 `skills.install` 的输入约束。

涉及：
- 运行时 prompt/context 资源
- tool capability 声明
- chat send 前的上下文拼装

### M2 Gateway / Tool Protocol 同构

目标：
- 打通 `tool_use / tool_result / thinking / tool lifecycle` 的真实协议链。
- 不再只靠浏览器快捷特判。

涉及：
- `GatewayRpc`/event 类型补齐
- Gateway 事件分发
- 主进程到 renderer 的流式工具事件
- tool-only 消息收敛逻辑

### M3 Renderer Tool UI 同构

目标：
- 在聊天页显示工具调用、执行中状态、结果摘要和失败态。
- 让用户能看见“为什么安装成功/失败”，而不是只看到一段普通文本。

涉及：
- `src/stores/chat.ts`
- `src/pages/Home/index.tsx`
- `src/components/chat/*`

### M4 Skill Install Service / API 同构

目标：
- 统一市场安装、GitHub skill 目录安装、安装后启用和刷新语义。
- 明确 `skills.install` 的 tool 契约。

涉及：
- `electron/service/skill-install-service.ts`
- `electron/api/routes/skills.ts`
- `electron/gateway/handlers/skills.ts`
- `electron/gateway/rpc-dispatch.ts`

### M5 Conversational Install 同构

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

涉及：
- tool planner / conversational bridge
- 安装结果回写
- 安装后的 runtime refresh

### M6 验收封板

目标：
- 把 mocked UI 回归、真实 smoke、打包态 smoke 分开管理。
- 确保“同构 100%”是以真实链路为标准，而不是只看页面 mock。

## 8. 推荐 sub-agent 数量

### 8.1 推荐编制

- `7` 个 sub-agent

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

### 8.2 最小可行编制

- `5` 个 sub-agent

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

## 9. sub-agent 分工建议

| 角色 | 数量 | 负责范围 | 文件所有权 |
| --- | --- | --- | --- |
| 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/*` |

## 10. 建议推进波次

### Wave 1

- `A1 + M1 + M2`

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

### Wave 2

- `M4 + M5`

目标：
- 把现有 `SkillInstallService` 接进聊天运行时
- 形成第一条“对话安装 skill”闭环

### Wave 3

- `M3 + I1`

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

## 11. 验收标准

### 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 不可用时有明确失败原因。

### 11.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. 本轮计划结论

本轮结论很明确：

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