awesome-dsh

Readme

# awesome-dsh

按种类和功能浏览 GitHub topic [`dsh-plugin`](https://github.com/topics/dsh-plugin) 下的**全部**插件，英文简介由 Workers AI 自动译成中文。

线上地址：<https://dsh.jamintextiles.com>

本仓库同时是一个可安装的 DSH 插件：`dsh plugin --profile <profile> add github:stakeswky/awesome-dsh` 会把按需查插件的技能注册进 DSH。

## 架构

单个 Cloudflare Worker 承载整站。两条 cron 分工，数据与页面分离，更新数据不需要重新部署。

```
  ┌─ cron 17 */6 * * *  抓取 ─────────────────────────┐
  │   GitHub Search API ──▶ 按 star 分区取全量        │
  │                          ▼                        │
  │                    KV plugins:latest ◀────────┐   │
  └───────────────────────────────────────────────┼───┘
  ┌─ cron */5 * * * *   翻译 ─────────────────────┼───┐
  │   Workers AI ──▶ 每轮译 60 条 ──▶ KV 翻译缓存 ─┘   │
  └───────────────────────────────────────────────────┘
                             │
         浏览器 ◀─ /api/plugins.json ◀─ fetch()
         浏览器 ◀─ index.html（静态资源直出）
```

### 取全量：按 star 分区

GitHub 搜索对**单个查询**最多只返回 1000 条，而该 topic 已有 2600+ 仓库。抓取时把 star 区间切成若干片分别查询，某片命中数超过 1000 就继续二分；单一 star 值（如 `stars:0`）仍超限时改按仓库创建时间二分。任何分布都能取全，且随生态增长自动适应。

抓取全程约 3.5 分钟：匿名调用 GitHub 搜索限额为每分钟 10 次，代码按 6.5 秒一次节流；配了 `GITHUB_TOKEN` 后限额升到 30 次/分钟，间隔自动降到 2.1 秒。

### 翻译：增量填充 + 永久缓存

- 简介里中日韩字符达到 6 个即视为已是中文，跳过翻译。
- 译文按 `full_name` + 原文指纹缓存在 KV，原文没变就永不重译；抓到新快照时自动回填。
- 每 5 分钟译 60 条，首次填满 1400 余条约需 2 小时，之后只翻新增的。
- 模型 `@cf/meta/llama-3.3-70b-instruct-fp8-fast`（对比过 m2m100、llama-3.2-3b：m2m100 把 “AI agent” 译成 “AI特工”，3b 会脑补原文没有的内容）。
- 单条翻译失败只跳过该条，留待下一轮重试，不影响其余。

### 抓取失败的保护

抓取或校验失败时**保留上一份快照**，只把错误记到 KV，页面不会变空。新结果少于 100 条、或少于上一份的一半时同样拒绝发布。

## 端点

| 端点 | 说明 |
| --- | --- |
| `GET /` | 导航页面 |
| `GET /api/search` | 按相关度检索，只回少量精简结果；参数 `q`、`kind`、可重复的 `fn`、`limit`（默认 8，上限 25） |
| `GET /api/facets.json` | 可用的种类与功能标签及各自数量 |
| `GET /api/plugins.json` | 完整快照（约 1.1 MB，gzip 后约 290 KB）；带 `ETag`，命中条件请求返回 304 |
| `GET /api/status.json` | 抓取与翻译进度，以及未恢复的错误 |
| `POST /api/refresh` | 手动触发抓取，需 `Authorization: Bearer <REFRESH_KEY>` |
| `POST /api/translate` | 手动触发一批翻译，同样需要令牌 |

自动化调用方（如 `dsh-plugin-finder` skill）应当只用 `/api/search`：全量快照有 1.1 MB，为挑几个插件把整份目录读进上下文是浪费。检索排序为「词条得分 × 流行度系数」——该 topic 下有成批靠仓库名塞关键词的克隆仓库，纯词条打分会让它们压过成熟项目。

两个 `POST` 端点立即返回 `202`，任务在后台跑，结果轮询 `/api/status.json`。

**注意**：后台任务的存活时间短于一次全量抓取（约 3.5 分钟），所以 `/api/refresh` 在匿名抓取下大概率跑不完就被回收——**全量抓取以 6 小时的 cron 为准**（cron 有 15 分钟额度）。配上 `GITHUB_TOKEN` 后抓取缩短到约 70 秒，手动触发才稳定可用。`/api/translate` 一批只要十几秒，不受此限。

## 运维

部署：

```bash
cd /Volumes/data/dev/dsh-plugin-explorer/worker && npx wrangler deploy
```

查看抓取与翻译进度：

```bash
curl -s https://dsh.jamintextiles.com/api/status.json
```

手动催一批翻译（密钥存在 `worker/.refresh-key`，已 gitignore）：

```bash
cd /Volumes/data/dev/dsh-plugin-explorer/worker && curl -X POST -H "Authorization: Bearer $(cat .refresh-key)" https://dsh.jamintextiles.com/api/translate
```

实时日志（含两条 cron 的执行结果）：

```bash
cd /Volumes/data/dev/dsh-plugin-explorer/worker && npx wrangler tail
```

本地开发。Workers AI 只有远端实现，所以**不要加 `--local`**，否则 AI 绑定直接报错：

```bash
cd /Volumes/data/dev/dsh-plugin-explorer/worker && npx wrangler dev --port 8788
```

```bash
curl "http://localhost:8788/cdn-cgi/local/scheduled?cron=17+*/6+*+*+*"
```

## 配置

都在 `worker/wrangler.jsonc`，改完重新部署生效：

- `vars.GITHUB_TOPIC` — 抓取的 topic，默认 `dsh-plugin`
- `vars.TRANSLATE_BATCH` — 每轮翻译条数，默认 60
- `vars.CRON_FETCH` / `vars.CRON_TRANSLATE` — 必须与 `triggers.crons` 里的表达式逐字一致，否则 `scheduled()` 会拒绝执行并报错
- `triggers.crons` — 定时表达式

提高 GitHub 限额（可选，能让手动抓取也稳定跑完）：

```bash
cd /Volumes/data/dev/dsh-plugin-explorer/worker && npx wrangler secret put GITHUB_TOKEN
```

## 分类规则

种类（单选）与功能标签（可叠加）都由名称、描述、topic 的关键词匹配得出，规则是 `worker/src/index.ts` 里的 `KINDS` 和 `FUNCTIONS` 两个数组，发布快照时算好存进去。页面和 `/api/search` 共用这份结果，规则只有这一处；页面只保留 id 到显示名的映射。

分类只看**原文**：把译文一并计入会让 “vision → 视觉” 这类词重复命中，放大误判。搜索则同时匹配原文和译文，所以用中文也搜得到英文项目。

## 按需查插件的 skill

[`SKILL.md`](SKILL.md) 把「用户说要什么 → 检索本站 → 给出真实安装命令」这套流程固化下来，含检索技巧（中英混合词、宽泛诉求改用标签筛选）和两个已知坑：git 源插件首次 `add` 会被 pnpm 的 `allowBuilds` 拦下，以及未声明 `dsh.bundle` 的包只会作为普通依赖装上、不激活插件层。

同一份 SKILL.md 有两种装法，都只读公开端点，不需要任何密钥。

**装进 DSH**（本仓库即 DSH 插件包）：

```bash
dsh plugin --profile <profile> add github:stakeswky/awesome-dsh
```

插件把 `SKILL.md` 注册为 `ctx.skills` 上的 `dsh-plugin-finder`，DSH 智能体按需加载。

**装进 Claude Code**：

```bash
mkdir -p ~/.claude/skills/dsh-plugin-finder && cp SKILL.md ~/.claude/skills/dsh-plugin-finder/
```

装好后说「给 DSH 装个能看图的插件」「DSH 有没有记忆类插件」即可触发。

## 自行部署一份

`worker/wrangler.jsonc` 里的 KV namespace id 和自定义域名属于本站账号，换成自己的：

```bash
cd worker && npm install
npx wrangler kv namespace create DSH_PLUGINS   # 把输出的 id 填进 wrangler.jsonc
```

再把 `routes` 换成自己的域名（或整段删掉，走 `*.workers.dev`），然后：

```bash
npx wrangler deploy
npx wrangler secret put REFRESH_KEY   # 自定一个随机串，用于手动触发抓取/翻译
```

首份数据等抓取 cron 触发即可（最长 6 小时），或临时把 `CRON_FETCH` 与 `triggers.crons` 改密一些跑一轮再改回来。Workers AI 与 KV 均需 Workers 付费计划：全量抓取要跑约 3.5 分钟，超出免费版的 CPU 与子请求额度。