---

description: "DSH 跨版本启动护航：一套引擎，同时以命令行工具（dsh-guard.cmd、pull-dsh.cmd）和可安装的 Web 插件（侧边栏「启动护航」面板 + 同源路由）两种形态交付。" kind: "package-bundle"

dsh-guard-plugin

English | 中文

摘要

DSH 跨大版本升级后，profile 里的社区插件跟不上新框架时就启动不了。本包就是为了让这种情况可恢复， 并按用户真正需要的两种形态交付：

• 作为命令行工具（dsh-guard.mjs + dsh-guard.cmd / pull-dsh.cmd）：动态解析 DSH 安装、 对组合后的 profile 做预检；正常组合起不来时自动降级到安全模式（停用插件、整份备份配置）或一个干净的 guard-rescue profile。DSH 已经趴下时，只有它能用。
• 作为插件（dsh plugin --profile web add）：同一套引擎，在运行中的 Web 界面里呈现为侧边栏 启动护航 / Startup Guard 面板——guard 状态、检查更新、还原插件配置、一键进入安全模式。

两个形态驱动同一个引擎，插件不复制任何逻辑。引擎随包发布，所以安装时不需要配置任何外部路径。

目录

• 它是什么
• 环境要求
• 作为插件安装
• 使用插件
• 使用命令行
• 命令
• HTTP 接口
• 配置
• 自测
• 打包与发布
• 卸载
• 已知边界与待办

它是什么

