dsh-plugin-guard

一句话定位

为 DeepSeek Harness（DSH）打造的"插件安装安全网"：安装前自动留底、坏插件自动隔离，并生成事故报告让 AI 自动接手分析。它不评判插件好坏，只保证"任何变更都可逆 + 启动失败自动回退 + 事故不会被悄悄吃掉"。

核心能力

• 安装前自动快照：DSH 内部任何安装/卸载/启用切换插件的工具运行前，都会对所有 profile 自动留一份配置快照（不会阻塞调用）
• 一键或自动回退：把 profile 的 4 个配置文件还原到任意一份快照，并重跑 pnpm install --frozen-lockfile 复原 node_modules
• 守护启动：boot-guard 脚本在启动 dsh web 前做快照、启动后做 HTTP 健康检查；失败时自动 kill 进程、回退、重试一次
• 黑屏/客户端崩溃检测：v0.3.1+ 起会确认 web 客户端真正渲染成功，区分"HTTP 200 但页面黑屏报错"和真正可用
• 自动隔离不兼容插件：v0.3.2+ 当回退和重试都失败时，从启动日志诊断出问题插件并写入 disabled: true 让应用至少能起来
• 事故报告自动触发 Agent 分析：任何启动失败都会写一份"事故定位报告"，并在下一次会话的提示词里强制让 AI 先去读它

技术实现

• 语言: JavaScript (ESM，Node 18+) + PowerShell（Windows 守护脚本）+ bash（macOS/Linux 守护脚本）
• 关键依赖: js-yaml（解析 cordis.patch.yml）+ @deepseek-ai/schemastery（声明 settings.namespace 的 schema）+ Node 自带 node:fs/node:http/node:child_process；客户端侧通过 ModuleLoader.load 注入 React 组件
• 架构模式: 标准 Cordis bundle 插件 + 进程外脚本（CLI + 守护）。Node 端通过 tools.guard 钩子 + systemPrompt.section 注入 + webServer.register 注册 HTTP API + settings.register('guard', schema) 注册插件自有设置卡；客户端 lib/client.js 通过 slots.inject 注册 settings.section / shell.overlay / settings.plugin.item 三个槽位
• 入口文件: src/index.js（node 端 export apply）+ lib/client.js（浏览器端 export inject）+ scripts/guard-cli.js（独立 CLI dsh-guard）+ scripts/boot-guard.{sh,ps1}（守护启动脚本）

适用场景

每天都要折腾插件、频繁安装/卸载新功能、DSH 自带 dsh plugin add 经常"装上后应用就崩"的用户。装了它之后，即便踩到一个坏插件，下次启动也会自动还原成正常状态——你不用再为插件实验支付"应用起不来"的代价。事故报告还会让 AI Agent 自动接手诊断，省掉手动翻日志的功夫。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard

安装到 web profile 后需要重启 dsh web 让 bundle 插件生效，并建议改用 boot-guard 脚本启动以启用启动级回退保护。

配置项

所有配置项都在 $DSH_HOME/guard/config.json，首次写入时自动创建。普通用户无需手动编辑。

常见问题

Q: 安装后是否需要做额外配置？

A: 不需要。所有配置项都有合理默认值，配置文件在首次写入时自动生成。建议在 DSH 设置 → 备份管理页面里检查下保留快照数量是否合心意。

Q: 插件安装失败或被隔离了，怎么恢复？

A: 隔离意味着插件与当前 DSH 版本不兼容、回退无法解决。两种恢复方式：①升级该插件到兼容版本；②确认不需要它（保持禁用状态）。需要取消隔离时执行 dsh-guard quarantine --undo <插件id>，会从 cordis.patch.yml 里移除 disabled: true 行。

Q: 数据会不会被回滚弄丢？

A: 只回滚 5 个配置文件 + 通过 pnpm install --frozen-lockfile 复原依赖，不 触及 ~/.dsh 下的会话日志、凭据、用户数据。回退前会自动先存一份 pre-rollback 快照，所以回退本身也可一键还原。

Q: 怎么卸载？

A: 从 cordis.patch.yml 删除 guard 这一行，重启 dsh web。如需彻底清理数据，删除 $DSH_HOME/guard/ 与 $DSH_HOME/rollbacks/ 目录即可。

Q: 我改了 dsh web 的端口（不是默认 3080）怎么办？

A: 编辑 $DSH_HOME/guard/config.json 把 port 字段改成实际端口；或临时用 dsh-guard health --port <N> / dsh-guard incident --port <N> 覆盖。

