Skip to content
dsh marketplace

dsh-plugin-resolver

Verified

dsh-plugin-resolver · v0.1.3 · MIT

Agent-facing DSH plugin resolver: search the catalog, pick a version the running DSH accepts, install (registry or GitHub-source build), and verify - no trial and error.

Install

dsh plugin add dsh-plugin-resolver

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

DSH Plugin Resolver — install the right plugin in one call

简体中文 | English

npm test 45 checks MIT DSH Node

dsh-plugin-resolver

一次工具调用，把插件装对。

搜索目录 → 同名消歧 → 按当前 DSH 内核选兼容版本 → registry / GitHub 源码安装 → 装后校验，一次走完。

实测装 1 个歧义 + 1 个 GitHub-only 插件：工具调用 约 45 → 6，耗时 20+ 分钟 → 约 3 分钟，失败重试 0。

host-only 插件 · 4 个工具 · 纯 ESM 免构建 · DSH >=0.2.0-rc.2 <0.3.0 · Node >=20

终端运行 npm test（2026-10-27 录制，当时 39 项检查）

真实输出：2026-10-27 录制时为 39 项；当前 npm test 为 45 项（35 逻辑 + 10 harness）全绿（VHS tape 可重录）

目录

为什么需要它

给一台 DSH 装两个真实插件：dsh-better-sidebar（npm 上的 latest 不保证兼容当前内核）和 dsh-browser（9 个同名 owner、GitHub-only、还要本地构建）。把安装交给 agent 时，手工路径实际发生的是：

手工路径上会发生什么 代价（真机实测）
从 GitHub Pages 拉一次社区目录（8.78 MB，2026-10-27；2026-10-18 为 6.4 MB） 91 s（2026-10-18 实测），模型还得读大量条目
目录里 406 组同名，dsh-browser 一条就有 9 个 owner 靠猜；其中 64 组星数最高的是 GitHub-only、同组却有 npm 包
latest 未必兼容当前内核（peer 线或 engines.dsh 高于宿主） 装上后被启动预检静默禁用
直连 npmjs 慢 两次 90 s 超时，换镜像后 13.4 s
GitHub-only 仓库不提交构建产物 main 指向不存在的文件——装上了也永远不会加载
装完不知道有没有生效 还要另找手段回读 loader entry / 前端 boot 表

这个插件把这些判断与验证固化一次；之后每次安装只需要一次工具调用。

它不是官方 Discover 的替代品：对点 UI 的人，插件市场已经够好；它服务的是把安装交给 agent 的人。

怎么工作

一次工具调用的五个阶段：检索、解析、安装、校验、上报

两条必须如实上报的失败路径也画在图里：没有兼容版本、装上了但没挂载。

四个工具里只有 plugin_install 会写环境；其余都是只读。歧义名、GitHub 源码、未知来源会先给出解析计划，不替你猜。

快速开始

第一次先把 resolver 装进来（约 10 秒）；从下一次安装开始，用户只需要说“帮我装 xxx”。

插件市场（推荐，图形界面）

插件 → 实验性插件 → 打开自定义插件市场 → 发现 → 添加索引源：

https://sakikoTGW.github.io/dsh-plugin-resolver/market/index.json

然后安装 dsh-plugin-resolver。

npm（已发布 0.1.3）

dsh plugin --profile <profile> add dsh-plugin-resolver

GitHub 源码 / tarball

# 建议锁 commit
dsh plugin --profile <profile> add github:sakikoTGW/dsh-plugin-resolver#<commit>

# 或者本地打包
npm pack && dsh plugin --profile <profile> add ./dsh-plugin-resolver-0.1.3.tgz

装完重启一次宿主。之后：

“帮我装 dsh-browser”          → 列出 9 个同名候选，要求 owner=，不猜
“装 dsh-builtin-browser”      → 选到与当前内核兼容的版本并装好
“帮我装 dsh-better-sidebar”   → latest 不兼容时自动降级，并说明跳过了哪些版本

plugin_resolve 真实调用动画：从目录与 registry 解析出兼容版本

真实调用动画（2026-10-18 本地 harness 录制，宿主 0.2.0-rc.2）：从真实目录与 registry 解析出一个兼容版本。

真实调用长这样（宿主 0.2.1-rc.2）：

