DeepSeek Harness (DSH) 插件生態強調一切皆插件。但在實際使用中，agent 往往會陷入某種形式的死循環，例如模型反覆輸出固定的文本片段，導致任務在後臺無限空轉卻無實質性進展。本文介紹 dsh-loop-guard，用於檢測並阻斷這類單條消息內部的重複退化。
問題背景¶
DeepSeek 的 deepseek-v4.1-flash 模型在 “thinking” 模式下存在一個特定的故障場景：模型可能反覆吐出極少量的固定文本（如 “好。寫。執行。”），且不產生任何工具調用。這通常由以下因素疊加導致：
- thinking 模式開啓：思維鏈體量最大，重複軌跡最長。
- tools 場景下的全量回傳：當請求帶 tools 時，歷史所有輪次的
reasoning_content必須完整傳回，導致重複軌跡被不斷強化。 - KV Cache 壓縮：該模型的核心賣點，它把低熵的重複內容壓縮得幾乎無損，卻抹掉了能打破循環的邊緣信號。
- 上下文壓縮失效：循環中單條消息 token 極少，上下文不增長，導致針對總量觸發的壓縮機制全程旁觀。
任何基於”比較前後兩條消息是否相同”的傳統守衛都夠不着它。循環本質上發生在單條 assistant 消息內部。
核心功能¶
該插件通過”窗口重複密度”作爲主判據，覆蓋兩種常見的循環形態：
- 單行刷屏：單行文本重複次數極高（如
</parameter>重複 1729 次）。 - 多標記交替滾動：不同標記（輸出、生成、工具調用、好。）交替出現，單行重複佔比低，但整體密度高。
插件會在檢測到退化時向下一步注入破環提醒，阻止 agent 循環。
安裝與啓用¶
安裝前需確保環境滿足 Node >= 20。
1. 通過命令安裝插件¶
使用 DSH 插件命令將包加入 profile 依賴：
dsh plugin --profile <你的 profile> add github:GRUST303/dsh-loop-guard
2. 配置 Bundle（關鍵步驟）¶
執行上述命令只是將包寫入 dependencies。DSH 依賴 dsh.profile.bundles 字段決定加載哪些插件。必須在 profile 的 package.json 中顯式聲明：
{
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-loop-guard" // 必須在此列出
]
}
}
}
3. 重啓 Profile¶
Bundle 層在啓動時被讀取併合成 cordis.yml，必須完整重啓 profile 才能生效，HMR 不夠。
配置¶
配置通過 profile 插件行的 config 段提供。以下是典型的配置示例：
- id: loop-guard
name: dsh-loop-guard
config:
preset: balanced
repeatDensity: 0.35 # 主判據：窗口重複密度閾值
window: 12 # 滑動窗口行數
lineRepeatThreshold: 6 # 單行重複次數閾值（需同時滿足佔比 ≥ 50%）
contextLineRepeatThreshold: 20 # 歷史污染閾值
minChars: 120 # 短於此長度的消息不參與判定
crossStepThreshold: 3 # 跨步重複次數
debug: false # 寫入調試日誌
配置修改後，必須重啓 profile 生效。
檔位說明¶
插件提供三個檔位供選擇：
- conservative（保守）：密度閾值
0.5。適合大量輸出表格或代碼的場景，誤報率最低。 - balanced（平衡）：密度閾值
0.35（默認）。實測誤報率極低，覆蓋已觀察到的所有循環形態。 - aggressive（激進）：密度閾值
0.25。最早介入，輕微重複也會提醒，適合無人值守的長任務。
注意事項¶
- 不重寫 LLM 請求參數：插件不會修改
temperature、presence_penalty等參數，因爲 DeepSeek 的 thinking 模式下這些參數不支持或無效。 - 不阻斷、不重置：插件只注入提醒，不 veto、不 block 或重置會話。上游若拒絕該步，原樣透傳。
- 設置頁渲染問題：插件聲明瞭設置頁槽位
settings.plugins.tab，但在 DSH 0.1.7-rc.2 版本上未渲染出來。請直接通過config段配置，核心功能不受影響。 - 依賴要求：需要 Node.js >= 20。依賴
@deepseek-ai/schemastery用於配置校驗，若缺失設置頁不可用，但核心防循環功能仍正常工作。
總結¶
dsh-loop-guard 針對的是 DSH 生態中一種隱蔽且難以察覺的故障模式。通過在單條消息內部進行滑動窗口的密度檢測，它能有效識別並阻斷模型在 thinking 模式下因 KV Cache 壓縮導致的無限重複空轉，保障 agent 的穩定運行。
項目地址：https://github.com/GRUST303/dsh-loop-guard
