dsh-plugin-resolver

dsh plugin --profile web add dsh-plugin-resolver

<p align="center">

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/banner.svg" alt="DSH Plugin Resolver — install the right plugin in one call" width="1280">

</p>

<p align="center">

<strong>简体中文</strong> | <a href="https://github.com/sakikoTGW/dsh-plugin-resolver/blob/main/README.en.md">English</a>

</p>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-plugin-resolver"><img alt="npm" src="https://img.shields.io/npm/v/dsh-plugin-resolver?style=flat-square&color=4D6BFE&logo=npm&logoColor=white"></a>

<a href="https://github.com/sakikoTGW/dsh-plugin-resolver/actions/workflows/test.yml"><img alt="test" src="https://img.shields.io/github/actions/workflow/status/sakikoTGW/dsh-plugin-resolver/test.yml?style=flat-square&label=test&color=2FBF71"></a>

<img alt="45 checks" src="https://img.shields.io/badge/checks-45%20passing-2FBF71?style=flat-square">

<a href="https://github.com/sakikoTGW/dsh-plugin-resolver/blob/main/LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>

<img alt="DSH" src="https://img.shields.io/badge/DSH-0.2.0--rc.2%2B-4D6BFE?style=flat-square">

<img alt="Node" src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white">

</p>

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

<p align="center">

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/demo.gif" alt="终端运行 npm test（2026-10-27 录制，当时 39 项检查）" width="760">

</p>

<p align="center">_{真实输出：2026-10-27 录制时为 39 项；当前 <code>npm test</code> 为 45 项（35 逻辑 + 10 harness）全绿（<a href="https://github.com/sakikoTGW/dsh-plugin-resolver/blob/main/demo/demo.tape">VHS tape</a> 可重录）}</p>

目录

• [为什么需要它](#为什么需要它)
• [怎么工作](#怎么工作)
• [快速开始](#快速开始)
• [四个工具](#四个工具)
• [版本选择规则](#版本选择规则)
• [安装路径与重启判定](#安装路径与重启判定)
• [结构](#结构)
• [效果与证据](#效果与证据)
• [市场收录](#市场收录)
• [测试与 CI](#测试与-ci)
• [已知限制](#已知限制)
• [反馈与安全](#反馈与安全)
• [License](#license)

为什么需要它

给一台 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 的人。

怎么工作

<p align="center">

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/flow.svg" alt="一次工具调用的五个阶段：检索、解析、安装、校验、上报" width="1200">

</p>

<p align="center">_{两条必须如实上报的失败路径也画在图里：没有兼容版本、装上了但没挂载。}</p>

四个工具里只有 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 不兼容时自动降级，并说明跳过了哪些版本

<p align="center">

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/demo-resolve.gif" alt="plugin_resolve 真实调用动画：从目录与 registry 解析出兼容版本" width="760">

</p>

<p align="center">_{真实调用动画（2026-10-18 本地 harness 录制，宿主 0.2.0-rc.2）：从真实目录与 registry 解析出一个兼容版本。}</p>

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

$ plugin_resolve dsh-builtin-browser
target kind: npm   running DSH: 0.2.1-rc.2
package: dsh-builtin-browser@0.4.15
install spec: dsh-builtin-browser@0.4.15
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: dsh-better-sidebar@0.28.1
install spec: dsh-better-sidebar@0.28.1
...
restart: not required — manager applied the change in place

四个工具

工具 · 作用 · 是否改动环境

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/icons/search.svg" width="18" alt=""> plugin_search · 搜社区目录（npm 载体优先），排序并显式标出同名歧义 · 只读

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/icons/resolve.svg" width="18" alt=""> plugin_resolve · 只解析不装：目录条目、兼容版本、registry、是否需要源码构建 · 只读

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/icons/install.svg" width="18" alt=""> plugin_install · 完整安装：选版本 → 安装/构建 → 回读校验 → 下一步提示 · 写 profile

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/icons/status.svg" width="18" alt=""> plugin_status · 已装 bundle / loader entry / fiberPhase 盘点 · 只读

<p align="center">

<img src="https://raw.githubusercontent.com/sakikoTGW/dsh-plugin-resolver/main/assets/tool-search.png" alt="plugin_search 真实输出：9 个同名 dsh-browser 候选，要求 owner=" width="980">

</p>

<p align="c

…(truncated)