安装安全网 lxzy-7/dsh-plugin-guard

dsh-plugin-guard

为 DeepSeek Harness 打造的安装安全网：安装前自动快照、一键/自动回退、守护启动，事故报告还会自动触发智能体分析。

DeepSeek Harness 的插件安装安全网：安装前自动快照、一键/自动回退、守护启动、事故报告自动触发 Agent 分析。

它能做什么

插件装坏了，应用可能直接起不来，手动修通常得翻配置文件。这个插件把整条链路自动化：

安装插件（任何方式） │ tools.guard 钩子：安装之前自动快照（进程内完成） ▼ 守护启动（boot-guard 脚本） │ 启动前快照 → 拉起 dsh web → 健康检查 ├─ 健康 ─────────────────────────────► 原样放行 └─ 不健康 ─► 自动回退到上一个可用快照 → 重试一次 → 写一份事故报告 + 打上待处理标记 → 下个会话的提示词会告诉智能体去分析它 → 修好之后，调用 incident_resolved 清除标记

它怎么发现问题（这点很重要）

守护机制不会静态检查插件代码，也不会把插件单独拎出来「测试」。检测分三层：

1. 快照就是纯文件复制。 打快照只是复制 5 个配置文件（package.json、pnpm-lock.yaml、pnpm-workspace.yaml、cordis.yml、cordis.patch.yml）。不运行任何插件，也不评估任何行为。

2. 启动级检测确实会运行 harness —— 而且带着你的插件一起跑。 boot-guard 脚本会拉起整个 dsh web 进程（它会加载所有已安装插件，包括你刚加的那个），然后在超时时间内对 HTTP / 做健康检查。如果某个插件把启动搞挂了 —— 加载报错、启动崩溃、服务器无响应 —— 检查就会失败，守护机制随即杀掉整个进程树，回退到上一个可用快照，再重试一次。所以是的：要抓出搞挂启动的插件，harness（以及那个插件）必须真的启动起来。这是检测过程中唯一会「运行插件」的时刻。从 v0.3.1 起，检查还会确认 web 客户端确实渲染出来了（插件崩溃导致页面黑屏报错时，HTTP 200 依然在 —— 守护机制的客户端会上报渲染崩溃，boot-guard 会回退，而不是把黑屏当成「健康」）；事故报告还会记录每个快照对应的 dsh 版本，并在启动失败发生在 harness 更新之后、而配置档回退又救不回来时给出提示。从 v0.3.2 起，当回退和重试都失败时（DSH 更新导致插件不兼容），boot-guard 会从启动日志里诊断出问题插件，把它隔离（往 cordis.patch.yml 追加 disabled: true），不带它启动，并清楚报告摘掉了哪个插件、以及怎么恢复（dsh-guard quarantine --undo <id>）。
3. 只在运行时才会暴露的问题，安装时查不出来。 插件装得上、启动也正常，但之后才出问题（执行某个操作时崩溃、弄坏状态等），这种情况没有通用防护能提前预判，除非跑你真实的工作负载。真出了事故，dsh_rollback action=incident 会生成一份问题定位报告（最近的启动日志、服务器 stderr，以及配置档配置与上一个正常快照的 diff），并打上待处理标记，让下一个会话自动聚焦诊断。而且任何变更之前都会先拍快照，所以事后你随时可以手动回滚。

一句话：防护从不评判插件好不好。它只保证三件事：(a) 每次变更都可回滚，(b) 启动失败自动回滚，(c) 出事故会被分析，而不是悄悄弄坏你的环境。

安装

From GitHub source (current):
dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard

From the tarball stored in the repo:
dsh plugin --profile web add https://raw.githubusercontent.com/lxzy-7/dsh-plugin-guard/main/dist/dsh-plugin-guard-0.3.2.tgz

重启 dsh web。这是标准 bundle 插件：加入配置档层栈后自动生效。（发布到 npm 之后，dsh plugin --profile web add dsh-plugin-guard 也能用。）

启用带防护的启动（强烈推荐）： 通过 scripts/boot-guard.ps1（Windows）或 scripts/boot-guard.sh（macOS/Linux）启动，不要直接跑 dsh web。Windows 示例，写在你的启动器里：

@echo off
set DSH_HOME=%~dp0.dsh-home
cd /d %~dp0
powershell -NoProfile -ExecutionPolicy Bypass -File node_modules\dsh-plugin-guard\scripts\boot-guard.ps1

可选的命令行垫片（覆盖手动终端安装）： 包里带一个 dsh-guard bin（scripts/guard-cli.js）。把它放进 PATH，在终端里执行 dsh plugin add <pkg> 之前先跑 dsh-guard snapshot，或者用它包一层你自己的 dsh 包装脚本。这样能覆盖不走进程内 tools.guard 钩子的安装。

