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

ClawX Skill 安装能力迁移计划

1. 结论先行

本轮对比后的结论很明确：

• 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 目前都还没有原生支持这条链路。

本轮已经完成一项落地验证：

• 已把 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	结论
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 基础设施

2.2 关键差距

差距项	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	会误导手动安装与报错提示

2.3 关键证据

ClawX 现状：

• ClawX/package.json 已声明 clawhub 依赖
• ClawX/electron/gateway/clawhub.ts 的运行时安装参数只有 slug/version/force
• ClawX/electron/main/index.ts 会给 ClawHubService 接入 marketplace provider

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

3. 迁移范围

本计划只覆盖“安装 skill”闭环，严格排除以下范围：

• 不改 Skills 详情页视觉样式
• 不扩展 API Key / env 配置能力
• 不处理 skill 导入导出
• 不迁移 ClawX 全量 extension framework
• 不重构其它插件、频道、模型、任务执行逻辑

本次必须覆盖的范围只有四件事：

1. 让 zn-ai 先真正具备可工作的 marketplace slug 安装能力
2. 增加 GitHub skill 链接/仓库路径安装能力
3. 让“通过对话安装 skill”有清晰的运行时入口
4. 安装完成后自动启用、刷新、回显结果

4. 目标闭环

迁移完成后，zn-ai 至少要满足下面的用户路径：

4.1 Marketplace 路径

• 用户在 Skills 页面搜索 marketplace
• 点击安装
• 应用把 skill 安装到 ~/.openclaw/skills/<slug>
• 自动写入 enabled 配置
• 页面刷新后能看到 skill，且状态为已启用

4.2 GitHub 链接路径

• 用户在对话中粘贴 https://github.com/<owner>/<repo>/blob/<ref>/<path>/SKILL.md
• 系统把它解析为 repo/ref/repoPath
• 下载的是“整个 skill 目录”，不是单个 SKILL.md
• 校验目录中存在 SKILL.md
• 复制到 ~/.openclaw/skills/<skill-name>
• 自动启用并返回安装结果、实际路径、后续提示

4.3 失败时的最低可用体验

• 链接无效时，明确提示“不是可安装的 skill 目录链接”
• 目标目录已存在时，给出“已安装/是否覆盖”提示
• 网络失败时，提示下载失败与建议重试
• 目录缺 SKILL.md 时，提示“不是合法 skill 包”

5. 推荐设计

5.1 不把 install 继续绑定死在 clawhub

当前 zn-ai 的 /api/clawhub/install 天然只适合 marketplace slug。
如果要支持 GitHub skill 链接，建议把安装能力上提为统一安装服务：

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 };

建议新增：

• electron/services/skill-install.ts

由它统一负责：

• 解析安装源
• 下载或 checkout skill 目录
• 校验 SKILL.md
• 写入 ~/.openclaw/skills
• 更新 openclaw.json
• 返回安装结果

/api/clawhub/install 可以继续保留，但只作为 marketplace 的兼容入口，内部调用统一安装服务。

5.2 GitHub 安装逻辑建议直接落在 Electron TypeScript

不建议把 Python helper script 直接搬进 zn-ai 运行时。
建议在 Electron 侧用 TypeScript 实现，参考两类现有逻辑：

• GitHub 安装语义：参考本地 skill-installer 的 install-skill-from-github.py
• skill 目录复制语义：参考 ClawX/scripts/bundle-preinstalled-skills.mjs

运行时 GitHub install 最小步骤：

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 }

5.3 “通过对话安装”优先走 tool，而不是字符串黑魔法

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

skills.install({
  source: 'marketplace' | 'github-url' | 'github-repo-path',
  slug?: string,
  version?: string,
  url?: string,
  repo?: string,
  ref?: string,
  path?: string,
  force?: boolean
})

这样做的好处：

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

这次迁移里，不需要重做整个聊天架构，只要补一个 install skill 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/api/routes/skills.ts
• electron/gateway/clawhub.ts
• src/lib/skills-api.ts

SA-3：Chat Tool Bridge

职责：

• 给聊天链路增加 skills.install tool
• 负责“通过对话贴 GitHub skill 链接即可安装”的入口
• 负责 tool result 事件与前端可见反馈

文件责任边界：

• electron/gateway/*
• 运行时/类型定义文件
• 与聊天消息 tool block 相关的 renderer 连接层

SA-4：Skills UI & QA

职责：

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

文件责任边界：

• src/pages/Skills/index.tsx
• src/pages/Skills/components/MarketplaceDrawer.tsx
• src/i18n/locales/*/skills.json
• docs/*
• tests / smoke scripts

主协调 agent

职责：

• 维护安装请求契约
• 控制范围不外溢到 skill 详情/配置等无关功能
• 处理 agent 间接口对齐与回归顺序

8. 推荐推进顺序

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

推荐实装验证用例就用这次的目标 skill：

• https://github.com/MiniMax-AI/skills/blob/main/skills/minimax-xlsx/SKILL.md

原因：

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

9. 风险与控制

风险 1：把 GitHub SKILL.md 当成单文件安装

后果：

• skill 看起来“装上了”，实际运行时找不到脚本和模板

控制：

• 安装器必须强制校验 skill 目录，不接受单文件安装

风险 2：覆盖用户已有 skill 目录

后果：

• 覆盖用户定制内容

控制：

• 默认禁止覆盖
• 返回 “destination exists”
• 只有 force=true 才允许升级或替换

风险 3：路径文案与真实目录不一致

后果：

• 手动安装指导错误

控制：

• 所有 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”