English: README.en.md

装上它，你的 DSH Agent 就有了"自己找插件"的能力：用平常说话的方式描述需求，它从 dsh.so 实时索引里挑出最匹配的插件，把名称、star 数、标签、验证等级、安全状态、安装命令摆成一张卡片给你看；你点头，它就自动装好。从"想要"到"装好"，全程不离开对话。

这是什么？

一句话：给你的会话装一个插件搜索引擎。

没有它，你想装个新插件，得自己打开市场网页、翻列表、比对星级和安全状态、复制安装命令。有了它，这些全部变成一句话的事：

举个例子：你对助手说 "帮我找个能做 OCR 的插件"，它自动调用 plugin_finder，回你一张推荐卡；你回一句"安装"，它就装好了。

30 秒上手

1. 装 —— dsh plugin --profile web add @dsh-so/dsh-plugin-finder
2. 重启 —— dsh web（新插件要重启才会加载）
3. 说需求 —— "帮我找支持 OCR / 截图转文字的 dsh 插件"，剩下的交给它

更多安装方式（其他 profile、升级、卸载、老包迁移）见下方安装一节。

找到的结果长什么样？

每次检索都是一张推荐卡：最匹配的排最上面，附 2 个备选，关键信息一眼看全：

✅ 帮你找到了最匹配的插件

🏆 dsh-macos-vision-ocr · 1★ vision desktop network 🏅 L5 · Run verified ｜ 🔒 安全通过：低风险 Offline macOS Vision OCR for DSH — accurate, local, API-key free.｜DSH 本地离线 OCR 插件 🔗 dsh.so/artifact/dsh-macos-vision-ocr

👉 回复「安装」即可自动装好，重启一次 dsh web 生效

备选：2. dsh-vision-router（1,086★）· 3. ds-vision-plugin（5★）

🏷️ 出处：dsh.so 插件市场 · 实时索引

（摘自 dsh.so 实时索引的真实输出，排名与 star 数会随时间变化；卡片界面是中文，插件数据本身多为英文。）

没找到时它也会直说"该需求暂时没有现成插件"，而不是硬凑一个糊弄你。

它是怎么工作的？

几个你可能关心的点：

• 数据从哪来 —— dsh.so 官方索引（www.dsh.so/plugins-index.json），每个插件的名称、简介、star、标签、验证等级、安全状态都在里面。
• 不是每次都联网 —— 索引缓存 12 小时（一天最多抓 2 次），内存 + 磁盘双份；断网或抓取失败时自动用上次的数据，功能不中断。
• 想用自己的索引 —— 配置 indexUrl 指向自建镜像即可，见配置。

凭什么说推荐的"靠得住"？

不是随便抓几个凑数。每个插件要先过三道筛子，才有资格出现在你的推荐卡上：

卡片上徽标的含义：

| 徽标 | 意思 | |---|---| | 🏅 L5 · Run verified | 运行已验证：平台真实运行过这个插件的功能（L1 仅收录 → L4 装得上 → L5 跑得通，L5 最高） | | 🔒 安全通过：低风险 | 安全审计通过，没发现明显问题 | | ⚠️ 安全提示：中风险 | 审计发现了 warning 级小问题（仍会推荐） | | 🚨 高风险 / ❓ 未通过 / ⏳ 检测中 | 默认门槛直接排除，不会推荐给你 |

它怎么挑出"最匹配"的那个？

靠关键词打分——简单、透明、可预期，不是玄学：

两个实用推论：

• 中文也能搜 —— 内置中英概念词典（记忆→memory、账单→billing…）加 CJK 二元组匹配，中文长句照样命中；但短英文词（ocr、tui）命中率依旧最好。
• 没结果就换个说法 —— "好看的界面" 不如 "terminal TUI" 准。

会乱装东西吗？不会。

三道防线，安装和卸载永远在你的掌控之下：

还有一种容易忽略的场景：当你的需求已装的插件都做不到时，Agent 会自动让 plugin_finder 去市场先找一圈再回答——详见下文能力缺口自动搜索与安装确认。

能力缺口自动搜索与安装确认

当你的需求已安装的插件都无法满足时，agent 会自动调用 plugin_finder 搜索缺失的能力。结果默认通过质量门槛——L5（运行已验证）验证等级 且 安全审计通过（warning 级发现可接受，排除 high/critical 风险）。随后工具会高亮最匹配的一个插件、给出安装命令，并先向用户确认再安装——未经同意不会安装任何插件。

工具参数

plugin_finder 是模型工具，不需要手动敲命令。它接受这些参数：

| 参数 | 必填 | 说明 | |---|---|---| | query | 查询时必填 | 需求描述，如 "vision OCR screenshots"，中英文均可 | | limit | ❌ | 返回条数，默认 5，上限 10 | | install | ❌ | 仅在你明确同意安装后传入：npm 包名或 github:owner/repo | | remove | ❌ | 仅在你明确要求卸载后传入已装的包名（不接受 github: 目标） | | profile | ❌ | 安装/卸载的目标 profile，默认 web |

安装

| 场景 | 命令 | |---|---| | dsh.so 市场（推荐） | dsh plugin --profile web add @dsh-so/dsh-plugin-finder | | 其他 profile | dsh plugin --profile tui add @dsh-so/dsh-plugin-finderdsh plugin --profile headless add @dsh-so/dsh-plugin-finder | | 升级 | dsh plugin --profile web add @dsh-so/dsh-plugin-finder@latest | | 卸载 | dsh plugin --profile web remove @dsh-so/dsh-plugin-finder |

