agent-trace 是一款面向 AI 编程智能体的会话后分析工具，以命令行界面（CLI）形式提供。它的核心目标是回答一个常见但难以量化的问题：你的 AI 编程智能体在长时间运行中究竟做了什么、花了多少钱、哪些工具反复失败、为什么重试了多次。
用途
当 AI 编程智能体连续运行数小时，它会调用工具、消耗 Token、重试失败操作。但用户往往不清楚实际成本、失败工具、重试原因、模型慢还是工具坏、每次对话耗时等。agent-trace 通过一条命令在本地快速生成这些洞察，无需 API 密钥、无需云服务。
主要能力
- 追踪成本：基于标准 API 定价计算会话费用。
- 追踪 Token：从消息历史中提取 Token 使用量。
- 工具健康分析：统计工具调用的成功与失败率。
- 对话记录：解析消息历史，提取角色、Token、时间戳。
- 异常检测：识别高重试、高失败、高成本等异常情况。
- 多会话汇总视图：展示多个会话的汇总信息。
- 单会话详情视图：深入查看某个会话的细节。
- 自动检测：默认扫描所有已知路径，自动识别正在使用的智能体。
- 强制指定智能体：可手动指定要分析的智能体。
- 输出格式：支持终端输出或 JSON 输出，便于 CI 集成。
支持的智能体
根据官方资料，agent-trace 支持 Kimi Code、Claude Code、Codex、OpenCode。官方文本中亦提及“CLI for monitoring Claude, Cursor, Kimi Code sessions”，但未明确列出 Cursor 的完整支持细节，此处仅按原文呈现。
使用方式
通过 npx 直接运行，无需安装：
npx @liangzhengtao/agent-trace
默认情况下，agent-trace 会扫描所有已知路径并自动检测智能体类型。用户也可以强制指定特定智能体进行分析。工具读取本地会话文件，不发起网络请求或 API 调用；解析消息历史，提取角色、Token、时间戳；分析工具调用，追踪成功/失败率；基于标准 API 定价计算成本；检测异常（高重试、失败、成本）；生成报告，输出到终端或 JSON。
适用场景
- 开发者希望了解 AI 编程智能体的实际运行成本。
- 需要排查哪些工具频繁失败或重试。
- 评估模型响应速度与工具健康状态。
- 在 CI 流程中集成会话分析，输出 JSON 报告。
- 对多个会话进行汇总对比。
限制与隐私
- 100% 本地运行，数据不离开本机。
- 只读模式，绝不修改会话文件。
- 无需 API 密钥，不依赖外部服务。
- 无追踪、无分析、无遥测。
- 成本计算基于标准 API 定价，实际费用可能因定价变化而有所差异。
- 官方资料未提供具体的安装要求、系统兼容性、版本号或详细配置参数，这些信息暂未提供。
贡献与许可
项目欢迎贡献，流程为：Fork 仓库、创建功能分支、提交更改、推送分支、发起 Pull Request。完整指南见 CONTRIBUTING.md。项目采用 MIT 许可证，版权归 Serennity007 所有。
