dsh-plugin-guard
DSH Desktop 插件安全防护工具 —— 给 DeepSeek Harness 桌面端的本地插件加两道保险：
- 启动崩溃自我修复：应用因某个插件加载失败而崩溃后，自动读取
harness.log，识别崩溃原因并分派修复，修好并验证通过后恢复挂载。 - 插件安全验证 + 写完插件自动提示：对插件做安全检查（8 项核心，另有 2 项可选），全部通过才给出「✅ 可以安全重启」；每次你写完/改完插件，右下角会自动弹出验证提醒，点一下即检。
> 面向 DSH Desktop 的"本地插件"（profiles//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下：
/profiles//node_modules/dsh-plugin-guard/
- 在
/profiles//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 的挂载行无需改动。
3. 重启 DSH Desktop，再用 plugin_verify（或右下角胶囊）做一次验证。
> 本插件会自我监控——更新后会提示"检测到插件变更：dsh-plugin-guard"，点击验证即可。
使用
- 右下角状态胶囊（client 横幅）：
- 绿点 = 正常；黄点 + 数字徽标 = 有待验证的插件变更。
- 检测到变更会自动展开："⚠️ 检测到插件变更：xxx，建议执行安全验证（点击即检查）"。
- 点击「验证插件」一键运行安全检查（8 项核心 + 2 项可选），结果摘要内联展示。
- 提示词经验配置：面板内「提示词经验」入口，用口语化表达快速录入经验/约束，自动按 该做 / 不该做 / 怎样工作 归类并写入记忆库（
/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。需要商业授权请直接联系作者。
