dsh-tool-failure-circuit-breaker：DeepSeek Harness 工具失敗熔斷器

前言¶

DeepSeek Harness（DSH）的插件生態允許開發者擴展智能體的能力。在開發過程中，模型經常會對失敗的工具調用進行重試，尤其是那些依賴外部狀態（如輪詢 API）的操作。如果模型重試了參數完全相同的失敗調用，這會浪費大量的延遲、網絡請求、執行資源以及提供商成本。

與官方的 @deepseek-ai/dsh-repeat-tool-reminder 不同，該插件僅提供建議而不進行阻斷。dsh-tool-failure-circuit-breaker 旨在解決這一痛點，它通過在插件層攔截重複的失敗調用，直接阻止模型發送無意義的重試請求。

插件介紹¶

這是一個用於 DeepSeek Harness 的安全類插件，用於阻止 Agent 在工具調用失敗後，再次分發參數完全相同的請求。

名稱：dsh-tool-failure-circuit-breaker
維護者：icyaaaww
類別：admin-security
許可：MIT

安裝與啓用¶

插件通過本地路徑安裝。在安裝前，請確保插件目錄位於 Harness 項目的父目錄中。

dsh plugin --profile web add ./dsh-tool-failure-circuit-breaker

核心功能¶

該插件通過以下機制工作：

阻斷重複失敗：插件會觀察權威的 tools/result 失敗結果，並在達到配置的閾值後，拒絕下一次參數完全相同的調度。
預執行攔截：監聽 tools/pre-execute 事件，被拒絕的重試請求從未到達工具的具體執行邏輯。
結果一致性：將拒絕操作記錄爲正常的工具結果，確保模型歷史記錄和重放機制的一致性。
隔離故障鏈：故障鏈按“活動代理”隔離，以工具名稱加上規範 JSON 參數作爲鍵值。

配置說明¶

插件會在安裝時插入默認配置行。你需要根據業務邏輯調整以下參數：

- id: tool-failure-circuit-breaker
  name: dsh-tool-failure-circuit-breaker
  config:
    maxFailures: 2        # 允許連續失敗的最大次數，默認爲 2
    include: []           # 需要保護的工具名通配符模式，爲空則保護所有工具
    exclude: []           # 需要繞過熔斷機制的工具名通配符模式
    errorPreviewChars: 300 # 在拒絕消息中展示的失敗信息字符數，默認爲 300

include：用於指定哪些工具需要開啓熔斷保護。
exclude：對於某些需要保持不變參數進行輪詢的工具（例如檢查特定狀態是否就緒），應使用 exclude 來跳過熔斷檢測。
maxFailures：決定在觸發阻斷前允許多少次相同的失敗。

行爲與限制¶

狀態管理：插件狀態存儲在內存中。當進程或插件重啓時，歷史失敗記錄會重置。
並行調用：如果多個並行請求同時發出且都失敗，在達到閾值前，所有請求都可能已經發出。
匹配精度：僅檢測參數完全一致的重試，無法檢測參數相似的重試。
阻斷方式：阻斷是可選的，需通過安裝插件來啓用。請謹慎選擇 exclude 規則，避免攔截合法的重複探查。

結語¶

該插件通過在 tools/pre-execute 階段切斷無意義的重試鏈路，有效降低了智能體的運行開銷。對於需要頻繁調用外部 API 且存在重試邏輯的 Agent 場景，這是一個實用的防禦性工具。