$ plugin_resolve dsh-builtin-browser
target kind: npm   running DSH: 0.2.1-rc.2
package: [email protected]
install spec: [email protected]
registry: https://registry.npmmirror.com
notes:
- newest of 41 published versions whose DSH constraint accepts 0.2.1-rc.2

安装调用还会带上校验与重启判定：

$ plugin_install dsh-better-sidebar
target kind: npm   running DSH: 0.2.1-rc.2
package: [email protected]
install spec: [email protected]
...
restart: not required — manager applied the change in place

四个工具

工具 作用 是否改动环境
plugin_search 搜社区目录（npm 载体优先），排序并显式标出同名歧义 只读
plugin_resolve 只解析不装：目录条目、兼容版本、registry、是否需要源码构建 只读
plugin_install 完整安装：选版本 → 安装/构建 → 回读校验 → 下一步提示 写 profile
plugin_status 已装 bundle / loader entry / fiberPhase 盘点 只读

plugin_search 真实输出：9 个同名 dsh-browser 候选，要求 owner=

真实输出（本地 harness，2026-10-27）：同名歧义不会被猜，候选带 owner、星数、npm 名与安装命令。

plugin_resolve 真实输出：target kind / package / install spec / registry

真实输出：只解析、不写环境，先给出一份可复核的安装计划。

版本选择规则

  1. 运行时版本取 pluginManager.listBundles() 里 @deepseek-ai/dsh-base 的版本；
  2. 声明了 engines.dsh 的版本只看它（与宿主 dsh-app-boot 预检一致，peer 不再参与）；
  3. 未声明 engines.dsh 时，所有 @deepseek-ai/dsh / @deepseek-ai/dsh-* peer 必须满足（含 optional；workspace:^、workspace:~、workspace:* 视作当前宿主）；@deepseek-ai/cordis、@deepseek-ai/schemastery 等同命名空间但不同版本线的库不算运行时约束——误把兄弟库当内核线曾把 4/8 个包误判成“无兼容版本”（见 ABLATION）；
  4. 取第一个通过者；全不通过时列出最近版本的拒绝原因；用户显式给 version 时跳过求解。

安装路径与重启判定

  • registry 包：pluginManager.installBundle(name@resolved, { registry })，profile / lockfile / 激活生命周期都交给插件管理器；
  • GitHub-only：检出到 $DSH_HOME/plugin-sources/<owner>__<repo>，缺构建产物且声明了 build 时执行 pnpm install + pnpm run build，随后 installBundle('link:<pkgDir>')，已构建的检出直接复用；
  • 显式 spec（github: / link: / file: / https:）：原样交给插件管理器。

plugin_install 不再无条件要求重启；安装前后会比较 listBundles() 的 bundle 集合与运行时文件 hash（排除 README / docs / 版本号），新增 bundle 以管理器的应用结果为准：

变化 结果
无变化 / 仅版本号 / 管理器就地应用（含新增 bundle 的 HMR 重组合） restart: not required
管理器要求重启（bundle 新增、运行时代码变化、client 半变化） restart: required — <原因>
带 client 半的新插件 额外提示刷新 GUI

结构

稳定壳与热加载逻辑两层结构

稳定壳改动要重启；logic/ 改动下一次工具调用就生效。

host/register.js 每次调用计算 logic/ 下最大 mtime，以 import('./logic/api.js?v=<mtime>') 导入；逻辑模块之间用同一个 ?v= 传递依赖。Node 的 ESM 缓存按完整 URL 计，于是：

  • 改 logic/ 任何文件 → 下一次工具调用立即生效，不用重启宿主（实测 2–5 ms，重启约 30–40 s）
  • 只有改动工具定义层（index.js / host/register.js）才需要重启

这是为无 HMR 的打包运行环境设计的：宿主拿不到真 HMR 所需的 Node 内部模块加载器，但“重新 import 一个带新 query 的模块”完全可行。

效果与证据

手工路径与 resolver 的基准对比：目录、registry、调用次数、端到端耗时

同一件事的两种路径；数字来自 BENCHMARK.md 与 ABLATION.md。

指标 agent 手工路径 本插件 来源
工具调用（1 歧义 + 1 GitHub-only） ≈ 45 次 ≈ 6 次 BENCHMARK
端到端耗时 20–25 分钟 约 3 分钟（含不可压缩的安装/编译） BENCHMARK
决策链耗时 每次重新推 约 1.9 s（9 次调用，2026-10-27） BENCHMARK
目录获取 91.06 s（2026-10-18）/ 8.78 MB（2026-10-27） 1.5 s / 2 个请求（2026-10-27） BENCHMARK
安装失败重试 2 次 90 s 超时 0 次 会话日志
安装后额外探测 2 次 0 次 BENCHMARK

