前言¶

在使用 DeepSeek Harness (DSH) 構建智能體時，模型容易陷入重複調用同一工具的循環（例如不斷重試一個 404 的 API，或者重複發送相同的 read 命令）。這不僅浪費 Token，還可能觸發限流。爲了避免這種情況，需要在 DSH 端進行阻斷。

插件介紹¶

dsh-repeat-tool-breaker 是一個用於 DeepSeek Harness (DSH) 的同步插件。它通過註冊一個 ctx.tools.guard 門控，對智能體在滑動窗口內的工具調用進行語義指紋檢測。一旦檢測到重複調用或連續失敗，它會觸發警告、要求總結，並在達到閾值時阻斷調用，從而強制模型改變策略。

核心功能¶

1. 語義指紋檢測：插件不依賴完全相同的字節，而是基於語義指紋進行匹配。支持的指紋類型包括：
   • exact：完全相同的工具調用。
   • cmd：命令級指紋。
   • net：網絡級指紋（如主機名摺疊後的路徑）。
   • host：主機級指紋。
   • sink：數據流指紋。
2. 失敗追蹤軌道：除了檢測重複調用外，插件還追蹤連續失敗。如果指紋連續失敗，會在第 3 次觸發提示，第 5 次觸發阻斷。
3. HTTP 請求處理：插件會拒絕 Shell 環境下的 HTTP 請求，並重定向模型使用 web_fetch_file 工具來獲取頁面並返回路徑。
4. 門控機制：這是一個同步門控，一旦觸發，調用不會執行，模型會收到錯誤反饋。

安裝與啓用¶

安裝前請確保你的 DSH 版本符合要求。該插件支持 dsh >= 0.1.7 (Session 格式 4) 以及 dsh 0.2.0 系列版本。

如果使用 DSH 0.1.5，請安裝特定版本：

dsh plugin install dsh-repeat-tool-breaker@0.7

對於 DSH 0.1.7 及 0.2.0 (rc.1 到 0.2.1 之前)，請使用最新版本（目前爲 0.8.x 系列）：

dsh plugin install dsh-repeat-tool-breaker

典型用法¶

插件安裝後，其門控邏輯默認生效。當調用被阻斷時，模型會收到一個 isError 結果，該結果以 REPEAT_TOOL_BLOCKED 開頭，並包含對之前調用的引用及建議的替代方案。

在配置層面，可以通過 onLimit 參數控制阻斷後的行爲：
* onLimit: ask（默認）：在阻斷時詢問操作員是否允許本次調用（即給予一次性的豁免權）。
* onLimit: deny：直接拒絕，不詢問。

適用場景與注意¶

1. 版本兼容性：該插件依賴 DSH 的 Session 格式 4，且 0.1.7 版本重構了設置 API。這意味着在一個構建中無法同時爲 0.1.7 和 0.1.5 兩個世代註冊設置頁面。如果使用 0.1.5，只能獲得功能邏輯，無法使用設置卡片。
2. 官方插件協同：官方插件 @deepseek-ai/dsh-repeat-tool-reminder 可以與 dsh-repeat-tool-breaker 共存。Reminder 負責早期提示（在 3/5/8 次重複時），Breaker 負責後期的阻斷（在 12 次時）。
3. 運行權限：插件以當前 DSH 進程的權限運行。在安裝前，建議檢查其源碼與許可證（MIT）。

結語¶

dsh-repeat-tool-breaker 通過引入語義指紋和雙軌道檢測機制，爲 DSH 智能體提供了防止死循環的硬性保障。它從簡單的重複計數演變爲對失敗行爲的分析，能夠有效識別模型在特定資源上的“鑽牛角尖”行爲。

查看目錄頁
查看 GitHub 源碼