dsh-find-plugins

Readme

# dsh-find-plugins

给 DeepSeek Harness **找到对的那个**插件，而不是找到一堆插件。

**中文** | [English](./README.en.md)

本插件给 agent 一个工具 —— `find_dsh_plugins` —— 搜遍整个 DSH 插件生态，
并按 **相关度 × 可信度 × 新鲜度 × 热度** 排序，而不是只看 star。

---

## 为什么要有它

两种显而易见的做法都有可以量化的毛病。

**只取 GitHub 一页再按 star 排**，会让一个名字里恰好带关键词的大仓库压掉真正的插件。
搜 `memory` 返回 8 个通用 agent 库、**0 个 DSH 插件**；搜 `terminal` 第 1 名是一个终端
**coding agent**，不是插件。

**只按字面名字匹配**，会让一个名字里不含关键词的知名插件沉底。实测一个 ★3k 的终端 UI
插件在搜 `terminal` 时排到 **第 117 位**，前面全是一排 ★1 仓库。

本插件的做法是聚合多个目录、按各自隐含的审查强度加权，并且把热度保留为一个**有界**信号
而不是全部答案：

| 查询 | 本工具 | GitHub 单页 + star | 字面名字匹配 |
|---|---|---|---|
| `terminal` | `dsh-tianshu-tui` ★277 第 1（radar 实测 + 4 目录互证），`DSH-better-sidebar` ★3604 靠前 | 终端 coding agent 第 1 | 全是 ★1–★20 冷门仓库 |
| `memory` | `graph-memory` ★622、`MindMemOS` ★985、`dsh-mnemon` ★374 | 只有通用 agent 库 | `graph-memory` 第 1 |

---

## 安装

```sh
dsh plugin --profile <你的 profile> add dsh-find-plugins
```

然后重启 DSH。agent 就多了一个工具 `find_dsh_plugins`。

需要 DSH 带 `@deepseek-ai/dsh-tools` ≥ 0.1.5-rc.2、Node ≥ 22。**零运行时依赖。**

---

## agent 会看到什么

```
本次查询了 7 个源：dsh.so ✓(11322 条) · radar ✓(280 条) · 岚叔目录 ✓(558 条) · awesome-dsh-plugin ✓(3722 条) · npm ✓(50 条 · 相关 4980) · dsh.works ✓(13056 条) · GitHub topic ✓(34 条 · 相关 43)
候选池 16368 条，命中 1185 条，返回 8 条。
（还有 1177 条命中未返回：需要更多就把 limit 调大，上限 20。）

1. huiliyi37/dsh-tianshu-tui  ★276  更新于 2026-09-14
   用途：DeepSeek Harness 的终端 UI（TUI）。
   装它：@huiliyi37/dsh-tianshu-tui
   npm 版本：1.0.0-rc.1（仓库已核对）
   可信：radar + 岚叔目录 + awesome-dsh-plugin + dsh.works · 实测过
   兼容：核对于 dsh 0.1.0-rc.8（2026-08-20）
```

这段输出里有五处比看起来更重要：

- **源状态头** —— 让 agent 能区分「生态里就这些」和「有一个目录超时了」；`相关 N` 只在源自己报了
  匹配总数时出现（搜索类源读的永远是一页，不是全部）；
- **`可信`** —— 哪些目录认识它、验证等级、安全扫描结果；
- **`风险`** —— 各目录自己的审查结论，包括「发现安装生命周期脚本」这类东西；
- **`兼容`** —— 目录是拿哪个 dsh 版本核对过的。兼容性是这生态第一失败模式（核心一次发版就可能砍掉
  某个 client 模块入口），所以源报了就一定呈现；
- **`npm 版本`** —— 装它这一行给的是 npm 包时，附上 registry 里的版本；`（仓库已核对）` 表示拉过
  manifest 确认过 repository 字段指向同一个仓库。

---

## 怎么工作的

**数据源**（全部只读、实时拉取、进程内缓存）：

| 源 | 规模 | 提供什么 |
|---|---|---|
| dsh.so 索引 | ~15k | 验证等级 L1–L5、安全扫描、仓库健康度 |
| dsh.works 注册表 | ~13.5k | 每条都能指出安装路径的证据文件、核对时用的 dsh 版本、17 个功能标签、monorepo 子目录 |
| dsh-plugin-radar | ~280 | 唯一会**真的跑一遍**它收录的插件的目录 |
| awesome-dsh-plugin | ~3.6k | 人工双语描述、npm 包名 |
| 岚叔目录 | ~560 | 归档状态、最后提交时间、许可证、审查结论 |
| npm registry 搜索 | 实时(同类包 ~5k) | 只有它能看到"只发在 npm、没进任何目录、连仓库字段都没有"的包 |
| GitHub `dsh-plugin` / `dsh-plugins` topic | 实时 | 唯一能看到「今天刚发布」的源 |

