插件语义搜索ihuajiu/dsh-plugins-finder

dsh-plugin-finder

从 dsh.so 注册表查找 DeepSeek Harness 插件——就像 find-skill，但用于 dsh 插件。

此插件注册了一个 agent 工具，find_plugin：用自然语言描述需求，它会在 dsh.so 插件索引中搜索最匹配的插件，返回名称、GitHub 星标数、主题、描述、验证级别（L1–L5）、安全状态与风险、安装命令以及详情链接。

由 dsh.so 提供支持

the DeepSeek Harness plugin registry — discover, compare and install plugins · 发现、对比并安装 DSH 插件

中文版: README.zh.md

目录

1. 安装
2. 对等依赖警告（重要）
3. 用法
4. 输出格式
5. 搜索技巧
6. 配置
7. 数据源与匹配
8. 常见问题
9. 开发

1. 安装

此包发布在 @dsh-so npm 组织下：
- npm: https://www.npmjs.com/package/@dsh-so/dsh-plugins-finder
- 组织：@dsh-so——官方 dsh.so 插件注册表命名空间

从 dsh.so 市场安装（推荐）：

dsh plugin --profile web add @dsh-so/dsh-plugins-finder

其他 profile 用法相同——只需更改名称：

dsh plugin --profile tui add @dsh-so/dsh-plugins-finder
dsh plugin --profile headless add @dsh-so/dsh-plugins-finder

从本地检出安装（开发）：

dsh plugin --profile web add E:\AgentsWs\PluginBuilder\dsh-plugin-finder

⚠️ 版本说明：如果你使用的是 0.1.0，请先升级——0.1.0 将 @deepseek-ai/dsh-tools 作为常规依赖安装，这会与宿主机的副本冲突，并导致 agent 循环崩溃，报错 Cannot read properties of undefined (reading 'prepare')。已在 0.1.1 中修复；请重新安装：

dsh plugin --profile web add @dsh-so/dsh-plugins-finder@^0.1.1

重启 web profile 以加载新 bundle：

dsh web

重启后，find_plugin 工具会出现在会话中——只需告诉 agent 你需要什么（参见用法）。

升级 / 升级

dsh plugin --profile web add @dsh-so/dsh-plugins-finder@latest
dsh web    # restart to load the new bundle

卸载 / 卸载

dsh plugin --profile web remove @dsh-so/dsh-plugins-finder
dsh web    # restart to unload the bundle
⚠️ 卸载务必用包名，绝不把本地路径传给 remove/del，否则会删掉源码目录的文件。

2. 对等依赖警告（重要）

安装过程中你很可能看到如下 pnpm 输出：

WARN  Issues with peer dependencies found
└─┬ @dsh-so/dsh-plugins-finder 0.1.9
├── ✕ missing peer @deepseek-ai/cordis@^4.0.1
├── ✕ missing peer @deepseek-ai/dsh-tools@0.1.0-rc.6
└── ✕ missing peer @deepseek-ai/schemastery@^3.18.1

这是无害的误报——无需任何操作，插件可正常工作。

为什么会出现

- dsh plugin add 的实现方式是在 profile 目录中运行 pnpm add；pnpm 检查对等依赖时只对照 web profile 自身声明的依赖（目前仅有 @dsh-so/dsh-plugins-finder）。
- 这三个 @deepseek-ai/ 包由 DSH 宿主管理，实际位于上一级目录 ~/.dsh/profiles/node_modules 中。
- 运行时，Node 的模块解析会沿目录树向上查找，因此插件能正常解析到宿主提供的包。

如何确认没有问题

只需确认宿主侧的版本满足插件的要求。在当前环境已验证：

| 插件要求 | 宿主拥有 | 结果 |
|---|---|---|
| @deepseek-ai/cordis@^4.0.1 | 4.0.1 | ✅ |
| @deepseek-ai/dsh-tools@0.1.0-rc.6 | 0.1.0-rc.6 | ✅ |
| @deepseek-ai/schemastery@^3.18.1 | 3.18.1 | ✅ |

与 dsh 的适配版本

