dsh-plugin-resolver 0.0.0-stage → 0.1.1

package/ABLATION.md

@@ -0,0 +1,78 @@
+# 消融测试（Ablation）
+
+把插件的每项能力单独"拆掉"，换成没有它时最自然的那种朴素做法，测量代价。全部是**真跑**：真目录、真 npm registry、真运行版逻辑；脚本无副作用（不安装、不改 profile）。
+
+```sh
+node test/ablation.mjs          # 人类可读报告
+node test/ablation.mjs --json   # 机器可读
+```
+
+运行环境：DSH 0.2.x（本仓库开发所对的宿主版本线）；日期 2026-10-18。网络类数字随线路波动，量级结论稳定。
+
+## 汇总
+
+| 拆掉的能力 | 朴素做法 | 实测代价 | 本插件 |
+|---|---|---|---|
+| 同名消歧 | 取第一个/星数最高命中 | 目录 287 组同名，其中 **51 组**星数最高的是 GitHub-only、同组却有 npm 包 → naive 会装到另一条来源 | 显式列出 owner/星数/来源，要求 `owner=` 或完整 spec |
+| 版本兼容解析 | 直接装 `latest` | 8 个样本中 **2 个 latest 与宿主不兼容**；本插件为挑兼容版本**累计跨过 12 个更新版本** | 逐版本检查 `@deepseek-ai/dsh*` peer + `engines.dsh`，并给出拒绝原因 |
+| peer 作用域（只认 dsh*） | 把所有 `@deepseek-ai/*` 当内核版本 | 曾经的实现 bug：**4 / 8 个包被误判为"无兼容版本"**（把 cordis `^4.x`、schemastery `~3.x` 当成内核版本） | 只把 `@deepseek-ai/dsh*` 与 `engines.dsh` 当运行时约束 |
+| registry 选择 | 直连 `registry.npmjs.org` | 同一份元数据：**784 ms vs 镜像 13 ms（60.3×）**；会话实测安装面：npmjs 两次 90 s 超时，镜像 13.4 s 装完 170 包 | 优先 `pluginRegistryProbe.fastest()` / 配置镜像 |
+| GitHub-only 源码构建 | `dsh plugin add github:…` 后直接用 | 样本仓库 `lib/index.js` 探针 **404**：包声明的入口不在仓库 → 插件无法加载（`src/` 才是源码） | 自动检出 → `pnpm install` → `build` → `link:` 注册 |
+| 安装后校验 | 相信安装器返回的 `applied` | 模拟"安装器报成功但进程里没有 entry"：无校验会把**静默失败报成安装成功** | 同一调用内回读 loader entry / bundle / client 半，报 `restart` 或刷新提示 |
+| 逻辑热加载 | 改代码 → 重启宿主 | 重启 **约 30–40 s** 且中断进行中的回合（开发本插件时为此重启 3 次） | cache-busted 重新 `import`：**3 ms** |
+
+## 分项细节
+
+### A1 同名消歧
+
+- 目录 5,065 条，`base name` 相同的有 **287 组**
+- 其中 **51 组**：星数最高的是 GitHub-only，同组却有 npm 发布版 → "按第一个命中/最高星"的选择会装到**不同来源的另一个插件**
+- `dsh-browser` 一条就有 6 个 owner；没有 owner 维度时无法判断你要哪个
+
+### A2 版本兼容
+
+样本 8 个真实 npm 包，逐个拉一次 registry 元数据：
+
+| 包 | latest | latest 兼容? | 本插件选择 | 跳过版本数 | naive（放大 peer） |
+|---|---|---|---|---|---|
+| dsh-better-sidebar | 0.28.0 | ❌ | **0.26.1** | 2 | 无（误判） |
+| dsh-builtin-browser | 0.4.13 | ✅ | 0.4.13 | 0 | 无（误判） |
+| dshmarket | 1.66.36 | ✅ | 1.66.36 | 0 | 无（误判） |
+| dsh-find-plugin | 0.4.0 | ❌ | 无（该包要求更高内核） | 10 | 无 |
+| dsh-plugin-subscriptions | 0.9.9 | ✅ | 0.9.9 | 0 | 无（误判） |
+| @anweat/dsh-browser | 0.2.1 | ✅ | 0.2.1 | 0 | 0.2.1 |
+| dsh-config-manager | 0.1.76 | ✅ | 0.1.76 | 0 | 0.1.76 |
+| @noob-stupid/dsh-plugin-console | 0.5.59 | ✅ | 0.5.59 | 0 | 0.5.59 |
+
+要点：**"直接装 latest" 在 2/8 的样本上会装坏**；而"把所有 `@deepseek-ai/*` 都当内核约束"这个更隐蔽的错误会让 **4/8 的包看起来完全装不了**——这正是本仓库开发过程中真实踩到的坑（已用单测钉住）。
+
+### A3 registry
+
+同一份 `dsh-better-sidebar` 元数据单次读取：`registry.npmjs.org` **784 ms**，`registry.npmmirror.com` **13 ms**（60.3×）。
+安装面更悬殊：会话实测 npmjs **两次 90 s 超时**（90,103 ms / 90,145 ms），镜像 **13.4 s** 装完 170 个包。
+
+### A4 GitHub-only 源码构建
+
+对 `omdsh-dev/dsh-browser` 的桥接子包做仓库探针：
+
+- `lib/index.js` → **404**（构建产物不在仓库）
+- `src/index.ts` → 200（只有源码）
+- `package.json` → 200
+
+结论：不构建就注册，等于装了一个 `main` 指向不存在文件的包——**装上了也永远不会加载**。
+
+### A5 安装后校验
+
+模拟"安装器返回 `applied`，但当前进程里没有该 loader entry"：
+
+- 无校验：向用户报告"安装成功"
+- 本插件：同一调用内报出 `loader entry: not found`，并按 client 半情况给出刷新/重启提示
+
+### A6 逻辑热加载
+
+带新 `?v=` 重新 import 逻辑模块：**3 ms**，两次加载是不同模块实例。
+对照：重启宿主约 **30–40 s**，且会中断进行中的回合；开发本插件期间为此重启了 3 次。
+
+## 结论
+
+每项能力拆掉后，失败方式都不是"慢一点"，而是**装错版本 / 装错来源 / 装完不加载 / 静默失败**——这些恰好是这次真实装机时全部踩过一遍的坑。消融结果与 [BENCHMARK.md](BENCHMARK.md) 的端到端对比互相印证：插件省下的主要是**判断与验证**，不是下载和编译的物理时间。

