dsh-plugin-resolver

让 agent 自己把 DSH 插件装明白。 搜索 → 同名消歧 → 按当前内核选兼容版本 → 安装（registry 或 GitHub 源码构建）→ 装后校验，一次调用走完。

装两个典型插件：工具操作 −87%（45 → 6 次），实际耗时 −80%（20+ 分钟 → 约 3 分钟），失败重试 0。

基线是"同一个 agent、没装 resolver 时的手工流程"，不是官方 Discover 的点击次数——对点 UI 的人，市场已经够好；这个插件服务的是把安装交给 agent 的人。

搜索 → 同名消歧 → 按当前内核选兼容版本 → 安装（registry / GitHub 源码构建）→ 装后校验，一次调用走完。 host-only 插件，给 DSH 加 4 个模型工具，不注册服务、没有前端、纯 ESM 免构建。

---

为什么要它

场景：给一台 DSH 装两个真实插件——dsh-better-sidebar（npm 上的 latest 不保证兼容当前内核）和 dsh-browser（6 个同名 owner、GitHub-only、还要本地构建扩展）。当时在 agent 侧，这是这样一串手工活：

实际会发生的事	代价（真机实测，agent 手工路径）
目录在 GitHub Pages 上，拉一次 6.4 MB	91 s，模型还得读一堆条目
同一个名字有多个 owner（dsh-browser 有 6 个）	靠猜，猜错就装错来源
latest 未必兼容当前内核（peer 线或 engines.dsh 可能高于宿主）	装上后启动预检把它静默禁用
直连 npmjs 慢	两次 90 s 超时，换镜像后 13.4 s
GitHub-only 仓库不提交构建产物	dsh plugin add github:… 装了个 main 指向不存在文件的包
装完不知道有没有生效	需要另找手段回读 loader entry / 前端 boot 表

这个插件的存在意义：把上面这些判断与验证固化一次，之后每次只需一次工具调用。

怎么工作

flowchart LR
    Q["“装 xxx 插件”"] --> S["plugin_search<br/>目录检索 / 同名消歧"]
    S --> R["plugin_resolve<br/>读取宿主版本<br/>peer + engines 求解"]
    R --> C{有兼容版本?}
    C -- 否 --> X["列出拒绝原因<br/>（需要 DSH 几）"]
    C -- 是 --> V["选最高兼容版本"]
    V --> K{npm 发布?}
    K -- 是 --> I["installBundle<br/>最快 registry"]
    K -- 否 --> B["检出源码<br/>pnpm install + build<br/>link: 注册"]
    I --> H["回读 loader entry<br/>bundle / client 半"]
    B --> H
    H --> O["如实告知：刷新 / 重启 / 已生效"]

先装一次，之后都能一句话

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

• 官方版：插件 → 实验性插件 → 打开自定义插件市场 → 发现 → 添加索引源（URL 见下），安装 dsh-plugin-resolver；
• 或者 CLI（profile 名以你的 DSH 安装为准）：

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

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

"帮我装 dsh-browser" → 列出 6 个同名候选，要求 owner=，不猜； "装 dsh-builtin-browser" → 选到与你内核兼容的版本并装好。

明确的包直接装；歧义名、GitHub 源码、未知来源会先给出解析计划。它不是插件市场的替代品，而是"把安装交给 agent"的那条路径。

三种安装方式（任选）

要求 DSH >=0.2.0-rc.2 <0.3.0（已在 engines.dsh 声明）。纯 JS、无构建、无 install 脚本，三种方式都不需要 allowBuilds 授权：

# npm（已发布 0.1.2；profile 名以你的 DSH 安装为准）
dsh plugin --profile <profile> add dsh-plugin-resolver
# GitHub 源码安装（建议锁 commit）
dsh plugin --profile <profile> add github:sakikoTGW/dsh-plugin-resolver#<commit>
# tarball
npm pack && dsh plugin --profile <profile> add ./dsh-plugin-resolver-0.1.2.tgz

插件市场（Discover）索引（在插件页打开实验性「自定义插件市场」，然后 插件 → 发现 → 添加索引源）：

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

