前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，工具一旦反覆失敗，模型往往不會回到系統提示裏讀「失敗兩次就停」這類規則——它主要在讀自己的推理鏈。表現上常見同一命令換參數再試、推理裏出現大量短句重複，而會話仍在空轉。單靠 prompt 很難從內部打斷這種「連續失敗循環」。
dsh-fail-guard 是社區維護的工作流類插件：從外部監聽工具結果，當同一工具連續失敗達到閾值時，向對話注入一段結構化的停手說明，讓智能體轉向彙報而不是繼續第四種拼寫方式。下面介紹它的定位、安裝與配置，以及使用時需要接受的邊界。
這是什麼¶
- 名稱：dsh-fail-guard（倉庫 FenrirCait/dsh-fail-guard）
- 維護者：FenrirCait
- 分類：工作流（社區目錄 SkillHub 條目）
- 一句話：在智能體對同一工具連續失敗 N 次後停止繼續重試，改爲推送四段式停手指令（嘗試過什麼 / 完整錯誤 / 初步原因猜測 / 需要你做什麼）。
插件通過 dsh.bundle 掛載 cordis.patch.yml，在 Cordis 側攔截工具結果並計數，不依賴你在 profile 裏手寫 patch。
核心功能¶
外部打斷，而非 prompt 規則¶
README 說明：連續失敗時模型往往讀的是自己的 thinking，而不是當時的系統提示，因此「失敗兩次就停」寫進 prompt 在該狀態下通常無效；中斷必須由插件從會話外部注入。
連續失敗計數與重置¶
- 計數按會話、默認按工具分別統計（可通過配置改爲全工具共用一個計數器）。
- 任意一次該工具（或全局，取決於配置）成功會清零計數。
- 觸發停手後，計數會重新開始；再次連續失敗到閾值會再次觸發——它不是速率限制器，而是可重複觸發的 guard。
什麼算一次「失敗」¶
滿足任一條件即計入：
message.isError === truemeta.opsShell.exitCode存在且非零
兩者都要考慮：shell 退出碼爲 1 時未必帶 isError；部分工具級錯誤也沒有 exit code。
停手時注入的內容¶
達到閾值後，插件向對話推送內置或可配置的 stopText（四段式說明）和麪板上的 stopSummary（一行摘要），目的是讓智能體彙報而不是再試同一種思路。
明確不做什麼（Limits）¶
- 不會撤銷「剛剛已經失敗」的那次工具調用。
- 不判斷失敗是否「合理」——非零退出碼即算。
- 不會重置整段對話；停手指令相當於又多一條用戶側消息。
- 觸發後若繼續失敗，會重新計數並可能再次觸發。
當前 package 版本爲 0.2.0（以倉庫 package.json 爲準），許可證 MIT。
安裝與啓用¶
在 DSH 桌面 profile 下執行官方安裝命令：
dsh plugin --profile desktop add dsh-fail-guard
安裝後重啓一次 DSH。cordis.patch.yml 經 dsh.bundle 清單應用，一般無需手動改 profile 裏的 patch 列表。
插件以當前 DSH 進程權限運行；安裝前建議瀏覽倉庫源碼並確認 MIT 許可證與行爲是否符合你的環境策略。社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
配置¶
在客戶端 Plugins → dsh-fail-guard → details 中編輯。字段標記爲 .volatile()：保存後立即生效，無需重啓。
| Key | 默認值 | 含義 |
|---|---|---|
threshold |
2 |
連續失敗多少次後停手 |
sameToolOnly |
true |
按工具分別計數；設爲 false 則所有工具共用一個計數器 |
stopText |
內置 | 注入對話的停手正文 |
stopSummary |
內置 | 面板一行摘要 |
debug |
false |
是否把事件、計數、觸發寫入日誌 |
logFile |
<plugin dir>/fail-guard.log |
debug 寫入路徑 |
也可直接在 cordis.patch.yml 中寫插件 config，例如：
- id: dsh-fail-guard
config:
threshold: 3
典型用法：保持默認 threshold: 2、sameToolOnly: true，在智能體容易對 Shell 或某固定工具死磕的任務裏啓用；若希望「任意工具加起來連續失敗 N 次就停」，將 sameToolOnly 設爲 false 並按需調高 threshold。排查計數行爲時可臨時打開 debug 並查看 logFile。
適用場景與注意¶
適合：長會話、多步工具鏈、容易出現同一命令反覆改參數仍失敗的工作流；希望失敗循環由外部 guard 切斷、讓模型輸出結構化錯誤彙報的場景。
注意：
- 誤報：任何非零 exit 都算失敗，包括你可能認爲「可接受」的退出碼。
- 不會阻止失敗當次調用已完成的事實；停手發生在下一次模型決策之前（通過注入消息影響後續輪次）。
- peer 依賴包括
@deepseek-ai/cordis、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-llm等，需與當前 DSH 版本兼容（見倉庫package.json）。
README 中引用的觀測數據（例如某 74 輪會話裏短句片段佔比隨連續失敗上升）來自插件作者自測描述，用於解釋現象，並非對你環境的保證。
結尾¶
dsh-fail-guard 把「同一工具連續失敗」從 prompt 規則裏拆出來，用 Cordis 插件在外部計數並在閾值處注入四段式停手指令，減少智能體在錯誤參數上無限重試。安裝命令以 README 爲準，配置可在 UI 即時生效。
