前言¶
在 DeepSeek Harness（DSH）裏跑智能體對話時，模型有時會陷入「只出思考、不出正文或工具調用」的狀態，整條流卡住，或反覆吐出同一段文本。宿主按默認策略對同一次失敗重試多次後，一次本來幾秒內就能判定的異常，可能被放大成數十分鐘甚至數小時的會話空轉。
dsh-loop-guard 是社區維護的 DSH 工作流類插件：在流式輸出路徑上儘早掐斷這一次嘗試，並只對自己產生的失敗碼做有限次數的糾正重試，避免把同一確定性失敗重複跑滿默認重試輪次。下面介紹它的定位、規則、安裝方式與使用注意。
這是什麼¶
| 項目 | 說明 |
|---|---|
| 名稱 | dsh-loop-guard（包名與倉庫一致） |
| 維護者 | zuaonew-ops |
| 版本 | 0.5.1（資料來自倉庫 package.json） |
| 許可 | MIT |
| 形態 | DSH 插件：宿主半區 index.js、設置頁 client.js、中英界面文案 locale/*.json |
| 發佈 | 未發佈到 npm（private: true），需從 GitHub 安裝 |
| 依賴 | 無第三方依賴；可選 webServer（缺失時守衛仍工作，但沒有設置頁） |
一句話：把一次可能卡幾十分鐘到幾小時的會話，壓縮成幾秒鐘的一次乾淨中止，並止住圍繞同一次循環的反覆重試。
它針對哪些現象¶
用戶側常見表述包括「對話無限重複」「卡會話」「子會話運行時間過長」。資料中的因果鏈可概括爲：
- 模型推理循環、流卡死或輸出退化，導致本次嘗試以錯誤結束；
- 宿主默認重試策略對同一次失敗再試多輪（資料寫明默認可至 5 次）；
- 每輪嘗試本身可能耗時數分鐘到數小時，子會話時間預算被耗盡後零產出。
插件用實測會話區分四類壞形態（另有第五條絕對時間兜底）：
| 形態 | 簡要現象 |
|---|---|
| 分片洪水 | 多次重試均大量推理分片、正文分片爲 0 |
| 卡住不動 | 長時間沒有任何分片到達 |
| 慢速滲流 | 分片持續到來但長時間仍無產出（僅盯分片數或空檔的規則可能漏檢） |
| 輸出退化重複 | 思考內容中行級或片段級高度重複 |
核心功能：五條規則與觸發後行爲¶
任一規則命中即掐斷；優先級自上而下。判據與默認閾值以倉庫 README 爲準。
| # | 規則 | 默認閾值要點 |
|---|---|---|
| 1 | chunk（分片洪水） |
推理分片 ≥ reasoningChunkLimit 且產出分片 = 0，默認 20,000 片 |
| 2 | stall（卡住不動） |
距上一分片（或起始）≥ stallTimeoutMs，默認 180,000 ms（3 分鐘） |
| 3 | noOutput（慢速滲流） |
已耗時 ≥ noOutputMs 且產出 = 0，默認 600,000 ms（10 分鐘） |
| 4 | repeat（輸出退化） |
行判據 + 片段兜底，見配置項 repeat* 默認值 |
| 5 | absolute（兜底） |
單次嘗試已耗時 ≥ attemptBudgetMs，默認 1,800,000 ms（30 分鐘），不看產出 |
關鍵定義：產出分片 = text-delta + tool-call-delta；reasoning-delta 不計入產出。
觸發之後（資料中的鏈路）：
- 掐斷：停止向上遊取值，向下遊發送終結塊
{type:'finish', reason:{kind:'error', failure:{code:'LOOP_GUARD', …}}}；觸發前已到達的塊原樣透傳。 - 止住重試風暴：僅對
LOOP_GUARD接管；同一turn/step允許maxGuardedRetries次糾正重試（默認 1），之後終結；其它失敗碼走宿主默認策略。 - 降檔（可選）：最近 120 秒內觸發過循環的 agent，下一次請求將
reasoningEffort降一檔（max → high → low → off），可由配置關閉。
邊界（README 明確列出）：不修復模型本身的循環；不改寫、不丟棄、不重排上游數據塊；統計在內存、不寫會話數據；只處理本插件產生的 LOOP_GUARD；不做遙測、不髮網絡請求（設置除寫入本地設置文件外無額外落盤）。
安裝與啓用¶
前置：DSH 宿主能正常啓動，環境具備 plugin_manager 工具。
從 GitHub 安裝¶
dsh plugin add github:zuaonew-ops/dsh-loop-guard
資料註明該命令鏈路在作者環境中未實測；另一種已實測方式爲克隆倉庫後用 plugin_manager action=install_bundle 指定本地絕對路徑（任務要求禁止 git clone，生產安裝以上述 dsh plugin add 爲準）。
重啓宿主¶
裝完後必須重啓一次 DSH 宿主，否則守衛可能已生效但設置頁進不了瀏覽器 boot graph（左側導航無「循環守衛」）。
確認裝上¶
- 打開 設置 → 左側導航「循環守衛」；
- 或請求狀態端點：
curl -s http://127.0.0.1:<宿主端口>/loop-guard/state
期望 ok 爲 true，value.enabled 爲 true，value.config 含與文檔一致的配置鍵；對話一輪後 value.stats.attempts 會增大，表示監聽已掛上。更完整的安裝、升級、卸載與排障見倉庫 docs/INSTALL.md。
配置與設置頁¶
設置頁路徑：設置 → 循環守衛（約每 5 秒刷新）。可改總開關、11 個閾值（時間類在界面按秒填寫）、「重試時降低推理檔位」開關，並查看統計、按規則分佈與最近觸發記錄。
配置分三層優先級（低 → 高）：包內 cordis.patch.yml → $DSH_HOME/loop-guard-settings.json（未設 DSH_HOME 時爲 ~/.dsh/loop-guard-settings.json，僅在插件掛載時讀一次）→ 設置頁或 POST /loop-guard/config 寫盤。運行中直接改 JSON 文件不生效，需用設置頁或重啓宿主。
HTTP 端點（需 webServer）：
| 方法 | 路徑 | 用途 |
|---|---|---|
GET |
/loop-guard/state |
開關、可改配置、統計、最近觸發 |
POST |
/loop-guard/config |
改配置 |
POST |
/loop-guard/reset |
統計清零 |
資料強調 noOutput 在五條規則中最可能誤殺「長時間思考後纔出第一個產出」的正常請求；若有此類負載，應優先調大 noOutputMs。absolute 到 30 分鐘無條件切斷，屬於 deliberate 兜底。
適用場景與注意¶
適合誰：長期在 DSH 上跑多步智能體、且遇到過流卡死、推理洪水、重複退化或子會話被重試拖垮的開發者。
權限與安全：插件以當前 DSH 進程權限運行，安裝前應自行查看倉庫源碼與 MIT 許可證。社區插件目錄（如 SkillHub）與 DeepSeek / 幻方無官方從屬關係，不宜當作官方應用商店。
能力上限：上游連接徹底掛起時，iterator.return() 能否打斷掛起的 next() 取決於適配器實現；插件保證的是下游在超時時刻收到終結塊並結束自己的流。
結尾¶
dsh-loop-guard 用可配置的流式判據提前結束壞嘗試，並用 LOOP_GUARD 與有限糾正重試打斷默認多輪重試放大效應，配合可選推理降檔，把「卡死數十分鐘」收成「數秒內可判定的一次失敗」。查閱插件說明與源碼：
- 目錄頁：https://www.skillhub.cn/plugins/zuaonew-ops/dsh-loop-guard
- GitHub：https://github.com/zuaonew-ops/dsh-loop-guard
配套文檔：倉庫內 docs/INSTALL.md、docs/CONFIG.md、docs/FAQ.md。