package/BENCHMARK.md

@@ -0,0 +1,76 @@
+# 效果与复杂度量化
+
+两层数字：**插件路径**全部是本次在本机跑出来的实测值（`node test/benchmark.mjs` + 会话日志）；**手工路径**取自今天这次真实安装过程里记录到的耗时/输出，标注为实测的就来自日志或终端计时，标注为估算的按页面对比估算。
+
+复现插件侧数字：
+
+```sh
+node test/benchmark.mjs
+```
+
+## 1. 插件路径实测（决策链，不含 pnpm 真正下载安装）
+
+| 任务 | 工具调用 | 耗时 | 网络请求 | 返回给模型的文本 |
+|---|---|---|---|---|
+| 目录冷加载（npm 载体） | `plugin_search` | 943 ms | 2 | 955 B |
+| 同名歧义搜索 | `plugin_search` | 34 ms | 0 | 1,932 B |
+| 目录命中缓存 | `plugin_search` | 17 ms | 0 | 2,042 B |
+| 同名歧义解析 | `plugin_resolve` | 16 ms | 0 | 1,611 B |
+| 按 `engines.dsh` 选版本 | `plugin_resolve` | 57 ms | 1 | 241 B |
+| 跨 peer 线选版本（含跳过 0.28.0） | `plugin_resolve` | 105 ms | 1 | 835 B |
+| GitHub 源码安装计划 | `plugin_resolve` | 10 ms | 0 | 438 B |
+| 安装编排 + 安装后校验 | `plugin_install` | 47 ms* | 1 | 1,148 B |
+| 已装插件盘点 | `plugin_status` | 1 ms | 0 | 246 B |
+| **合计** | **9 次调用** | **1.23 s** | **5 次请求** | **9.2 KiB** |
+
+\* 47 ms 只覆盖解析+调 `installBundle`+回读校验；真正 pnpm 安装时间由插件管理器独占（镜像上一次 170 包的安装实测 13.4 s）。
+
+## 2. 同一件事的手工路径 vs 插件路径
+
+以"装一个名字有歧义的插件 + 一个 GitHub-only 插件"为例：
+
+| 环节 | 手工（本次会话实测） | 插件（本次实测） | 缩减 |
+|---|---|---|---|
+| 获取插件目录 | GitHub Pages 拉 6.4 MB / **91.06 s**；模型还要读大量条目 | npm 载体 2 个请求 / **0.94 s** | **约 97× 时间**，目录内容不进模型上下文 |
+| 同名候选消歧 | 打印约 60 条中英双语条目（约 20 KB）后人工挑 | 1 次调用，1.9 KB，带 owner/星数/npm 名/install 命令 | 输出体积 **约 10×** 更小，决策 1 步 |
+| 版本兼容判定 | 手工对着 22 个版本推 semver；中途写错过"哪些 peer 算内核约束"（靠 19 条单测才抓出来） | **0.06–0.11 s**，自动降级并列出被跳过版本及原因 | 1 次调用，**0 次试错** |
+| 安装 | 直连 npmjs **两次 90.1 s 超时**（90,103 ms / 90,145 ms），换镜像后 13.4 s 成功 | 自动走 `pluginRegistryProbe.fastest()`，**13.4 s 一把过** | 省 **约 180 s / 2 次失败** |
+| GitHub-only 源码安装 | 下载 2 s + `pnpm install` 113 s + build 9 s + 扩展安装 6.7 s + 构建 ~2 s，外加 5+ 个分步决策与一次装错依赖的返工 | 同一条流水线收进 1 次 `plugin_install`（约 140 s，主要是不可压缩的编译时间） | 决策步骤 **5+ → 1**，失败点内聚 |
+| 安装后校验 | 额外 2 次探测：`/ext/bridge-config` HTTP + GUI boot 清单 | 同一调用内回读 loader entry / bundle / client table，**0 次额外调用** | 2 → 0 |
+| 读文档 | 2 个 dshbase 页面 ≈ 60 KB 文本（估算） | 目录里一行摘要（< 1 KB） | 约 **60×** 上下文体积 |
+| **合计** | **约 45 次工具调用**、**约 20–25 分钟**（含试错与重启折腾）、**3–4 次失败/返工** | **约 6 次调用**、决策链 **1.2 s** + 不可压缩安装/编译 ≈ **3 分钟**、**0 次失败** | 调用 **−87%**，时间 **−80% 以上**，失败 **→ 0** |
+
+> 口径说明：手工的 91 s / 90 s×2 / 13.4 s / 113 s / 6.7 s 都是本机日志或计时器实测；45 次调用与 20–25 分钟是按本次会话记录统计的近似值；60 KB 的文档体积为估算。
+
+## 3. 复杂度从哪来、被收进哪里
+
+手工路径要求模型（或人）当场掌握 9 类领域知识，每一类都可能单独出错：
+
+1. 目录从哪来、结构是什么、同名如何区分
+2. npm registry 文档结构、怎么拿全部版本与 peer
+3. semver 的 `includePrerelease` 语义与 caret 跨 minor 的陷阱
+4. 哪些 `@deepseek-ai/*` peer 才算内核版本约束（cordis/schemastery 不算）
+5. 区域网络：npmjs 慢、要选镜像、要与安装器的 registry 参数对上
+6. `dsh plugin` 安装路径 / generation 安装语义 / 何时 restart-required
+7. GitHub-only 仓库不提交 `lib/`，必须先构建再 `link:` 注册
+8. 安装后如何判断真的生效（loader entry、bundle、client boot 表）
+9. 哪些失败是"等一下重试"、哪些是"永远装不上"
+
+这些现在被固化在约 **1,820 行**代码里：
+
+| 文件 | 行数量级 | 承担的知识 |
+|---|---|---|
+| `logic/semver.js` | ~300 | 第 3 条：版本比较 + range 求值（含 `-0` 上界语义） |
+| `logic/catalog.js` | ~330 | 第 1 条：目录获取/缓存/检索/歧义检测 |
+| `logic/resolve.js` | ~390 | 第 2、4、7 条前半：registry 读版本、peer 作用域、GitHub spec 解析 |
+| `logic/install.js` | ~330 | 第 6、7、8 条：安装编排、源码构建、安装后校验 |
+| `logic/api.js` + `host/register.js` | ~470 | 工具面、输出格式、可热加载边界 |
+
+并有 **19 条离线单测 + 10 条宿主无关harness 检查**（含"同名歧义不得猜""跳过不兼容版本""已加载插件不得假装热换"这类回归）。也就是说：同样的判断，从"每次会话重新推一遍、推错就重来"变成"写一次、测住、以后每次 1 次调用"。
+
+## 4. 插件不能压缩的部分（诚实边界）
+
+- **pnpm 下载与编译时间**是物理成本：镜像安装仍要 ~13 s，源码构建仍要 ~2 分钟。插件省的是决策、试错、验证与上下文，不是 CPU/带宽。
+- **替换已加载插件**仍要重启宿主（`restart-required`）：这是 loader 模块缓存 + 打包宿主没有 Node 内部 loader 的硬边界，插件如实报出来，不伪装成功。
+- **同名歧义**仍需要一次人类/上层的选择（`owner=`），插件故意不猜。
+- 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sakikoTGW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# dsh-plugin-resolver
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**让 agent 自己把 DSH 插件装明白。**
+搜索 → 同名消歧 → 按当前内核选兼容版本 → 安装（registry 或 GitHub 源码构建）→ 装后校验，一次调用走完。
+
+[![test](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/test.yml/badge.svg)](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/test.yml)
+[![ablation](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/ablation.yml/badge.svg)](https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/ablation.yml)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-resolver?logo=npm)](https://www.npmjs.com/package/dsh-plugin-resolver)
+[![license](https://img.shields.io/github/license/sakikoTGW/dsh-plugin-resolver)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
+[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.2%2B-4d6bfe)](https://github.com/deepseek-ai/deepseek-harness)
+[![tests](https://img.shields.io/badge/tests-29%20checks%20passing-brightgreen)](test)
+[![stars](https://img.shields.io/github/stars/sakikoTGW/dsh-plugin-resolver?style=social)](https://github.com/sakikoTGW/dsh-plugin-resolver/stargazers)
+
+> **装两个典型插件：工具操作 −87%（45 → 6 次），实际耗时 −80%（20+ 分钟 → 约 3 分钟），失败重试 0。**
+>
+> 搜索 → 同名消歧 → 按当前内核选兼容版本 → 安装（registry / GitHub 源码构建）→ 装后校验，一次调用走完。
+> host-only 插件，给 DSH 加 4 个模型工具，不注册服务、没有前端、纯 ESM 免构建。
+
+---
+
+## 为什么要它
+
+**场景**：给一台 DSH 装两个真实插件——`dsh-better-sidebar`（npm 上的 latest 不保证兼容当前内核）和 `dsh-browser`（6 个同名 owner、GitHub-only、还要本地构建扩展）。当时在 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 表 |
+
+这个插件的存在意义：把上面这些**判断与验证**固化一次，之后每次只需一次工具调用。
+
+## 怎么工作
+
+```mermaid
+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["如实告知：刷新 / 重启 / 已生效"]
+```
+
+## 30 秒上手
+
+要求 **DSH `>=0.2.0-rc.2 <0.3.0`**（已在 `engines.dsh` 声明）。纯 JS、无构建、无 install 脚本，三种方式都不需要 `allowBuilds` 授权：
+
+```sh
+# npm（已发布 0.1.1；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.1.tgz
+```
+
+装完（宿主重启后最稳）直接说：
+
+> "帮我装 dsh-browser" → 它会先问/列出 6 个同名候选；
+> "装 dsh-builtin-browser" → 自动选到与你内核兼容的版本并装好。
+
+插件市场（Discover）索引（在插件页打开实验性「自定义插件市场」，然后 `插件 → 发现 → 添加索引源`）：
+
+```text
+https://sakikoTGW.github.io/dsh-plugin-resolver/market/index.json
+```
+
+真实调用长这样：
+
+```text
+$ 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
+```
+
+```text
+$ 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](ABLATION.md)）；
+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:`）：原样交给插件管理器。
+
+## 结构：稳定壳 + 可热加载逻辑
+
+```
+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 的模块"完全可行。
+
+## 效果
+
+| 指标 | 手工路径 | 本插件 | 来源 |
+|---|---|---|---|
+| 工具调用（装 1 歧义 + 1 GitHub-only 插件） | ≈ 45 次 | **≈ 6 次** | [BENCHMARK](BENCHMARK.md) |
+| 决策链耗时 | — | **1.23 s / 9 个决策任务** | benchmark.mjs |
+| 目录获取 | 91.06 s / 6.4 MB | **0.94 s / 2 请求** | benchmark.mjs |
+| 安装失败重试 | 2 次 90 s 超时 | **0 次** | 会话日志 |
+| 安装后校验调用 | 2 次额外探测 | **0 次** | benchmark.mjs |
+
+消融测试（逐项拆能力）见 [ABLATION.md](ABLATION.md)：同名 287 组、naive 会选错 51 组；8 个真实包中 2 个 latest 不兼容；镜像元数据延迟比 60.3×；GitHub-only 入口探针 404；静默失败可检测；逻辑热加载 3 ms vs 重启 30–40 s。
+
+```sh
+node test/benchmark.mjs   # 插件路径基准
+node test/ablation.mjs    # 消融测试（无副作用）
+```
+
+## 测试与 CI
+
+```sh
+npm test        # = selftest(19) + 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），插件会如实报 `restart-required`；
+- 同名歧义不猜，需要调用方给 `owner=` 或完整 spec；
+- 目录是社区维护的第三方列表，插件只保证"按声明来源装对版本"，不做安全审计；
+- GitHub 源码构建依赖宿主环境里的 `pnpm`（PATH 或 `DSH_PNPM_PATH`）与 `tar`，大仓库首次构建较慢。
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Bundle layer for dsh-plugin-resolver: one host-only plugin row that adds the
+# plugin_* tools. No client half, no background services.
+- insert:
+    - id: plugin-resolver
+      name: 'dsh-plugin-resolver'

package/host/register.js

@@ -0,0 +1,166 @@
+/**
+ * Host shell: tool schemas, the profile's plugin manager, and one cache-busted
+ * import of the reloadable logic entry.
+ *
+ * This file is the only part that needs a host restart to change. Everything
+ * under `logic/` is imported with `?v=<newest logic mtime>` on every tool call,
+ * so logic edits are live on the next call — Node caches ES modules by full
+ * URL, and a changed query string is a new URL.
+ *
+ * @module dsh-plugin-resolver/host/register
+ */
+
+import { statSync } from 'node:fs'
+
+/** Logic directory, resolved next to this file. */
+const LOGIC_DIR = new URL('../logic/', import.meta.url)
+
+/** Files whose mtimes make up the logic version. */
+const LOGIC_FILES = ['api.js', 'catalog.js', 'resolve.js', 'semver.js', 'install.js', 'util.js']
+
+const SEARCH_TIMEOUT_MS = 120_000
+const INSTALL_TIMEOUT_MS = 20 * 60 * 1000
+
+/**
+ * A version string that changes whenever any logic file changes.
+ *
+ * @returns {string}
+ */
+export function logicVersion() {
+  let newest = 0
+  for (const file of LOGIC_FILES) {
+    try {
+      const stat = statSync(new URL(file, LOGIC_DIR))
+      if (stat.mtimeMs > newest) newest = stat.mtimeMs
+    } catch {
+      // a missing file cannot raise the version
+    }
+  }
+  return String(Math.round(newest))
+}
+
+/**
+ * Import the logic entry fresh whenever its files changed.
+ *
+ * @returns {Promise<any>}
+ */
+export async function loadLogic() {
+  const url = new URL('api.js', LOGIC_DIR)
+  url.searchParams.set('v', logicVersion())
+  return await import(url.href)
+}
+
+/**
+ * Register the resolver tool set on `ctx.tools`.
+ *
+ * @param {any} ctx Cordis context
+ * @param {{catalogUrl?: string, catalogTtlMs?: number, registry?: string, githubProxy?: string, hotMount?: boolean}} options
+ * @returns {Array<() => void>} disposers owned by the caller's effect
+ */
+export function registerTools(ctx, options) {
+  const disposers = []
+  /** @param {any} definition */
+  const add = (definition) => {
+    const dispose = ctx.tools.register({
+      ...definition,
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { text: { type: 'string' } },
+          required: ['text'],
+        },
+        render: (_args, value) => [{ type: 'text', text: typeof value?.text === 'string' ? value.text : '' }],
+      },
+    })
+    if (typeof dispose === 'function') disposers.push(dispose)
+  }
+
+  /** Run one logic entry point with the shell-owned context and options. */
+  const run = async (method, args) => {
+    try {
+      const logic = await loadLogic()
+      const fn = logic[method]
+      if (typeof fn !== 'function') throw new Error(`logic entry does not export ${method}`)
+      return await fn(ctx, ctx.get('pluginManager'), options, args)
+    } catch (error) {
+      return { text: `${method} failed: ${error?.message ?? String(error)}` }
+    }
+  }
+
+  add({
+    name: 'plugin_search',
+    description:
+      'Search the DSH community plugin catalog. Returns ranked entries with owner, stars, npm package and the documented install command, and flags same-name ambiguity so a bare name is never guessed. Read-only.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', description: 'Name, keyword, owner, or a partial description fragment.' },
+        limit: { type: 'number', description: 'Maximum results, 1-25. Defaults to 8.' },
+        refresh: { type: 'boolean', description: 'Ignore the cached catalog and refetch it.' },
+      },
+      required: ['query'],
+    },
+    timeoutMs: SEARCH_TIMEOUT_MS,
+    execute: (args) => run('pluginSearch', args),
+  })
+
+  add({
+    name: 'plugin_resolve',
+    description:
+      'Resolve a plugin name, name@version or install spec into a concrete plan WITHOUT installing: which catalog entry, which published version accepts the running DSH version, which registry is used, and whether a GitHub source build is required. Use before plugin_install when the target is ambiguous.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        target: { type: 'string', description: 'Catalog name, npm name, name@version, or a github:/link: spec.' },
+        owner: { type: 'string', description: 'Repository owner, when several catalog entries share the name.' },
+        version: { type: 'string', description: 'Pin an exact version instead of resolving a compatible one.' },
+        registry: { type: 'string', description: 'Registry URL to ask first.' },
+        refresh: { type: 'boolean', description: 'Refetch the catalog instead of using the cache.' },
+      },
+      required: ['target'],
+    },
+    timeoutMs: SEARCH_TIMEOUT_MS,
+    execute: (args) => run('pluginResolve', args),
+  })
+
+  add({
+    name: 'plugin_install',
+    description:
+      'Install a DSH plugin end to end: resolve a DSH-compatible version, install through the profile plugin manager (registry mirror included), build GitHub-only sources when they ship no build output, then verify the loader entry and report whether a GUI refresh or restart is needed.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        target: { type: 'string', description: 'Catalog name, npm name, name@version, or a github:/link: spec.' },
+        owner: { type: 'string', description: 'Repository owner, when several catalog entries share the name.' },
+        version: { type: 'string', description: 'Pin an exact version instead of resolving a compatible one.' },
+        registry: { type: 'string', description: 'Registry URL to ask first, e.g. https://registry.npmmirror.com.' },
+        skipBuild: { type: 'boolean', description: 'Refuse rather than build when a GitHub source has no build output.' },
+        refresh: { type: 'boolean', description: 'Refetch the catalog instead of using the cache.' },
+      },
+      required: ['target'],
+    },
+    timeoutMs: INSTALL_TIMEOUT_MS,
+    execute: (args) => run('pluginInstall', args),
+  })
+
+  add({
+    name: 'plugin_status',
+    description:
+      'Report third-party plugins in this profile: installed bundles with versions, their loader entries, enablement and fiber phase. Use it to check whether an earlier install actually mounted, or what is currently active.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', description: 'Optional substring filter over bundle and entry names.' },
+      },
+    },
+    timeoutMs: 60_000,
+    execute: (args) => run('pluginStatus', args),
+  })
+
+  return disposers
+}

