chenw2759-wq/dsh-plugin-healthcheck

dsh-plugin-healthcheck

DSH 插件健康检查 —— 装完新插件后不重启后端即可验证插件是否会导致事故。
纯静态检查 + 配置组合 + 隔离试跑 + 木马扫描，发现即修复（自动修复 / 自动回滚 / 预制提示词）。

#dsh-plugin · DeepSeek Harness (DSH) · TypeScript · turtle-ui

截图

设置面板 →「插件检测」：

插件检测面板

运行一次检测（L0 静态 + L1 配置组合 + L2 隔离试跑 + 木马扫描）：

插件检测结果

它解决什么问题

DSH 的 dsh plugin add 只负责把插件装进 profile（薄 pnpm 转发器），装完不做任何验证——
问题要等下次后端启动才暴露。常见事故：

| 事故 | 根因 | 本插件拦截方式 |
|---|---|---|
| 启动报 ERR_MODULE_NOT_FOUND（缺哈希 chunk） | files 白名单漏掉代码分割产物 | C1 files 完整性 |
| 后端启动报缺 zod / schemastery | 插件登记成 link: 依赖，绕过了 profile 的 node_modules | C2 依赖声明审计 |
| agent 报 Cannot read properties of undefined (reading 'prepare') | file: 依赖装出 harness 核心包副本 → 模块双实例 → Symbol 身份错位 | C3 高危副本检测 |
| dsh-skin CLI not found（Windows） | 命令不在注册表 PATH / execFile 只认 .exe | C5 Windows 命令 |
| 改了 link:→file: 不生效 | pnpm 不重解析 lockfile | C6 lockfile 一致性 |
| 被禁用的插件长期残留在依赖里 | 禁用是压制症状而非修复 | C7 禁用插件识别 |
| 供应链投毒 / 恶意代码 | 发布包内注入恶意逻辑 | C8 木马扫描（纯静态隔离） |
| 启动报 loader fibers failed（cannot get property "fs" without inject） | 插件未构建（lib 缺失）或 cordis 用法错误（ctx.plugin() 后同步取服务） | C9 cordis 用法检测（毫秒级） + L2 隔离试跑（重启前确认） |

实战案例（真实事故）

案例 A：未构建的插件导致后端启动崩溃

dsh-ssh-workspace（SSH 远程工作区）登记进了 profile（file: 依赖 + bundle），但它的
lib/ 从未构建 —— 源码在、构建产物缺。重启后端时报：

Error: dsh: plugin tree failed to load: loader fibers failed
Error: failed to apply loader entry ssh-workspace-fs (@deepseek-ai/dsh-ssh-workspace/fs):
cannot get property "fs" without inject

根因链：ctx.plugin(SandboxedFileSystem) 是异步的，随后立即同步取 localCtx.fs 拿不到
服务（隔离作用域的 key 对不上）→ cannot get property "fs" without inject。

L2 隔离试跑如何救场：装完插件后不重启，直接跑一遍子进程完整 boot——它在后端真正
重启之前就把这条链断掉了（报同样的错），而不是等用户重启才发现。

修复（插件侧，不涉及 harness）：
1. 改用同步 new SandboxedFileSystem(localCtx, config) 并持有实例引用，不再
ctx.plugin() 后同步取服务；
2. 直接 new 不走 cordis config 默认值填充，需显式传入
{ cwd, diffBasisMaxBytes: 10 * 1024 * 1024 }；
3. inject 补上 sandboxPolicy。

这个案例说明：C8 木马扫描 + L2 隔离试跑在 CI 化的安装流程里互为补充——
静态检查看"有什么"，隔离试跑看"装完能不能起来"。

检查能力

L0 静态检查（不加载、不启动）
| 检查器 | 内容 |
|---|---|
| C1 files 完整性 | files 白名单 vs 实际 lib 产物，缺 chunk → error |
| C2 依赖声明 | link: 带运行时依赖 / file: 带 harness peer |
| C3 高危副本 | 6 个核心包（cordis/cosmokit/dsh-tools/schemastery/dsh-credentials/dsh-home-paths）是否被装成真实目录副本 |
| C4 依赖可解析 | 逐个依赖从插件锚点试解析 |
| C5 Windows 命令 | execFile/spawn 引用的命令在注册表 PATH 是否有真 .exe |
| C6 lockfile 一致性 | specifier 与 lockfile version: 前缀是否一致 |
| C7 禁用插件 | 被 disabled 但仍登记的插件（皮肤互斥正常机制不误报） |
| C9 cordis 用法 | 静态检测三类 cordis 错误：E1 ctx.plugin() 后同步取服务、E2 直接 new 需 config 的 Service 缺 config、E3 访问的服务不在 inject 声明里 → 提前捕获 cannot get property "X" without inject 类崩溃 |

L1 配置组合
复用基座 composeEntries 组合 bundle + profile + home 补丁层，与真实启动用同一算法；
检测补丁语法错误、行 id 冲突、补丁跳失。

