dsh-guardian
DeepSeek Harness（DSH）任务防护插件：把真实故障中总结的教训变成主动防护，防止任务意外中断、防止任务把系统带入自我递归或崩溃状态。永不终止任务，只做检测、引导与上报。
防护机制（对应四条教训）
1. 插件预检：防止"坏插件把宿主搞崩"
历史事故：插件用了 ctx.setInterval（timer 服务）却漏声明 inject: ["timer"] → Cordis 启动抛 cannot get property "timer" without inject → 整棵插件树崩溃、宿主宕机、会话中断。
防护：部署任何新插件前运行预检扫描器，静态分析 lib/index.js 的 ctx.<服务> 用法与 inject 声明是否一致：
node <dsh-guardian>/scripts/preflight.mjs <插件目录或 index.js>- ✅ 通过：
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 <dsh-guardian>\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