akira399/dsh-stall-guard

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