# dsh-plugin-guard

> DeepSeek Harness installation safety net: automatic snapshot before installation, automatic rollback on startup failure, incompatible plugins automatically isolated with incident reports generated, triggering Agent analysis.

## Metadata

- Author: [@lxzy-7](https://github.com/lxzy-7)
- Repo: <https://github.com/lxzy-7/dsh-plugin-guard.git>
- GitHub: [lxzy-7/dsh-plugin-guard](https://github.com/lxzy-7/dsh-plugin-guard)
- Stars: 28
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `dsh-plugin`
- Forks: 2
- Open Issues: 2
- Last push: 2026-08-18T17:37:47.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
为 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 自动接手诊断，省掉手动翻日志的功夫。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | >= 18 | package.json `engines.node` 字段；使用 `node:` 协议内置模块 |
| DSH | rc.7+（推荐） | 设置面板里"插件 → 插件配置"卡片依赖 rc.7 引入的 settings.namespace；早期版本会回退为只通过 config.json 路径工作，备份管理 HTTP API 仍可用 |
| pnpm | 任意已安装版本 | 守护脚本与回退流程会调用 pnpm install --frozen-lockfile；通过 `DSH_GUARD_PNPM` 环境变量可手动指定 pnpm 路径，否则按 PATH 探测 |
| 平台 | Windows / macOS / Linux | 跨平台；Windows 用 boot-guard.ps1 + rollback.cmd，其他系统用 boot-guard.sh + dsh-guard CLI |
| 原生模块 | 无 | 全部使用 Node 内置模块和 js-yaml 纯 JS 依赖，无需 native binding |

## 安装方式
```bash
dsh plugin --profile web add github:lxzy-7/dsh-plugin-guard
```

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

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `keepSnapshots` | 整数 | 每个 profile 保留多少份历史快照，超出的旧快照会被自动清理 | 10（最少 2，最多 100） |
| `port` | 整数 | 健康检查和事故报告使用的 web 端口（与 dsh web 实际端口一致即可） | 3080 |
| `DSH_HOME` 环境变量 | 路径 | 所有 guard 状态文件根目录；用于多用户/多实例隔离 | `~/.dsh` |
| `DSH_GUARD_PNPM` 环境变量 | 命令路径 | 强制覆盖 pnpm 启动器查找路径 | 自动探测 PATH |

> 所有配置项都在 `$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 回退撤销；事故报告会检测并明确标注这种情形

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-plugin-guard](https://deepseek-plugin.org/plugins/lxzy-7/dsh-plugin-guard)
Wiki generated by AI (model: `MiniMax-M3`)