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