vclike/dsh-find-plugin

dsh-find-plugin

在 agent 内部查找 DeepSeek Harness (DSH) 插件 —— 它会搜索实时的
GitHub dsh-plugin topic 以及精选的
awesome-dsh-plugin 列表（约 3400 条，带
双语描述），合并结果并返回可直接运行的
dsh plugin add 命令。

会话内发现 DSH 插件：同时查 GitHub dsh-plugin topic 与 curated 列表（约 3400 条，
全带中英双语描述），合并去重后给出可直接执行的安装命令。

这是 vclike/dsh-find-plugin，基于上游
awesome-dsh-plugin/dsh-find-plugin
0.3.7 的维护分支。改动与实测证据见 CHANGELOG.md。

Why this fork / 为什么有这个分支

上游匿名调用 GitHub 搜索接口。该端点仅允许
每个公网 IP 每分钟 10 次请求，而且该配额由同一出口 IP 背后的所有人共享 —— 因此该工具
总是以裸的 GitHub search HTTP 403 失败（实测：13 次快速调用 → 7 次 403 / 6 次 200；甚至一次会话的首次
调用也可能 403）。上游唯一的缓解措施是按查询 5 分钟缓存，而且
约 3400 条的 curated 列表仅在搜索成功之后才会被使用，因此它
永远无法充当兜底。

上游匿名调用 GitHub 搜索接口，而该接口只有 10 次/分钟/公网 IP 的额度、且按出口 IP
共享 —— 于是 find_dsh_plugin 经常直接以 403 失败（实测 13 次连发 7 次 403；一次会话的
首次调用就可能 403）。上游的防护只有 5 分钟按 query 缓存，而 curated 列表只在搜索
成功之后才被使用，起不到兜底作用。

本分支增加了 token 鉴权、双源合并、持久化 + 条件式
registry 缓存，以及真正的降级链。

本分支补上：token 鉴权、双源合并、registry 磁盘缓存 + 条件请求、以及真正的降级链。

What's different / 与上游的差异

| | 上游 0.3.7 | 本分支 0.4.0 |
|---|---|---|
| GitHub 鉴权 | 匿名（10 次请求/分钟/IP） | GITHUB_TOKEN 凭据 → 30 次请求/分钟，不按 IP 共享 |
| 403 / 429 | 抛出 | 重试一次，然后抛出携带 limit/remaining/resetAt 的类型化限流错误 |
| 网络错误 | 抛出 | 重试一次 |
| 失败缓存 | 无 | 60 秒（重试循环无法持续消耗配额） |
| curated 列表 | 仅用于描述增强，在搜索成功后 | 作为真正的第二数据源合并；同时作为兜底 |
| registry 获取 | 每小时 2.7MB，仅内存 | 磁盘缓存 + If-None-Match/If-Modified-Since（304 = 零响应体） |
| 离线兜底 | 内置快照（约 176 条，已过时） | 内存 → 磁盘缓存（约 3400 条）→ 内置快照 |
| 结果标注 | — | 每项 source，渲染文本中带 [curated] 标记 |
| exec.signal | 声明了 timeoutMs，signal 被忽略 | 转发；timeoutMs 25 秒 |
| 测试 | 未附带 | 33 个离线用例 + 可选的在线用例 + tsc --noEmit |

Install

dsh plugin --profile web add github:vclike/dsh-find-plugin

然后重启 dsh web（bundle 层在启动时组合）。

Configure a GitHub token (recommended)

没有 token 时该工具仍可工作，但被限制为每个公网 IP 每分钟 10 次请求，并且一旦配额耗尽就会降级到 curated 列表。有了
token，你可以获得每分钟 30 次请求，且没有共享 IP 干扰。
令牌从名为 GITHUB_TOKEN 的 DSH 凭据中读取（通过
ctx.credentials.resolve('GITHUB_TOKEN')）——与 dsh-github-companion 使用的是同一份凭据，
通常由 DSH 进程的 GITHUB_TOKEN 环境变量提供。该插件保持 零依赖：它从不
导入 @deepseek-ai/dsh-credentials，仅在凭据服务存在时通过该服务解析此引用。

未配置 token 时也能用，但受 10 次/分钟/公网 IP 限制，额度耗尽即降级到 curated 列表；
配置后为 30 次/分钟且不受共享出口 IP 影响。凭据名是 GITHUB_TOKEN（与
dsh-github-companion 同一份）。

Output

1. dsh-mnemon ★143 — 跨会话记忆 / cross-session memory
https://github.com/owner/dsh-mnemon
install: dsh plugin --profile web add github:owner/dsh-mnemon

2. some-curated-only ★7 [curated] — 仅见于 curated 列表的条目
https://github.com/other/some-curated-only
install: dsh plugin --profile web add github:other/some-curated-only

来源：GitHub 实时 dsh-plugin 搜索（按 stars 排序） + curated 列表（source=live，3408 条，
标 [curated] 的是仅见于 curated 的条目）。All plugins are third-party code — review the
source and pin a commit when installing. Browse https://awesome-dsh-plugin.com

排序：GitHub 结果在前（按 stars，与上游一致），curated-only 条目补足剩余名额。
GitHub 不可用时 note 说明原因，结果为 curated 关键词匹配（并标注）。

Tool parameters

| param | meaning |
|---|---|
| query (required) | 关键词，例如 "wechat notifications"、"TUI"、"跨会话记忆" |
| limit | 最大结果数，默认 8，上限 20 |
| lang | 首选描述语言（en / zh），默认 en |

Development

node --test "test/*/.test.mjs"               # 33 offline cases (mock fetch), ~8s
FINDP_LIVE=1 node --test test/live.test.mjs    # 3 cases against the real network
npm run typecheck                              # tsc --noEmit over src/.ts (TS 5.9.3)

lib//.js 是运行时产物与唯一真源；src//.ts 是类型镜像，由 typecheck
校验但不会编译覆盖 lib/——上游的 prepack 会静默还原对 lib/ 的修复，因此
此处已移除该脚本。

lib/ 是运行时产物与唯一真源；src/.ts 是类型镜像，由 typecheck 校验但不会编译
覆盖 lib/（上游的 prepack 会静默还原对 lib/ 的修复，本分支已移除该脚本）。

Layout / 目录：

lib/index.js                    tool registration, dual-source merge, rendering
lib/github.js                   GitHub search: token, retry, typed rate-limit error, caches
lib/registry.js                 curated registry: disk cache, conditional request, fallbacks
data/registry-snapshot.json     last-resort bundled snapshot
test/                           node:test suites (offline by default)

License

MIT —— 与上游相同。上游版权归其作者所有；详见 LICENSE。