前言¶
DSH（DeepSeek Harness）的理念是「一切皆插件」，但在做智能體開發時，多數擴展都在給 Agent 加能力，很少有人在管運行節奏。DeepSeek V4 Flash 配合 reasoningEffort: max 跑長任務時，會出現兩種典型異常：
- 想完就停：模型輸出完整思考後直接正常結束 turn，沒有正文、沒有工具調用，任務還掛着——表現爲「不幹活」。
- 推理死循環：推理進入重複空轉，持續數分鐘不停，實測單 step 全量落盤可達 132 萬字符——表現爲「停不下來」。
常見的應對方式是人工盯守：發現空轉就手動停止，發現停擺就手動催促，對長任務來說既耗時也不穩定。dsh-run-guard 在插件層把這兩端補齊。下面介紹它的定位、工作方式、安裝配置和注意事項。
這是什麼¶
dsh-run-guard 是一個 DeepSeek Harness 插件，定位爲 Agent 運行節奏守護，由 Dis2017 維護，MIT 許可證（© 2026 Dis2017）。一句話概括：guard（剎車）攔截推理死循環，continue（油門）防止想完就停不幹活。
剎車和油門共用一套狀態感知，互不干擾：guard 中斷的 turn 以 error 結束，continue 只在 completed 時觸發，不會誤推；反過來，continue 推進的新 turn 若再次死循環，guard 會立刻攔截。
核心功能¶
guard（剎車）：攔截推理死循環¶
- 監聽
llm/stream流，做滑動窗口重複率檢測，另設硬性上限雙保險。 - 死循環在 1~2 秒內被中斷，而不是空轉數分鐘。
- 中斷後自動重試，默認每 turn 2 次（可配）；仍失敗才停止，並給出中文原因提示。
recovery（恢復）：上游瞬時失敗自動重試¶
PI_AI_ERROR 等瞬時上游失敗，即使不在 llm-retry 默認重試集合裏，也會被自動重試；錯誤碼白名單可擴展，與 guard 共用每 turn 重試上限。
continue（油門）：防止提前停擺¶
turn 正常結束後自動續跑，分兩種情況：
- 有未完成 todo：注入當前狀態引導續跑，連續無產出續跑有計數上限（
continue.maxAutoFollowups，默認 3）。 - 無 todo 但模型想完就停（最後只有推理、無正文無工具調用）：注入簡潔提示續跑，無上限。
pause_work：隨時人工暫停¶
模型可隨時調用 pause_work 工具主動暫停；一旦標記，guard 和 continue 兩路都不會再自動繼續。
擴展點與設置頁¶
插件通過四個擴展點接入宿主：llm/stream（waterfall）、session/event、systemPrompt.context、`tools.register。同時提供設置頁（設置 → Run guard），可編輯全部配置項，保存後落盤、重啓生效。
安裝與啓用¶
安裝使用 GitHub 發佈版：
dsh plugin --profile web add "github:Dis2017/dsh-run-guard#v0.1.16"
命令中的 #v0.1.16 對應倉庫的發佈 tag，升級時替換爲新 tag 即可。執行後先做驗證，再做日常使用：
- 重啓 GUI。
- 打開 設置 → 插件 → Plugin list，確認
dsh-run-guard爲 Mounted / Enabled。 - 打開 設置 → Run guard，檢查或修改配置。
經過上面的步驟，插件即進入工作狀態：死循環會在 1~2 秒內被中斷並自動重試；「想完就停」後會自動收到續跑提示。
典型用法¶
開發模式¶
調試時不必反覆打包發佈，在 ~/.dsh/profiles/web/cordis.patch.yml 以絕對路徑掛載 lib/index.js，改代碼即時生效：
# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
- id: run-guard
name: /絕對/路徑/dsh-run-guard/lib/index.js?v=1
測試與升級¶
pnpm install
pnpm test
測試共 54 個單元/集成測試。倉庫打新 tag 後，重新執行 dsh plugin --profile web add ...，或先 remove 再 add，即可完成升級。
主要配置項¶
| 配置項 | 默認值 | 說明 |
|---|---|---|
enabled |
true |
總開關 |
guard.enabled |
true |
死循環攔截開關 |
guard.windowChars |
2000 |
滑動窗口大小（字符） |
guard.substrLen |
32 |
重複檢測子串長度 |
guard.repeatRatio |
0.7 |
窗口重複率閾值 |
guard.checkEvery |
50 |
每 N 塊檢測一次（降頻） |
guard.maxBlocks |
10000 |
硬閘：單次調用推理塊數上限 |
guard.maxChars |
500000 |
硬閘：單次調用推理字符數上限 |
guard.maxGuardRetries |
2 |
中斷後每 turn 自動重試次數上限 |
guard.autoRetryErrors |
["PI_AI_ERROR"] |
額外自動重試的錯誤碼白名單 |
continue.enabled |
true |
自動繼續開關 |
continue.maxAutoFollowups |
3 |
有 todo 場景連續無產出續跑上限 |
以上配置項均可在設置頁編輯，保存後落盤、重啓生效。
適用場景與注意¶
適合用 DeepSeek V4 Flash 配 reasoningEffort: max 跑長任務、遇到過想完就停或推理死循環的 DSH 用戶；如果希望這類異常在插件層自動兜底，而不是靠人工盯守，這個插件值得試。
使用前有幾點需要注意：
- 權限與審查：插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（MIT）。
- 依賴約定：插件的
@deepseek-ai/*依賴必須放peerDependencies（由宿主提供單例）；放dependencies會在 profile 頂層產生第二份副本，運行時報Cannot read properties of undefined (reading 'prepare')。遇到該錯誤，把依賴移回peerDependencies、清理 profile 頂層副本後重啓。 - 歷史會話：已落盤過死循環推理的歷史會話（單 step 可達 132 萬字符）打開可能卡死，需清理數據或歸檔；插件只保證之後不再產生新的。
- 續跑邊界：有 todo 場景的連續無產出續跑默認上限 3 次；無 todo 的想完就停續跑無上限；模型調用過
pause_work後兩路都不續跑。
結尾¶
dsh-run-guard 用一套狀態感知同時管住剎車和油門：guard 保證 Agent 不會無限幹活，continue 保證它不會不幹活，對長任務來說是一個小而實用的兜底件。
- 社區插件目錄頁：https://www.skillhub.cn/plugins/Dis2017/dsh-run-guard （獨立站點，與 DeepSeek / 幻方無官方從屬關係）
- GitHub 倉庫：https://github.com/Dis2017/dsh-run-guard