- 目标依赖线：@deepseek-ai/dsh-tools@0.1.0-rc.6 · @deepseek-ai/cordis@^4.0.1 · @deepseek-ai/schemastery@^3.18.1——即 dsh rc.6 系列。
- 实测环境：dsh 10.28.1（web profile）。
- 状态：作者声明（Declared），未经独立验证——遵循 dsh.so 兼容性矩阵语义。
- 升级 dsh 后自查：重启 profile 并确认 find_plugin 存在；若大版本升级跨了依赖线，先执行 dsh plugin --profile web update @dsh-so/dsh-plugins-finder 再试。

事实上，任何正确声明了对等依赖的第三方 DSH 插件，在安装到 profile 时都会触发同样的警告（harness 自身的 @deepseek-ai/dsh-tool-cordis 也以相同方式声明了 @deepseek-ai/cordis）。这只是 pnpm“信息不足”，并非错误。

应避免的修复方式

1. 不要将插件的 peerDependencies 移入 dependencies——否则每个插件都会自带一份宿主核心包的副本，遮蔽宿主的单例，并再次触发 ctx.tools 崩溃（即上文 0.1.0 的 bug）。
2. 避免将 3 个 peer 显式安装到 profile 中 —— 版本会被固定在那里；当宿主升级其核心包时，插件仍会加载旧版本，导致静默的 API 不匹配。

如果你只是想要一份干净的 CI 日志，可以显式安装这些 peer（代价是一次性的 declares no dsh.bundle 提示）：

dsh plugin --profile web add @deepseek-ai/cordis@4.0.1 @deepseek-ai/dsh-tools@0.1.0-rc.6 @deepseek-ai/schemastery@3.18.1

日常使用时：直接忽略该警告即可。

3. 用法

find_plugin 是一个智能体工具 —— 无需手动命令；只需告诉智能体你需要什么，它就会自动调用该工具。以下是一些示例提示（中文也可以）：

- “帮我找一个用于 OCR / 截图的插件”
- “我需要一个终端 TUI 插件”
- “有哪些用于 memory / RAG 的 dsh 插件？”
- “帮我找一个用于价格跟踪的插件”
- “帮我找支持 OCR / 截图转文字的 dsh 插件”
- “有没有能识别图片内容的插件？”

示例对话

英文 —— OCR / 截图

- 你： 帮我找一个用于 OCR / 截图的插件*
- 智能体： 自动调用 find_plugin，参数为 {"query": "vision OCR screenshots", "limit": 3} 并返回一个排序列表 —— 参见输出格式
- 你： 我该如何安装排名第一的那个？
- 智能体： 运行 dsh plugin --profile web add dsh-vision-router，然后重启 dsh web。

中文 —— 终端 TUI

- 你： 有没有终端 TUI 插件？
- 助手： 自动调用 find_plugin，query 为 "terminal TUI" → 返回 dsh-tianshu-tui、dsh-whale-tui、dsh-tui 等结果
- 你： 帮我装第一个
- 助手： 执行 dsh plugin --profile web add dsh-tianshu-tui，然后重启 dsh web。

工具参数

| 参数 | 必需 | 类型 | 描述 |
|---|---|---|---|
| query | ✅ | string | 需求，例如 "vision OCR screenshots"、"memory rag"。中英文均可；英文匹配效果更好 |
| limit | ❌ | number | 最大结果数；默认为 maxResults 配置（5），限制在 1–10 之间 |

4. 输出格式

每个结果包含：排名、插件名称、星标数、主题、验证级别（L1–L5）以及安全状态/风险徽章、描述、安装命令、详情链接。以下真实示例取自实时注册表 —— 排名和星标数会随时间变化。

find_plugin("vision OCR screenshots", limit=3)

1. dsh-vision-router — 46★ [developer, vision] · ✔ 基础验证通过 · ⚠️ 安全提示:中风险
Eyes for text-only DeepSeek Harness agents: built-in free vision chain (no key) + pixel-level vision tools (Q&A, grounding, crop, pixel diff, colors, OCR, SVG trace, cutout, screenshots)……
Install: dsh plugin --profile web add dsh-vision-router
https://www.dsh.so/plugins/dsh-vision-router/

2. agent-vision-toolkit — 819★ [developer, vision, automation, ai, ui] · ✔ 基础验证通过 · ⚠️ 安全提示:中风险
为纯文本模型"看图"设计更好的视觉工具箱和技能,支持多图理解,图片问答,
前端UI还原、GUI 自动化等……
Install: dsh plugin --profile web add agent-vision-toolkit
https://www.dsh.so/plugins/agent-vision-toolkit/

