bashkit-debug

BashKit 除錯追蹤分析器是一個專為開發人員構建的診斷工具，用於使用 BashKit 框架開發代理程式。透過處理代理程式執行期間生成的 JSONL 格式除錯檔案，此技能提供了對工具執行內部生命週期的可視性，包括從開始到結束的關聯、嵌套的父子任務關係以及精確的時序指標。對於需要了解代理程式為何停滯、特定工具為何返回錯誤或如何優化複雜的多步驟工作流程的工程師來說，這是一個必不可少的工具。該分析器解析來自 bash、read、write、edit、glob、grep、task 和基於 web 的操作的特定工具摘要欄位，以提供全面的診斷分析。

• 使用唯一的 ID 追蹤自動關聯工具調用事件，以連結開始、結束和錯誤訊號。

• 計算每次工具調用的延遲和持續時間，突顯超過效能閾值的緩慢操作。

• 彙總錯誤統計資訊並識別失敗模式，例如重複的 bash 退出代碼、失敗的文件讀取或 grep 操作中的 regex 不匹配。

• 透過映射多代理執行流程中的父子關係來視覺化子代理任務層級。

• 提供循序漸進的分析手冊，以評估代理行為、檢測無限迴圈並驗證工具參數的輸入與輸出。

• 使用 BASHKIT_DEBUG=file:/path/to/trace.jsonl 作為日誌的標準輸入格式。

• 包含用於終端機中對大型追蹤檔案進行摘要的輔助腳本，以便在不人工檢查檔案的情況下識別趨勢。

• 非常適合用於除錯 Vercel AI SDK 整合、本地沙盒環境和 Vercel 遠端沙盒部署。

• 支援分析複雜的嵌套子代理互動和任務工具內的 Token 使用報告。

• 對於排查檔案系統錯誤（例如編輯操作期間的「字串未找到」）或 bash 指令執行中的「退出代碼 1」失敗非常有效。