前言¶
DeepSeek Harness（DSH）发版节奏快，每次核心升级都可能收紧插件依赖的契约：模块表变严、服务注入缺字段就抛错、UI 导出改名、会话消息格式变更。社区里常见的结果是页面报 Failed to load plugins、插件链里大量 PENDING，或跑完任务才在格式化消息处失败。手工对照 changelog 和逐个试升级成本高，也容易漏掉「静态代码里还在引用已删除的服务名」这类问题。
下面介绍维护者 wqx11235 在 SkillHub 插件目录 发布的 dsh-upgrade-guard（分类：工作流）。它把历次升级事故里总结出的检查固化成三条可重复执行的动作：升级前盘点、升级后扫契约、切流量前做启动冒烟。
这是什么¶
dsh-upgrade-guard 是面向 DSH 0.1.x / 0.2.x 的升级安全网插件（当前包版本 0.2.0，MIT 许可证，要求 Node >= 22）。它不替代官方发布说明，而是对已知的破坏性契约做离线扫描，在升级前对照 npm 上的插件兼容声明做预检，并在临时端口上拉起一次宿主做启动级验证。
插件在 Web 配置档（profiles/web）与官方桌面端（profiles/desktop）共用同一套逻辑：宿主侧不 import @deepseek-ai/* 包，通过 webServer 服务挂路由；客户端遵循 0.1.2+ 的 inject / slots 约定，只 require('react')，以降低「宿主契约变了、插件还在引旧包」这类历史故障面。
核心功能：三个动作¶
README 将能力归纳为下表对应的三项（名称与时机以仓库文档为准）。
| 动作 | 时机 | 作用 |
|---|---|---|
| Contract scan（契约扫描） | 随时 / 升级后 | 离线、秒级：对照 KNOWN_RULES 目录，扫描已安装插件是否触犯已知破坏性契约（已移除/重命名的服务、session 消息 v4 的 source 形态、引用宿主 ui-primitives 中不存在的导出等） |
| Preflight（预检） | 升级前 | 在线、约 10–40 秒：逐插件看声明的兼容范围、npm 最新版、是否支持目标宿主版本，输出「能否升级、需联动升级谁、建议先禁用谁」 |
| Boot smoke（启动冒烟） | 切换端口前 | 约 30–90 秒：在测试端口启动临时宿主，读启动摘要（SKIPPED / DEGRADED / PENDING 等），探测各 client bundle 可达性，结束后结束测试进程 |
契约扫描的规则类型在 lib/guard.mjs 的 KNOWN_RULES 中维护，文档列出的类别包括：removed-service、session-source-v4、missing-host-export、pinned-exact。新事故以「补一条规则」的方式扩展目录，而不是泛化猜测。
安装与启用¶
安装命令以 GitHub README 为准。典型 Web 配置档路径如下（PowerShell 示例）：
cd $env:USERPROFILE\.dsh\profiles\web
pnpm add github:wqx11235/dsh-upgrade-guard
随后在该 profile 的 package.json 里，把 "dsh-upgrade-guard" 加入 dsh.profile.bundles。
无网络时可手动把整个仓库放到 %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-upgrade-guard，同样写入 dsh.profile.bundles。桌面端把路径中的 web 换成 desktop。
完成依赖安装与 bundle 登记后，重启宿主、强刷页面，在界面打开 设置 → 通用 → 升级守卫。
说明：本文不给出 git clone 或凭插件名拼接的 dsh plugin add 命令；请以 README 中的 pnpm add github:wqx11235/dsh-upgrade-guard 为准。
典型用法¶
图形界面¶
路径：Settings → General → Upgrade guard（中文：设置 → 通用 → 升级守卫）。三个按钮对应上述三项能力；页脚会标明结果所依据的宿主版本、运行时与 ui-primitives 来源，避免「磁盘上的 primitives 副本与运行中宿主不一致」时误判导出是否存在。
- Contract scan：摘要形如
critical N / warn N (scanned M plugins)，并列出发现项。 - Preflight：摘要含目标版本、插件数量与有更新的数量，并给出列表。
- Boot smoke：
PASS/FAIL，并附带关键行（如ROOT?、PENDING、SKIPPED、DEGRADED、BADBUNDLE）。
命令行（同一套引擎）¶
控制台输出刻意使用英文/ASCII（避免 Windows cmd 代码页 936 下 UTF-8 中文乱码）；中文报告写入 --report 指定文件（默认目录为 $DSH_HOME/upgrade-guard/）。
node lib/guard.mjs scan --json --report scan.md [--profile <dir>] [--primitives <dir>]
node lib/guard.mjs preflight --json --report preflight.md --target 0.1.8-rc.1 [--no-network]
node lib/guard.mjs smoke --bin <.../dsh/lib/bin.js> --cwd <dir> --port 3099 --timeout 120 [--keep]
常用环境变量：DSH_HOME（默认 ~/.dsh）、DSH_PROFILE、DSH_PRIMITIVES、DSH_SMOKE_BIN、DSH_SMOKE_PORT、DSH_SMOKE_CWD、DSH_SMOKE_TIMEOUT、DSH_SMOKE_KEEP=1。
HTTP 接口¶
宿主注册 POST /api/dsh-upgrade-guard，README 示例：
{ "action": "status" }
{ "action": "scan" }
{ "action": "preflight", "target": "latest" }
{ "action": "smoke", "port": 3099 }
分别返回路径与宿主信息、扫描统计与报告路径、预检行数据、冒烟结论与报告路径等（字段以实际响应为准）。
适用场景与限制¶
适合谁：经常在单机或团队环境里升级 DSH 核心、且 profile 里挂了大量社区插件的维护者；希望在「改生产端口」之前先看到启动链路与 bundle 层面的红灯。
运行权限：插件与当前 DSH 宿主同一进程权限执行；安装前请自行审阅 GitHub 仓库 源码与 MIT 许可证，勿在未检查的情况下在生产环境直接启用冒烟或预检（预检会访问 npm registry）。
文档明确写的限制（节选）：
- 冒烟只覆盖启动阶段（插件树加载、服务依赖、client bundle 可达性）；渲染期错误（例如 primitives 改名导致的
Minified React error #130）要靠契约扫描兜底。 - 契约扫描只覆盖已知目录；全新类型的破坏在规则补齐前不可见。
- Preflight 需要能访问 npm；从 git/url 安装的插件无法自动比对新版本，会标为需人工核对。
- 被宿主 peer 兼容门跳过（
SKIPPED）不等于崩溃；重装往往要配合dsh plugin allow-version等显式豁免。 - 打包后的桌面运行时（入口在
app.asar内）下冒烟会报告UNSUPPORTED并给出替代说明，而不是静默失败。
生态上，DSH 强调「一切皆插件」；SkillHub 是社区目录站点，与 DeepSeek / 幻方无官方从属关系。仓库当前 GitHub 星标为 2（以目录页/仓库页面为准）。
结尾¶
经过上面的步骤，你可以在升级 DSH 前用 Preflight 看清插件矩阵，升级后用 Contract scan 扫一遍已知契约，切端口前用 Boot smoke 确认启动摘要没有隐藏的 PENDING 根因。更多信息见目录页 wqx11235/dsh-upgrade-guard 与源码 github.com/wqx11235/dsh-upgrade-guard（含中文说明 README.zh.md）。