3. dsh-vision-toolkit — 317★ [vision, browser, automation, ui] · ✔ 基础验证通过 · ⚠️ 安全提示:中风险
让纯文本模型更好地做视觉任务的DeepSeek Harness插件:带意图的图片问答、长截图 OCR、UI 还原等……
Install: dsh plugin --profile web add dsh-vision-toolkit
https://www.dsh.so/plugins/dsh-vision-toolkit/

find_plugin("terminal TUI", limit=3)

1. dsh-tianshu-tui — 132★ [terminal, ui] · ✔ 基础验证通过 · 🔒 安全通过:低风险
dsh-tianshu-tui — DeepSeek Harness terminal UI
Install: dsh plugin --profile web add dsh-tianshu-tui
https://www.dsh.so/plugins/dsh-tianshu-tui/

2. dsh-whale-tui — 0★ [developer, terminal, ui] · ✔ 基础验证通过 · ⚠️ 安全提示:中风险
grok-build style terminal UI for DeepSeek Harness: a Rust/ratatui TUI shipped as a dsh plugin bundle
Install: dsh plugin --profile web add dsh-whale-tui
https://www.dsh.so/plugins/dsh-whale-tui/

3. dsh-tui — 4★ [developer, terminal, ai, ui] · ✔ 已收录(未功能测试) · 🔒 安全通过:低风险
Claude Code-style terminal UI for DeepSeek Harness agents, as an out-of-tree dsh plugin bundle
Install: dsh plugin --profile web add dsh-tui
https://www.dsh.so/plugins/dsh-tui-4/

find_plugin("memory rag", limit=3)

1. dsh-memory — 2★ [terminal, knowledge, storage] · ✔ 基础验证通过 · ⚠️ 安全提示:中风险
Cited memory over DSH's lossless session log — distilled, human-auditable facts with citations……; memory_read/memory_expand tools, recall index, and a dsh-memory CLI.
Install: dsh plugin --profile web add dsh-memory-2
https://www.dsh.so/plugins/dsh-memory-2/

2. dsh-memory — 1★ [knowledge, storage] · ✔ 基础验证通过 · ⚠️ 安全提示:中风险
Durable cross-session SQLite memory for DeepSeek Harness
Install: dsh plugin --profile web add dsh-memory
https://www.dsh.so/plugins/dsh-memory/

3. mindspace-dsh-session-memory — 1★ [knowledge, storage] · ✔ 基础验证通过 · 🔒 安全通过:低风险
Editable, session-isolated personalization memory for DeepSeek Harness
Install: dsh plugin --profile web add mindspace-dsh-session-memory
https://www.dsh.so/plugins/mindspace-dsh-session-memory/

💡 查询意图很重要:"price tracking" 匹配的是成本/余额追踪类插件(dsh-balance、deepseek-harness-wallet),而不是比价爬虫——匹配结果反映的是注册表实际描述的内容。

无匹配响应:

No plugins in the dsh.so registry matched that query. Suggest broader terms (e.g. "image", "terminal", "memory").

每个结果(无论匹配与否)都以 Powered by dsh.so 页脚加上一行版权/许可信息结尾(dsh-plugin-finder v0.1.8 · © 2026 zhoushimin · Apache-2.0)。可通过 attribution: false 禁用。

5. 搜索技巧

- 使用英文关键词:匹配时会对查询进行分词,因此单个英文单词(ocr、rag、tui)的效果远好于长短语。
- 要具体:"terminal TUI" 比模糊的描述更好。
- 使用主题标签:例如 vision、browser、automation、ui——主题命中的权重更高。
- 空查询会按星标返回排名靠前的条目(模型很少这样做,但该行为确实存在)。
- 匹配是关键词评分，而非 AI 语义：名称命中 +3，主题命中 +2，描述命中 +1，分数相同时按星数排序。如果措辞差异较大，请尝试换一种表述。

6. 配置

在宿主组合或 agent 预设的 cordis.yml 中配置（默认值即可，通常无需更改）：

- insert:
- id: dsh-plugin-finder
name: '@dsh-so/dsh-plugins-finder'
config:
indexUrl: https://www.dsh.so/plugins-index.json   # override for self-host / testing
maxResults: 5                                      # default result count
cacheTtlMs: 600000                                 # cache the index for 10 min
timeoutMs: 15000                                   # fetch timeout (ms)

