dsh-tool-failure-journal：異常工具調用的持久化與聚合日誌

前言¶

編碼智能體不僅會失敗，還會反覆以相同的方式失敗。在證據被摺疊、壓縮，或者僅僅是被後續的嘗試覆蓋到上下文窗口之外之前，沒人能看到這種模式。DSH 的會話日誌是模型的上下文，它會被重寫、摺疊和修剪，不適合作爲失敗歷史的存儲介質。

本插件提供了一個獨立的記錄機制，將異常退出的工具調用寫入磁盤上的 JSONL 文件，並在進程生命週期之外保存這些數據。

功能概覽¶

這是一個 DeepSeek Harness（DSH）主機插件。它監聽 tools/result 事件，捕獲工具調用中出現的異常、輸出 schema 違規、未知工具名、被拒絕的調用或被取消的調用。所有記錄都會被追加到磁盤日誌中，並通過算法將高度相似的失敗摺疊爲唯一的“簽名”和計數。

核心能力包括：

• 簽名摺疊：將工具名稱、錯誤代碼和規範化後的錯誤信息哈希，將多次相似失敗合併爲一條記錄，便於分析。
• 迴歸檢測：標記在會話早期成功過，但在後續失敗的工具調用。
• 內置修復建議：針對特定錯誤類型（如 COMMAND_NOT_FOUND、EDIT_NO_MATCH 等），記錄中會附帶明確的修復建議。
• 持久化存儲：日誌文件持久化存儲在 <DSH_HOME>/failure-journal/sessions/ 目錄下。

安裝與啓用¶

安裝過程與 DSH 的其他插件一致，通過 dsh plugin 命令將包添加到指定配置文件中。

dsh plugin --profile web add github:catsenior507/dsh-tool-failure-journal

安裝完成後需要重啓主機以使配置生效，然後通過以下命令驗證插件是否正確掛載：

failure_journal action=selftest

selftest 操作會檢查觀察者是否已掛載，並在日誌目錄中寫入一個測試文件以驗證寫入權限。

配置項¶

如果需要修改默認行爲，可以通過編輯配置文件中的 config 字段來調整。配置文件通常位於 profile 目錄下的 cordis.patch.yml 中：

- insert:
    - id: tool-failure-journal
      name: '@dsh-external/dsh-tool-failure-journal'
      config:
        maxBytes: 4194304
        clusterThreshold: 3
        excludeTools: ['todo_write']
        recordSuccesses: false
        exposeTool: true

• maxBytes：單個日誌文件的最大字節數（默認 4MB）。
• clusterThreshold：觸發簽名摺疊的相似度閾值。
• excludeTools：需要排除記錄的工具列表。
• recordSuccesses：是否記錄成功調用的日誌（默認爲 false，設爲 true 可追蹤命令的實際執行結果）。
• exposeTool：是否將 failure_journal 工具暴露給 agent。

使用方式¶

插件通過 failure_journal 工具暴露給智能體，支持以下操作：

示例用法：

failure_journal action=stats
failure_journal action=list
failure_journal action=show 9f2c1ab73e04
failure_journal action=sessions
failure_journal action=clear

存儲與設計¶

• 文件存儲：日誌以 JSONL 格式存儲，每個會話對應一個文件（<sessionId>.jsonl）。
• 日誌保留：文件按大小輪轉，但輪轉後的舊文件會被保留，不會被刪除。這確保了當智能體陷入循環錯誤時，歷史數據仍然可用。
• 運行機制：觀察者運行在進程內，執行同步的追加寫入操作，不阻塞主流程。它不依賴構建步驟、原生代碼或運行時的網絡請求。

注意事項¶

• 依賴環境：插件需要 Node.js 版本 >= 20。
• 權限要求：插件以當前 DSH 進程的權限運行，請確保目錄可寫。
• 許可證：MIT 許可證。

鏈接¶

• GitHub 倉庫
• DSH 生態目錄