前言¶
在 DeepSeek Harness（DSH）裏跑 Agent，常見兩類失敗並不是「上下文太長」：一是同一目標反覆改腳本、跑命令，工具調用堆到十幾輪，界面只剩「一直在思考」；二是長回合裏一路調工具卻不對用戶說半句進展。裝上下文壓縮類插件往往治不了前者——上下文再短，模型仍可能在同一個坑裏換姿勢繼續試。下面介紹工作流插件 dsh-loop-guard（維護者 xfgil）：在單輪內記賬工具調用，撞牆時拒絕繼續同路試錯並逼模型轉向用戶；長任務沉默時在合適節點注入進展提醒。
這是什麼¶
dsh-loop-guard 是 DSH 上的通用工作流插件，npm 包名 @qzsecftb/dsh-loop-guard，當前版本 0.1.0，MIT 許可證。它掛在宿主通用鉤子（agent/pre-step 與 ctx.tools.guard()）上，不修改 system prompt，不跨輪記仇，也不判斷任務該不該做——只處理「原地打轉」和「太久沒對用戶出聲」兩類現象。README 中給出的實測背景包括：362 秒、16 次工具調用的改寫循環，以及 847 秒、59 次工具調用、中間零輸出的長回合。
核心功能¶
撞牆叫停¶
每次工具調用前記賬；命中任一條件則拒絕本次調用，並把一句帶「別的出路」的說明當作工具結果喂回模型（默認行爲下模型傾向於繼續試，插件刻意要求直接回複用戶：已試過什麼、卡在哪、需要用戶決定什麼）。
判據與默認閾值如下（同一目標指文件路徑或命令，不要求參數全等——改寫循環裏每版腳本內容不同，但目標未變仍會累計）：
| 條件 | 默認 |
|---|---|
| 同一目標被動次數 | 6（maxSameTarget） |
| 完全相同的調用重複 | 3（maxSameCall） |
| 連續失敗（換工具也算） | 5（maxFailures） |
| 單輪工具調用總數硬頂 | 40（maxCallsPerTurn） |
叫停後同一輪可配置不再重複提示（muteAfterTrip，默認 true）。守衛自身出錯時一律放行，避免把整個工具鏈卡死。
長任務播報¶
若本輪開始至今已過去默認 180 秒（narrateAfterMs，0 表示關閉），且尚未對用戶說過正文，則在下一步注入一句提醒。判據是本輪起點至今的時長，不是「距上次播報多久」——避免一次超長工具調用把間隔邏輯整段跳過。若 Agent 已在同步進展，則不再催。兩次提醒的最小間隔默認 240 秒（narrateEveryMs）。
觀測¶
只讀接口 GET /loop-guard 返回累計統計與當前輪賬本；文檔明確說明沒有「停用/重啓」類一鍵遙控——插件目的是減少用戶被晾着，而不是遠程開關。
安裝與啓用¶
官方安裝命令：
dsh plugin add dsh-loop-guard --profile <你的 profile>
也可手動：將倉庫放到本地目錄，在 profile 的 package.json 中增加依賴並 link，例如：
"dependencies": { "dsh-loop-guard": "link:D:/Plugins/dsh-loop-guard" }
並把 dsh-loop-guard 加入 dsh.profile.bundles。插件零依賴，不碰 QQ / 人格 / 渠道相關代碼，對所有會話一視同仁（網頁、subagent 等）。
支持的 DSH 版本：>=0.2.1-rc.2。
配置¶
全部項有默認值，不配也能用。總開關 enabled 默認爲 true。
| 鍵 | 默認 | 說明 |
|---|---|---|
enabled |
true |
總開關 |
maxSameTarget |
6 |
同一文件/命令被動幾次算撞牆 |
maxSameCall |
3 |
完全相同調用幾次算撞牆 |
maxFailures |
5 |
連續失敗幾次算路不通 |
maxCallsPerTurn |
40 |
單輪工具調用硬頂 |
muteAfterTrip |
true |
叫停後同一輪不再重複提示 |
narrateAfterMs |
180000 |
多久沒出聲就提醒（毫秒；0 = 不播報） |
narrateEveryMs |
240000 |
兩次提醒最小間隔 |
典型用法與開發自測¶
日常用法是安裝進 profile 後隨 DSH 啓動生效，無需額外命令。需要覈對行爲時，可請求 GET /loop-guard 查看賬本與統計。
維護者在倉庫內用純函數自測（不依賴真實宿主）：
node test/selftest.mjs
其中一組斷言復現了 2026-10-26 某次 turn 的調用序列，用於釘住「此類循環應在十幾步內被叫停」的判據。
適用場景與注意¶
適合：長時間自主調工具的 DSH Agent 會話，尤其是容易出現「改腳本—運行—再改」或長回合零用戶可見輸出的場景。
邊界（README 已寫明）：不跨輪累計；不替 Agent 做任務價值判斷；與 dsh-onebot-companion 等插件分屬不同狀態域——本插件只持有「本輪」指紋賬本，輪末清賬；單獨安裝應能完整工作，與其它插件配合時走可選注入，避免硬耦合讀對方配置文件。
安全與信任：插件以當前 DSH 進程權限運行，安裝前請自行審閱 GitHub 源碼 與 MIT 許可證。Node 引擎要求 >=22。
結尾¶
dsh-loop-guard 用單輪內的上限、重複動作識別和長回合沉默播報，把兩類真實出現過的「空轉」和「悶頭幹」攔在工具層之前，並推動模型向用戶交代進展或止損。社區目錄頁：skillhub.cn/plugins/xfgil/dsh-loop-guard；源碼與完整說明：github.com/xfgil/dsh-loop-guard。