package/index.js

@@ -0,0 +1,62 @@
+/**
+ * dsh-plugin-resolver — host half.
+ *
+ * Adds four model-facing tools that turn "install this plugin for me" into a
+ * deterministic flow instead of manual trial and error:
+ *
+ * - `plugin_search`   search the community catalog, disambiguating same names
+ * - `plugin_resolve`  pick a concrete install spec and a DSH-compatible version
+ * - `plugin_install`  install through the profile's plugin manager, building
+ *                     GitHub-only sources when they ship no build output
+ * - `plugin_status`   report installed bundles, entries and their fiber phase
+ *
+ * The plugin owns no service of its own. Tool schemas and the plugin-manager
+ * bridge live in `host/register.js` (stable, needs a restart to change); the
+ * actual decision logic lives under `logic/` and is re-imported with a
+ * cache-busted URL on every call, so logic edits take effect without a host
+ * restart.
+ *
+ * @module dsh-plugin-resolver
+ */
+
+import { registerTools } from './host/register.js'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'plugin-resolver'
+
+/** Services required by this plugin; the rest are read through `ctx.get`. */
+export const inject = ['tools']
+
+/**
+ * Mount the resolver tools.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, unknown> | undefined} config plugin config
+ * @returns {void}
+ */
+export function apply(ctx, config) {
+  const options = normalizeConfig(config)
+  ctx.effect(() => {
+    const disposers = registerTools(ctx, options)
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  }, 'plugin-resolver: tools')
+}
+
+/**
+ * Read the plugin config defensively: patch rows may omit every field.
+ *
+ * @param {Record<string, unknown> | undefined} config
+ * @returns {{catalogUrl?: string, catalogTtlMs?: number, registry?: string, githubProxy?: string}}
+ */
+function normalizeConfig(config) {
+  const value = config ?? {}
+  /** @type {{catalogUrl?: string, catalogTtlMs?: number, registry?: string, githubProxy?: string}} */
+  const options = {}
+  if (typeof value.catalogUrl === 'string' && value.catalogUrl !== '') options.catalogUrl = value.catalogUrl
+  if (Number.isFinite(value.catalogTtlMs) && value.catalogTtlMs > 0) options.catalogTtlMs = Number(value.catalogTtlMs)
+  if (typeof value.registry === 'string' && value.registry !== '') options.registry = value.registry
+  if (typeof value.githubProxy === 'string' && value.githubProxy !== '') options.githubProxy = value.githubProxy
+  return options
+}