| 配置 | 默认值 | 描述 |
|---|---|---|
| indexUrl | https://www.dsh.so/plugins-index.json | 机器可读的 dsh.so 插件索引 URL |
| maxResults | 5 | 未传入 limit 时的默认结果数量 |
| cacheTtlMs | 600000（10 分钟） | 在重新获取之前复用已获取索引的时长 |
| timeoutMs | 15000 | 获取超时时间（毫秒） |
| attribution | true | 在每个结果后附加“Powered by dsh.so”推广信息和版权页脚 |

7. 数据源与匹配

- 数据源：https://www.dsh.so/plugins-index.json —— 一个机器可读的索引，包含 dsh.so 上列出的每个插件（id、名称、描述、星数、主题、安装方式、url、验证级别、安全状态与风险）。
- 匹配：查询会被分词，每个词元都会评分——名称包含 +3，主题包含 +2，描述包含 +1；结果按分数排序，分数相同时按星数排序，然后取前 limit 个。
- 缓存：索引在 cacheTtlMs 内会被复用；不会重复请求。

8. 常见问题

问：已安装，但会话中没有 find_plugin 工具？
答：检查两件事：① dsh plugin --profile web list 确认它已安装；② 你必须重启 dsh web 才能加载新的 bundle。

问：我应该处理 missing peer 警告吗？
答：不用——它们是误报；参见第 2 节。

问：我的查询没有结果？
答：使用更宽泛的英文术语，例如 "image"、"terminal"、"memory"，或者去掉过于具体的限定词。

问：如何更新插件？
答：dsh plugin --profile web add @dsh-so/dsh-plugins-finder@latest，然后重启。

问：如何卸载？
答：dsh plugin --profile web remove @dsh-so/dsh-plugins-finder，然后重启。

问：PowerShell 报错“The splatting operator '@' cannot be used...”？
答：此插件现在是一个作用域包（@dsh-so/dsh-plugins-finder）。dsh plugin 命令会为你处理作用域名称，因此无需加引号。如果你在 PowerShell 中直接调用 npm/pnpm，则仍然需要加引号：npm view '@dsh-so/dsh-plugins-finder' version。

问：启动失败并报 ERR_MODULE_NOT_FOUND: Cannot find package '@dsh-so/dsh-plugins-finder'？
A：一个过期的安装条目（或 bundle patch 的 name）仍然引用旧的无作用域名称。按包名移除后重新安装：dsh plugin --profile web remove @dsh-so/dsh-plugins-finder，然后再次 add。

Q：npmjs.com 页面显示的版本比 registry 更旧？
A：网站有缓存；registry 才是权威来源。在终端中验证：npm view '@dsh-so/dsh-plugins-finder' version --prefer-online；强制刷新页面（Ctrl+F5）或等待几分钟。

Q：如何检查已安装的是哪个版本？
A：dsh plugin --profile web list 显示该 profile 的依赖；npm view '@dsh-so/dsh-plugins-finder' version 显示 npm 上的最新版本。

9. 开发

pnpm install     # 或 npm install（peer 依赖来自 dsh 宿主；devDependencies 用于本地构建/测试）
pnpm build       # tsc -> lib/
pnpm test        # node --test（匹配逻辑单元测试）

- bundle patch 在 cordis.patch.yml 中声明，由 package.json 中的 dsh.bundle.patch 引用。
- 发布到 npm 时，需包含 lib/、cordis.patch.yml、README.md 和 README.zh.md（参见 package.json 中的 files 字段）。

发布后自检 / Release verification

每次 npm publish 后，运行自动化安装检查，以确认两个受支持的安装源针对已发布产物仍然可用：

npm run verify:install            # 离线：npm registry + GitHub，功能冒烟测试
npm run verify:install -- --live  # 同时查询真实的 dsh.so 索引

该脚本会从 npm 以及从 github:ihuajiu/dsh-plugins-finder 将 @dsh-so/dsh-plugins-finder@ 安装到临时目录中（模拟 dsh profile 的设置），断言安装的 bundle 与预期的 name/version 匹配，并包含 lib/index.js + lib/match.js，然后对匹配逻辑运行功能冒烟测试。如果任一安装源失败，它会以非零状态退出。npm run verify（test + verify:install）是完整的门禁。

License

Apache-2.0 · Copyright (c) 2026 zhoushimin