agenttrace 工作階段稽核
概觀
使用此技能搭配 agenttrace 來稽核本機 AI 編碼代理的工作階段。它專注於工作階段執行過程中的面向:token 與成本異常、工具失敗、重試迴圈、延遲瓶頸、異常事件、健康分數以及工作階段間的差異比對。
agenttrace 是本機優先的工具,可讀取來自 Claude Code、Codex CLI、Gemini CLI、Aider、Cursor 匯出檔案、OpenCode、Qwen Code、Kimi 以及通用 JSON 或 JSONL 追蹤格式的工作階段記錄。
何時使用此技能
- 當使用者詢問為何 AI 編碼執行緩慢、昂貴、淺薄或不可靠時。
- 在重新執行失敗或可疑的工作前,審查本機代理記錄時。
- 當要為 AI 輔助編碼工作階段建立輕量級 CI 健康閘道時。
- 當要比較兩次嘗試,並尋找工具路徑、重試或成本模式的變化時。
運作方式
步驟 1:探索可用的工作階段
若環境中已安裝 agenttrace 二進位檔且在 PATH 上,則優先使用。如果當前儲存庫是 luoyuctl/agenttrace,則改用 go run ./cmd/agenttrace。
agenttrace --doctor
agenttrace --overview
如果未偵測到任何工作階段,回報 --doctor 檢查的目錄,並要求使用者提供匯出的工作階段檔案或記錄目錄。
步驟 2:產出可讀性高的稽核報告
當使用者希望獲得一份可以檢視或分享的簡潔報告時,使用 Markdown 格式。
agenttrace --overview -f markdown -o agenttrace-overview.md
在報告中,優先列出風險最高的工作階段,並說明其原因:重大異常、重複的工具失敗、token 或成本浪費、長時間延遲瓶頸、低健康分數,以及可疑的淺薄工作階段。
步驟 3:檢查單一工作階段或目錄
使用最新的工作階段進行快速檢查,或在使用者提供明確的匯出路徑時傳入該路徑。
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
步驟 4:在意義比較時進行差異比對
即使代理自信地採取了錯誤的實作路徑,token 和延遲指標仍可能看起來健康。當風險在於語意偏離時,應將追蹤稽核與先前或已知良好的工作階段進行 diff 比對。
關注以下幾點:
- 與預期任務不同的已變更檔案或命令
- 與參考工作階段相比缺少的測試或驗證步驟
- 在相同檔案上反覆編輯卻無明確原因
- 因跳過必要的探索而導致成本降低
步驟 5:加入自動化閘道
對於 CI 或可重複的團隊工作流程,使用 JSON 輸出或健康門檻。
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
根據專案調整門檻值。嚴格的閘道對關鍵工作流程很有用;在團隊了解基線行為之前,僅回報的指令會更合適。
範例
快速本機審查
agenttrace --overview
agenttrace --latest
在長時間的 AI 編碼執行後使用此指令,以決定下一個提示是否應分割任務、避開失敗的工具路徑、加入遺漏的測試或重設上下文。
CI 健康檢查
agenttrace --overview --fail-under-health 80 --fail-on-critical
當 CI 中已提供代理工作階段記錄,且團隊想要一個簡單的防禦機制來防範重大異常或不健康的執行時使用。
最佳做法
- 當工作階段發現不確定時,從
--doctor開始。 - 如實回報遺漏的欄位;不要虛構成本、模型、延遲或健康資料。
- 將提示、程式碼和工作階段內容視為私有的本機資料。
- 自動化時偏好 JSON 輸出,人工審查時使用 Markdown 輸出。
- 使用追蹤指標處理過程失敗,使用 diff/參考審查處理語意偏離。
限制
- agenttrace 只能分析本機存在或以匯出形式提供的記錄。
- 部分代理並未提供足夠的欄位來推斷成本、模型、快取使用或延遲。
- 健康的追蹤指標並不能證明最終程式碼是正確的;仍需執行測試並審查 diff。
- CI 閘道應先以建議性質啟用,直到團隊理解正常的基線行為為止。
安全性與安全須知
- 除非使用者明確同意,否則請勿將私有的工作階段記錄上傳至外部服務。
- 除非使用者要求特定的輸出路徑,否則請勿覆寫使用者報告。
- 避免列印在提示、工具輸出、環境變數或記錄中發現的秘密資訊。
常見陷阱
-
問題: 找不到任何工作階段。 解決方案: 執行
agenttrace --doctor,然後將 agenttrace 指向匯出的檔案或記錄目錄。 -
問題: 一次執行看起來便宜又快速,但卻產生了錯誤的重構。 解決方案: 將工作階段與先前的嘗試或已知良好的 diff 進行比較;僅靠成本指標會錯過語意偏離。
-
問題: 加入健康閘道後 CI 頻繁失敗。 解決方案: 先使用 JSON 或 Markdown 報告,檢查正常的基線行為,然後逐步收緊門檻值。
相關技能
@langfuse- 用於生產環境 LLM 應用程式的追蹤與評估。@observability-engineer- 用於更廣泛的服務監控、SLO 與事件處理工作流程。