# 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”