session-investigator

Session Investigator 是 fast-agent 框架開發者與進階使用者的關鍵診斷工具。它提供了一套結構化的方法，用於檢查、聚合並關聯存放在 .fast-agent/sessions 目錄中的資料。透過解析 session.json 中繼資料與 history_*.json 訊息檔，使用者能夠重建對話流程、追蹤工具呼叫鏈結，並量化 LLM 互動與外部 MCP 伺服器呼叫的延遲。此技能特別適用於識別複雜的多回合任務為何失敗、除錯遞迴的工具迴圈，或將子代理（sub-agent）軌跡關聯回主會話內容。

• 對會話歷史 JSON 檔案進行深入分析，識別特定的訊息角色、停止原因與內容結構。

• 執行基於 jq 的自動化查詢，計算 LLM 呼叫統計數據，包括總持續時間、平均回應延遲，以及最小/最大執行時間。

• 關聯助理的工具呼叫與後續使用者的工具結果，以驗證資料完整性並診斷孤立或失敗的工具執行。

• 產生會話時序與訊息速率指標，視覺化互動流程並識別代理效能的潛在瓶頸。

• 特別檢查 agent__ 為前綴的工具呼叫模式與時序，以最佳化複雜的工作流程編排。

• 提供常見失敗模式檢測，特別是針對助理請求與預期工具結果之間斷裂的未回應工具呼叫。

• 本技能假設可存取本地的 .fast-agent 檔案系統結構，其中會話以 YYMMDDHHMM-<random> 格式儲存。

• 使用者應具備基本的 jq 指令列處理知識，以充分利用所提供的腳本進行日誌操作與指標提取。

• 強烈建議在會話以非描述性錯誤結束時使用此工具，例如意外的對話終止或工具執行期間的 API 超時。

• 在執行分析腳本之前，請務必先參考 session.json 檔案，以確認與該會話 ID 關聯的正確歷史檔案（舊檔 vs. 現行檔）。

• 非常適合在 fast-agent 開發生命週期中使用，特別是在測試新的 MCP 伺服器整合或調校代理系統提示詞以提高可靠性並降低工具迴圈頻率時使用。