dsh-stall-guard

DeepSeek Harness（DSH）任务看门狗插件：监控任务执行状态，判断是否真正卡死，并通过"排查→修复→换方向"的阶梯式引导帮助任务恢复——全程不终止任何任务。

核心流程（监控 → 判断 → 继续 / 修复 / 换方向）

agent/status (running/idle) ─┐
session/event (turn/step/tool/llm) ─┼─→ 追踪每个会话的"最后活动时间"与"在飞操作"
                                  │
周期扫描（checkIntervalMs）──→ 运行中且 静默 > stallThresholdMs ？
                                  │
          ├─ 有在飞操作（busy>0）或持续有事件 → 判定"推进中" → 继续执行，不干预
          │       （超 busyTimeoutMs 仅记一条 LONG_RUNNING 日志）
          │
          └─ 真静默（无事件 + 无在飞）→ 阶梯式引导（注入提示消息）：
               第1级 诊断（DIAGNOSED）  ：请 Agent 排查当前状态、说明卡住原因（附看门狗诊断现场）
               第2级 修复（FIXING）     ：请 Agent 针对卡点重试/完成/修复后继续
               第3级+ 换方向（REDIRECTING）：请 Agent 放弃当前方法、改用替代方案持续推进
               （每级按冷却间隔推进，第3级后循环；任何活动事件都会重置回第1级）
                                  │
                        事件写入 $DSH_HOME/stall-guard/events.jsonl
                        状态查询 GET /api/dsh-stall-guard/status

关键承诺：插件永不终止任务。 它只通过注入消息引导 Agent 自己排查、修复、换方向；没有 terminate 选项，也没有任何终止指令。

安装

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

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

配置（settings.yaml 的 stall-guard 命名空间）

键	默认值	说明
enabled	true	总开关
stallThresholdMs	120000	真静默阈值（毫秒）：运行中、无任何事件、且无在飞操作时，静默超过该值判定卡顿
checkIntervalMs	5000	扫描间隔（毫秒）
busyTimeoutMs	600000	在飞操作观察窗口（毫秒）：有工具调用 / LLM 请求在飞 = 任务在推进，永不引导；仅静默超过该值后记录一条 LONG_RUNNING；0 关闭该记录
stallRecordIntervalMs	60000	STALL 记录节流间隔（毫秒），防止持续卡顿时日志刷屏
policy	"auto"	auto（诊断→修复→换方向阶梯）/ report（仅记录不引导）
nudgeCooldownMs	30000	阶梯消息的冷却间隔（毫秒）
diagnoseMessage	内置默认	第 1 级：排查指令（自动附加诊断现场：最后活动、位置、静默时长）
fixMessage	内置默认	第 2 级：修复指令
redirectMessage	内置默认	第 3 级+：换方向指令

示例：

stall-guard:
  stallThresholdMs: 60000
  checkIntervalMs: 3000
  policy: auto

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

防误杀：什么才算"卡住"

任务情况	判定	行为
持续有事件（步骤/工具/LLM 流在动）	推进中	不动（计时持续刷新，任何活动都会把阶梯重置回第 1 级）
单个长操作在飞（如 10 分钟构建、长文本生成）	推进中（busy > 0）	不引导、不干预；超过 busyTimeoutMs 仅记一条 LONG_RUNNING
无任何事件 + 无在飞操作，静默超 stallThresholdMs	真卡死	阶梯式引导（诊断 → 修复 → 换方向循环）

"任务执行时间长"≠"卡住"：只要项目有推进（事件或在飞操作），看门狗就不会碰它。

查看状态

• 事件日志：~/.dsh/stall-guard/events.jsonl（每行一个 JSON 事件：STALL / LONG_RUNNING / DIAGNOSED / FIXING / REDIRECTING；永远没有终止类事件）
• 实时状态：GET http://127.0.0.1:3080/api/dsh-stall-guard/status（当前配置、各会话看门状态含 ladderStage、最近 50 条事件）

设计边界（重要）

• 检测：基于"运行中 + 无活动事件 + 无在飞操作"判定卡顿，覆盖：LLM 调用挂起、工具调用挂起、循环空转等无进展场景。turn/start/turn/end 驱动运行状态，插件从 turn 打开即开始监视（即使错过 agent/status 事件）。
• 在飞豁免：tool/call→tool/result、request/header→assistant/message、tool-workflow/run-* 维护在飞计数；有操作在飞 = 推进中，绝不引导。
• 引导方式：通过注入 user/message 事件生效（这是外部向 Agent 输入消息的合法通道）；若 Agent 卡死在一个永不返回的 await 上，注入消息会排队到该步骤结束后才被处理——此时继续等待下一级引导，永不终止。
• 诊断信息：每条阶梯消息都附带看门狗自己的诊断（最后活动事件、turn/step 位置、静默时长），帮助 Agent 快速定位卡点。
• 上报：事件落盘 + 状态路由 + 插件日志。GUI 通知可作为后续增强。

验证

pnpm verify

覆盖：语法、默认配置、活动追踪、在飞豁免（长工具不引导、在飞 LLM 永不引导）、真静默检测、诊断→修复→换方向阶梯、换方向循环不终止、活动重置阶梯、STALL 节流防刷屏、turn/start 独立触发监视、无任何终止事件、事件落盘、状态路由、隐私扫描。

许可

MIT © 2026 dsh-stall-guard contributors