dsh-plugin-guard

August 24, 2026 · View on GitHub

DSH Desktop 插件安全防护工具 —— 给 DeepSeek Harness 桌面端的本地插件加两道保险：

启动崩溃自我修复：应用因某个插件加载失败而崩溃后，自动读取 harness.log，识别崩溃原因并分派修复，修好并验证通过后恢复挂载。
插件安全验证 + 写完插件自动提示：对插件做安全检查（8 项核心，另有 2 项可选），全部通过才给出「✅ 可以安全重启」；每次你写完/改完插件，右下角会自动弹出验证提醒，点一下即检。

面向 DSH Desktop 的"本地插件"（profiles/<profile>/node_modules/ 下的目录 + cordis.patch.yml 挂载行）。纯本地，不上传任何数据。

功能一览

能力	说明
启动崩溃自我修复	读日志尾部 → 按原因分派修复 → 完整验证 → 恢复挂载 / 安全隔离
插件安全验证	8 项核心检查 + 2 项可选（见下），全绿才「可以安全重启」
写完插件自动提示	变更检测（内容哈希），右下角胶囊提醒，点击即验证
对话内工具	`plugin_verify` / `plugin_repair` / `plugin_guard_status` 三个可调用工具

安全检查（8 项核心 + 2 项可选）

#	检查	说明
1	语法检查 host	`node --check` 校验 `lib/index.js`，ESM 按 `.mjs` 解析
2	语法检查 client	`node --check` 校验 `lib/client.js`
3	inject 一致性	静态扫描 `ctx.X` 直访（排除 `ctx.get` 等；`timeout/interval/throttle/debounce` 归并为 `timer`）↔ 插件导出的 `inject` 数组一一对应
4	defineTool DSL	用真实 `@deepseek-ai/dsh-tools` 的 `defineTool` 校验工具定义（`required: false`、空 `enum`、嵌套 object 缺 `additionalProperties` 均报错）
5	cordis 真实加载	真实 cordis `Context` + 桩服务执行 `apply`，抛错即"启动必崩"
6	patch 组合	解析 `cordis.patch.yml`，逐行校验包可解析、id 唯一
7	路由冲突	递归扫描 `@deepseek-ai` 下插件声明的 `webServer` 前缀（如 `/xmhs-cards`）是否唯一
8	宿主文件状态	`.credentials.yaml` 的 `version` 为无引号数字 1（只读检查，绝不改写）
9	深度组合校验（可选）	`dsh --dump-config` 深度校验；默认跳过（会在运行中的实例外再启动一次 profile，可能冲突）
10	业务冒烟（可选）	默认跳过，参数显式启用

三条"血泪教训"（验证清单必须覆盖）

DSH 插件启动崩溃的三种最常见原因，正是本工具自动修复的对象：

错误	现象	自动修复
inject 声明缺失	`cannot get property "webServer" without inject`	在插件 `inject` 数组补上缺失项
defineTool DSL 非法	`JsonSchemaError: ... required must be true when present`	删除 `required: false` / 空 `enum`（先屏蔽字符串与注释，避免误伤）
宿主敏感文件类型错误	`declares version "1"; this build reads version 1`	只读检查并提示人工处理，绝不改写 `.credentials.yaml`

其他未知错误 → 安全隔离（目录改名 .bak + patch 行移除，与桌面端 recovery 同策略）；修好根因后重跑 plugin_repair 自动恢复挂载。

安装

把 dsh-plugin-guard 目录放到目标 profile 的 node_modules 下：
```
<DSH_HOME>/profiles/<profile>/node_modules/dsh-plugin-guard/
```
在 <DSH_HOME>/profiles/<profile>/cordis.patch.yml 的 - insert: 列表里加一行：
```
- insert:
    - id: plugin-guard
      name: dsh-plugin-guard
```
重启 DSH Desktop。重启后右下角会出现 🛡️ 插件安全防护 状态胶囊（常驻入口）。

