前言¶
在 DSH 這類智能體運行時裏，工具調用失敗並不罕見。更麻煩的是，失敗原因可能並不變，只是參數換了，模型還會繼續重試。
dsh-failbook 針對這個問題做了一層記錄與攔截：把工具調用失敗寫進賬本，按失敗原因聚類，並在同一失敗簽名反覆出現時注入建議性提醒。它不替代工具執行，也不修改工具結果，只在失敗發生時提供可見的記錄和下一輪請求裏的上下文。
這是什麼¶
dsh-failbook 是一個 DeepSeek Harness（DSH）插件，用於記錄工具調用失敗、按失敗簽名聚類，並在重複失敗時進行失敗感知重試攔截。插件包含 Web UI 設置面板，MIT 許可，零配置開箱即用。
倉庫地址在 G1en-114/dsh-failbook。
核心功能¶
下面是它已確認提供的主要能力：
-
自動記錄工具調用失敗
包括結構化錯誤、非零退出碼、沙箱拒絕、常見錯誤文本。 -
失敗簽名聚類
同一失敗原因會被歸到同一個桶，不會只因參數不同而散落成多個條目。 -
跨會話持久化
通過官方ctx.storageDomain存儲，可跨會話持久化；沒有該服務時自動降級爲內存賬本。 -
失敗感知重試攔截
同一簽名在近窗口內失敗達到閾值時，注入建議性提醒。 -
Web UI 面板
設置頁提供失敗賬本面板，可查看 Top 失敗簽名、次數、近窗口、最近時間，並支持靜音、單刪和清空。 -
靜音與排除
誤報桶可以一鍵靜音，也可以通過excludeTools/patterns做更細的控制。 -
保守檢測
設計原則是寧可漏判，不要誤判，只認確鑿的失敗標記。
安裝與啓用¶
安裝命令：
dsh plugin --profile web add "github:G1en-114/dsh-failbook#main"
這條命令會把插件加入 web profile 的 DSH 配置。
如果不使用安裝命令，也可以手動編輯配置目錄中的 cordis.patch.yml，插入以下內容：
- insert:
- id: failbook
name: dsh-failbook
config:
enabled: true
重啓 dsh web 後，打開：
設置 → 失敗賬本
可以看到失敗賬本面板。
典型配置¶
插件默認啓用。已確認的默認配置包括：
enabled: true
retryGuardThreshold: 2
reminderCooldownSec: 300
reminderLocale: "zh"
exitFailureMin: 2
excludeTools:
- todo_write
maxBuckets: 1000
其中幾個關鍵項：
enabled：總開關。retryGuardThreshold：近窗口內同一簽名失敗達到該次數後觸發提醒。reminderCooldownSec：同一桶兩次提醒之間的最小冷卻時間。reminderLocale：提醒文案語言，示例中可用"en"。exitFailureMin：退出碼達到該值時才記爲失敗。excludeTools：不追蹤的工具列表。maxBuckets：賬本桶數量上限，超出後按最近使用淘汰。
如果想讓攔截更激進，可以改成：
- insert:
- id: failbook
name: dsh-failbook
config:
exitFailureMin: 1
retryGuardThreshold: 1
reminderLocale: "en"
這個示例把退出碼 1 也納入失敗判斷，並把觸發提醒的閾值降到 1 次。
運行方式與邊界¶
dsh-failbook 的提醒通過 additionalContexts 注入。它不修改工具結果，也不打斷工具執行管線，只在模型下一輪請求時提供可見的上下文。
它還有幾條比較明確的安全邊界：
- Web API 僅迴環地址可訪問。
- 賬本只保存截斷後的預覽。
- 完整命令輸出不會離開宿主。
- 沒有
ctx.storageDomain服務時，會自動降級爲進程內 / 內存賬本。降級後記錄與攔截功能不變，但重啓會清空。
開發與驗證¶
倉庫提供了本地開發與驗證命令：
npm install
npm test
npm run test:integration
npm run build
其中 npm test 用於運行測試，npm run test:integration 用於集成驗證，npm run build 用於構建。
package.json 中可見依賴包括：
"@deepseek-ai/schemastery": "^3.18.1",
"zod": "^4.4.3"
資料中 peerDependencies 不完整，本文不據此補充完整依賴列表。
適用場景與注意¶
它適合這類使用場景：
- 使用 DSH Web 配置，希望看到失敗記錄面板。
- 希望把工具失敗從臨時日誌變成可查詢的賬本。
- 希望減少模型在同類錯誤上反覆重試。
- 需要對某些工具或錯誤模式做靜音和排除。
使用前需要注意：
- 插件運行在 DSH 宿主側，並以當前
dsh進程權限運行。 - 安裝前應檢查源碼、依賴和許可證。
- 許可證爲 MIT。
- 如果你依賴跨會話持久化，需要確認當前環境是否提供
ctx.storageDomain；沒有該服務時會退化爲內存賬本。
結尾¶
dsh-failbook 的價值在於把“工具失敗”變成可追蹤、可聚合、可提醒的賬本記錄。它不改變 DSH 的執行模型，而是在失敗發生之後提供一層結構化的反饋。
相關鏈接：
- GitHub 倉庫：https://github.com/G1en-114/dsh-failbook
- 目錄頁線索：https://www.skillhub.cn/plugins/G1en-114/dsh-failbook（該 URL 來自線索，未在已抓取資料中核實）
