DingZhiQi5596/dsh-plugin-guard

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

1. 启动崩溃自我修复：应用因某个插件加载失败而崩溃后，自动读取 harness.log，识别崩溃原因并分派修复，修好并验证通过后恢复挂载。
2. 插件安全验证 + 写完插件自动提示：对插件做安全检查（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 自动恢复挂载。

---

安装

1. 把 dsh-plugin-guard 目录放到目标 profile 的 node_modules 下：

   <DSH_HOME>/profiles/<profile>/node_modules/dsh-plugin-guard/
   

2. 在 <DSH_HOME>/profiles/<profile>/cordis.patch.yml 的 - insert: 列表里加一行：

   - insert:
       - id: plugin-guard
         name: dsh-plugin-guard
   

3. 重启 DSH Desktop。重启后右下角会出现 🛡️ 插件安全防护 状态胶囊（常驻入口）。

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

更新到本机已安装插件

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

1. 在仓库目录拉取最新代码（Git Bash）：

   git pull
   

2. 把仓库内容同步到已安装位置（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 的挂载行无需改动。

3. 重启 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。需要商业授权请直接联系作者。