外部插件管理 YUYUY9527/dsh-plugin-management

dsh-plugin-management · 外部插件管理器

给 DeepSeek Harness（dsh）用的外部插件管理器：在「设置 → 插件 → 外部插件」里看清当前 profile 装了哪些第三方插件、各自是什么版本、有没有更新，然后一键更新。

定位：官方「插件」设置页回答的是「哪些插件加载了」（Loader 条目、启用状态、fiber 相位）；本插件回答的是「哪些外部包装着」（npm 版本、能否更新、是否真的生效为插件层）。两者互补。

它解决什么

dsh plugin --profile add 把插件装进 profile 后，日常会遇到三个问题：

1. 装了记不住：~/.dsh/profiles//package.json 里躺着一堆包，谁还在用、谁已经废弃，没人知道。
2. 装了没生效：依赖在 dependencies 里，却不在 dsh.profile.bundles 里 —— 装了个寂寞（不声明 dsh.bundle.patch 的库）或者被后来改动挤掉了。
3. 更新靠记忆：想知道 pnpm outdated 的结果、想升级，得自己进 profile 目录敲命令。

本插件把这三件事变成一页 UI + 一个模型工具。

功能

| 能力 | 说明 |
| 外部插件清单 | 列出该 profile dependencies 里所有非 @deepseek-ai/ 的包：已装版本、版本范围、是否生效为插件层（dsh.profile.bundles）、是 registry 包还是本地 link: |
| 版本检查 | pnpm outdated --format json，区分「直接可更新（范围内）」与「可跨大版本升级（需要 --latest）」 |
| 一键更新 | 单个插件 / 全部可更新插件 / 跨大版本升级，三种粒度 |
| 卸载 | 每行一个「卸载」按钮（两下确认），走 dsh plugin --profile remove ，同步把包名从 dsh.profile.bundles 摘掉 |
| 每行安装命令 | 每个插件下方给出可直接复制的 dsh plugin --profile add …（registry 包钉到最新版；本地/git/tarball 依赖原样复用 spec），带「复制」按钮 |
| 结果可见 | 回显真实执行的命令、退出码、stdout/stderr 尾部，并提示需要重启 dsh 才会加载新版本 / 真正卸载 |
| profile 切换 | 自动识别「当前正在运行的是哪个 profile」，也可手动切到别的 profile |
| 给 agent 用 | 注册模型工具 external_plugins（action: list \| update \| uninstall），agent 自己就能查、更新与卸载 |
| 双语 | 界面文案跟随 locale（zh / en） |

安装

装完重启 dsh 生效（bundle 装配在启动时完成）。add 后面的 spec 会原样转发给 pnpm，所以 pnpm 支持的写法都能用：

—— 公网获取（使用者 / 分发）—— ① 锁定版本，推荐：git tag
dsh plugin --profile web add github:YUYUY9527/dsh-plugin-management#v1.0.0

② 跟随最新代码
dsh plugin --profile web add github:YUYUY9527/dsh-plugin-management

③ Release 包 URL：只需能上 HTTPS，本机不需要 git
dsh plugin --profile web add https://github.com/YUYUY9527/dsh-plugin-management/releases/download/v1.0.0/dsh-plugin-management-1.0.0.tgz

④ npm registry（尚未发布，发布后对所有人生效）
dsh plugin --profile web add dsh-plugin-management

—— 本地目录（开发 / 自用，改完代码重启即可）——
dsh plugin --profile web add D:\fubin\dev\mini-tools\dsh\dsh-plugin-management

--profile 必须是你实际在跑的那个 profile（dsh web 就是 web）。
加完可以立刻检查装配结果：

dsh --profile web --dump-config | grep dsh-plugin-management

公网各方式的取舍、npm 发布步骤与排查见 INSTALL.md。

使用

界面

重启 dsh 后打开 设置 → 插件，会多出一个 「外部插件」 tab（排在官方 configurable / all 之后）：

- 顶部：profile 选择器（自动 = 当前运行的 profile）、刷新、一键更新 (N)
- 每行：包名、已装版本 · 版本范围、状态徽标（可更新到 x / 可升级到 x / 已是最新 / 本地链接 / 非插件层 / 已废弃）、该插件自己的安装命令（带「复制」按钮）
- 每行操作：更新（范围内）、升级到最新（--latest，会改写 package.json 的版本范围）、卸载（点一下变「确认卸载」，4 秒内再点一下执行）
- 底部：操作结果（含完整命令与输出）与重启提示

