前言¶
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 檢索。
