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 服务器集成或调优代理系统提示词以提高可靠性并降低工具循环频率时使用。