前言¶
DSH 长任务运行时，开发者常需要判断一个任务到底是“执行时间长”，还是已经停止推进。dsh-stall-guard 是一个 DeepSeek Harness（DSH）任务看门狗插件，用来监控任务执行状态，区分真实静默与在飞操作，并对真正无进展的任务做阶梯式引导。全程不终止任务。
这是什么¶
dsh-stall-guard 是 DSH 的任务看门狗插件，仓库位于 akira399/dsh-stall-guard，许可证为 MIT。
它做三件事：
1、监控 DSH 任务执行状态。
2、判断任务是否真正卡死。
3、通过“排查→修复→换方向”的阶梯式引导帮助任务恢复。
插件默认启用，要求 Node >=20，零 npm 依赖。
核心功能¶
dsh-stall-guard 已核实的能力如下：
- 监控 DSH 任务执行状态，并追踪会话最后活动时间和在飞操作。
- 周期扫描判断“运行中、无事件、无在飞操作”的真实静默状态。
- 对在飞操作（busy>0）或持续有事件的任务豁免，不引导、不干预。
- 真静默时按诊断、修复、换方向阶梯注入引导消息，并循环推进。
- 不终止任务：没有
terminate选项，也没有终止指令或终止类事件。 - 将
STALL、LONG_RUNNING、DIAGNOSED、FIXING、REDIRECTING事件写入 JSONL。 - 提供 loopback 状态路由
GET /api/dsh-stall-guard/status。 - 支持
settings.yaml的stall-guard命名空间配置，且修改后热生效。 - 支持
policy=auto阶梯引导与policy=report仅记录不引导。 - 通过注入
user/message事件向 Agent 传递诊断、修复、换方向指令。 - 每条阶梯消息附带诊断现场：最后活动、turn/step 位置、静默时长。
可配置项包括：
enabled
stallThresholdMs
checkIntervalMs
busyTimeoutMs
stallRecordIntervalMs
policy
nudgeCooldownMs
diagnoseMessage
fixMessage
redirectMessage
安装与启用¶
安装命令使用资料中给出的完整命令：
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:akira399/dsh-stall-guard
安装后重启 DSH。插件默认启用。
典型用法¶
先确认环境满足 Node >=20，再执行上面的安装命令。
安装后可以在 settings.yaml 的 stall-guard 命名空间下配置。资料给出的示例如下：
stall-guard:
stallThresholdMs: 60000
checkIntervalMs: 3000
policy: auto
修改配置后热生效，无需重启。
查看事件日志时，资料给出的路径示例为：
~/.dsh/stall-guard/events.jsonl
资料中同时出现 $DSH_HOME/stall-guard/events.jsonl，二者是否等同未在资料中说明。
查询实时状态的示例请求为：
GET http://127.0.0.1:3080/api/dsh-stall-guard/status
资料未说明该端口是否固定。
运行验证命令如下：
pnpm verify
适用场景与注意¶
这个插件适合希望观察 DSH 任务是否真的无进展、同时不希望看门狗直接终止任务的开发者。
使用时注意以下几点：
- 有工具调用或 LLM 请求在飞时，插件视为任务在推进，不引导、不干预。
- 超过
busyTimeoutMs时，仅记录一条LONG_RUNNING。 policy=report时仅记录不引导。policy=auto时按诊断、修复、换方向阶梯引导。- 插件以当前 DSH 进程权限运行，会通过事件监控和消息注入参与任务恢复；安装前建议检查源码与许可证。
结尾¶
dsh-stall-guard 的价值在于把“任务卡住”从人工观察变成一个可记录的看门流程：真静默时引导 Agent 排查、修复或换方向，在飞操作时保持豁免，并且全程不终止任务。
GitHub 仓库：
https://github.com/akira399/dsh-stall-guard
本资料未给出独立目录页 URL；如需在 DSH 插件目录中查看，可按插件名 dsh-stall-guard 检索。
