feat: add GitHub skill installation support

- Implemented functionality to install skills from GitHub URLs. - Updated API to handle new installation requests from GitHub. - Enhanced UI to allow users to input GitHub skill URLs for installation. - Added translations for new GitHub installation features in English, Thai, and Chinese. - Created tests for the new skill installation service and API routes to ensure proper functionality.
2026-04-23 11:41:52 +08:00
parent f80bdc7f11
commit 655e7c51d2
16 changed files with 1818 additions and 51 deletions
--- a/docs/ClawX-Skill-Install-Migration-Plan.md
+++ b/docs/ClawX-Skill-Install-Migration-Plan.md
@@ -0,0 +1,427 @@
+# 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 链接，建议把安装能力上提为统一安装服务：
+
+```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 };
+```
+
+建议新增：
+
+- `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，例如：
+
+```ts
+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”
+