前言¶

在 DeepSeek Harness (DSH) 的開發過程中，自主智能體在遇到工具故障、指令歧義或幻覺時，容易陷入無限重試循環。例如，反覆讀取同一目錄、編輯相同代碼行，或在輸出流中不斷重複相同文本。這種情況會迅速消耗 token 預算和 API 信用，卻無法推進用戶目標。dsh-agent-loop-guard 是一個爲 DSH 設計的原生主機運行時插件，旨在攔截並阻斷此類失控循環，防止資源浪費。

核心功能¶

插件通過以下機制實現閉環防護：

1. 進度感知工具調用守衛
   使用基於 epoch 的狀態跟蹤，僅在未檢測到有意義的狀態變更或新證據時，才阻斷重複調用。這允許合法的迭代（如 read ➔ edit ➔ read ➔ edit）正常執行，避免誤殺有效操作。

2. 助手輸出循環阻斷器
   實時檢測流式文本中的重複行或 markdown 塊。當連續生成內容超過閾值時，會強制取消會話生成，避免輸出失控。

3. 零核心修改
   插件完全基於 Cordis 生命週期鉤子實現，無需對 DeepSeek Harness 核心代碼進行任何修改。

4. 企業隱私與 Token 遮蔽
   日誌系統會自動遮蔽敏感憑證，如 Bearer token、密碼、cookie 及查詢參數中的 secret，將它們替換爲 [redacted]，防止敏感信息泄露。

5. 原生 WebUI 設置與遙測
   提供原生 WebUI 配置入口，支持插件設置與遙測數據上報。

安裝與啓用¶

插件以當前 DSH 進程的權限運行，安裝前請確保環境滿足依賴要求。

1. 環境檢查
   確保系統已安裝 Node.js 20 或更高版本。
   確保已安裝 DeepSeek Harness 及其核心依賴。

2. 安裝方法
   由於未提供直接的安裝命令，請通過官方插件目錄進行安裝：
   訪問目錄地址：https://www.skillhub.cn/plugins/GooDAnDReaDY/dsh-agent-loop-guard
   在目錄頁面中完成插件的添加與啓用操作。

3. 依賴校驗
   安裝過程中，DSH 會自動檢查以下對等依賴是否已滿足：

   • @deepseek-ai/cordis
   • @deepseek-ai/schemastery
   • @deepseek-ai/dsh-settings

典型用法¶

插件通過停止詞和配置參數來控制循環行爲。

1. 觸發阻斷的停止詞
   在用戶消息分析階段，插件支持多種停止詞來立即觸發拒絕執行：

   • stop, halt, cancel
   • прекрати (俄語：停止)
   • ответь (俄語：回答)
   • петля (俄語：循環)

2. 默認配置參數
   插件內置了默認的循環限制策略，通常無需修改即可生效：

   • 最大重複調用次數：同一組調用中，默認限制爲 5 次。
   • 最大工具嘗試次數：單輪對話中，默認限制爲 64 次非生產性工具嘗試。

3. 配置方式
   所有設置均可通過 WebUI 進行可視化配置：
   進入 WebUI 設置頁面 -> 選擇 Plugins -> 點擊 Plugin Settings。在此處調整循環阻斷的具體閾值與行爲。

適用場景與注意¶

該插件適用於任何需要防止智能體陷入死循環的場景，特別是長任務執行或自動化腳本開發中。

1. 運行權限
   插件以當前 DSH 進程的權限運行，這意味着它擁有與 DSH 相同的系統訪問能力。在安裝和啓用前，請務必檢查插件源碼與許可證（MIT），確認其行爲符合你的安全與合規要求。

2. 配置調整
   在生產環境中，建議根據具體任務的複雜度，適當調整 maxCallsPerRepeatGroup 和 maxToolAttemptsPerTurn 參數，以平衡安全性與任務靈活性。

結語¶

dsh-agent-loop-guard 提供了一種 Fail-Closed（失敗-關閉）的運行時保護機制，幫助開發者構建更穩定、更可控的 DeepSeek Harness 智能體系統。

• 項目目錄：https://www.skillhub.cn/plugins/GooDAnDReaDY/dsh-agent-loop-guard
• 源碼倉庫：https://github.com/GooDAnDReaDY/dsh-agent-loop-guard