dsh-so/dsh-plugin-advisor

dsh-plugin-advisor

让 DSH Agent 自己会找插件 —— 一句自然语言检索 dsh.so 插件市场，拿回验证等级、安全状态与安装命令。

像 find-skill 找技能，这次是找插件。装完即用、零配置：插件只注册一个 plugin_advisor 工具，剩下的交给 Agent。

English: README.en.md

plugin_advisor 是 dsh.so 插件市场的检索入口：你用一句自然语言描述需求，它就从 dsh.so 实时插件索引里挑出最匹配的插件，返回插件名、GitHub star 数、标签、简介、验证等级（L1–L5）、安全状态与风险等级、安装命令和详情链接。从"想要"到"装好"，全程不必离开对话。

Powered by dsh.so
DeepSeek Harness 插件市场 —— 发现、对比并安装插件

功能特性

- 一句话找插件 —— "帮我找个能做 OCR 的插件"就够了，不用记插件名、不用翻市场，Agent 会自己调用 plugin_advisor。
- 结果是一张卡，不是链接堆 —— 直接给出最匹配插件的 star 数、标签、验证等级、安全徽标与详情链接，并附 2 条备选。
- 默认质量门槛 —— 只返回 L5（实测通过） 且 安全审计通过 的插件；warning 级发现可接受，high/critical 风险直接排除。
- 能力缺口自动兜底 —— 已装工具都做不到时，AUTO-TRIGGER 让 Agent 先去插件市场找，再说"做不到"。
- 确认后一键装好 —— 用户明确同意后，工具直接调用 dsh plugin add 安装（卸载同理），装完提醒重启。
- 中英文通吃 —— 内置 zh→en 概念词典（记忆→memory、账单→billing…）加 CJK 二元组匹配，中文长句同样命中。
- 零运行依赖 —— 只声明 3 个 peer 依赖，由 dsh 宿主统一提供，绝不打包宿主核心库副本。
- 离线也不空手 —— 索引缓存 12 小时并落盘，profile 重启后依然有效；抓取失败时回退到陈旧缓存。
- 可自建索引 —— indexUrl 可指向任意自建镜像。

快速上手

1. 安装 —— dsh plugin --profile web add @dsh-so/dsh-plugin-advisor
2. 重启 —— dsh web（新 bundle 需要重启才会加载）
3. 说需求 —— 对助手说 "帮我找支持 OCR / 截图转文字的 dsh 插件"，它会自动检索，并在你确认后装好

安装

| 场景 | 命令 |
| --- | --- |
| dsh.so 市场（推荐） | dsh plugin --profile web add @dsh-so/dsh-plugin-advisor |
| 其他 profile | dsh plugin --profile tui add @dsh-so/dsh-plugin-advisordsh plugin --profile headless add @dsh-so/dsh-plugin-advisor |
| 本地源码（开发调试） | dsh plugin --profile web add E:\AgentsWs\...\dsh-plugin-advisor |
| 升级 | dsh plugin --profile web add @dsh-so/dsh-plugin-advisor@latest |
| 卸载 | dsh plugin --profile web remove @dsh-so/dsh-plugin-advisor |

安装、升级、卸载之后都要重启 profile（dsh web）才会生效。
⚠️ 版本提示：若你装的是 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-plugin-advisor@^0.1.1

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

关于 peer 依赖警告（重要）

执行安装命令时，你大概率会看到这样一段 pnpm 输出：

WARN  Issues with peer dependencies found
└─┬ @dsh-so/dsh-plugin-advisor 0.1.1
├── ✕ 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 校验 peer 依赖时，只看 web profile 自己声明的依赖（目前只有 @dsh-so/dsh-plugin-advisor 一个）。
- 而这 3 个 @deepseek-ai/ 包由 DSH 宿主统一管理，实际安装在上一级目录 ~/.dsh/profiles/node_modules。
- 运行时 Node 的模块解析会逐级向上查找，所以插件能正常 import 到宿主提供的这些包。