一键手动回滚（Windows）： 包里还带 scripts/rollback.cmd。安装后它位于 $DSH_HOME/profiles/<profile>/node_modules/dsh-plugin-guard/scripts/rollback.cmd —— 右键 → 创建快捷方式（或把文件复制到任意位置），双击即可恢复每个配置档的上一个正常快照，并重新执行 pnpm install --frozen-lockfile。回滚还会删掉 node_modules 里残留的孤立 bundle 插件符号链接（pnpm 从不移除过期的 link: 条目 —— 只说 "Already up to date" —— 所以防护直接对着恢复后的 package.json 动手）。应用起不来时它照样能用，环境没设 DSH_HOME 时它会自己推导出来。

用法

设置面板 — 备份管理 (Backup Manager)。 在 Web UI 里打开 设置 (Settings) → 备份管理：按环境列出快照列表、加载指定备份、手动创建快照，以及设置每个环境保留多少快照（最少 2 个）。从 v0.3.0 起，插件还会注册一张 设置 → 插件 → 插件配置 设置卡片（rc.7 插件自有设置界面）：它通过 harness 的 settings 服务编辑同一个保留数量（schema 校验、revision 围栏），备份管理面板与命令行则通过 config.json 保持同步。

智能体工具（为配置档中的每个会话注册）：

| 工具 | 用途 |
| dsh_snapshot | 手动为某个配置档或全部配置档创建快照 |
| dsh_rollback | list / rollback / status / incident（基于 Node，跨平台） |
| incident_resolved | 分析或修复完成后，把待处理事件标记为已解决 |

命令行（dsh-guard，应用起不来时也能用）：

snapshot [--profile X] [--tag T] [--reason R] [--force]
list [--profile X]
rollback [--profile X] [--id I | --good] [--skip-install]
keep [N] # show or set the per-profile cap (min 2)
health [--port N]
incident [--kind K] [--no-marker]
resolve
profiles

配置

$DSH_HOME/guard/config.json（首次写入时自动创建；字段全部可选）：

{
"keepSnapshots": 10,
"port": 3080
}

- keepSnapshots — 每个配置档保留多少快照（限制在 2–100，默认 10）。清理时删掉较旧的快照。
- port — 健康检查 / 事件报告使用的 Web 端口（默认 3080）。如果你的 dsh web 跑在别的端口，就设置它。也可以给命令行传 --port。

所有路径都以 $DSH_HOME 为根（环境变量未设置时默认 ~/.dsh）：

$DSH_HOME/rollbacks/<profile>/<stamp>/ snapshots (5 config files + manifest.json)
$DSH_HOME/guard/logs/ boot/server logs, incident reports, last-boot.txt
$DSH_HOME/guard/pending-incident.json pending incident marker
$DSH_HOME/guard/config.json guard settings (keepSnapshots, port)

回滚语义

- 回滚 = 还原 4 个配置文件 + pnpm install --frozen-lockfile，精确复现 node_modules。
- pnpm 解析顺序：快照清单里记录的绝对路径（与安装时同一环境，不依赖当前 PATH）→ DSH_GUARD_PNPM 环境变量 → 当前 PATH → harness 本地的 node_modules/.bin。
- 每次回滚前先写一份 pre-rollback 快照，所以回滚本身也可回滚。
- 「最后一个可用版本」= 最新一份未打 pre-boot/pre-rollback 标签的快照。

平台支持

| 组件 | Windows | macOS / Linux |
| 插件（工具 / 钩子 / 提示词注入） | ✅ | ✅ |
| dsh-guard 命令行 | ✅ | ✅ |
| 受守护的启动脚本 | PowerShell | bash |

安全说明

- 插件只读写配置档配置文件和快照，绝不执行第三方代码。pnpm install --frozen-lockfile 只还原快照里记录的锁定依赖。
- 快照和事故报告都是本地文件，不含凭据（凭据存放在 $DSH_HOME 下的其他位置，不在这套目录结构里）。
- 只有启动健康检查失败时才会自动回滚；正常运行期间，guard 绝不会悄悄改动配置。

已知限制

- 事故自动分析覆盖启动失败类事故；会话中途出错时，手动运行 dsh_rollback action=incident 可生成同样的报告。
- 改动 bundle 插件后需要重启 web 才能生效。
- 会话日志损坏属于数据问题，不在回滚范围内。

开发

node scripts/smoke-test.js # engine smoke test (throwaway DSH_HOME, no side effects)
node scripts/guard-cli.js help

发布

本包采用 MIT 协议，已可发布到 npm（包名：dsh-plugin-guard）。它不带任何运行时依赖，每次发布前都会自动跑一遍引擎冒烟测试（prepublishOnly），所以坏掉的构建永远发不出去。发布步骤：