层	作用	什么时候用
引擎（dsh-guard.mjs）	解析安装 → 预检 → 启动并看护端口 → 失败则进入安全模式（整份备份、停用插件）→ 再退到 guard-rescue；另含 pull、restore、safe	始终，两个形态都靠它
host 半（lib/index.js）	注册同源 /dsh-guard/* 路由，转调包内引擎	作为插件安装后
client 半（lib/client.js）	侧边栏入口 + 控制面板（普通 fetch，不走 RPC）	作为插件安装后
命令行入口（dsh-guard.cmd、pull-dsh.cmd）	引擎的可双击包装	DSH 起不来时，或在终端里

插件做不到的是「启动前」那一段：插件运行在 DSH 进程内部，DSH 起不来时它根本不存在。 这就是命令行入口必须保留的原因。

环境要求

• DSH 0.1.5-rc.1 或更高（依赖该代际的 dsh.bundle.patch + dsh.client 契约）。
• Node.js >= 20。
• 无需任何外部准备：引擎就在本包里。

作为插件安装

cd /d D:\app\deepseek_HARNESS\chat
dsh-guard\dsh-guard.cmd resolve
rem 使用上面打印的 bin.js：
node "<bin.js>" plugin --profile web add "file:D:/app/deepseek_HARNESS/chat/dsh-guard"

发布之后，同一条命令也可以直接写包名：

node "<bin.js>" plugin --profile web add dsh-guard-plugin

然后重启 DSH 并刷新页面。若提示 'pnpm' is not recognized，说明 pnpm 不在 PATH，需要先配好 corepack。

装插件正是这套 guard 要防的那种有风险的操作。 建议先留还原点：dsh-guard\dsh-guard.cmd safe，出问题用 restore --yes 回退。

使用插件

启动护航 / Startup Guard 出现在侧边栏底部、设置正上方：

• 状态：选定版本、本地已装版本、端口是否在监听、是否安全模式、上次成功启动的版本、用户插件数、备份数；每 20 秒自动刷新。
• 刷新：重新读取状态。
• 检查更新：pull --dry-run——只查 registry 并与本地比对，不写盘、不启动。
• 还原插件配置：restore，从最近一次备份还原。
• 进入安全模式：safe——先整份备份，再停用用户插件。需要重启 DSH 才生效。

面板里刻意没有「立即拉取」：拉取会改写正在被加载的安装，而且拉完必须重启， 在页面里做等于自己把自己的连接掐断。请用 pull-dsh.cmd。

使用命令行

在本包目录（D:\app\deepseek_HARNESS\chat\dsh-guard）下：

dsh-guard.cmd                 rem 带护航启动（预检、看护端口、失败自动降级）
dsh-guard.cmd status          rem 体检：安装候选、端口、安全模式、备份
dsh-guard.cmd start --update  rem 先拉最新版再启动
pull-dsh.cmd                  rem 只拉取（先把 tag 解析成精确版本）
dsh-guard.cmd safe            rem 立刻进入安全模式，不启动
dsh-guard.cmd restore --yes   rem 从最近备份把插件配置还原回来
node dsh-guard.mjs <命令>      rem 直接用引擎，命令集相同

在上一层 chat 目录里，给命令加前缀 dsh-guard\ 即可。

命令

命令	作用
start（默认）	解析 → 预检 → 启动 → 看护；失败自动降级
status	安装候选、选定版本、端口、bundles、安全模式、备份（--json 输出结构化数据）
resolve	打印安装候选与最终选用的 bin.js
pull	把 dist-tag 解析成精确版本，与本地比对，只在需要时拉取（从不启动）
restore	从备份还原 profile 配置并解除安全模式（默认最新，或 --backup <dir>）
safe	只进入安全模式（整份备份后停用用户插件），从不启动

退出码：0 成功/已在运行，1 失败，2 参数错误，3（pull）DSH 正在运行且未给 --yes。

HTTP 接口

由 host 半注册，浏览器端用普通 fetch 调用（不走 RPC，不走 typert）：

方法	路径	对应引擎命令
GET	/dsh-guard/health	—（存活探测；同时报告引擎是否存在）
GET	/dsh-guard/status	status --json
POST	/dsh-guard/check	start --dry-run --json
POST	/dsh-guard/pull	pull（body：tag/to/dryRun/yes/force）
POST	/dsh-guard/restore	restore（body：backup）
POST	/dsh-guard/safe	safe（body：reason）

配置

可选。查找顺序：环境变量 > <包目录>\guard.config.json > %DSH_HOME%\dsh-guard.config.json > 包内自带的 dsh-guard.mjs。配置文件里的相对路径按该文件所在目录解析。参见 guard.config.example.json。

环境变量：DSH_GUARD_SCRIPT、DSH_GUARD_NODE、DSH_GUARD_HOME、DSH_GUARD_PROFILE、 DSH_GUARD_PORT、DSH_GUARD_HOST、DSH_GUARD_WORKSPACE、DSH_GUARD_TIMEOUT。

自测

两套，都是离线安全、都不会碰你真实的 %USERPROFILE%\.dsh：

cd /d D:\app\deepseek_HARNESS\chat\dsh-guard
node test\selftest.mjs   rem 引擎：70 项，对 mock DSH，不联网、不碰真实 DSH
node test\e2e.mjs        rem 插件：19 项，在隔离 DSH_HOME 里起真实 dsh web

e2e 会把整个包拷进隔离 profile 的 node_modules（模拟普通插件安装），起真实 dsh web， 断言六个路由以及 boot 清单。它不设置 DSH_GUARD_SCRIPT——这正是「本包自包含」的证明。 当前 70 passed / 0 failed 与 19 passed / 0 failed。

e2e 不能证明的是：它验证 client bundle 被登记并下发，不是它在浏览器里的渲染效果。 装好后请刷新页面亲眼确认；面板没出现就按 F12 看 console。

打包与发布

cd /d D:\app\deepseek_HARNESS\chat\dsh-guard
npm pack

test\ 通过 files 排除；运行所需的一切（引擎、两个半部、两个 .cmd、补丁、文档、LICENSE）都在包里。 发布名 dsh-guard-plugin，目前在 npm 上未被占用。npm publish --dry-run 已验证退出码为 0。

卸载

node "<bin.js>" plugin --profile web remove dsh-guard-plugin

然后确认 dsh.profile.bundles 里没有残留。命令行入口不受影响——引擎在本目录，不在 profile 里。

已知边界与待办

• dsh.client.inject 故意写成 []：浏览器端只 require('react')（platform 模块），不列任何 client 包行，这样将来 DSH 版本删掉其中某个包时，不至于让整块 bundle 抛错。
• host 半只 inject ['webServer']；不用 typert，不用 RPC。
• 子进程输出走临时文件而非管道，因此在没有命名管道的受限环境里也能工作。
• 插件自己也是插件：安全模式会把它一起停用。用 dsh-guard.cmd restore --yes 把大家接回来。
• npm 安装后 node_modules 里的两份 .cmd 只是便利副本；正式入口是本目录里的那两个。
• repository / homepage / bugs 尚未设置；不填也能发布，只是 registry 页面没有源码链接。

相关文件

• test\selftest.mjs、test\mock-dsh\、test\mock-registry.mjs —— 引擎的测试替身。
• test\e2e.mjs —— 整包安装、对真实 DSH 的端到端测试。