655e7c51d2
- 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.
428 lines
14 KiB
Markdown
428 lines
14 KiB
Markdown
# 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”
|
||
|