npm login # once, on your machine
npm publish # runs npm test first, then publishes with public access

repository / homepage 是可选字段——等你有了 GitHub 仓库再加上（这两个字段只是让 npm 页面更好看）。

用户可以从线上仓库安装：dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard（或用 dist/ 里的 tarball）；等它上了 npm，dsh plugin --profile web add dsh-plugin-guard 也能用。

许可证

MIT

这是什么

一次坏的插件安装可能让应用起不来、对话崩溃，修复常常要手动翻配置。本插件把整条链路自动化：

安装插件(任何途径)
│ tools.guard 钩子:安装前自动快照(进程内) ▼
守护启动(boot-guard 脚本)
│ 启动前快照 → 启动 dsh web → 健康检查 ├─ 正常 ────────────────────────────────► 无感放行 └─ 异常 ─► 自动回退到最后良好快照 → 重试一次 → 生成事故定位报告 + 待处理标记 → 下一次会话的提示词自动告诉 Agent 去分析 → 修复后调用 incident_resolved 标记已处理

它如何检测问题（重要，请理解）

Guard 不会静态分析插件代码，也不会单独"测试"某个插件。检测分三层：

1. 快照只是纯文件复制。 备份只是复制 5 个配置文件（含 cordis.yml——MCP 服务器实例就配在这里，坏掉的 MCP 配置可随回滚一并撤销），不会运行任何插件，也不评估任何行为。

2. 启动级检测确实会运行 harness——连同你装的插件一起。 boot-guard 会启动整个 dsh web 进程（会加载所有已装插件，包括你刚加的），然后在超时内对 HTTP / 做健康检查。如果插件导致启动失败（加载报错、启动崩溃、服务无响应），检查即失败，guard 会自动杀掉进程树、回退到最后良好快照并重试一次。所以是的：要抓住"搞坏启动"的插件，harness（连同该插件）必须真正启动一次——这是检测中唯一需要"运行插件"的时刻。v0.3.1 起还会确认 web 客户端真正渲染成功（插件崩溃导致页面黑屏报错时 HTTP 仍是 200——guard 客户端会上报渲染崩溃，守护脚本会回滚而不是把黑屏当成"健康"）；事故报告会记录每个快照对应的 dsh 版本，并在启动失败紧跟 harness 更新时明确标注（profile 回滚无法撤销 DSH 根目录更新）。v0.3.2 起，当回滚与重试都失败（DSH 更新导致插件不适配）时，boot-guard 会从启动日志诊断出问题插件并隔离（在 cordis.patch.yml 追加 disabled: true），不带它启动，并明确显示被拔出的插件及恢复方法（dsh-guard quarantine --undo <id>）。
3. 只在运行期才出问题的插件，安装时检测不到。 如果一个插件装得上、启动也正常，只是后来才出错（在某个操作下崩溃、弄坏状态等），任何通用 guard 都无法在不运行你的真实工作负载的情况下预判。这类事故发生后，dsh_rollback action=incident 会生成事故定位报告（最近启动日志、服务端 stderr、profile 配置与最近良好快照的差异），并设置待处理标记，让下一次会话自动聚焦于诊断它。而且任何变更前都会先快照，所以你事后也随时能手动回退。

一句话总结：guard 从不评判一个插件"好不好"。它保证：(a) 任何变更都可回退；(b) 启动失败自动回退；(c) 事故会被分析，而不是悄悄搞坏你的环境。

安装

从 GitHub 源码安装(当前方式)：
dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard

或从仓库里的安装包：
dsh plugin --profile web add https://raw.githubusercontent.com/lxzy-7/dsh-plugin-guard/main/dist/dsh-plugin-guard-0.3.2.tgz

重启 dsh web。这是标准 bundle 插件：加入 profile 层栈自动生效。(发布到 npm 后 dsh plugin --profile web add dsh-plugin-guard 也可用。)

启用守护启动(强烈推荐)： 把启动命令改为经过 scripts/boot-guard.ps1(Windows) 或 scripts/boot-guard.sh(macOS/Linux)，而不是直接跑 dsh web。Windows 启动器示例：

@echo off
set DSH_HOME=%~dp0.dsh-home
cd /d %~dp0
powershell -NoProfile -ExecutionPolicy Bypass -File node_modules\dsh-plugin-guard\scripts\boot-guard.ps1

可选 CLI 垫片(覆盖终端手动安装)： 包内带 dsh-guard 命令(scripts/guard-cli.js)。加入 PATH 后，在终端执行 dsh plugin add <pkg> 前先 dsh-guard snapshot（或自己包一层包装），覆盖不走进程内 tools.guard 钩子的安装途径。