如何确认没问题

| 插件要求 | 宿主实际版本 | 结果 |
|---|---|---|
| @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 rc.6 系列（@deepseek-ai/dsh-tools@0.1.0-rc.6 · @deepseek-ai/cordis@^4.0.1 · @deepseek-ai/schemastery@^3.18.1）。
- 实测环境：dsh 10.28.1（web profile）。
- 状态：作者声明（Declared），未经独立验证 —— 遵循 dsh.so 兼容性矩阵语义。
- 升级 dsh 后自查：重启 profile 确认 plugin_advisor 存在；若大版本升级跨了依赖线，先 dsh plugin --profile web update @dsh-so/dsh-plugin-advisor 再试。

事实上，DSH 生态里任何正确声明了 peer 依赖的第三方插件，装进 profile 时都会出现类似警告（harness 自己的 @deepseek-ai/dsh-tool-cordis 也是这么声明 @deepseek-ai/cordis 的）。这是 pnpm 的“信息缺失”提示，不是错误。

不建议的“修复”方式

1. 不要把插件的 peerDependencies 改成 dependencies —— 那会让每个插件自带一份宿主核心包副本，遮蔽宿主单例，反而触发 ctx.tools 崩溃（即 0.1.0 的 bug）。
2. 不建议把 3 个 peer 显式装进 profile —— 版本会被钉死在 profile 里；宿主将来升级核心包时，插件仍加载旧版，产生 API 错位的隐蔽问题。

若只是想让 CI 日志干净，可以显式安装（会换来一次性的 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

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

使用方法

plugin_advisor 是模型工具，不需要手动敲命令 —— 直接对助手说需求，它会自动调用。示例（中英文均可）：

- “帮我找支持 OCR / 截图转文字的 dsh 插件”
- “有没有终端 TUI 插件？”
- “我想做 RAG 记忆，有什么插件”
- “Find me a plugin for price tracking”

完整对话示例

中文 —— OCR / 截图

- 你：帮我找支持 OCR / 截图转文字的 dsh 插件*
- 助手：自动调用 plugin_advisor，参数 {"query": "vision OCR screenshots", "limit": 3}，返回一张推荐卡 —— 见下文输出格式
- 你：装第一个
- 助手：调用 plugin_advisor 并传 install: "github:leozou320-ai/dsh-macos-vision-ocr"，装好后提醒你重启 dsh web。

English —— terminal TUI

- You: I need a terminal TUI plugin
- Agent: calls plugin_advisor with "terminal TUI" → returns ranked matches
- You: Install the first one
- Agent: calls the tool again with install, then reminds you to restart dsh web.

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

工具参数

| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| query | 查询时必填 | string | 需求描述，如 "vision OCR screenshots"、"memory rag"。中英文均可，英文短词命中率更高 |
| limit | ❌ | number | 返回条数，默认取配置 maxResults（5），上限 10 |
| install | ❌ | string | 仅在用户明确同意安装后传入安装目标：npm 包名（可带 scope 与 @version）或 github:owner/repo |
| remove | ❌ | string | 仅在用户明确要求卸载后传入已安装的包名（不接受 github: 目标） |
| profile | ❌ | string | 安装/卸载的目标 profile，默认 web；非法字符会被过滤 |

输出格式

每次检索渲染成一张推荐卡：最匹配插件（名称 / star / 标签 / 验证等级 / 安全徽标 / 简介 / 详情链接）加 2 条备选。

plugin_advisor("vision OCR screenshots", limit=3) —— 真实输出（取自 dsh.so 实时索引，排名与 star 数会随时间变化）：

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