Q: 为什么 bundle 插件的修改要重启 dsh web？

A: 因为 DSH 在 web 进程启动时一次性加载 bundle 插件到 profile 层栈，运行期改 cordis.patch.yml 不影响已加载的实例——这是 DSH 本身的加载机制限制。

Q: 它会在 DSH 进程里执行第三方代码吗？

A: 快照只是纯文件复制（5 个配置文件 + manifest），不运行任何代码、不评估任何行为。启动级检测由 boot-guard 脚本启动 dsh web 完成（DSH 会连同所有已装插件一起加载），这是检测"插件是否搞坏启动"必须的一步。运行期间插件从不执行额外代码、从不修改配置。

上手难度

入门 — 普通用户安装后零配置即可享受"安装前自动快照 + 启动失败自动回退"的核心保护；高级用法（CLI、quarantine、定制 boot-guard 启动器）属于可选项，遇到事故时再学即可。

已知问题与限制

• 事故自动分析仅覆盖启动失败类事故；对话中途报错需要主动调用 dsh_rollback action=incident（或 dsh-guard incident）手动生成报告
• bundle 插件的加载变化需要重启 dsh web 才生效（DSH 自身机制，非本插件限制）
• 会话日志损坏属于数据问题，不在回退范围——回退只覆盖 5 个配置文件与 node_modules
• 健康检查只看 HTTP /（200-499 即视为健康），不看具体业务接口；客户端渲染崩溃自 v0.3.1 起才被检测（需要 dsh-client-runtime 配合上报心跳）
• 自动隔离（quarantine）只对 cordis.patch.yml 里的可禁用插件生效，普通 npm 依赖类插件无法被自动隔离
• DSH 根目录（node_modules/.pnpm）的版本更新无法通过 profile 回退撤销；事故报告会检测并明确标注这种情形

Install safety net for DeepSeek Harness: pre-install snapshots, one-click / automatic rollback, guarded boot, and incident reports that auto-trigger agent analysis.

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

---

English

What it does

A bad plugin install can leave the app unable to boot, and fixing it by hand usually means digging through config files. This plugin automates the whole chain:

Install a plugin (any method)
   │  tools.guard hook: automatic snapshot BEFORE the install (in-process)
   ▼
Guarded boot (boot-guard script)
   │  snapshot before boot → start dsh web → health check
   ├─ healthy ─────────────────────────────► passes through untouched
   └─ unhealthy ─► auto-rollback to last good snapshot → retry once
                   → write an incident report + set a pending marker
                   → the next session's prompt tells the agent to analyze it
                   → after fixing, call `incident_resolved` to clear the marker

How it detects problems (important to understand)

The guard does not statically inspect plugin code, and it does not try to "test" a plugin in isolation. Detection works at three levels:

1. Snapshots are pure file copies. Taking a snapshot just copies 5 config files (package.json, pnpm-lock.yaml, pnpm-workspace.yaml, cordis.yml, cordis.patch.yml). No plugin is run, no behavior is evaluated.

