前言¶
在使用 DeepSeek Harness（DSH）構建智能體時，模型有時會陷入“推理退化”的狀態：它不斷產生 reasoning-delta，卻沒有任何工具調用，甚至只輸出低熵的重複短句（如 好。執行。好。）。DSH 自帶的 guard/ 家族（如 guard/timeout-policy 和 guard/repeat-tool-reminder）主要監控工具調用，無法捕捉這種“零工具、純推理”的循環。結果就是回合永遠無法 settle，界面顯示“思考中”，但任務實際卡死，只能手動中止。
是什麼¶
mrweicodes/dsh-loop-guard 是一個爲 DSH 提供的思考循環守護插件。當檢測到模型陷入這種不產出結果的退化循環時，它會自動從 llm/stream 瀑布流內部切斷當前調用，並注入糾正提示，讓任務繼續向下執行，無需人工干預。
- 維護者: MrWeiCodes
- 許可: MIT
- 核心價值: 解決“只思考不做事”的死循環，且不中斷會話流程。
核心功能¶
- 五層檢測機制: 覆蓋純推理空轉、複述上一步材料、可見輸出週期循環、可見輸出短語重排、推理內部短語重排。
- 流內切斷: 不依賴“調用結束後”的判定，直接在流內部檢測並截斷，能處理“永不結束的回合”。
- 任務不中斷: 切斷隻影響當前調用，回合以正常完成（
completed）收尾，會話存活，工具調用結果保留，可直接繼續後續任務。 - 低誤報率: 實測在 119 個有產出的調用中零誤報；在 735 個會話掃描中誤判 12 個（已被集中度護欄擋住）。
- 精確判據: 使用逐字週期和跨調用複述作爲判定依據，而非時長或簡單比率。
- 行爲剋制: 默認不自動重試，防止將退化模型再次喂入循環；注入提示僅要求“繼續完成任務”，不引導其直接收尾。
- 離線分析器: 提供
tools/analyze-session.mjs，可複用運行時檢測器對歷史會話進行回放分析。 - 可觀測: 切斷時會寫入 warn 日誌，並在軌跡視圖中顯示注入的提示。
安裝¶
本插件依賴 DSH 的 llm/stream 瀑布流特性，需 DSH 0.1.2-rc.1 及以上版本。
安裝命令：
dsh plugin --profile web add @mrweicodes/dsh-loop-guard
注意：npm 上存在同名包 dsh-loop-guard（不帶 scope），與本插件無關，請認準 @mrweicodes/dsh-loop-guard。
使用¶
插件開箱即用，無需額外配置即可攔截常見的推理退化循環。默認配置下，它會自動打斷純推理空轉和可見輸出的刷屏式重複。
如需在切斷後自動繼續執行，可在配置中啓用 resumeAfterBreak：
- id: loop-guard
config:
resumeAfterBreak: true
注意事項¶
- 自動續跑慎用：默認配置下，切斷後任務會停留在
idle狀態，等待用戶確認。開啓resumeAfterBreak後會自動進入下一個回合。由於切斷髮生在模型尚未自主行動時，無人值守的長任務建議開啓此選項，但需留意切斷後的糾正提示內容。 - DSH 版本要求：必須使用支持
llm/stream的 DSH 版本。
結語¶
對於需要長時間運行、高 reasoning effort 的 DSH 工作流，dsh-loop-guard 是解決“思考死鎖”的有效手段。它通過流內干預保證了任務的連續性，配合低誤報率和離線分析工具，能夠顯著提升智能體運行的穩定性。
- 插件目錄: https://www.skillhub.cn/plugins/MrWeiCodes/dsh-loop-guard
- GitHub 倉庫: https://github.com/MrWeiCodes/dsh-loop-guard