一键手动回退(Windows)： 包内还带 scripts/rollback.cmd。安装后位于 $DSH_HOME\profiles\<profile>\node_modules\dsh-plugin-guard\scripts\rollback.cmd——右键 → 创建快捷方式放到桌面(或把该文件复制到任意位置)后双击，即可把所有 profile 还原到最近一份「良好」快照并重跑 pnpm install --frozen-lockfile。应用完全启动不了时也能用；环境未设置 DSH_HOME 时它会从自身位置自动推导。

使用

设置面板 — 备份管理。 网页界面里打开 设置 → 备份管理：按环境列出快照、加载指定备份、手动存档、设置每个环境保留的快照数量(最少 2)。v0.3.0 起插件还会注册 设置 → 插件 → 插件配置 设置卡片（rc.7 插件自有设置表面）：通过 harness 的 settings 服务编辑同一保留数量（schema 校验 + revision 冲突保护），与备份管理面板、CLI 通过 config.json 保持同步。

Agent 工具(profile 内每个会话都会注册)：

| 工具 | 作用 |
| dsh_snapshot | 手动快照一个或全部环境 |
| dsh_rollback | list / rollback / status / incident(跨平台 Node 实现) |
| incident_resolved | 分析并修复后标记事故已处理 |

CLI(dsh-guard，应用起不来时也能用)：

snapshot [--profile X] [--tag T] [--reason R] [--force]
list [--profile X]
rollback [--profile X] [--id I | --good] [--skip-install]
keep [N] # 查看或设置保留快照数(最少 2)
health [--port N]
incident [--kind K] [--no-marker]
resolve
profiles

配置

$DSH_HOME/guard/config.json(首次写入时自动创建；全部可选)：

{
"keepSnapshots": 10,
"port": 3080
}

- keepSnapshots — 每个环境保留多少份快照(钳制 2–100，默认 10)，超出的旧快照会被清理。
- port — 健康检查/事故报告用的 web 端口(默认 3080)。如果你的 dsh web 跑在其他端口，改成实际值即可；CLI 也可用 --port 覆盖。

所有路径都锚定 $DSH_HOME(未设置时默认 ~/.dsh)：

$DSH_HOME/rollbacks/<profile>/<stamp>/ 快照(5 个配置文件 + manifest.json) $DSH_HOME/guard/logs/ 启动/服务器日志、事故报告、last-boot.txt $DSH_HOME/guard/pending-incident.json 待处理事故标记 $DSH_HOME/guard/config.json 备份设置(keepSnapshots, port)

回退语义

- 回退 = 恢复 4 个配置文件 + pnpm install --frozen-lockfile 精确还原 node_modules。
- pnpm 定位顺序：快照 manifest 记录的绝对路径(与当初安装同环境，不依赖回退时的 PATH) → DSH_GUARD_PNPM 环境变量 → 当前 PATH → harness 本地 node_modules/.bin。
- 每次回退前自动先存一份 pre-rollback 快照：回退本身可逆。
- 「最后良好」= 最新的非 pre-boot/pre-rollback 标签快照。

平台支持

| 组件 | Windows | macOS/Linux |
| 插件(工具/钩子/提示注入) | ✅ | ✅ |
| dsh-guard CLI | ✅ | ✅ |
| 守护启动脚本 | PowerShell | bash |

安全说明

- 本插件只读写 profile 配置文件与快照，不执行第三方代码；pnpm install --frozen-lockfile 只按快照锁文件还原。
- 快照与事故报告是本地文件，不含凭据(凭据在 $DSH_HOME 其他位置，不在此目录约定内)。
- 自动回退只发生在「启动健康检查失败」时，运行期不会随意改动配置。

已知边界

- 事故自动分析覆盖启动失败类事故；对话中途报错可用 dsh_rollback action=incident 手动生成同款报告。
- bundle 插件的加载变化需要重启 web 生效。
- 会话日志损坏属于数据问题，不在回退范围。

开发

node scripts/smoke-test.js # 引擎冒烟测试(临时 DSH_HOME，无副作用)
node scripts/guard-cli.js help

发布

MIT 许可，可直接发布到 npm(包名 dsh-plugin-guard)。包零运行时依赖，且 prepublishOnly 会在每次发布前自动跑引擎冒烟测试，坏包永远发不出去：

npm login # 在本机登录一次
npm publish # 先跑 npm test，再以 public 权限发布

repository / homepage 已指向 GitHub 仓库(仅影响 npm 页面的展示)。

用户可从在线仓库安装：dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard(或下载 dist/ 里的 tgz 按路径安装)；发布到 npm 后 dsh plugin --profile web add dsh-plugin-guard 也可用。

License

MIT