dsh-loop-guard：結果感知循環檢測器

在 DeepSeek Harness 工作流中，智能體常陷入重複調用相同工具且持續返回相同結果的死循環，導致步數與令牌的浪費。dsh-loop-guard 插件通過結果感知機制，在連續調用運行長度達到閾值時介入，提供提示性通知或直接拒絕後續相同調用。

核心功能¶

該插件爲 DeepSeek Harness 提供結果感知的循環檢測功能，核心包含以下三點：

1. 結果感知跟蹤
   插件跟蹤具有相同工具名、排序參數和結果內容的連續工具調用的運行長度。只有完全相同的“工具名 + 參數 + 結果”纔會計入循環計數，因此合法的狀態輪詢或文件重讀不會誤觸發。

2. 軟硬階段阻斷
   * 軟階段（Advisory）：當運行長度達到 softThreshold（默認 4）時，插件會注入提示性通知，告知模型當前調用已重複，並提示在硬閾值觸發時將被拒絕。
   * 硬階段（Hard Stop）：當運行長度達到 hardThreshold（默認 8）時，插件會單調拒絕下一個相同的工具調用，並附帶修正反饋。模型需改變行動才能解除阻斷。

3. 用戶干預重置
   當 source.kind === 'user' 時，鏈條會被重置。這意味着跨用戶消息的重複調用不會被視爲循環，確保用戶手動干預後能繼續操作。

安裝與啓用¶

使用官方安裝命令將插件添加到指定配置文件：

dsh plugin --profile <name> add github:erdholion/dsh-loop-guard

也可以從本地檢出目錄安裝：

dsh plugin --profile <name> add ./dsh-loop-guard

配置¶

在 DSH 配置文件中添加插件定義，需注意無效配置會在插件加載時拋出錯誤：

- id: loop-guard
  name: dsh-loop-guard
  config:
    softThreshold: 4     # 0 禁用提示，默認 4
    hardThreshold: 8     # 0 禁用拒絕，必須大於軟閾值，默認 8
    resultHashChars: 4000 # 參與哈希的結果序列前綴長度

典型用法與場景¶

該插件特別適用於需要處理不確定返回值或狀態變更的場景：

• 合法輪詢：允許具有不同結果的輪詢（例如作業狀態檢查）。只要結果發生變化，循環計數不會增加，不會誤判爲死循環。
• 狀態恢復：允許具有不同結果的重新讀取（例如編輯後重新讀取文件）。
• 組合使用：可與官方的 @deepseek-ai/dsh-repeat-tool-reminder 一起使用。前者負責在參數相同時提供早期提醒，後者負責在結果相同時進行硬性拒絕。

注意事項¶

• 配置約束：硬閾值必須嚴格大於軟閾值，否則插件加載會報錯。
• 阻斷機制：硬階段觸發的拒絕是一個正常的錯誤結果，會返回給模型修正反饋。這對於前端將提供者 4xx 錯誤視爲致命的情況尤爲重要。
• 通知來源：插件注入的通知來源爲插件本身，不會觸發鏈條重置。

該插件通過結果感知機制，有效避免了智能體陷入無信息產出的重複調用循環，提升資源利用效率。