真实调用长这样：

$ plugin_resolve dsh-builtin-browser
target kind: npm   running DSH: 0.2.1-rc.2
package: dsh-builtin-browser@0.4.13
install spec: dsh-builtin-browser@0.4.13
registry: https://registry.npmmirror.com/
notes:
- newest published version whose DSH peer range accepts the running host

$ plugin_resolve dsh-better-sidebar
package: dsh-better-sidebar@0.28.0
install spec: dsh-better-sidebar@0.28.0

四个工具

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

版本选择规则

1. 运行时版本 = pluginManager.listBundles() 里 @deepseek-ai/dsh-base 的版本；
2. 逐版本从高到低检查：非可选 @deepseek-ai/dsh* peer 必须满足运行时版本；声明了 engines.dsh 也要满足；
3. @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 不再无条件要求重启；安装前后会比较：

• pluginManager.listBundles() 的 bundle 集合
• 已安装包运行时文件的 hash（排除 README / docs / 版本号）

结果：

• 无变化 / 仅版本号变化 / 管理器已就地应用 → restart: not required
• bundle 新增、运行时代码变化、client 半变化 → restart: required — <原因>

本插件自身的 logic/ 改动可以按 mtime 热加载，不需要重启；新增 bundle 或宿主壳变化仍然必须重启。

结构：稳定壳 + 可热加载逻辑

index.js           宿主入口（稳定）
host/register.js   工具 schema + pluginManager 桥接（稳定，改动需重启）
logic/             目录 / 版本 / 兼容 / 安装编排（每次调用按 mtime 重新 import）

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

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

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

效果

指标	agent 手工路径（未装 resolver）	本插件	来源
工具调用（装 1 歧义 + 1 GitHub-only 插件）	≈ 45 次	≈ 6 次	BENCHMARK
决策链耗时	—	1.05 s / 9 个决策任务	benchmark.mjs（官方 0.2.1-rc.2）
目录获取	91.06 s / 6.4 MB	0.86 s / 2 请求	benchmark.mjs（官方 0.2.1-rc.2）
安装失败重试	2 次 90 s 超时	0 次	会话日志
安装后校验调用	2 次额外探测	0 次	benchmark.mjs

基线是 agent 手工流程，不是官方 Discover 的点击次数：对点 UI 的人市场已经够用，这个插件服务的是把安装交给 agent 的人。

消融测试（逐项拆能力）见 ABLATION.md：同名 287 组、naive 会选错 51 组；8 个真实包中 2 个 latest 不兼容；镜像元数据延迟比 59.6–78.8×（随线路波动）；GitHub-only 入口探针 404；静默失败可检测；逻辑热加载 2 ms vs 重启 30–40 s。

node test/benchmark.mjs   # 插件路径基准
node test/ablation.mjs    # 消融测试（无副作用）

测试与 CI

npm test        # = selftest(25) + harness(10)
npm run bench   # 基准
npm run ablate  # 消融

• test/selftest.mjs：semver 子集、版本选择、spec 解析、目录检索（离线）
• test/harness.mjs：假 Cordis ctx + 假 pluginManager 驱动真实工具体
• test/benchmark.mjs / test/ablation.mjs：真实目录 + 真实 registry 的测量脚本
• CI：每次 push 跑 test；ablation 走手动/每周定时任务

已知限制

• 兼容性以 npm 元数据里的 peer / engines.dsh 为准，宿主启动预检另有判断时以宿主为准；
• 替换已加载插件仍需要重启宿主（loader 模块缓存 + 打包宿主无 Node 内部 loader）；新增 bundle 只看管理器的应用结果：管理器就地应用（HMR 重组合）时不再报 restart-required，只有它自己要求重启时才报；带 client 半的新插件会额外提示刷新 GUI；
• 同名歧义不猜，需要调用方给 owner= 或完整 spec；
• 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计；
• GitHub 源码构建依赖宿主环境里的 pnpm（PATH 或 DSH_PNPM_PATH）与 tar，大仓库首次构建较慢。

License

MIT