路径全部在运行时从 DSH 环境派生（process.execPath / DSH_HOME），无需改任何绝对路径；部署到不同机器直接可用。

更新到本机已安装插件

本机已安装旧版、想升级到仓库最新版时：

在仓库目录拉取最新代码（Git Bash）：
```
git pull
```
把仓库内容同步到已安装位置（PowerShell，Windows 示例，路径按实际情况替换）：
```
robocopy "G:\你的仓库\dsh-plugin-guard" "$env:DSH_HOME\profiles\web\node_modules\dsh-plugin-guard" /MIR /XD .git
```
/MIR 让两边完全一致（.git 不会被拷过去）；cordis.patch.yml 的挂载行无需改动。
重启 DSH Desktop，再用 plugin_verify（或右下角胶囊）做一次验证。

本插件会自我监控——更新后会提示"检测到插件变更：dsh-plugin-guard"，点击验证即可。

使用

右下角状态胶囊（client 横幅）：
- 绿点 = 正常；黄点 + 数字徽标 = 有待验证的插件变更。
- 检测到变更会自动展开："⚠️ 检测到插件变更：xxx，建议执行安全验证（点击即检查）"。
- 点击「验证插件」一键运行安全检查（8 项核心 + 2 项可选），结果摘要内联展示。
- 提示词经验配置：面板内「提示词经验」入口，用口语化表达快速录入经验/约束，自动按该做 / 不该做 / 怎样工作归类并写入记忆库（<DSH_HOME>/plugin-guard/prompt-rules.json），可逐条删除、一键总结"我们的经验总结"。
- 关闭前安全守卫：仅当存在"未验证的插件变更"时，关闭/刷新/重启前弹出安全提示确认；可开关（面板「关闭前安全检测提醒」）。
对话内工具（模型可调用）：
- plugin_verify：验证单个插件或 patch 中全部插件，全绿输出「✅ 可以安全重启」。
- plugin_repair：从日志定位崩溃 → 修复 → 验证 → 恢复挂载；支持 dryRun 与 env 覆盖（测试夹具可用）。
- plugin_guard_status：最近崩溃、待验证变更、上次验证/修复摘要。

plugin_verify / plugin_repair 均接受 env 参数以 JSON 覆盖环境路径，便于脱离本机做演练。

架构

dsh-plugin-guard/
├─ lib/
│  ├─ index.js          # 宿主半：工具 + HTTP 路由(/plugin-guard/*) + 变更检测定时器
│  ├─ client.js         # 客户端半：shell.overlay 常驻状态胶囊 + 一键验证
│  └─ guard-check.mjs   # 检查引擎（独立 Node 脚本：10 项检查 + 隔离/恢复动作）
├─ test/fixtures/       # 合成验收夹具（坏插件 ×3 + 正常插件 + 伪造日志 + 凭据副本）
├─ package.json         # type:module + dsh.client 声明
├─ LICENSE              # 自定义非商业许可（源可用）
└─ README.md

宿主半读取日志、改插件源码、写 patch —— 均为 DSH 环境内常规文件操作（运行时可直读直写）。
检查引擎以子进程方式运行，路径全部由宿主从运行时派生后经参数传入。

测试

见 test/fixtures/README.md。夹具为合成数据，用 env 参数把工具指向本地夹具目录即可复现四条验收场景（required:false、inject 缺失、正常插件、未知错误隔离）。

许可证

自定义非商业许可（源可用，source-available），非 OSI 开源。

版权人保留全部商业使用权；
任何第三方仅可将其用于非商业目的（个人、学习、研究、组织内部工具等）；
任何商业使用（收费产品/服务、SaaS、广告促销、营利性业务等）均需版权人事先书面许可；
分发衍生作品时必须保留本版权声明与协议全文。

详见 LICENSE。需要商业授权请直接联系作者。