前言¶
DeepSeek Harness (DSH) 的智能體循環執行中，有時會出現單輪步數過高或陷入重複調用的問題。根據 2026-09-13 的實測日誌，單次 turn 最多可能跑出 337 步，同一條命令被重複調用 120 次甚至 85 次。
DSH 自帶的 repeat-tool-reminder 插件僅做提醒，不進行中斷；而 dsh-agent-loop 目前只暴露 maxParallelToolCalls 參數，缺乏對步數上限的控制。這導致用戶往往需要等待數小時，或在最後時刻手動輸入 /stop。
dsh-loop-breaker 插件就是爲了解決這一缺口而設計，通過硬止損機制，在檢測到重複調用時直接中斷本輪。
定位¶
這是一款硬止損插件，用於在 DSH 環境中，當同一工具配合同一參數被反覆調用時，強制中斷當前執行輪次。
- 維護者: ikta2010
- 許可證: MIT
- 核心作用: 防止 Agent 陷入死循環或無效重複
核心功能¶
插件通過兩個上游擴展點實現邏輯：
tools/post-execute(waterfall): 計數，當達到閾值時返回{kind:'block', feedback, additionalContexts}，否決當前結果並展示說明。agent/pre-step(waterfall): 返回{kind:'reject'}，阻止下一步進入，從而結束本輪。
判定鍵爲「工具名 + 參數規範化後的 JSON」。這意味着正常的差異化命令調用不會觸發誤傷。
配置項支持以下功能：
* consecutiveLimit: 控制連續重複多少次觸發硬止損。
* totalLimit: 控制單輪內累計重複多少次觸發硬止損。
* include / exclude: 過濾需要統計的工具列表。
* argumentsPreviewChars: 控制參數預覽的字符數。
安裝與啓用¶
安裝腳本位於指定路徑，執行即可：
bash /nas/dsh/工具/dsh-loop-breaker/install.sh
安裝完成後，必須重啓一次 dsh web 纔會加載該插件。重啓期間網頁會短暫斷開，但會話數據不會丟失：
dsh-restart
典型用法¶
在 DSH 的配置文件中添加以下 YAML 配置：
- id: loop-breaker
name: 'dsh-loop-breaker'
config:
consecutiveLimit: 4 # 連續重複多少次硬止損
totalLimit: 12 # 單輪內累計多少次硬止損
include: [] # 只統計這些工具（空=全部）
exclude: [] # 排除這些工具
argumentsPreviewChars: 400
適用場景與注意¶
本插件以當前 DSH 進程的權限運行。安裝前，建議檢查源碼與許可證。
- 加載機制: 插件安裝後需重啓 Web 服務才能生效。
- 判定邏輯: 依賴工具名和規範化後的 JSON 作爲判定鍵，能夠有效區分不同命令，避免誤殺正常業務邏輯。
- 生態背景: DSH 的核心理念是「一切皆插件」。社區目錄（如 SkillHub）提供插件索引，獨立於 DeepSeek 或幻方，供開發者查閱。
結語¶
dsh-loop-breaker 補齊了 repeat-tool-reminder 只提醒不中斷的短板，爲 DSH 智能體循環提供了必要的硬性約束。通過合理的 consecutiveLimit 和 totalLimit 設置，可以有效避免長時間無意義的重複執行。