打开页面会先出本地清单（快），随后自动补一次联网版本检查；这一步失败会把原因显示出来，不会只留一句「未检查」。

模型工具

external_plugins action=list # 看清单（默认联网核对最新版本） external_plugins action=list check=false # 只看本地已装版本，不联网 external_plugins action=update profile=web # 更新该 profile 全部外部插件 external_plugins action=update names=["dsh-tinyfish-search"] external_plugins action=update latest=true # 跨大版本升级 external_plugins action=uninstall names=["dsh-tinyfish-search"] # 卸载（必须点名）

HTTP 接口（面板与其它前端复用）

默认前缀 /dsh-plugin-management/api：

| 方法 | 路径 | 说明 |
| GET | /inventory?profile=&check=1&refresh=1 | 清单；check=1 联网核对最新版本，refresh=1 强制重扫 profile 目录 |
| POST | /update | body { profile?, names?, latest? }，跑更新并返回命令与输出 |
| POST | /uninstall | body { profile?, names }，卸载指定包；names 必填，没有「卸全部」 |

跨站请求会被拒（只接受同源），包名/profile 名都经过严格字符校验后才拼进命令。

它怎么判断 text $DSH_HOME/profiles// package.json dependencies → 谁装着（外部插件 = 非 @deepseek-ai/ 开头的包） dsh.profile.bundles → 谁生效为插件层 node_modules//package.json version → 实际装的是哪个版本 dsh.bundle.patch → 它到底是不是一个插件层（bundle）

- 外部插件：dependencies 里非 @deepseek-ai/ 的包。
- 插件层：同时出现在 dsh.profile.bundles 里 —— 这才是真正被 Loader 装配的。
- 本地链接：link: / file: / workspace: / portal: 协议，不来自 registry，因此不参与更新。
- 当前 profile：从运行实例的 client bundle 绝对路径（/profiles//node_modules/...）反推，比猜目录 mtime 可靠。

更新统一走 dsh plugin --profile update ...（官方转发器，装完还会把 dsh.bundle 声明变化重新对齐进 dsh.profile.bundles）；若 dsh 不在 PATH，自动回落 pnpm update ...（cwd = profile 目录）。

配置

行配置只有一项（都可不填）： yaml ~/.dsh/profiles/web/cordis.patch.yml
- id: dsh-plugin-management
config:
apiPath: /dsh-plugin-management/api # 仅在路由撞车（同名 kind+path 会抛错）时改 sandboxMode: danger-full-access # 执行 pnpm/dsh 命令时声明的沙箱模式

sandboxMode 为什么默认 danger-full-access：执行命令时必须显式给出执行策略，否则可写根是 dsh 自己的（进程 cwd），而 pnpm 装包要写 pnpm store（如 D:\.pnpm-store\v11、~/.local/share/pnpm/store）—— 它不在任何 profile 目录里，于是即便沙箱健康，「一键更新」也会在写 store 时 Access is denied。改成 read-only / workspace-write 可以收紧，代价是更新会被同一条规则拒掉（有意的取舍）。

卸载

从面板卸载（1.2.0 起）：在「外部插件」页对应行点「卸载」→ 按钮变「确认卸载」→ 4 秒内再点一下执行。命令是 dsh plugin --profile remove ，官方转发器会同步把包名从 dsh.profile.bundles 摘掉；重启 dsh 后该插件才真正不再加载。

命令行卸载本插件自己： bash
dsh plugin --profile web remove dsh-plugin-management # 官方路径

临时禁用而不卸载：在 profile 的 cordis.patch.yml 里给该行加 disabled: true。

设计取舍

- 纯 JavaScript，零构建：lib/.js 就是源码也是产物，github: 安装不需要本机有构建环境（pnpm 默认拦截 git 包的 build 脚本，TS 插件很容易卡在这一步）。
- 没有硬依赖：webServer / tools / shell / clientModules 全部惰性获取。缺 webServer 就没有面板，缺 tools 就没有模型工具，但插件本身永远能加载。
- 模型工具的双路径：能解析到 @deepseek-ai/dsh-tools 时用官方 defineTool（带参数校验），解析不到就用本地转换的 raw JSON Schema 注册 —— 外挂包不该因为一个可选包而整体挂掉。注意两种形态不能混用（defineTool 吃 DSL、register 吃 raw，{type:'json'} 只在 DSL 里合法），细节见 lib/tool.js 头注释。
- 不做自动重启：更新落地 ≠ 生效。插件把「需重启」明确写在结果里，而不是替用户重启进程。

