dsh-thinking-guard：純思考空轉熔斷器

前言¶

在 DSH 智能體開發中，當模型持續輸出 reasoning-delta 時，現有的 dsh-agent-loop 邏輯僅能在流結束後判定終止，而 dsh-llm-deepseek 的 idleWatchdog 只檢測連接活性，不會因爲任務進展停滯而中斷。這會導致回合無限持續，只能由用戶手動中止。dsh-thinking-guard 掛在 agent/assistant-stream 事件上，通過三重熔斷機制防止 Agent 進入“只思考、零產出”的退化狀態。

插件概覽¶

名稱：dsh-thinking-guard
維護者：ethanwong-hk
許可證：MIT
核心功能：監聽 agent/assistant-stream 事件，對純思考空轉回合實施三重熔斷（超時、容量、重複）。

安裝¶

通過 npm 安裝：

dsh plugin add @ethanwong-hk/dsh-thinking-guard

安裝後重啓 DSH。驗證是否生效：

grep -n "thinking-guard" ~/.dsh/cordis.patch.yml

核心功能¶

該插件僅使用 harness 的 agent/assistant-stream 事件和 agent.cancel/followup 接口，無其他依賴。

三重熔斷機制¶

thinkingOnlyMs（超時）
- 默認值：45000 ms
- 生效條件：僅在零 text、零 tool-call 時生效。
- 邏輯：錨定“最後一次進展”（text 或 tool-call 到達的時刻），而非 attempt 起點。
maxThinkingChars（容量）
- 默認值：80000 字符
- 邏輯：單次嘗試 reasoning 總量超限，不依賴是否有 text 產出。
degenerate-loop（退化循環）
- 默認值：3 次重複
- 邏輯：檢測尾部窗口的重複模式，包括精確重複單元、句子級模板重複、稀疏復讀或 N-gram 高密度。

命中任一條件時，觸發 agent.cancel({ kind:'thinking-guard', reason, detail })，並嘗試通過 agent.followup() 注入說明。

配置¶

在 ~/.dsh/cordis.patch.yml 的 thinking-guard 條目下調整參數，重啓 DSH 生效。

- insert:
    - id: thinking-guard
      name: "dsh-thinking-guard"
      config:
        enabled: true
        thinkingOnlyMs: 45000
        maxThinkingChars: 80000
        repeatThreshold: 3
        notify: true
        verbose: false

環境變量可臨時覆蓋參數：

環境變量	作用
`DSH_THINKING_GUARD_DISABLED=1`	停用插件
`DSH_THINKING_ONLY_MS`	純思考停滯閾值
`DSH_MAX_THINKING_CHARS`	思考容量閾值
`DSH_THINKING_REPEAT_THRESHOLD`	重複次數閾值
`DSH_THINKING_GUARD_VERBOSE=1`	開啓詳細日誌

已修復缺陷¶

插件修復了 formatNotice 函數中的 cfg 作用域引用錯誤 (ReferenceError)。
* 原因：模塊級函數引用了 apply() 內的局部 cfg 變量。
* 影響：該異常直接中斷了 trip() 函數，導致 agent.cancel 永不執行，熔斷器完全失效。
* 修復：顯式傳遞 cfg 參數，並將 agent.cancel 邏輯前置，確保熔斷動作不依賴於通知環節的成功。

測試與驗證¶

運行內置測試用例，覆蓋 11 個場景，包括純思考超時、退化復讀、容量上限、正常回合放行等。

node ~/.dsh/plugins/dsh-thinking-guard/test/guard.test.mjs

依賴與環境¶

依賴：@deepseek-ai/cordis (^4.0.1)
Node 版本：>= 18
權限：插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證。