🏆 dsh-macos-vision-ocr  1★
vision desktop network
🏅 L5 · Run tested · 🔒 安全通过:低风险
Offline macOS Vision OCR for DSH — accurate, local, API-key free. | DSH 本地离线 OCR 插件
🔗 https://www.dsh.so/artifact/dsh-macos-vision-ocr/
━━━━━━━━━━━━━━━━━━━━━━━━━━
👉 回复「安装」即可自动装好，重启一次 dsh web 生效

备选：
2. dsh-vision-router (1,086★) — Eyes for text-only DSH agents: built-in free v…
3. ds-vision-plugin (5★) — Paste images into DSH with a four-model vision…

徽标含义：

| 徽标 | 含义 |
|---|---|
| 🏅 L5 · Run tested | 验证等级：L1 收录 → L5 实际跑通功能测试 |
| 🔒 安全通过:低风险 | 安全审计通过，低风险 |
| ⚠️ 安全提示:中风险 | 已审计但有 warning 级发现（默认门槛仍会放行） |
| ⏳ 安全检测进行中 / ❓ 未通过 / 🚨 高风险 | 未审计、审计失败或 high/critical 风险（默认门槛会排除） |

无匹配时：

没有找到完全匹配的 dsh.so 插件。已自动用更宽泛的关键词再试一次也没有结果。
可以直接告诉用户：该需求暂时没有现成插件，可关注 dsh.so 的更新，或描述更具体的需求换个说法再试。

每条结果（匹配或无匹配）末尾都会附带 Powered by dsh.so 推广与版权行（dsh-plugin-advisor v0.2.1 · © 2026 zhoushimin · Apache-2.0），可用 attribution: false 关闭。

查询技巧

- 中文查询已优化：内置中英概念词典（记忆→memory、账单→billing 等）与 CJK 二元组匹配，中文长句也能命中；英文短词仍最优。
- 把需求说具体："terminal TUI" 比 "好看的界面" 结果更准。
- 可以用标签词：如 vision、browser、automation、ui，标签命中权重更高。
- 空 query 会按 star 数返回 Top N（模型一般不会这么用，但行为如此）。
- 匹配是关键词打分，不是 AI 语义：名称命中 +3、标签命中 +2、简介命中 +1，同分按 star 数排序。措辞差异大时，换个说法再试。

配置

在宿主 composition 或 agent preset 的 cordis.yml 中配置（默认值即可，通常无需修改）：

- insert:
- id: dsh-plugin-finder
name: @dsh-so/dsh-plugin-advisor
config:
indexUrl: https://www.dsh.so/plugins-index.json   # 索引地址，自建/测试时覆盖
maxResults: 5                                      # 默认返回条数
cacheTtlMs: 43200000                               # 索引缓存 12 小时
timeoutMs: 15000                                   # 抓取超时（毫秒）

| 配置项 | 默认值 | 说明 |
|---|---|---|
| indexUrl | https://www.dsh.so/plugins-index.json | dsh.so 机器可读插件索引地址 |
| maxResults | 5 | 未传 limit 时的默认返回条数 |
| cacheTtlMs | 43200000（12 小时） | 索引缓存时长：一天最多抓取 2 次 |
| timeoutMs | 15000 | 抓取索引的超时时间（毫秒） |
| attribution | true | 在每次结果末尾追加 "Powered by dsh.so" 推广与版权信息 |
| minVerificationLevel | 5 | 结果需达到的最低验证等级（L1–L5），0 表示不过滤 |
| requireLowRisk | true | 仅保留已审计插件；warning 可接受，排除 high/critical |

数据来源、缓存与匹配规则

- 数据源：https://www.dsh.so/plugins-index.json —— dsh.so 全部插件的机器可读索引（id、name、description、stars、topics、install、url、verification 验证等级、security 安全状态与风险）。
- 匹配：query 分词 → 中文概念扩展（zh→en 词典 + CJK 二元组）→ 逐 token 打分（名称 +3 / 标签 +2 / 简介 +1）→ 按总分排序，同分按 star 数排序，取前 limit 条。
- 质量门槛：先按 minVerificationLevel 与 requireLowRisk 过滤，再对通过者排序。
- 缓存：内存 + 磁盘双层，命中 cacheTtlMs 内直接复用；磁盘缓存位于 %TEMP%\dsh-plugin-advisor\index-.json（按 indexUrl 的 sha256 前 16 位命名），profile 重启后依然有效。抓取失败时回退到陈旧缓存。