2. Boot-level detection does run the harness — with your plugin loaded. The boot-guard script starts the whole dsh web process (which loads every installed plugin, including the one you just added) and then health-checks HTTP / within a timeout. If a plugin breaks boot — load error, startup crash, unresponsive server — the check fails, and the guard automatically kills the tree, rolls back to the last good snapshot, and retries once. So yes: to catch a boot-breaking plugin, the harness (and therefore that plugin) has to actually start. That is the one moment where "running the plugin" is part of detection. Since v0.3.1 the check also confirms the web client actually rendered (a plugin crash that black-screens the page with an error leaves HTTP 200 up — the guard's client reports render crashes, and the boot-guard rolls back instead of calling a black screen "healthy"); incident reports additionally record the dsh version per snapshot and flag when a boot failure follows a harness update that a profile rollback cannot undo. Since v0.3.2, when rollback and the retry both fail (a DSH update made a plugin incompatible), the boot-guard diagnoses the offending plugin from the boot logs, quarantines it (appends disabled: true to cordis.patch.yml), boots without it, and clearly reports which plugin was pulled out and how to restore it (dsh-guard quarantine --undo <id>).

3. Runtime-only problems are not detected at install time. If a plugin installs and boots fine but only misbehaves later (crashes under a specific operation, corrupts state, etc.), no generic guard can predict that without running your real workload. When such an incident happens, dsh_rollback action=incident builds a problem-localization report (last boot logs, server stderr, and a diff of the profile config against the last good snapshot) and sets a pending marker so the next session automatically focuses on diagnosing it. And because a snapshot is always taken before any mutation, you can always roll back manually afterwards.

In short: the guard never judges whether a plugin is "good". It guarantees that (a) every mutation is reversible, (b) boot failures roll back automatically, and (c) incidents get analyzed instead of silently breaking your setup.

Install

# 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

Restart dsh web. This is a standard bundle plugin: it joins the profile layer stack and takes effect automatically. (Once published to npm, dsh plugin --profile web add dsh-plugin-guard also works.)

Enable guarded boot (strongly recommended): launch through scripts/boot-guard.ps1 (Windows) or scripts/boot-guard.sh (macOS/Linux) instead of running dsh web directly. Example on Windows, inside your launcher:

@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

Optional CLI shim (covers manual terminal installs): the package ships a dsh-guard bin (scripts/guard-cli.js). Put it on your PATH and run dsh-guard snapshot before dsh plugin add <pkg> from a terminal, or wrap your own dsh wrapper with it. This covers installs that do not go through the in-process tools.guard hook.

One-click manual rollback (Windows): the package also ships scripts/rollback.cmd. After install it lives at $DSH_HOME/profiles/<profile>/node_modules/dsh-plugin-guard/scripts/rollback.cmd — right-click → Create shortcut (or copy the file anywhere) and double-click it to restore the last good snapshot of every profile and re-run pnpm install --frozen-lockfile. Rollback also deletes any orphaned bundle-plugin symlinks left in node_modules (pnpm never removes a stale link: entry — "Already up to date" — so the guard does it directly against the restored package.json). It works even when the app cannot start, and it self-derives DSH_HOME when the environment does not set it.

Usage

Settings panel — 备份管理 (Backup Manager). In the web UI, open 设置 (Settings) → 备份管理: per-environment snapshot lists, load a specific backup, create a manual snapshot, and set how many snapshots each environment keeps (minimum 2). Since v0.3.0 the plugin also registers a 设置 → 插件 → 插件配置 settings card (rc.7 plugin-owned settings surface): it edits the same keep-count through the harness settings service (schema-validated, revision-fenced), and the 备份管理 panel plus the CLI stay in sync via config.json.

Agent tools (registered for every session in the profile):

CLI (dsh-guard, usable even when the app will not start):

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

Configuration

$DSH_HOME/guard/config.json (auto-created on first write; all optional):

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

• keepSnapshots — how many snapshots each profile retains (clamped to 2–100, default 10). Pruning removes older ones.
• port — web port used by health checks / incident reports (default 3080). Set it if your dsh web runs on another port. You can also pass --port to the CLI.

Every path is anchored at $DSH_HOME (defaults to ~/.dsh when the env var is unset):

$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)

Rollback semantics

• Rollback = restore the 4 config files + pnpm install --frozen-lockfile to reproduce node_modules exactly.
• pnpm resolution order: absolute path recorded in the snapshot manifest (same environment as when installed, independent of the current PATH) → DSH_GUARD_PNPM env var → current PATH → harness-local node_modules/.bin.
• Every rollback first writes a pre-rollback snapshot, so rollback itself is reversible.
• "Last good" = the newest snapshot not tagged pre-boot/pre-rollback.

Platform support

Security notes

• The plugin only reads/writes profile config files and snapshots; it never executes third-party code. pnpm install --frozen-lockfile restores only the locked dependencies recorded in the snapshot.
• Snapshots and incident reports are local files without credentials (credentials live elsewhere under $DSH_HOME, not in this directory layout).
• Automatic rollback happens only when the boot health check fails; the guard never silently changes config during normal runtime.

Known limitations

• Incident auto-analysis covers boot-failure class incidents; for mid-session errors, run dsh_rollback action=incident manually to produce the same report.
• Bundle-plugin changes require a web restart to take effect.
• Corrupted session logs are a data problem and are out of scope for rollback.

Development

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

Publish

The package is MIT-licensed and ready to publish to npm (name: dsh-plugin-guard). It ships zero runtime dependencies and runs its engine smoke test automatically before every publish (prepublishOnly), so a broken build can never be published. To publish:

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

repository / homepage are optional — add them once you have a GitHub repo (the fields only improve the npm listing).

Users can install it from the live repo with dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard (or the tarball in dist/); once it reaches npm, dsh plugin --profile web add dsh-plugin-guard also works.

License

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 内每个会话都会注册)：

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 标签快照。

平台支持

安全说明

• 本插件只读写 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