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