消融测试逐项拆能力，结果不是“慢一点”，而是装错版本 / 装错来源 / 装完不加载 / 静默失败：

  • 目录 6,896 条（npm 载体 2026.1026.10371，2026-10-27），406 组同名；64 组“按星数/第一个命中”会装到另一条来源
  • 8 个真实包里 2 个 latest 与宿主不兼容（宿主 0.2.0-rc.2；0.2.1-rc.2 上为 1/8）；朴素 peer 判断会把 4/8 误判成“装不了”
  • 同一份 registry 元数据：约 5–60×（2026-10-27 实测 12.2–37.4×，2026-10-18 为 60.3×）
  • GitHub-only 仓库入口探针 404（只有源码，没有构建产物）
  • 模拟“安装器报成功但进程里没有 entry”：无校验会把静默失败报成成功
  • 逻辑热加载 2–5 ms vs 重启 30–40 s

完整方法与口径见 BENCHMARK.md 与 ABLATION.md。数字只覆盖判断、试错与验证；下载和编译的物理时间压不掉。

市场收录

DSH 设置 → 插件市场 → 发现，搜索 plugin-resolve 显示 dsh-plugin-resolver 已安装

DSH 设置 → 插件市场 → 发现（搜索 plugin-resolve，2026-10-27 截图）：截图时为 v0.1.2。

DSH → 插件 → 发现：自定义索引源里的 dsh-plugin-resolver 卡片

DSH 桌面版 → 插件 → 发现（已添加本仓库索引源）里的样子（2026-10-27 截图）。

dsh.so 收录页：L5 运行已验证、低风险、MIT

dsh.so 收录页（2026-10-27 截图）：L5 运行已验证 · 低风险 · MIT。

dshbase 收录页：Verified · install-tested on dsh · Actively maintained

dshbase 收录页（2026-10-27 截图）：Verified · install-tested on dsh · Actively maintained。

收录状态与提交记录维护在 PUBLISHING.md。

测试与 CI

npm test        # 35 条离线逻辑检查 + 10 条宿主无关 harness = 45 项
npm run bench   # 插件路径基准（真实目录 + registry）
npm run ablate  # 消融测试（无副作用）
  • test/selftest.mjs：semver 子集、版本选择、spec 解析、目录检索（离线）
  • test/harness.mjs：假 Cordis ctx + 假 pluginManager 驱动真实工具体
  • test/benchmark.mjs / test/ablation.mjs：真实目录 + 真实 registry 的测量脚本
  • CI：每次 push/PR 跑 test（Node 24）；ablation 走手动 / 每周定时任务

沙箱或 CI 里默认缓存目录不可写时，用 DSH_HOME 指到临时目录即可：DSH_HOME=/tmp/dsh npm test。

已知限制

  • 兼容性判定对齐宿主 dsh-app-boot 的预检规则：声明了 engines.dsh 只看它，否则所有 @deepseek-ai/dsh* peer 都算（含 optional；workspace:^|~|* 视作当前宿主）；宿主精确版本豁免（allow-version）仍然优先；
  • 替换已加载插件仍需要重启宿主（loader 模块缓存 + 打包宿主无 Node 内部 loader）；新增 bundle 只看管理器的应用结果：管理器就地应用（HMR 重组合）时不再报 restart-required，只有它自己要求重启时才报；带 client 半的新插件会额外提示刷新 GUI；
  • 同名歧义不猜，需要调用方给 owner= 或完整 spec；
  • 目录是社区维护的第三方列表，插件只保证“按声明来源装对版本”，不做安全审计；
  • GitHub 源码构建需要 pnpm 与 tar：先找 DSH_PNPM_PATH（本插件约定，不是宿主契约），再找 PATH；宿主自带的 pnpm 未导出到 PATH，没有全局 pnpm 的机器需要先安装 pnpm。大仓库首次构建较慢。

反馈与安全

License

MIT

Built for DeepSeek Harness · 属于 dsh-plugins 插件集 · 图标与横幅源码在 assets/ · 回到顶部 ↑