前言¶

在 DeepSeek Harness (DSH) 的開發實踐中，智能體很容易陷入邏輯死循環。例如，一個智能體調用 search 查詢天氣，讀取結果，決定再次調用 search 查詢天氣。單個調用沒有錯誤，直到達到預算或預算限制或人工干預。dsh-loop-brake 插件通過檢測並阻止第三次連續調用，解決了這個問題。

插件介紹¶

dsh-loop-brake 是 DeepSeek Harness 的一個函數插件，它是一個針對相同工具調用的電路斷路器。

• 維護者：jwilson411
• 類別：工作流
• 許可證：MIT
• 核心價值：防止智能體無限重複執行相同的工具調用，無需進行模型推理或額外的運行時依賴。

安裝與配置¶

安裝插件需要使用官方的 DSH CLI 命令。該命令會從包清單中讀取 dsh.bundle.patch 並將其追加到配置文件的有序插件列表中。

dsh plugin --profile default add github:jwilson411/dsh-loop-brake

安裝後，插件會應用默認配置。默認行爲是允許連續執行 3 次相同的工具調用，第 4 次將被拒絕。可以在插件配置中調整此閾值。

配置示例：

- id: loop-brake
  config:
    maxRepeats: 5

注意：
* maxRepeats 必須是至少爲 1 的整數。
* 如果值爲 1，將立即拒絕所有重複調用（包括同一次調用中的第一次），主要用於調試。
* 配置項缺失時，插件會讀取環境變量 DSH_LOOP_BRAKE_MAX_REPEATS，但插件配置優先級高於環境變量。

工作原理¶

該插件使用 SHA256 哈希算法進行精確匹配。兩個調用被視爲相同，當且僅當以下哈希值相同：

sha256(toolName + "\n" + canonicalJson(args))

這裏的 canonicalJson 僅對對象鍵進行排序，不進行其他標準化處理。這意味着 {"a":1,"b":2} 和 {"b":2,"a":1} 被視爲一次調用。

匹配規則：
* 捕獲：智能體逐字節重複相同的調用（例如 search {q: "weather"}）。
* 不捕獲：參數中包含時間戳、nonce、頁游標或重試計數器的調用。這些調用雖然邏輯上相似，但哈希不同，插件不干預。
* 不捕獲：在兩個調用之間交替（例如 A, B, A, B）。插件只跟蹤連續的重複次數，而不是總次數。

會話隔離：
計數是按會話進行的。一個會話內的重複計數不會影響其他會話。如果計數器中斷（例如調用了不同的工具），計數會重置。

錯誤處理¶

當插件觸發斷路器時，會拋出 LoopBrakeError 錯誤。工具主體代碼不會執行。錯誤對象包含以下屬性，用於在日誌中快速定位問題：

• code: 'LOOP_BRAKE'
• toolName: 觸發錯誤的工具名稱
• count: 當前重複次數（包含本次被拒絕的調用）
• maxRepeats: 配置的最大重複次數
• hashPrefix: 調用哈希的前 12 個十六進制字符（用於在日誌中識別調用，無需記錄完整參數）
• sessionId: 觸發錯誤的會話 ID
• plugin: 插件名稱 'dsh-loop-brake'

由於安全原因，錯誤的詳細信息中不包含具體的參數內容。

直接使用庫¶

除了作爲插件使用外，該庫也提供了獨立的 API，供希望在調用點直接控制斷路邏輯的主機使用。

import { LoopBrake, decorateTool, wrapExecute } from 'dsh-loop-brake/loop-brake'

const brake = new LoopBrake({ maxRepeats: 3 })

// 包裝單個執行函數
const guarded = wrapExecute(execute, brake, { tool: 'search', sessionId: 's1' })

// 或複製整個工具定義並包裹其執行邏輯
const braked = decorateTool(definition, brake)

注意事項與適用場景¶

• 適用場景：智能體因爲邏輯缺陷或上下文不足而反覆調用同一個工具且參數完全一致。
• 不適用場景：智能體在循環中修改參數（如增加頁碼），或在不同工具間輪詢。
• 依賴要求：無運行時依賴，僅依賴 Node.js 內置的 node:crypto。
• 版本要求：需要與 @deepseek-ai/dsh-tools 版本 0.1.1-rc.2 兼容。
• 補丁機制：如果通過 id-targeted 補丁配置此插件，必須替換整個 config 對象，而不是合併。

結語¶

dsh-loop-brake 提供了一種低成本、無模型調用開銷的方式來防止智能體陷入重複調用的死循環。它通過嚴格的哈希匹配機制，確保了斷路行爲的確定性，便於調試和排查。

• 目錄頁: https://www.skillhub.cn/plugins/jwilson411/dsh-loop-brake
• GitHub 倉庫: https://github.com/jwilson411/dsh-loop-brake