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

English | 中文

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

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

它解决什么

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

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

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

功能

能力	说明
外部插件清单	列出该 profile `dependencies` 里所有非 `@deepseek-ai/*` 的包：已装版本、版本范围、是否生效为插件层（`dsh.profile.bundles`）、是 registry 包还是本地 `link:`
版本检查	`pnpm outdated --format json`，区分「直接可更新（范围内）」与「可跨大版本升级（需要 `--latest`）」
一键更新	单个插件 / 全部可更新插件 / 跨大版本升级，三种粒度
卸载	每行一个「卸载」按钮（两下确认），走 `dsh plugin --profile <p> remove <包名>`，同步把包名从 `dsh.profile.bundles` 摘掉
每行安装命令	每个插件下方给出可直接复制的 `dsh plugin --profile <p> 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 名都经过严格字符校验后才拼进命令。

它怎么判断

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

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

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

配置

行配置只有一项（都可不填）：

# ~/.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 后该插件才真正不再加载。

命令行卸载本插件自己：

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/<name>/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 <p> update`	`lib/inventory.js` `update()`	报 dsh 不可用	已内置 `pnpm update` 兜底
`ctx.shell` 执行器	`lib/exec.js`	命令跑不动	已内置 `child_process` 兜底

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

发版（维护者）

本包的分发方式是 GitHub Release + git 安装，不发布到 npm：

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 <tgz-url> 直接使用。

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

npm 没有 "pending publisher"：可信发布只能挂到已存在的包上，staged publishing 同样要求包已存在，所以第一步必须人工发布一次（npm publish --otp=<6位码> 或带 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）

开发

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

仓库结构：

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

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

English | 中文

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

它解决什么

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

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

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

功能

能力	说明
外部插件清单	列出该 profile `dependencies` 里所有非 `@deepseek-ai/*` 的包：已装版本、版本范围、是否生效为插件层（`dsh.profile.bundles`）、是 registry 包还是本地 `link:`
版本检查	`pnpm outdated --format json`，区分「直接可更新（范围内）」与「可跨大版本升级（需要 `--latest`）」
一键更新	单个插件 / 全部可更新插件 / 跨大版本升级，三种粒度
卸载	每行一个「卸载」按钮（两下确认），走 `dsh plugin --profile <p> remove <包名>`，同步把包名从 `dsh.profile.bundles` 摘掉
每行安装命令	每个插件下方给出可直接复制的 `dsh plugin --profile <p> 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 名都经过严格字符校验后才拼进命令。

它怎么判断

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

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

配置

行配置只有一项（都可不填）：

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

卸载

命令行卸载本插件自己：

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/<name>/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 <p> update`	`lib/inventory.js` `update()`	报 dsh 不可用	已内置 `pnpm update` 兜底
`ctx.shell` 执行器	`lib/exec.js`	命令跑不动	已内置 `child_process` 兜底

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

发版（维护者）

本包的分发方式是 GitHub Release + git 安装，不发布到 npm：

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 <tgz-url> 直接使用。

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

npm 没有 "pending publisher"：可信发布只能挂到已存在的包上，staged publishing 同样要求包已存在，所以第一步必须人工发布一次（npm publish --otp=<6位码> 或带 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）

开发

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

仓库结构：

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

YUYUY9527/dsh-plugin-management

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

它解决什么

功能

安装

使用

界面

模型工具

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

它怎么判断

配置

卸载

设计取舍

已知限制

维护指南（dsh 升级后看哪里）

发版（维护者）

开发

License

Community comments

YUYUY9527/dsh-plugin-management

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

它解决什么

功能

安装

使用

界面

模型工具

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

它怎么判断

配置

卸载

设计取舍

已知限制

维护指南（dsh 升级后看哪里）

发版（维护者）

开发

License

Community comments