前言¶

在 DSH 裏跑長鏈路 Agent 時，常見的問題不是「模型不夠聰明」，而是行爲失控：同一句話反覆輸出、同一工具帶着相同參數來回點、工具結果在幾個固定值之間振盪，或者模型口頭說「完成」卻沒有任何可覈對的工具證據。單靠提示詞很難穩定攔住這些情況，需要在 Harness 層做監聽與干預。

下面介紹社區插件 dsh-shepherd（維護者 Boris-boomer）。它在 DSH 側組合循環守護與模式守衛，對思考流和工具調用流做實時檢測，並按嚴重程度選擇警告、阻斷單次工具調用或終止本輪生成。SkillHub 將其歸類爲工作流插件；倉庫當前版本爲 0.5.0，許可證 MIT，GitHub 星標爲 0（以目錄頁與倉庫公開信息爲準）。

這是什麼¶

dsh-shepherd 的定位是 Agent 行爲守衛：專爲 DeepSeek Harness 設計，用來減少死循環、空轉和「無證據完成」。目錄頁英文簡介爲「Orchestration and management plugin for DSH agent workflows」；package.json 中的描述進一步概括爲：7 個循環/空轉/假完成檢測器，以及 planning / coding / verify 模式守衛與原生審批熔斷。

插件依賴 DSH 生態中的 Cordis 與 Typert 協議（peerDependencies 要求 @deepseek-ai/cordis 4.x、@deepseek-ai/dsh-typert-protocol 0.2.x），並在 Web 客戶端注入懸浮審計控制台（dsh.client 配置）。

七大循環檢測器¶

插件監聽 Agent 的流式文本與工具執行事件。README 列出的七類檢測器如下，名稱與觸發條件以倉庫文檔爲準：

1. 文本重複（A）：輸出大量完全相同文本塊或字符週期。
2. 工具重複（B）：反覆調用同一工具，且分頁或重試參數構成周期時被忽略。
3. 無進展（C）：連續多次工具結果無變化，或在少數固定值之間振盪。
4. 工具超時（D）：單次工具調用超過預設閾值仍未返回。
5. 無落地（E）：多輪生成既無可見文本也無工具調用，純思考空轉。
6. 硬上限（F）：單輪步數或總耗時達到配置的安全上限。
7. 無證據完成（G）：宣稱完成或已修復，但本回合內缺少成功工具調用作爲證據，或寫操作後未驗證。

爲減少誤殺，實現上會剝離時間戳、UUID、耗時等易變字段後再計算狀態指紋，以便區分合法輪詢與真實死鎖。

三級模式守衛¶

除循環檢測外，插件支持在懸浮窗中切換工作模式，約束高風險工具：

README 舉例：編碼模式下可將 execute_command、pytest 列入黑名單，由用戶審批後再執行。

干預方式與工作流程¶

檢測命中後，仲裁層結合置信度與歷史觸發次數決定干預級別，而不是一律中斷：

• 警告：注入系統提示，不打斷生成。
• 阻斷：在工具執行前拒絕，僅攔截單次調用。
• 終止：取消本輪生成並注入強指令。

文檔中的處理鏈路可概括爲：狀態採集 → 對工具結果做指紋剝離與哈希 → 仲裁決策 → 分發上述三種干預。

同一 Agent 被強行打斷的次數可通過 maxInterruptsPerAgent 封頂，避免「打斷套娃」。

配置示例¶

閾值與模式均在 DSH 插件配置中調整。README 給出的典型結構如下：

{
  "loop": {
    "enabled": true,
    "maxInterruptsPerAgent": 3,
    "noEvidence": { "keywords": ["完成", "done"] }
  },
  "mode": {
    "enabled": true,
    "mode": "planning",
    "blacklist": ["execute_command", "pytest"]
  }
}

說明（均來自 README 參數說明）：

• loop.enabled / mode.enabled：分別開關循環守護與模式守衛。
• maxInterruptsPerAgent：同一 Agent 允許的最大強制打斷次數。
• noEvidence.keywords：配合「無證據完成」檢測器使用的完成類關鍵詞。
• noProgress.window：連續多少次無進展結果觸發報警（字段名在說明中出現，具體默認值以插件 schema 或源碼爲準）。
• mode.mode：當前模式，示例爲 planning。
• mode.blacklist：編碼模式下需人工審批的工具名列表。

啓用後，Web 端懸浮窗支持拖拽、改參，並查看最近的工具攔截記錄。

安裝與啓用¶

DeepSeek Harness 採用「一切皆插件」的擴展方式；社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係，安裝前請自行閱讀倉庫源碼與 MIT 許可證。

目錄頁提供「發送給 DeepSeek Harness 安裝」的說明，插件標識爲 Boris-boomer/dsh-shepherd。按頁面指引讓 Harness 安裝該插件即可；具體 CLI 或配置入口以你使用的 DSH 版本文檔爲準，此處不拼接未在官方資料中出現的安裝命令。

安裝後若需改前端資源，維護者在倉庫中使用 pnpm build 構建；這與終端用戶使用插件無直接關係。

典型用法¶

1. 在插件配置中開啓 loop.enabled 與 mode.enabled，按任務階段將 mode.mode 設爲 planning、coding 或 verify。
2. 長任務或易反覆讀文件的 Agent：保持循環檢測開啓，必要時調低無進展窗口或超時閾值（在配置 schema 允許範圍內）。
3. 編碼階段：在 mode.blacklist 中登記終端、測試等工具，利用審批或熔斷避免未審查的執行。
4. 驗證階段：切換到 verify，放行測試與命令類工具，同時仍保留「無證據完成」等檢測，避免未跑測試就宣告結束。

noEvidence.keywords 可按團隊用語補充中英文完成表述，與檢測器 G 配合使用。

適用場景與注意¶

適合：多步工具鏈、自動修 bug、批量讀寫的 Agent 工作流；需要在 Harness 層統一治理循環與階段權限的團隊。

注意：

• 插件以當前 DSH 進程的權限運行，模式守衛與黑名單隻能約束 Agent 可見的工具面，不能替代操作系統級隔離。
• 干預會改變模型軌跡；maxInterruptsPerAgent 等上限是爲平衡安全與可用性，過嚴可能打斷合法的長輪詢。
• peer 依賴版本需與本地 DSH / Cordis 匹配，升級 Harness 後應覈對插件是否仍兼容。

維護者本地開發可運行 pnpm test（Node 原生測試，無第三方測試框架）驗證守衛邏輯；普通用戶以發佈包爲準即可。

結尾¶

dsh-shepherd 把循環、空轉、假完成等異常收攏到一套可配置的檢測與分級干預裏，並用 planning / coding / verify 三態限制高風險工具，適合作爲 DSH 工作流裏的行爲護欄。

• 目錄頁：https://www.skillhub.cn/plugins/Boris-boomer/dsh-shepherd
• 源碼與文檔：https://github.com/Boris-boomer/dsh-shepherd