L2 隔离试跑（"不重启试跑"的核心）
子进程完整 boot() 全树（webserver 端口偏置为 0，与运行中后端零冲突），
基座 assertEntriesActivated 断言每个启用插件都激活，超时 90s 抓 hang。
失败 → 自动回滚（写 home patch 禁用行，HMR 热生效，无需重启）。

C8 木马扫描（纯静态、隔离）
- 隔离铁律：只 readFile，绝不 import / require / 执行插件代码。
- 7 类恶意模式：M1 下载执行、M2 凭据窃取、M3 外联回传、M4 混淆后门、M5 持久化、M6 破坏性、M7 环境劫持。
- 两级校准：强组合（下载执行 / 破坏性 / 凭据+外联）→ error；单一命中 → warn（提示人工复核）。
- 证据脱敏：密钥/令牌/私钥一律 [REDACTED]。
- 误报控制：跳过 tests/node_modules/构建产物；new Function("return …")（schemastery 惯用法）、
atob(dataUrl) 数据解码、downloadFile( 方法名、回环 IP、普通 https API 均不命中。

铁律（HARD RULE）

修复执行器严禁修改 harness 源码/安装本体，只允许修改：
1. 插件代码（~/.dsh/plugins/）
2. 配置层（~/.dsh/profiles/、~/.dsh/cordis.patch.yml）

所有写路径经 assertSafeTarget 门禁（realpath 后必须落在 home 内且不在安装根内），
界面弹确认后路由仍要求 confirmed: true。修复执行器自身不跑 LLM——需要判断力的修复
打包成预制提示词交给 agent。

安装

1. 克隆到插件目录
mkdir -p ~/.dsh/plugins
cd ~/.dsh/plugins
git clone https://github.com/chenw2759-wq/dsh-plugin-healthcheck.git

2. 装进 web profile
npx @deepseek-ai/dsh plugin --profile web add "file:$HOME/.dsh/plugins/dsh-plugin-healthcheck"

3. 重启后端，打开左下角设置 → 「插件检测」

Windows 下 file: 路径用正斜杠绝对路径，如
file:C:/Users//.dsh/plugins/dsh-plugin-healthcheck。

使用

1. 打开 Web GUI 左下角设置，导航里点「插件检测」；
2. 选作用域（全部插件 / 指定插件）与层级（L0/L1/L2/木马扫描）；
3. 点「开始检测」；
4. 结果按 severity 徽标列出，每条含证据 + 修复动作：
- 一键修复（确定性，弹确认）
- 自动回滚（L2 失败写 disabled 行，弹确认，HMR 热生效）
- 复制提示词（复杂问题交给 agent）

也可直接调 HTTP 路由：/healthcheck/inventory、/healthcheck/run、/healthcheck/status、
/healthcheck/repair、/healthcheck/rollback、/healthcheck/history。

开发

pnpm install          # devDeps（SDK 类型 + 构建工具）
pnpm run typecheck    # host/client 双 program
pnpm run build        # lib/index.js + lib/runner.js + lib/client.js
pnpm test             # vitest（fixtures 复刻历史事故）

需要环境变量 RUN_HEALTHCHECK_E2E=1 才会跑真实 profile 的 e2e（smoke boot / live 路由）。

测试

| 文件 | 覆盖 |
|---|---|
| tests/checkers.spec.ts | L0 检查器对 fixture 的断言（missing-chunk 复刻 dsh-pet、link-dep 复刻 zod 事故、peer-copy 复刻双实例事故） |
| tests/repair.spec.ts | 铁律门禁（harness 路径必须拒绝）+ files 修复 + 回滚/撤销幂等 |
| tests/malware.spec.ts | 恶意 fixture 拦截、零执行证明、干净插件不误报、密钥脱敏、禁用识别、patch 解析 |
| tests/cordis.spec.ts | C9 cordis 用法检测：E1 异步 plugin 后同步取服务、E2 new Service 缺 config、E3 inject 缺服务（复刻 dsh-ssh-workspace 事故） |
| tests/smoke.e2e.spec.ts | 真实 profile 子进程完整 boot（L2） |
| tests/live.e2e.spec.ts | 真实 profile HTTP 路由全链路（inventory/run/status/history） |

目录结构

src/
├── index.ts              # host 入口：/healthcheck 路由 + systemPrompt 通告
├── core/types.ts         # 共享类型（Envelope / Finding / 严重度）
├── host/
│   ├── env.ts            # home/profile/插件清单/禁用行解析
│   ├── checkers.ts       # L0 检查器（C1~C7）
│   ├── malware.ts        # C8 木马扫描（纯静态隔离）
│   ├── cordis.ts         # C9 cordis 用法检测（E1~E3，纯静态）
│   ├── verify.ts         # L1 配置组合 + L2 子进程试跑调度
│   ├── runner.ts         # L2 子进程入口（lib/runner.js）
│   ├── repair.ts         # 修复执行器 + 回滚（含铁律门禁）
│   ├── service.ts        # 检测编排（分层 + 历史）
│   └── routes.ts         # HTTP 路由
└── client/
├── index.ts          # settings.section 插槽注册
├── HealthcheckSection.tsx  # 检测面板
├── api.ts            # 浏览器客户端
└── locales.ts        # 中英文案

许可证

MIT