前言¶

在 DeepSeek Harness（DSH）里装插件，常见风险不是「装不上」，而是装完之后 dsh web 起不来：配置被改乱、node_modules 对不上、某个 bundle 插件在启动阶段直接崩掉。手工回退通常要翻 package.json、cordis.yml 和锁文件，再跑一遍 pnpm install，费时且容易漏步骤。

dsh-plugin-guard（维护者 lxzy-7）面向这类场景：在每次插件变更前自动快照，启动失败时自动回退，并生成事故报告供下一轮 Agent 会话分析。它在 SkillHub 社区目录的分类为 admin-security，当前 GitHub 星标 31。

这是什么¶

一句话：DSH 的插件安装安全网——安装前自动快照、一键或自动回退、守护启动、事故报告自动触发 Agent 分析。

它不静态审查插件源码，也不单独「沙箱测试」插件；而是通过文件快照 + 真实启动健康检查，保证每次变更可逆、启动失败可自动恢复、事故有据可查。

工作流程¶

下面介绍 guard 在一次插件安装后的完整链路：

安装插件（任意方式）
   │  tools.guard hook：安装前进程内自动快照
   ▼
守护启动（boot-guard 脚本）
   │  启动前快照 → 启动 dsh web → 健康检查
   ├─ 健康 ─────────────────────────────► 正常通过
   └─ 不健康 ─► 自动回退到上一个好快照 → 重试一次
               → 写入事故报告 + 设置 pending 标记
               → 下一轮会话提示 Agent 分析
               → 修复后调用 incident_resolved 清除标记

问题如何被检测到¶

理解检测边界，才能判断 guard 能防什么、防不了什么。

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

2、启动级检测会真正跑一遍 harness。 boot-guard 脚本启动完整的 dsh web 进程（加载所有已装插件，包括刚装的那个），在超时内对 HTTP / 做健康检查。若插件导致加载错误、启动崩溃或服务无响应，检查失败，guard 会杀掉进程树、自动回退到上一个好快照并重试一次。

自 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 <id>）。

3、纯运行时问题不在安装时检测。 插件能正常安装和启动，但在特定操作下才崩溃或损坏状态，guard 无法在安装阶段预测。此类情况可手动调用 dsh_rollback action=incident 生成问题定位报告（最近启动日志、服务端 stderr、配置与上一个好快照的 diff），并设置 pending 标记；因每次变更前都有快照，也可随时手动回退。

核心功能¶

安装前自动快照¶

通过 tools.guard hook，在进程内于插件安装前自动拍快照。若在终端手动执行 dsh plugin add，可配合 dsh-guard CLI 先执行 dsh-guard snapshot。

守护启动与自动回退¶

推荐通过 scripts/boot-guard.sh（macOS/Linux）或 scripts/boot-guard.ps1（Windows）启动，而非直接运行 dsh web。启动失败时自动回退并重试；仍失败则隔离问题插件。

Web UI 备份管理¶

在 设置 → 备份管理 中：按环境查看快照列表、加载指定备份、手动创建快照、设置每个环境保留的快照数量（最少 2 个）。自 v0.3.0 起，还在 设置 → 插件 → 插件配置 注册了设置卡片，通过 harness settings 服务编辑同一保留数量，与备份管理面板和 CLI 通过 config.json 保持同步。

Agent 工具¶

每个 profile 会话中注册以下工具：

CLI（dsh-guard）¶

应用无法启动时也可使用：

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

Windows 一键回退¶

包内附带 scripts/rollback.cmd，安装后位于 $DSH_HOME/profiles/<profile>/node_modules/dsh-plugin-guard/scripts/rollback.cmd。可创建快捷方式，双击即可恢复所有 profile 的上一个好快照并执行 pnpm install --frozen-lockfile。即使应用无法启动也能工作，且会在环境变量未设置时自行推导 DSH_HOME。

安装与启用¶

当前版本 0.3.2，要求 Node.js >= 18，许可证 MIT。以下为 README 中的安装命令：

# 从 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 层栈后自动生效。（发布后也可通过 dsh plugin --profile web add dsh-plugin-guard 从 npm 安装。）

启用守护启动（强烈建议）： 用 boot-guard 脚本替代直接运行 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 shim： 将包内的 dsh-guard（scripts/guard-cli.js）加入 PATH，在终端执行 dsh plugin add 前先 dsh-guard snapshot，或用它包装自己的 dsh 命令，覆盖不走 tools.guard hook 的手动安装。

配置与存储路径¶

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

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

• keepSnapshots：每个 profile 保留的快照数，范围 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               guard 设置

回退语义¶

回退 = 恢复 4 个配置文件 + pnpm install --frozen-lockfile，以精确复现 node_modules。回退还会删除 node_modules 中残留的 bundle 插件符号链接（pnpm 对失效的 link: 条目不会自动清理）。

适用场景与注意¶

适合谁： 经常尝试社区插件、在 profile 层叠多个 bundle、或需要无人值守安装回退的 DSH 用户。尤其适合把 dsh web 当作日常开发入口、不愿在配置损坏时手工排查的场景。

需要注意：

• guard 以当前 dsh 进程的权限运行，安装任何插件前都应检查源码与许可证（本插件为 MIT）。
• 它保证变更可逆和启动失败可恢复，不能替代对插件行为的业务层审查。
• 纯运行时故障需主动触发 incident 或依赖手动回退，不要假设「装完没报错就永远安全」。
• 健康检查会真正启动 harness 及所有已装插件；若环境对启动副作用敏感，应先在测试 profile 验证。

链接¶

• SkillHub 目录页：https://www.skillhub.cn/plugins/lxzy-7/dsh-plugin-guard
• GitHub 仓库：https://github.com/lxzy-7/dsh-plugin-guard

SkillHub 是面向中国用户的 Skills 社区目录，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」的理念，guard 是在这层生态里为插件安装过程加的一道安全网。