已知限制

- 只管理当前 profile 的第三方依赖；官方 @deepseek-ai/ 包与 profile 模板自带的 in-box bundle 不在管理范围（它们随 dsh 安装走）。
- 不做安装/卸载 UI（那是 dsh plugin add/remove 的职责）；本插件专注「看见 + 更新」。
- 更新不校验版本兼容性：跨大版本升级前请自行确认目标包支持你当前的 dsh。

维护指南（dsh 升级后看哪里）本插件依赖 dsh 的公开约定，而不是内部实现。dsh 升级后如果哪块失效，按这张表定位，通常只改一处：

| 依赖的约定 | 写在哪 | 失效表现 | 怎么改 |
| profile 布局 $DSH_HOME/profiles//package.json + dsh.profile.bundles | lib/scan.js | 清单为空 / profile 列表为空 | 对齐 @deepseek-ai/dsh-app-boot 的 PROFILES_DIR / resolveProfileDir |
| $DSH_HOME 解析优先级 | lib/scan.js resolveDshHome() | home 找错 | 对齐 @deepseek-ai/dsh-home-paths |
| 设置 slot settings.plugins.tab | lib/client.js 顶部 TAB_SLOT | 面板不出现（但工具还正常） | 查 Slots.listSubTree，改成新的 slot 名（一行常量） |
| dsh.client + exports["./client"] 客户端发现约定 | package.json | 面板不出现，控制台无此 bundle | 对齐 @deepseek-ai/dsh-client-modules 的 resolveMeta |
| webServer.register({ kind, path, handler }) | lib/index.js | API 404 | 对齐 webServer 服务签名 |
| pnpm outdated --format json 输出形状 | lib/inventory.js checkOutdated() | checkError 有值 | 按新输出调整解析（已是容错解析：非 JSON 即报错而非崩） |
| dsh plugin --profile update | lib/inventory.js update() | 报 dsh 不可用 | 已内置 pnpm update 兜底 |
| ctx.shell 执行器 | lib/exec.js | 命令跑不动 | 已内置 child_process 兜底 |

改完跑 npm test：25+ 条用例覆盖扫描、清单合并、命令拼装、兜底路径与打包契约，能在不看 UI 的情况下拦住大多数回归。

发版（维护者）

本包的分发方式是 GitHub Release + git 安装，不发布到 npm： bash
npm version patch && git push && git tag v1.0.1 && git push origin v1.0.1
npm pack # 产出 tgz，作为固定版本上传到该 tag 的 Release

装法见「安装」一节的方式 ①②③；Release 资产可被 dsh plugin add 直接使用。

npm 路径当前未启用（维护者账号的 2FA 阻塞了首次发布），材料保留备用：

- npm 没有 "pending publisher"：可信发布只能挂到已存在的包上，staged publishing 同样要求包已存在，所以第一步必须人工发布一次（npm publish --otp= 或带 Bypass 2FA 的 Granular Access Token）
- 首版发布后，在包设置里配 Trusted Publisher（GitHub Actions → YUYUY9527/dsh-plugin-management → workflow publish.yml），再把 .github/workflows/publish.yml 的触发条件从 workflow_dispatch 改回 tags: ['v'] 即可全自动发版（OIDC + provenance，本地零 token）

开发 bash
npm test # 无需 npm install：零运行时依赖，测试用 Node 内置 test runner
npm run check # 全部 lib 文件语法检查

仓库结构： text lib/scan.js profile 扫描与名称守卫（纯 Node，可单测） lib/exec.js 命令执行（ctx.shell 优先，child_process 兜底） lib/inventory.js 清单 / 版本检查 / 更新 的业务实现 lib/tool.js 模型工具定义（参数 DSL → JSON Schema） lib/index.js host 入口：HTTP API + 工具注册 lib/client.js client bundle：设置页「外部插件」tab test/.test.mjs 单测（含打包契约） cordis.patch.yml bundle 补丁层：插入一行插件

License

MIT