任务防护插件akira399/dsh-guardian

dsh-guardian

DeepSeek Harness（DSH）任务防护插件：把真实故障中总结的教训变成主动防护，防止任务意外中断、防止任务把系统带入自我递归或崩溃状态。永不终止任务，只做检测、引导与上报。

防护机制（对应四条教训）

1. 插件预检：防止“坏插件把宿主搞崩”
历史事故：插件用了 ctx.setInterval（timer 服务）却漏声明 inject: ["timer"] → Cordis 启动抛 cannot get property "timer" without inject → 整棵插件树崩溃、宿主宕机、会话中断。

防护：部署任何新插件前运行预检扫描器，静态分析 lib/index.js 的 ctx. 用法与 inject 声明是否一致：

node /scripts/preflight.mjs

- ✅ 通过：inject 声明完整（含 timer 类：ctx.setInterval/setTimeout/...）
- ❌ 失败：列出缺失的服务名（timer/tools/settings...）并给出修复提示
- 智能识别：ctx.get("X") / ctx.inject(["X"], cb) 的嵌套获取不需要顶层声明；sctx./wctx. 作用域上下文不会被误判

也可在代码里直接调用：import { scanSource } from "dsh-guardian/preflight"。

2. 循环检测：防止任务原地打转
同一工具调用（名称 + 参数指纹）在滑动窗口内重复 ≥ maxLoopRepeats 次 → 判定循环 → 注入换方向提示 + 记录 LOOP_DETECTED。

3. 递归防护：防止自我递归失控
子代理/工作流嵌套深度（tool-workflow/agent-start→agent-end 计数）超过 maxSubagentDepth → 注入收敛提示 + 记录 RECURSION_DETECTED。

4. 中断感知：防止任务执行中被打断
GET /api/dsh-guardian/status 返回：
- 各会话的 running / busy / 嵌套深度 / 近期调用数
- safeToRestart：只要还有会话在运行就为 false——重启宿主前先查这里，避免把正在执行的任务连同宿主一起杀掉（本会话多次中断的根因）。

安全重启助手（强制机制）：直接重启仍可能因疏忽打断任务，因此提供 scripts/safe-restart.ps1——它先查 safeToRestart，有会话在运行就拒绝重启（除非 -Force）：

powershell -NoProfile -ExecutionPolicy Bypass -File \scripts\safe-restart.ps1
强制重启（仅在确实需要时）：加 -Force

所有事件写入 $DSH_HOME/guardian/events.jsonl，状态路由可查最近 50 条。

安装

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-guardian

安装后重启 DSH。插件默认启用。

配置（settings.yaml 的 guardian 命名空间）

| 键 | 默认值 | 说明 |
| --- | --- | --- |
| enabled | true | 总开关 |
| maxLoopRepeats | 5 | 同一工具+参数重复多少次判定循环 |
| loopWindowSize | 8 | 循环检测滑动窗口（最近 N 次工具调用） |
| maxSubagentDepth | 5 | 子代理/工作流嵌套深度上限 |
| cooldownMs | 30000 | 引导消息冷却间隔（防止刷屏） |
| policy | "auto" | auto（检测到即引导）/ report（仅记录） |
| loopMessage | 内置默认 | 循环时注入的换方向提示 |
| recursionMessage | 内置默认 | 递归超深时注入的收敛提示 |

示例：

guardian:
maxLoopRepeats: 4
maxSubagentDepth: 3

修改后热生效（无需重启）。

查看状态

- 事件日志：~/.dsh/guardian/events.jsonl（GUARDIAN_ARMED / LOOP_DETECTED / LOOP_STEERED / RECURSION_DETECTED / RECURSION_STEERED）
- 实时状态：GET http://127.0.0.1:3080/api/dsh-guardian/status（配置、会话看门状态、safeToRestart、最近 50 条事件）

与 dsh-stall-guard 的分工

| 插件 | 关注点 | 动作 |
| --- | --- | --- |
| dsh-stall-guard | 静默：无事件 + 无在飞操作超时 | 诊断→修复→换方向阶梯引导 |
| dsh-guardian | 空转：有事件但在循环/递归 / 崩溃预防：插件注入预检 / 中断感知 | 循环/递归换向引导 + 预检 + safeToRestart |

两者都不终止任务，只通过注入 user/message 引导 Agent。

验证

pnpm verify

覆盖：语法、预检扫描器（真实插件通过 / 缺 timer·tools 的坏插件被拦截 / core-only 通过）、循环检测与冷却、递归深度防护、report 策略、safeToRestart 判定、事件落盘、隐私扫描。

许可

MIT © 2026 dsh-guardian contributors