前言¶
DeepSeek Harness（DSH）采用「一切皆插件」的扩展方式：Harness 本体与各类能力都以 bundle 形式安装、迭代。插件一多，版本往往分散在各自目录、pnpm-lock 与 npm registry 之间；若新版本在 package.json 里声明了 engines.dsh，还会在 DSH 版本不满足时被安装器挡在门外。手工逐个 pnpm update、对照 semver 与 DSH 门控，既慢也容易在「版本太新还不能装」或「传递依赖根本没动」这类细节上踩坑。下面介绍社区维护的 dsh-upgrade-assistant（GitHub：zhangrui824/dsh-upgrade-assistant）：在 DSH Web UI 的 Plugins 页增加 Upgrades 标签，把已安装插件的 npm 比对、engines.dsh 预检与就地升级收到同一界面，失败原因用可读文案说明。
这是什么¶
dsh-upgrade-assistant 是面向 DSH 的升级助手插件，维护者为 zhangrui824，在 SkillHub 目录中归类为 admin-security。它在插件管理页提供 Upgrades 标签：对每条已安装的 npm bundle 做更新检查（尊重 profile 镜像与约 5 分钟缓存、并发 3），对 Harness 本体做 npm 最新版比对；在升级前按 DSH 同款 semver 规则评估目标版本的 engines.dsh，不满足时显示 Needs newer DSH 并隐藏升级按钮；满足条件时可一键就地执行升级，并在跑完后从 node_modules 回读实际版本，避免「pnpm 成功但未真正升版」被误报为成功。
核心功能¶
Upgrades 标签里的信息结构¶
界面顶部有自检条（例如包管理器、语言、bundle 数量、当前 DSH 版本）。主体包括：
- Harness (DSH)：当前版本 / npm 最新版，以及 Check DSH updates。
- Installed plugins：Check plugin updates 后，每行显示 bundle 名、版本对比（如
0.77.0 → 0.78.1）、状态（Upgrade available、Up to date、Not on npm — skipped 等），以及engines.dsh摘要。 - Version exemptions：当前生效的、可跳过 DSH 门控的
package@version许可说明。 - When an upgrade fails：四类常见失败原因的说明。
更新检查¶
Check plugin updates 将各已安装 bundle 与 npm 比对（使用 profile 配置的 registry，默认 npmjs）。从 GitHub 或本地路径安装的 bundle 没有 npm 版本可比，会标记 Not on npm — skipped；对这类 GitHub 来源、且带有 npm 传递依赖的 bundle，可提供 Refresh bundled family，在父包 semver 允许范围内刷新依赖，而不是误用 --latest 去动传递链。
Check DSH updates 将当前运行的 Harness 与 npm 上最新发布比对。
就地升级机制¶
用户点击绿色 Upgrade available 后的 Upgrade（内联确认后执行）：
- npm 直装插件：执行
pnpm update --latest --config.minimumReleaseAge=0 <name>。仅在用户点击时关闭 pnpm 默认约 24 小时的「新版本冷却」限制，减少「版本太新无法安装」类失败。 - 传递依赖族（由 GitHub 来源 bundle 拉入的 npm 依赖）：因
pnpm update --latest无法单独推高传递依赖，插件改为在范围内刷新：pnpm update <deps> --config.minimumReleaseAge=0。 - 事后校验：从
node_modules读取实际安装版本；若 pnpm 退出成功但未改变版本，报告为stale，不算成功。 - 防降级：当 npm
latest标签低于已安装版本（官方@deepseek-ai/*等场景较常见）时拒绝更新。
engines.dsh 预检¶
目标新版本若声明 engines.dsh，在升级前用与 DSH 门控一致的 semver 评估（node-semver 语义，includePrerelease: true）。不满足的 bundle 显示 Needs newer DSH，不展示升级按钮。解析不了的 range 语法不会阻塞升级，仅原文展示，最终以真实安装结果为准。
安全模型¶
自定义 Web 路由不经过 DSH Web UI 的 cookie 认证，本插件对所有路由自建信任边界（与社区 dsh-update 同级）：
- 仅允许回环地址（127/8、
::1）且 Host 为回环。 - 浏览器请求须同源（Origin 匹配，
sec-fetch-site非 cross-site）。 - 不信任 X-Forwarded-For；拒绝时返回
403与 JSON 原因。 - 更新路由额外要求：POST、包名 allow-list 正则（防注入与路径穿越）、4 KB 请求体上限、single-flight（同一时刻仅一个 pnpm 操作）、10 分钟超时并强制结束进程（Windows 用 taskkill，Unix 用进程组）。
安装与启用¶
从 GitHub 安装（README 推荐方式）：
dsh plugin --profile <your-profile> add github:zhangrui824/dsh-upgrade-assistant
插件 package.json 声明 engines.dsh: >=0.2.1-rc.2，node: >=22。许可证为 MIT。
Host 侧改动需 重启 Harness 一次后，更新相关服务才会就绪；仅改客户端时刷新页面即可。若点击升级提示更新服务尚未就绪，通常也是 Host 未重启所致。
典型用法¶
- 侧栏进入 Plugins，打开 Upgrades 标签。
- 点击 Check plugin updates，查看各 bundle 与 npm 的版本差与
engines.dsh状态。 - 对 Upgrade available 行点击 Upgrade 完成就地升级；对 Needs newer DSH 行先升级 Harness，再回来升级插件。
- 需要时点击 Check DSH updates 检查 Harness 本体是否有 npm 新版本。
- 对 Not on npm — skipped 的 GitHub 来源 bundle，若存在 npm 依赖族，可使用 Refresh bundled family 刷新传递依赖。
与 dsh-update 的分工：dsh-update 侧重其作者 @linxin666/* 族与 release notes；本插件覆盖全局 npm bundle 视图，并显式区分直接依赖 --latest 与传递依赖 in-range 刷新两种模式。
适用场景与注意¶
适合在本地或内网长期运行 DSH、安装较多 npm/GitHub 混合来源插件、需要统一看版本与 DSH 兼容性的开发者与运维。插件以 当前 DSH 进程权限 执行 pnpm 与 HTTP 路由；安装前请阅读仓库源码与 MIT 许可证，自行评估是否纳入环境。
已知限制（来自 README）：运行中 DSH 版本来自 DSH_CLIENT_VERSION 或从入口脚本向上查找 @deepseek-ai/dsh manifest，否则显示 unknown（其余功能仍可用）；需认证的私有 registry 可能失败并显示原因；从本地路径安装时插件无法升级自身（发布到 npm 后可使用界面自举升级）。
结尾¶
dsh-upgrade-assistant 把插件与 Harness 的版本检查、engines.dsh 预检和一键就地升级集中到 Upgrades 标签，并对 npm 直装与传递依赖族、防降级与事后校验做了区分处理；安全上限制回环与同源，并对升级接口做并发与超时控制。目录页：https://www.skillhub.cn/plugins/zhangrui824/dsh-upgrade-assistant；源码与完整说明：https://github.com/zhangrui824/dsh-upgrade-assistant。