挂掉的源只汇报自己的状态、不贡献内容；**拉取成功过、之后才失败**的源会回落到进程内缓存
副本并标注出来。**不落盘**，所以不会悄悄过期。

**安装目标（`装它` 那一行）**

- 源给的 npm 名优先；没有 npm 名时给 `github:owner/repo`；
- **源钉住的版本 ref 会保留**：目录发布的是 `github:o/r#v0.3.90`，就给 `#v0.3.90`，而不是退回
  `github:o/r` 去装"现在的 HEAD"——目录验证过的是那个版本；
- monorepo 里的包带 `#path:/<子目录>`（与 `#ref` 同时存在时用 `&` 连接）；
- 返回的每一行（≤20）会再拉一次 npm manifest 做校验：**manifest 声明了 `dsh`** 且
  `repository` 与条目仓库一致时，安装目标升级成 npm 包并附版本（npm tarball 是作者带着构建
  产物发布的；`github:` 安装不跑构建，仓库没提交 lib/ 的插件装出来就是缺文件的）。
  只有 npm 来源、且 manifest 里没有 `dsh` 的条目会被剔除并计数（关键字是自报的，不能当证据）。

**排序**

```
最终 = 相关度 × 可信度 × 新鲜度 × 热度
```

- **相关度** —— BM25，检索字段含 name / repo / npm 名 / 中英描述 / 分类 / topics。
  中文按**二字切分**，所以 `跨会话记忆` 能命中写着 `跨会话长期记忆` 的描述。
  原始分做了幂次压缩（0.45），否则乘数根本没机会影响排序。
- **可信度** —— 多源互相印证、dsh.so 验证等级、radar 实测过、安全风险、归档状态。
  **没有任何 DSH 专属目录认识它**的条目会被打折：dsh.so 也索引通用 agent 项目。
  npm 不算 DSH 专属证据——它的关键字是自报的。
- **新鲜度** —— 按最后提交时间衰减。**时间未知给中性分而不是零**：只有部分源提供时间，
  把「未知」当「已废弃」会把生态里大部分条目直接删掉。
- **热度** —— star 走**对数**，范围 0.6–1.3。★1 和 ★3000 只差约 1.5 倍。够用来偏向
  「有人在用」，不足以覆盖真实的相关度差距。

**风险等级是破平局用的，不是排除理由。** 自动化静态分析是弱信号，误报不该让一个好用的
插件掉队——何况装之前本来就该读源码。结论会**原样展示**在输出里，排序只轻轻推一下。

**查询**支持空格分隔的多个词，而且**更多词通常更好而不是更窄**——中英混排会让双语条目
的排序更准。几十组常见中英对照会自动扩展，**单复数也会双向折叠**（`screenshots` 与
`screenshot` 换出同一批候选——实测不折叠时一个命中 92 条、另一个只有 26 条且排名被换掉）；
只有调用方才知道的词（功能背后的服务名、用户没说出口的同义词）需要调用方补上。

**首调不等 20 秒**：目录类源是几 MB 的慢变数据，所以在插件加载后 5 秒起后台预热一次
（查询类源不预热——空查询不发请求）。冷启动实测从 ~20s 降到 ~3s。
`DSH_FIND_PLUGINS_NO_PREWARM=1` 可以彻底关掉预热。

**任何一次调用都有 25 秒的墙钟预算**：单个源的请求超时（最长 60s）约束不了整个调用，
所以超预算的源按 `timeout` 汇报（它的请求会继续跑并把结果留在缓存里，下一次是热的），
其余源照常返回。

---

## 边界

这些是刻意的，而且是有承重的：

- **只读。** 不装、不卸、不启停，绝不碰 profile 或 `cordis.patch.yml`。
- **不拥有索引。** 不内置快照、不写磁盘缓存。把过期数据当当前数据呈现，比没有数据更糟。
- **自己不做模型调用。** 调它的 agent 本身就是模型；再花一次调用去重排只会更慢更差。
- **完全不知道 dsh 外面套着什么桌面壳。** 本插件对任何 DSH 用户行为一致，这正是重点。

---

## 开发

```sh
npm install
node --test test/*.test.mjs
```

**测试全部离线**（`globalThis.fetch` 被换成分派器，认不出的 URL 直接抛错，所以漏网的网络请求会
以失败的形式暴露），跑一遍不到 1 秒。fixtures 是**从各源真实抓取的样本**（`test/fixtures/`），
解析器是对着源**实际发出的格式**写的，不是对着它**应该发出的格式**。

### 可选：GitHub token

唯一用到凭据的地方是 GitHub 搜索源（其余目录都是公开 JSON，不需要认证）。
不带 token 时走匿名配额 **10 次/分钟**，正常使用足够（每次调用默认 2 个请求：单数/复数话题各一页）；
想放宽就设一个：

```sh
DSH_FIND_PLUGINS_GITHUB_TOKEN=ghp_xxx     # 或沿用通用的 GITHUB_TOKEN
```

只读公开数据，不需要任何 scope。

---

## 许可

MIT