Skip to main content
L

dsh-plugin-rack

lzm-p/dsh-plugin-rack

DSH 插件管理:所有插件一屏看完,一个开关直接开关,更新完自动热替换不用重启。/ Plugin rack for DSH: every plugin in one list with a power switch, an auto/manual flag that scopes the one-click bulk actions, and hot-swapped updates that need no restart.

Install

dsh plugin --profile web add github:lzm-p/dsh-plugin-rack

README

dsh-plugin-rack · 插件管理台

DSH(DeepSeek Harness)的插件面板:所有插件一屏看完,一个开关直接开关,更新完不用重启。

装在侧边栏,不用进设置页翻。

用来干什么

插件装多了以后有几件事很烦:

  • 装了哪些、现在开着还是关着、是本地开发版还是线上版,得一个个翻;
  • 关一个插件要重启整个 DSH;
  • 想看看有没有新版要自己去查 npm,装错了还得自己回滚;
  • 有些插件是 GitHub 直装、本地 tar 包、甚至只是个软链,普通办法根本看不出有没有新版。

这个面板把它们收进一个列表。

功能

列表

  • 四个页签:已安装插件 / 核心组件 / 异常 / 更新。
  • 每行显示:开关、手动或自动标记、装法来源(npm、npmmirror、github、本地文件包、本地软链)、有新版时的行内更新按钮。
  • 点整行展开详情:包名、版本、许可、作者、安装目录、依赖、GitHub / npm / 主页链接,以及具体功能说明。
  • 核心组件(@deepseek-ai/*)也全部列出,并按用途配了中文功能名,例如「插件设置」「文件工具」「会话检索」,知道哪个组件管什么才不会误关。
  • 「异常」页用来放加载失败的插件,写明失败原因;「被插件包关闭」这类由别的插件主动隐藏的组件会单独成组,那不是故障。

开关

  • 每个插件一个开关,点完立即生效,不需要重启 DSH(宿主支持热替换时)。
  • 手动 / 自动标记:只有标为「自动」的插件才会被「一键全部开启 / 关闭」影响。标成手动的,一键操作永远不会碰它。
  • 每页有自己的一套批量按钮:一键全部开启、一键全部关闭、全部设为自动、全部设为手动,只对当前这一页生效。
  • 批量操作前在面板内弹出确认条(不是浏览器弹窗),写清楚要动几个、动哪些。
  • 每行最左有一盏状态灯:绿=运行中、黄=加载中、红=加载失败、灰=未启用、空心=只读核心组件。加载失败的行整行淡红,不用展开就能看见。
  • 第一次打开时,「自动」名单默认只包含这个 profile 安装的第三方插件,并且排除本面板自己;内置核心组件一律「手动」,所以一键全关不会把 harness 拆掉。

更新

  • 「检查更新」把 profile 里按精确版本锁定的依赖逐个查 registry 最新版,有新的直接在列表行里标出来:⬆ v0.1.29 ➡ v0.1.30 npm,点一下只更新那一个插件。
  • 尊重你写的版本范围:package.json 里锁死精确版本(1.2.3)时照旧只看那一个版本;写成 ^1.2.3 / ~1.2.3 / 1.2 / 1.x / >=1.2.3 / >1.2.3 / <2.0.0 / 1.2.3 - 2.0.0 / ^1 || ^2 时,只有落在范围内的新版才算「可更新」。超出范围的新版会单独列在下方,标「超出声明范围」并附上你写的那段 spec —— 不会被批量更新悄悄顶到下一个大版本。link: / file: / github: / tarball 这些不可比的范围仍走「其他安装方式」,不参与版本更新。
  • 更新由宿主执行:点完就可以关掉面板,pnpm 照样跑完。重新打开面板时,顶部会显示「后台更新中 · N 个插件」,跑完了补一条结果提示。不用守着这个界面,也不用去翻日志。卡住了可以点横幅右边的「取消」。
  • 会话正忙时也不白点:需要下载的更新会先把附件取下来、核对 sha256,然后排队;宿主每 10 秒看一眼,等所有会话都空了就自己装上(下载过的东西不会重下)。排队期间横幅显示「已排队…」。
  • 网络不用你配:下载按这个顺序自动选路,config.json 里明确指定的代理 → 环境变量(HTTPS_PROXY / ALL_PROXY,NO_PROXY 会照规矩跳过)→ 系统代理(Windows 的 Internet 设置)→ 直连;一条走不通就换下一条,不会因为代理没开就整个更新失败。HTTP 代理和 SOCKS5 都支持,带用户名密码也行,查 GitHub 接口的部分同样走这些代理。
  • pnpm 从哪来:先找 PATH 上的 pnpm,再找 %APPDATA%\npm、%LOCALAPPDATA%\pnpm、PNPM_HOME、~/.local/share/pnpm、Homebrew 与系统级安装;Windows 的 pnpm.cmd / pnpm.ps1 会用 cmd.exe / powershell 包一层再跑。
  • 想固定某个代理,在数据目录写 config.json:{ "download": { "proxy": "http://127.0.0.1:7897" } };写 "off" 就只直连;不写就是自动。
  • 断点续传:连接断了按 Range 接着下,取消或失败后保留 .part,下次点更新从断的地方继续,不用重下 30 MB。总上限 30 分钟,30 秒没有数据就判定卡死。GitHub 偶尔会把连接挂住,宁可报错也不让面板一直转圈。下过的包按 sha256 复用,重试同一版本不会重新下载。
  • 所有更新通道合在一个列表、一个按钮里:勾选后按来源自动分流。精确版本锁定的依赖合成一次 pnpm add 跑完;GitHub 直装走重新拉取;本地压缩包走「下载官方附件 → 核对 sha256 → 替换」;压缩包地址走重新 pin。每个渠道各自成败,一条渠道失败不会中断其它渠道,最后给一份合并报告(「N 组里 M 组失败,其余已完成」)。
  • 装完自动热替换,新版本当场生效,不用重启;界面类插件刷新一下页面即可。
  • 能识别 GitHub 直装 / npm 镜像 tar 包 / 本地文件包 / 本地软链 这四种装法,并在同一个列表里标出各自来源;本地软链没有「升级」这回事,不会被勾选。
  • registry 取 profile 自己的配置(pluginManager.registries()),不强行走 npmjs;装了 GITHUB_TOKEN 的话查 GitHub 版本会用它提额。

安装与卸载

  • 输入包名先「检查」:只做预检,什么都不动。它会告诉你这是不是个 DSH 插件包、版本多少、干什么用的。像 is-odd 这种普通 npm 包会被拦下来,因为它没声明 dsh.bundle,装了也不会被加载。
  • 确认了再「安装」,走宿主官方的插件管理接口。
  • 每行可以「卸载」,要点两下确认;由宿主管理、不允许移除的核心包会被拒绝。

安全设计

这个面板能改你的运行环境,所以几条底线是硬编码的:

  • 动手之前先备份 package.json 与 pnpm-lock.yaml;一个都没装上才算整体失败,那时整体写回并补跑一次重同步,避免「文件回滚了但 node_modules 没回滚」的假回滚。
  • 一批里有的装不上,其它的照样装:pnpm 本身是全或无,所以更新是分轮跑的——先从失败输出里认出是哪个包在报错,把它剔掉重装剩下的;认不出名字时才逐个单独试。面板会分别列出「装上了哪些」和「哪几个没装上、为什么」,不会用一句「8 个包失败」把整批退回去。
  • 批量操作要过维护门:有会话正在跑时不动文件,等它空闲。
  • 并发守卫:安装 / 卸载 / 更新 / 批量操作四者互斥。同一时刻只允许一条写操作在跑。两个 pnpm 同时改同一份 package.json 会把 profile 写坏。
  • 面板不会卸载自己;removable 为 false 的包一律拒绝。
  • 只有标为「自动」的插件才进批量范围,页面筛选只能缩小范围,不能扩大。
  • 核心组件不会被一刀切跳过:204 个 @deepseek-ai/* 行里只有 16 个真只读,其余受开关控制。真正被跳过的只有面板自己那一行(在自己发起的请求里关自己,会让正在响应的路由断掉)。

自检

改动源码后跑一遍,它会检查那些「坏了但不会报错」的东西:

node test/self-check.mjs

检查项:中英文词条是否一一对应、有没有用到字典里没有的键、头部注释里列的路由和实际路由表是否一致、提前 return 之后有没有落下的 hook(这个曾经把整个面板搞崩过)、以及残留的调试语句。

安装

在 DSH 里装有三条路,任选其一:

① 从 GitHub 装(推荐,不依赖 npm)

dsh plugin add github:LZM-P/dsh-plugin-rack

② 从 npm 装(发布后可用)

dsh plugin add dsh-plugin-rack

③ 在插件管理界面里点「安装」,把上面任意一条的 spec 填进去。

装好后侧边栏会出现「插件管理」。

如果宿主版本不认 github: 前缀,改用 tarball 地址: dsh plugin add https://github.com/LZM-P/dsh-plugin-rack/archive/refs/heads/main.tar.gz

数据放在哪

  • 代码:插件自己的安装目录。
  • 运行时数据目录:<DSH_HOME>/plugin-dashboard/profiles/<profile>/(Windows 默认 C:\Users\<你>\.dsh\plugin-dashboard\profiles\desktop\)。一个 profile 一个目录,里面是:
    • state.json:哪几个插件被标成了自动,以及面板自己创建过哪些配置覆盖。几行 JSON。删掉只会让自动清单重置,不影响任何插件。
    • job.json:正在跑或上一次跑完的更新任务。面板关掉再打开靠它接回来。
    • queue.json:已下载校验、等会话空闲才装的更新。
    • config.json:下载代理等手工配置。
    • last-update.log / update-log.jsonl:前一个是最近一次更新的完整日志,后一个是每次更新的追加历史。
  • 每个 profile 各存一份:同一个 DSH 下开多个 profile 时,自动清单、正在跑的任务、待装队列、代理配置互不串台。

从旧版本升级(单一目录 → 按 profile 分目录)

早期版本把所有东西都放在 <DSH_HOME>/plugin-rack/ 这一个目录里。升级后第一次启动时,上面这些文件会逐个复制到按 profile 分的目录(已存在的不覆盖,旧文件保留不删):

  • 排好队还没装的更新会跟过来,不会静默丢失;
  • 手工配的下载代理继续生效,不用重配;
  • 任务历史与更新日志都能在面板里看到。

如果旧目录里的文件已经被你手动删掉,那这几项就按新装处理(队列空、代理回落到环境变量、历史为空),不影响插件本身。

结构

文件作用
index.js宿主端:注册 /api/dsh-plugin-rack 前缀路由,负责读取插件状态、批量操作、更新与安装卸载
client.js客户端:侧边栏图标 + main 面板的界面。生成文件,由 src/client/*.js 拼装(npm run build)
src/client/i18n.js中英词条表与插值(纯函数,可单独测)
src/client/view.js面板的判定逻辑:失败归类、勾选分流、报告合并、行尾徽章、更新页状态
src/client/style.js面板样式表
src/client/panel.js面板组件本身(React h,无构建期依赖)
scripts/build-client.mjs把上面几块拼成 client.js;--check 供 CI 判断是否过期
lib/spec.js版本范围算术(精确 / ^ / ~ / >= / < / 通配 / 连字符 / `
cordis.patch.ymlbundle 补丁,插入 plugin-rack 这一行
locale/{en,zh}.json插件名与描述(插件管理页展示用)
icon.svg插件图标
test/self-check.mjs自检脚本:词条对照、路由对照、hook 顺序、调试残留
test/spec.mjs范围算术单测:^0.2.3 不含 0.3.0、~1.2.3 不含 1.3.0、预发布版不穿越等边界
test/*.mjs行为 / 后台作业 / 下载 / pnpm 启动四套测试
scripts/publish.mjs发布脚本:token 只从 NPM_TOKEN 读,版本重复直接拒绝
eslint.config.js / tsconfig.jsonlint 与 tsc --checkJs(类型只覆盖 lib/)

接口

宿主端只暴露一个同源前缀路由,客户端直接用 fetch 调用,因此不依赖 remoteAccess 对 pluginManager/* 的授权策略:

GET  /api/dsh-plugin-rack/ping        存活探测,不碰任何服务
GET  /api/dsh-plugin-rack/            ping 的别名
GET  /api/dsh-plugin-rack/state       全部插件行 + 自动名单 + 批量进度
GET  /api/dsh-plugin-rack/detail      某个插件的包信息(?entryId=)
GET  /api/dsh-plugin-rack/updates     检查更新(按精确版本锁定的依赖)
GET  /api/dsh-plugin-rack/extras      非精确版本的安装来源(github / tar 包 / 本地文件 / 软链),供更新页分流
GET  /api/dsh-plugin-rack/updatelog   上一次更新的日志
GET  /api/dsh-plugin-rack/registries  当前生效的 registry
GET  /api/dsh-plugin-rack/removable   可以卸载的插件名单
GET  /api/dsh-plugin-rack/inspect     安装预检(?spec=,只查不装)
GET  /api/dsh-plugin-rack/fileplan    ?name= 本地 file: 依赖会升到哪个版本
GET  /api/dsh-plugin-rack/job         正在跑的装包任务,或上一次的结果(running / finishedAt / interrupted)+ 待装队列
POST /api/dsh-plugin-rack/job         { action: 'cancel' } 取消正在跑的那一次
GET  /api/dsh-plugin-rack/summary     只读精简行,给脚本和 agent 用
POST /api/dsh-plugin-rack/plugin      { entryId, enabled?, auto? }
POST /api/dsh-plugin-rack/bulk        { enabled, scope, save?, cancel? }
POST /api/dsh-plugin-rack/roster      { mode: 'group', scope, auto }
POST /api/dsh-plugin-rack/updates     { names: [...] }
POST /api/dsh-plugin-rack/extras      { name, action }
POST /api/dsh-plugin-rack/install     { spec }
POST /api/dsh-plugin-rack/uninstall   { name }

save 模式

POST /bulk 带 save: true 时只写一次 profile 的 cordis.patch.yml,不逐个去动插件:

save: true默认(逐个热生效)
写文件耗时约 0.4 秒—
重载方式宿主看到文件变了,一次性重载整批每个插件一次卸载+加载(宿主 O(N) 对账,通常几秒到几十秒)
适合「先全关 → 去更新 → 再重启」想马上看到单个插件的变化

写入是原子的(临时文件 + rename),只删自己创建过的覆盖项,用户原有的配置行原样保留。

只读行(management-required / unaddressable)在界面上开关与模式按钮都被禁用,并带标签说明原因。

安全模型

这个插件会写你的 cordis.patch.yml、调 pnpm、删包。为了让这些操作可控,做了四层防护:

  1. 网络暴露面:API 只在 127.0.0.1 / localhost / ::1 上可达。宿主的 web server 本来就只绑 loopback,所以外网碰不到这个端口。

  2. Host / Origin 校验:每个请求都先过两道闸:Host 头必须指向 loopback,Origin 头(如果存在)也必须解析到 loopback。这挡的是同机浏览器里的恶意网页:它无法用 <img> 或 fetch 跨站调用你的 API(DNS rebinding / CSRF 都被这两道闸拦下)。 2b. 写操作还要求"你确实是从面板来的":POST 除了要 application/json,还必须带 Origin、或 Sec-Fetch-Site: same-origin、或显式加上 x-dsh-plugin-rack: 1 请求头。

    这道门挡的是无意的跨站 POST(比如别处一个表单顺手打过来、或者某个页面被 XSS 后盲发请求),它对「完全不带 Origin」的请求本来是不设防的,而 curl -X POST 正好属于这一类。

    它不是鉴权:本机任何拿到这个端口的脚本,加一行请求头就能过。真要防住同机脚本得引入 token 或随机口令,目前没有做,也不假装做了。面板自己永远带这个头;写脚本调接口时也带一个:

    curl -X POST http://127.0.0.1:9546/api/dsh-plugin-rack/bulk \
      -H 'content-type: application/json' \
      -H 'x-dsh-plugin-rack: 1' \
      -d '{"enabled":false,"scope":"installed"}'
    
  3. 卸载白名单:界面上的「卸载」按钮不是对所有行都显示。只有宿主 pluginManager 服务明确标记为 removable 的包才会出现按钮。核心组件、面板自己、harness 命脉都永远不会出现在可卸载列表里,所以误点卸载也不会把系统拆坏。

  4. 更新回滚:批量更新前会备份 package.json + pnpm-lock.yaml + pnpm-workspace.yaml 三个文件。pnpm 返回非零退出码时,先把这三个文件写回原内容,再跑一次 pnpm install --prefer-offline 把 node_modules 也拨回去。失败 = 一个包都没改动,不会留下半个新依赖树。

写入 cordis.patch.yml 是原子操作(写临时文件 + rename),只删这个插件自己创建过的覆盖项,用户手写的内容原样保留。

网络要求

插件本身不带代理,也不改你的代理设置:它只是按顺序试「环境变量代理 → 系统的代理设置 → 直连」,把一个能通的路径交给自己的下载器;真正的安装动作交给宿主自己的 pnpm,所以走哪个 registry 完全听宿主的(pluginManager.registries() 解析出来的那个,没有就退回 registry.npmjs.org)。

你在做的事需要访问没有代理能行吗
检查 npm 包的更新、安装/更新 npm 包宿主的 registry(国内常见是 registry.npmmirror.com)行,镜像本来就直连可用
检查 github 安装的插件有没有新提交api.github.com视网络而定;被墙时会报错,其它行不受影响
更新 github 安装的插件github.com、codeload.github.com视网络而定,同上

几个具体结论:

  • 系统代理关掉但注册表里还留着旧的 ProxyServer 不会再把下载带偏:现在会读 ProxyEnable,值为 0 时直接跳过(这就是「tried 127.0.0.1:7900 … direct: The operation was aborted」那个报错的成因)。
  • 每一条回退路线各拿一份独立的超时预算,前一条失败不会把后一条的时间耗光。
  • GITHUB_TOKEN 可以不设。不设时按匿名额度查 public 仓库(每小时 60 次,按 IP 算);包多或频繁检查时才需要它,面板的「接口」页会显示当前是否已设置。
  • 不需要联网的操作:开/关插件、自动/手动清单、看日志、卸载、热替换。断网时面板照常可用,只有「检查更新」和一键更新会失败并给出原因。

兼容性

  • DSH >=0.2.1-rc.2 <0.3.0-0。已实测 0.2.1-rc.2、0.2.1-rc.5、0.2.2-rc.1、0.2.2-rc.2、0.2.2-rc.3; 名单之外的版本会明说不确定,不会假装兼容。

    这个区间怎么理解:engines.dsh 是宿主安装/启用插件时检查的硬门槛,落在区间外会直接拒绝启用。 所以上界特意放到 0.3.0 之前而不是紧贴当前版本——DSH 0.2.x 的小版本和 rc 都不会把插件锁死, 只有跨到 0.3 这种可能改表面的版本才需要重新确认一次。真到了那一天,插件本身也会先报错 (缺 pluginManager、缺 HMR、找不到 pnpm),不会静默半坏。

  • DSH 的 Web 界面(dsh.client.platform = web)。

  • 需要宿主提供 pluginManager 服务;没有它会明确报错,而不是假装成功。

  • 热替换依赖宿主的 HMR 服务;拿不到时退回提示「重启一次生效」,不会骗你说已经生效了。

开发

npm ci         # 只装 eslint + typescript(开发依赖,发布包不含 node_modules)
npm test       # 九套:自检 / 行为 / 范围算术 / 批量降级 / 迁移 / 客户端渲染 / 后台作业 / 下载 / pnpm 启动
npm run lint   # eslint(no-dupe-keys、no-undef 在这套配置下抓出过两处真 bug)
npm run types  # tsc --checkJs,只覆盖 lib/(JSDoc 当类型,不引入构建步骤)
  • 范围算术只有一份实现:lib/spec.js。index.js import 它,test/spec.mjs 直接跑它,所以「测试通过的是一套逻辑、线上跑的是另一套」不会发生。
  • CI 在 Windows 上跑 Node 20 与 22;另有一格把 npm pack 出来的 tarball 解压再跑一遍测试——files 里漏了哪个文件,本地是发现不了的。
  • 发一个版本:NPM_TOKEN=… node scripts/release.mjs patch。它按顺序做「工作区干净 → client.js 是新的 → 测试 → lint → 类型 → 同步 bump 两个版本号 → 发布 → 等 registry 真的能取到这个版本」。发布仪式手工走过四遍,每次都栽在同一处:改完代码忘了 npm run build、只改了 package.json 忘了 lock、registry 延迟期把 404 当成失败。
  • 打 tag:node scripts/tag.mjs。当前网络下 git push 走不通(直连 21 秒超时、代理 TLS 握手失败),这个脚本改走 api.github.com 建附注 tag,并且会先确认那个 commit 真的在远端分支上——不会造出一个指向本地孤魂的 tag。

English

A plugin dashboard panel for DSH (DeepSeek Harness): every plugin in one list, a power switch per plugin, an auto/manual flag that scopes the one-click bulk actions, inline update badges, and — the part that matters — updates are hot-swapped, so you do not restart DSH. It also detects GitHub / tarball / local-file / symlink installs, and can install and uninstall plugins through the host's official plugin manager API, with backups and rollback.

License

MIT

Related plugins