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. 目标架构

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。