lxzy-7/dsh-plugin-guard

dsh-plugin-guard

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

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

English

功能简介

一次糟糕的插件安装可能让应用无法启动，而手动修复通常意味着翻遍配置文件。本插件将整条链路自动化：

安装插件（任意方式）
│  tools.guard 钩子：安装前自动快照（进程内）
▼
守护启动（boot-guard 脚本）
│  启动前快照 → 启动 dsh web → 健康检查
├─ 健康 ─────────────────────────────► 原样通过
└─ 不健康 ─► 自动回退到上一个良好快照 → 重试一次
→ 写入事故报告 + 设置待处理标记
→ 下一次会话的提示词告知 Agent 分析该事故
→ 修复后调用 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 更新之后、而 profile 回退无法撤销该更新时发出标记。自 v0.3.2 起，当回退和重试都失败时（DSH 更新导致某个插件不兼容），boot-guard 会从启动日志中诊断出问题插件，将其隔离（向 cordis.patch.yml 追加 disabled: true），在不加载它的情况下启动，并清楚报告被移除的是哪个插件以及如何恢复它（dsh-guard quarantine --undo ）。
3. 仅运行时问题不会在安装时被检测到。 如果一个插件安装并启动正常，但之后才出问题（在特定操作下崩溃、破坏状态等），没有任何通用防护机制能在不运行你真实工作负载的情况下预测到这一点。当此类事件发生时，dsh_rollback action=incident 会生成一份问题定位报告（最近的启动日志、服务器 stderr，以及配置文件与上一个良好快照的差异），并设置一个待处理标记，以便下一个会话自动聚焦于诊断该问题。而且由于在任何变更之前都会始终创建快照，你之后总是可以手动回滚。

简而言之：该防护机制从不评判一个插件是否“好”。它保证的是：(a) 每一次变更都是可逆的，(b) 启动失败会自动回滚，(c) 事件会被分析，而不是悄无声息地破坏你的配置。

安装

从 GitHub 源码（当前）：
dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard

从仓库中存储的 tarball：
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 bin（scripts/guard-cli.js）。将其放到你的 PATH 上，并在从终端执行 dsh plugin add  之前运行 dsh-guard snapshot，或者用它包装你自己的 dsh 包装器。这覆盖了不经过进程内 tools.guard 钩子的安装。

一键手动回滚（Windows）： 该包还附带 scripts/rollback.cmd。安装后，它位于 $DSH_HOME/profiles//node_modules/dsh-plugin-guard/scripts/rollback.cmd —— 右键 → 创建快捷方式（或将文件复制到任意位置）并双击它，即可恢复每个 profile 的上一个良好快照，并重新运行 pnpm install --frozen-lockfile。回滚还会删除 node_modules 中遗留的任何孤立的 bundle 插件符号链接（pnpm 从不删除过期的 link: 条目 —— “Already up to date” —— 因此防护机制会直接针对恢复后的 package.json 执行此操作）。即使应用无法启动，它也能正常工作，并且当环境未设置 DSH_HOME 时，它会自行推导出 DSH_HOME。

用法
设置面板 — 备份管理 (Backup Manager)。 在 Web UI 中，打开 设置 (Settings) → 备份管理：按环境划分的快照列表、加载特定备份、创建手动快照，以及设置每个环境保留多少个快照（最少 2 个）。自 v0.3.0 起，该插件还注册了一个 设置 → 插件 → 插件配置 设置卡片（rc.7 插件自有设置界面）：它通过 harness settings 服务编辑同一个保留数量（经过 schema 校验、带修订版本围栏），并且 备份管理 面板与 CLI 通过 config.json 保持同步。

Agent 工具（为配置文件中的每个会话注册）：

| 工具 | 用途 |
|---|---|
| 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]                     # 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 运行在其他端口上，请设置此项。你也可以向 CLI 传递 --port。

每个路径都以 $DSH_HOME 为锚点（当环境变量未设置时默认为 ~/.dsh）：

$DSH_HOME/rollbacks///    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 快照，因此回滚本身是可逆的。
- “Last good” = 未标记为 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/ 中的 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 ）。
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  前先 dsh-guard snapshot（或自己包一层包装），覆盖不走进程内 tools.guard 钩子的安装途径。

一键手动回退(Windows)： 包内还带 scripts/rollback.cmd。安装后位于 $DSH_HOME\profiles\\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///   快照(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