装、升、卸之后都要重启 profile（dsh web）才生效。

⚠️ 从旧包名迁移：0.3.0 起插件由 @dsh-so/dsh-plugin-advisor 更名为 @dsh-so/dsh-plugin-finder，工具名同步从 plugin_advisor 改为 plugin_finder。装过旧包的：先 remove 旧包 → 再 add 新包 → 重启。

⚠️ 卸载务必用包名，别把本地路径传给 remove，否则会删掉源码目录的文件。

💡 PowerShell 里报 The splatting operator '@' cannot be used...？给包名加引号即可：dsh plugin --profile web add '@dsh-so/dsh-plugin-finder'。

配置（可选）

默认值开箱即用，通常不用改。确有需要时，在宿主 composition 或 agent preset 的 cordis.yml 中覆盖：

- insert:
    - id: dsh-plugin-finder
      name: @dsh-so/dsh-plugin-finder
      config:
        indexUrl: https://www.dsh.so/plugins-index.json   # 换成自建索引
        maxResults: 5                # 默认返回条数
        minVerificationLevel: 5      # 最低验证等级（L1–L5），0 = 不过滤
        requireLowRisk: true         # 只推安全审计通过的插件
        cacheTtlMs: 43200000         # 索引缓存 12 小时
        timeoutMs: 15000             # 抓取超时（毫秒）
        attribution: true            # 结果末尾的 "Powered by dsh.so" 署名

常见问题

Q：装完会话里没有 plugin_finder 工具？ A：两步排查：dsh plugin --profile web list 确认装上了；然后重启 dsh web——新插件不重启不加载。

Q：安装时一堆 missing peer 警告，要紧吗？ A：不要紧，是误报，插件照常工作。原因和细节见下方折叠区。

Q：查了没结果？ A：换更宽的英文词（image、terminal、memory），或去掉太具体的限定词再试。

Q：怎么知道装的是什么版本？ A：dsh plugin --profile web list 看已装版本；npm view @dsh-so/dsh-plugin-finder version 看 npm 最新版。

Q：npmjs.com 页面上的版本比注册表旧？ A：网页缓存而已，注册表才是权威。终端验证：npm view @dsh-so/dsh-plugin-finder version --prefer-online；网页 Ctrl+F5 硬刷新或稍等几分钟。

Q：启动报 ERR_MODULE_NOT_FOUND: Cannot find package '@dsh-so/dsh-plugin-finder'？ A：有残留的安装条目还在引用旧包名。按包名移除再重装：dsh plugin --profile web remove @dsh-so/dsh-plugin-finder，然后重新 add。

安装时 pnpm 会打印类似这样的警告：

WARN  Issues with peer dependencies found
└─┬ @dsh-so/dsh-plugin-finder 0.3.0
  ├── ✕ missing peer @deepseek-ai/cordis@^4.0.1
  ├── ✕ missing peer @deepseek-ai/[email protected]
  └── ✕ missing peer @deepseek-ai/schemastery@^3.18.1

这是误报，不用处理。 一句话说清原因：插件运行需要的这 3 个 @deepseek-ai/* 包由 DSH 宿主统一提供，实际装在上一级目录（~/.dsh/profiles/node_modules），Node 运行时会自动向上找到它们；而 pnpm 只检查 profile 目录自己这一层，看不见宿主那层，所以"以为"缺依赖。dsh 生态里任何正确声明 peer 依赖的第三方插件都会触发同样的提示。

| 插件要求 | 宿主实际版本 | 结果 | |---|---|---| | @deepseek-ai/cordis@^4.0.1 | 4.0.1 | ✅ | | @deepseek-ai/[email protected] | 0.1.0-rc.6 | ✅ | | @deepseek-ai/schemastery@^3.18.1 | 3.18.1 | ✅ |

实测环境：dsh 10.28.1（web profile）。状态：作者声明（Declared），遵循 dsh.so 兼容性矩阵语义。

两个不要做的"修复"：

1. 别把 peerDependencies 挪进 dependencies —— 每个插件会自带一份宿主核心包副本，遮蔽宿主单例，直接把 agent 搞崩（0.1.0 的老 bug 就是这么来的）。
2. 别把这 3 个包显式装进 profile —— 版本会被钉死在 profile 里，宿主升级后插件还在用旧版，产生隐蔽的 API 错位。

只是想让 CI 日志干净的话，可以显式安装（代价是一条一次性的 declares no dsh.bundle 提示）：

dsh plugin --profile web add @deepseek-ai/[email protected] @deepseek-ai/[email protected] @deepseek-ai/[email protected]

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

开发与发布

pnpm install     # peer 依赖由宿主提供，devDependencies 仅用于本地构建/测试
pnpm build       # tsc -> lib/
pnpm test        # node --test，匹配逻辑单测

• 插件 bundle 声明在 cordis.patch.yml，由 package.json 的 dsh.bundle.patch 指向；发布包含 lib/、cordis.patch.yml、两份 README 与 assets/。
• 发布后自检：npm run verify:install（从 npm 和 GitLab 两条路各装一遍 + 功能冒烟）；npm run verify = 单测 + 自检，是完整闸门。

许可

Apache-2.0 · Copyright (c) 2026 dsh.so