仓库结构

dsh-plugin-advisor/
├── src/
│   ├── index.ts              插件入口：Config schema、plugin_advisor 工具、卡片渲染、索引抓取与磁盘缓存
│   └── match.ts              纯函数匹配：分词、中英概念词典、CJK 二元组、打分排序
├── test/match.test.ts        匹配逻辑单测（node --test）
├── scripts/
│   ├── verify-install.mjs    发布后自检：npm / GitHub 两路安装 + 功能冒烟
│   ├── sync-readmes.mjs      中英 README 小节同步
│   └── restart-dsh-web.ps1   本地重启助手
├── assets/dsh-so-logo.svg    dsh.so 标志
├── cordis.patch.yml          bundle patch（package.json 的 dsh.bundle.patch 指向它）
└── README.md · README.en.md  中文（默认）/ 英文文档

常见问题 FAQ

Q: 装完插件，会话里没有 plugin_advisor 工具？
A: 检查两步：① dsh plugin --profile web list 确认已安装；② 安装后需要重启 dsh web 才能加载新 bundle。

Q: 安装时的一堆 missing peer 警告要不要管？
A: 不用管，是误报，见上文「关于 peer 依赖警告（重要）」。

Q: 查询没结果？
A: 换更宽的英文词，如 "image"、"terminal"、"memory"；或去掉过具体的限定词。

Q: 插件升级了，怎么更新？
A: dsh plugin --profile web add @dsh-so/dsh-plugin-advisor@latest，然后重启。

Q: 怎么卸载？
A: dsh plugin --profile web remove @dsh-so/dsh-plugin-advisor，然后重启。

Q: PowerShell 报错 "The splatting operator '@' cannot be used..."？
A: 只发生在 scoped 包（@scope/name）上 —— PowerShell 把行首 @ 当展开运算符，需要加引号：dsh plugin --profile web add '@scope/name'。

Q: 启动报 ERR_MODULE_NOT_FOUND: Cannot find package '@dsh-so/dsh-plugin-advisor'？
A: 有残留的安装条目（或 bundle patch 的 name）仍引用旧包名。先按包名移除再重装：dsh plugin --profile web remove @dsh-so/dsh-plugin-advisor，然后重新 add。

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

Q: 怎么查看当前安装的版本？
A: dsh plugin --profile web list 看 profile 的依赖；npm view @dsh-so/dsh-plugin-advisor version 看 npm 上的最新版。

开发与发布

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

- 插件 bundle 声明在 cordis.patch.yml，package.json 的 dsh.bundle.patch 指向它。
- 发布 npm 包需包含 lib/、cordis.patch.yml、README.md（中文，默认）、README.en.md（英文）与 assets/（见 package.json files 字段）。

发布后自检

每次 npm publish 后跑一遍自动安装检查，确认两种安装来源都能装上已发布的产物：

npm run verify:install            # 离线：npm registry + GitHub，功能冒烟
npm run verify:install -- --live  # 额外查询真实 dsh.so 索引
脚本会把 @dsh-so/dsh-plugin-advisor@ 分别从 npm 和 github:dsh-so/dsh-plugin-advisor 装进临时目录（模拟 dsh profile 的 settings），校验包名/版本与 lib/index.js、lib/match.js 是否齐备，再对匹配逻辑做一次功能冒烟；任一来源失败即非零退出。npm run verify（test + verify:install）是完整闸门。

许可

Apache-2.0 · Copyright (c) 2026 zhoushimin