前言¶

在 DSH 場景中，一次失敗往往不是單獨一行錯誤。它可能發生在工具調用、回合結束或 Agent 運行時錯誤，並且需要結合失敗前發生了什麼、項目當時狀態、運行環境和插件組合來判斷。普通錯誤日誌往往只有“最後哪裏炸了”。

dsh-failure-capsule 是 YiHarvest 維護的 DeepSeek Harness 插件，MIT 許可。它在工具或 Agent 失敗時生成脫敏 ZIP 證據包。已針對 @deepseek-ai/dsh@0.1.0-rc.7 的原生 session/event 與 agent/error 接口驗證。

這是什麼¶

dsh-failure-capsule 是本地優先的故障證據包插件。它在失敗發生後，把相關信號整理成一個 ZIP，並寫入本機目錄。

它不修改 Harness 核心，不上傳數據，也不調用模型診斷故障。

核心功能¶

下面介紹它的默認行爲和能力：

• 在 tool/result 且 isError=true、turn/end / error、turn/end / blocked、turn/end / interrupted、agent/error 時生成故障證據包 ZIP。turn/end / aborted 默認不觸發，可配置開啓。
• 本地優先：ZIP 只寫本機，沒有網絡請求和遙測後端。
• 默認脫敏敏感字段、憑據、token、AWS access key、環境變量賦值、URL 用戶密碼、私鑰塊和本機路徑。
• 採集 Git 證據、運行時信息、Loader 插件清單和有界 Session Event timeline。
• 可用本地 source map 反解壓縮後的 JS 棧幀。
• 支持通過 cordis.patch.yml 覆蓋配置。

採集和觸發也有邊界：

• Timeline 默認最多 80 條事件。
• 每條 Git 命令默認最多 512 KiB，達到預算會終止命令並明確標註截斷。
• Git 通過參數數組直接執行，不經過 shell，不讀取未跟蹤文件內容，也不運行 hook 或 textconv。
• 相同 Session Event 在一個插件生命週期內只生成一次；agent/error 會短暫等待對應的 turn/end，避免同一失敗重複打包。
• 錯誤配置在插件加載時直接失敗，不靜默回退。
• 插件卸載時會等待已啓動的證據包寫入結束。

安裝與啓用¶

需要 Node ^22.19.0 || >=24.0.0。

Web 與 headless 是兩個獨立 profile，需要分別安裝：

dsh plugin --profile web add dsh-failure-capsule
dsh plugin --profile headless add dsh-failure-capsule

安裝後先檢查組合層配置：

dsh --profile web --dump-config

輸出中應出現：

id: failure-capsule
name: dsh-failure-capsule

如果使用本地 tarball 驗證：

dsh plugin --profile web add ./dsh-failure-capsule-0.2.1.tgz
dsh --profile web --dump-config

典型用法¶

先安裝插件，再正常使用 DSH。失敗發生後，插件默認把證據包寫入：

.dsh/failure-capsules/

可以按下面步驟查看：

1、確認失敗類型，是 tool/result 工具失敗、turn/end 回合失敗，還是 agent/error。
2、打開對應 ZIP，查看失敗前後的 Session Event timeline、Git 證據、運行時信息和 Loader 插件清單。
3、如果失敗攜帶壓縮後的 JS 棧，查看本地 source map 反解後的棧幀。
4、分享前人工檢查 ZIP 內容，尤其是自由文本、源代碼 diff 和自定義插件事件。

如果需要在某個 profile 中調整配置，可以在該 profile 的 cordis.patch.yml 中用 row id failure-capsule 覆蓋整段配置。

適用場景與注意¶

這個插件適合需要離線排查 DSH 工具失敗、回合失敗或 Agent 運行時錯誤的場景。它把證據留在本機，不上傳數據，也不調用模型診斷故障。

使用前注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
• 自動脫敏不能證明 ZIP 中絕對沒有業務祕密，分享前仍應人工檢查。
• 需要 Node ^22.19.0 || >=24.0.0。
• 已針對 @deepseek-ai/dsh@0.1.0-rc.7 的原生 session/event 與 agent/error 接口驗證；兼容性和安全性仍應以可復現測試與源碼審查爲準。
• 在 Awesome DSH Plugins Radar 等目錄中被收錄只代表可發現，不等同於兼容或安全背書。

結尾¶

dsh-failure-capsule 把失敗前的事件、項目狀態、運行時信息和插件組合放進一個本地脫敏 ZIP，適合在 DSH profile 中做離線故障覆盤。

倉庫地址：https://github.com/YiHarvest/dsh-failure-capsule