# dsh-skill-store

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/dsh-skill-store)](https://www.npmjs.com/package/dsh-skill-store)
[![npm downloads](https://img.shields.io/npm/dm/dsh-skill-store)](https://www.npmjs.com/package/dsh-skill-store)
[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/cxy9204/dsh-skill-store)

[English](README.md) | **简体中文**

**DeepSeek Harness 社区技能商店** —— 在应用内浏览、搜索并一键安装来自三个数据源的 **14 万+** 个 Agent Skills，按星标 / 下载量排序，中文分类直达。

装了它之后：打开 DSH Web 界面，进入「设置 → 技能商店」，就能直接搜技能、看热度、点一下装到本地，不用再去 GitHub 手动翻仓库、下载 ZIP、解压到 skills 目录。

---

## 三个数据源

> 数量为本机 2026-09-02 实测，源站在持续增长，实际以界面显示为准。

| 数据源 | 技能数 | 星标 | 下载量 | 分类 | 内容下载 |
|---|---|---|---:|:---:|:---:|:---:|:---:|
| **SkillHub**（默认推荐） | 134,262 | ✅ | ✅ | ✅ 13 个中英双语大类 | ✅ |
| **ClawHub** | 6,632 | ✅ 最高 3982★ | ✅ 最高 47 万 | ✅ 1694 个 topics | ✅ |
| **GitHub 镜像**（awesome-skills-cn） | 2,063 | ❌ 目录非仓库 | ❌ | ⚠️ 11 个 collection 级 | ✅ |

三个生态互不重叠（SkillHub 与 ClawHub 名称匹配率仅 0.2%），因此设计为**并列切换**而非合并。

### GitHub 源的分类标签与上游可信度

| Collection | 分类 | 上游仓库 |
|---|---|---|
| `anthropics-skills` | Anthropic 官方 | anthropics/skills |
| `openai-skills` | OpenAI 官方 | openai/skills |
| `claude-scientific-skills` | 科学研究 | K-Dense-AI/claude-scientific-skills |
| `huggingface-skills` | HuggingFace | huggingface/skills |
| `obsidian-skills` | Obsidian | kepano/obsidian-skills |
| 其余 6 个 | 社区合集 | 见源码 `COLLECTIONS` |

上游仓库 Star 数会显示在卡片上，作为来源可信度参考。

---

## 安装

插件已发布到 **npm registry**（`dsh-skill-store@0.1.x`），推荐直接安装：

```bash
dsh plugin --profile web add dsh-skill-store
```

安装后**重启 DSH Web** 即可在设置中看到「技能商店」入口。

从源码安装：

```bash
git clone https://github.com/cxy9204/dsh-skill-store.git
cd dsh-skill-store
npm install
dsh plugin --profile web add file:./path/to/dsh-skill-store
```

卸载：

```bash
dsh plugin --profile web remove dsh-skill-store
```

---

## 功能

- **三源切换** —— 顶部按钮切换 GitHub / ClawHub / SkillHub，切到后两者会出现排序下拉框
- **热度排序** —— 按星标 / 下载量 / 安装量 / 名称排序，热门技能一目了然
- **分类筛选** —— 下拉选择分类，每项标注技能数量
- **全文搜索** —— 同时匹配技能名与描述
- **一键安装** —— 技能写入 `~/.dsh/skills/<name>/SKILL.md`，装完即可用
- **详情预览** —— 点卡片看完整 SKILL.md 正文与热度数据
- **渐进式加载** —— 骨架索引秒开，描述与热度在后台逐步填充，进度可查

## 实机输出

插件挂载后的真实运行状态（DSH Web 默认 `127.0.0.1:3080`）：

```bash
$ curl -s http://127.0.0.1:3080/api/dsh-skill-store/status
```

```json
{
  "github":  { "total": 2063, "enriched": 0, "pending": 2063,
               "activeMirror": "https://gcore.jsdelivr.net/gh/lingxling/awesome-skills-cn@main" },
  "clawhub": { "loaded": true, "count": 6632, "builtAt": "2026-09-02T07:10:44.288Z" },
  "skillhub":{ "loaded": true, "count": 2005, "builtAt": "2026-09-02T07:08:05.871Z",
               "progress": { "pages": 20, "fetched": 2005, "total": 134262 } }
}
```

`skillhub.count` 小于 `progress.total` 是渐进加载的正常中间态：索引边跑边用，可用技能数持续增长直至全量。

单个技能的真实元数据（SkillHub API 原文截取）：

```json
{
  "name": "B站视频分析",
  "slug": "bilibili-content-research",
  "canonicalName": "@user_825d9e7e/bilibili-content-research",
  "category": "content-creation",
  "subCategories": ["自媒体运营", "选题策划"],
  "stars": 1, "downloads": 167, "version": "1.0.2"
}
```

界面入口：**设置 → 技能商店**。顶部三源切换按钮、搜索框、分类下拉、排序下拉（ClawHub / SkillHub 下出现），卡片显示名称、描述与星标 / 下载量，点击卡片弹出详情预览与安装按钮。

## 设计说明

**为什么 GitHub 源没有星标？** 单个技能在仓库里是一个**目录**而不是一个仓库，本身不存在独立的 star 字段。实测原始仓库 frontmatter 中 `tags` 覆盖率仅 2%、`category` 6%，全仓库只有 8 个不同 tag —— 所以「全是未分类」是数据源缺陷而非 bug。本插件改为按 collection 归类并标注上游仓库 Star 作为替代。

**网络适配（国内可用）**：`raw.githubusercontent.com` 在国内常被 DNS 阻断（报错 `ENOTFOUND`，且**不抛异常、只表现为数据为空**，极难排查）。本插件改用 jsDelivr CDN 多镜像回退，并记忆上次成功的源：

```
cdn.jsdelivr.net → gcore.jsdelivr.net → fastly.jsdelivr.net → raw.githubusercontent.com
```

**两阶段加载**：全量抓取 13 万个 SKILL.md 不现实。骨架只遍历目录树（十几秒），详情按需单拉 + 后台渐进填充，每 60 条落盘，重启续跑。

---

## 权限与外部服务

本插件会向以下外部服务发出**只读** HTTPS 请求：

| 服务 | 用途 |
|---|---|
| `api.github.com` | 读取 awesome-skills-cn 目录树 |
| `*.jsdelivr.net` | 读取 SKILL.md 文件内容（CDN 镜像） |
| `clawhub.ai` | ClawHub 技能注册表与文件内容 |
| `api.skillhub.cn` | SkillHub 技能注册表与文件内容 |

本地写入仅限：
- `~/.dsh/skills/` —— 安装技能的目标目录
- `~/.dsh/skill-store-cache/` —— 索引缓存

**无遥测、无数据上传、不需要任何账号或 Token。** 设置 `GITHUB_TOKEN` 环境变量只是把 GitHub API 限额从 60 次/小时提升到 5000 次/小时，不设置也能正常使用。

## 兼容性

- **Profile**：`web`（需要 web 界面，headless 下 UI 不可用，API 端点仍可用）
- **注入依赖**：`@deepseek-ai/dsh-client-ui-settings`、`@deepseek-ai/dsh-client-ui-slots`
- **React**：18.x（可选 peerDependency，由宿主提供）
- **Node.js**：≥ 20（依赖内置 `fetch` 与 ESM）

## 开发

```bash
git clone https://github.com/cxy9204/dsh-skill-store.git
cd dsh-skill-store
node --check lib/index.js   # 语法检查
```

源码结构：

```
lib/index.js      主插件：路由、GitHub 源索引、安装逻辑
lib/client.js     前端 UI（React，宿主注入）
lib/clawhub.js    ClawHub 数据源
lib/skillhub.js   SkillHub 数据源
cordis.patch.yml  DSH 插件装载声明
```

调试接口：

```bash
curl http://localhost:<port>/api/dsh-skill-store/status
curl "http://localhost:<port>/api/dsh-skill-store/sources"
```

## 常见问题

**首次打开显示 0 个技能？** SkillHub 源首次索引约需 1-3 分钟在后台跑，刷新即可。访问 `/status` 端点可查看实时进度。

**ClawHub 技能安装失败？** ClawHub 存在同名歧义（如 `github` 有 6 个作者），插件会自动选第一个（通常最热）。若装错，请从详情页确认作者。

**安装后界面没出现？** DSH 插件需要重启 Web 进程才能完成前端注入。

## 许可证

MIT © 2026 cxy9204

本项目为独立社区项目，与 DeepSeek AI 无隶属关系。