- Home
- Plugins
- Dev & Plugin Tools
- dsh-plugin-rack
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-rackREADME
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.yml | bundle 补丁,插入 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.json | lint 与 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、删包。为了让这些操作可控,做了四层防护:
-
网络暴露面:API 只在
127.0.0.1/localhost/::1上可达。宿主的 web server 本来就只绑 loopback,所以外网碰不到这个端口。 -
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"}' -
卸载白名单:界面上的「卸载」按钮不是对所有行都显示。只有宿主
pluginManager服务明确标记为removable的包才会出现按钮。核心组件、面板自己、harness 命脉都永远不会出现在可卸载列表里,所以误点卸载也不会把系统拆坏。 -
更新回滚:批量更新前会备份
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之前而不是紧贴当前版本——DSH0.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.jsimport 它,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
deepseek-harness
deepseek-ai/deepseek-harness
dsh-market
dsh-market/dsh-market
dsh-web (dsh-plugin-manager)
zhu1090093659/dsh-web
dsh-web
zhu1090093659/dsh-web