Agent session trace audit

何时使用

适用：

• 用户问某次 AI 编码运行为何慢、贵、结果浅或不可靠，需要定位过程问题（token/成本飙升、工具失败、重试循环、延迟空档、异常、低健康分）。
• 重试一个失败或可疑任务前，先复盘本地 agent 日志。
• 为团队搭轻量 CI 健康门禁，守住 AI 辅助编码会话的底线。
• 对比两次尝试，排查改动路径、重试、成本模式的差异（语义漂移）。

不该用（负边界）：

• 不审计远端托管/生产 LLM 应用的链路追踪（那类需求转 langfuse / 通用可观测性）。
• 不上传私有会话日志到外部服务。
• 健康的 trace 指标不能证明最终代码正确——仍需跑测试、审 diff。

agenttrace 是 local-first 工具，读取本地会话日志，支持 Claude Code、Codex CLI、Gemini CLI、Aider、Cursor 导出、OpenCode、Qwen Code、Kimi，以及通用 JSON/JSONL trace。

步骤 / 指令

步骤 1：发现可用会话

优先用 PATH 上已安装的 agenttrace；若当前仓库就是 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 与延迟看着健康，agent 也可能自信地走错实现路径。怀疑语义漂移时，把 trace 审计与「对上一次 / 已知良好尝试的 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

长时间 agent 运行后，用它决定下一个 prompt 该拆分任务、绕开失败的工具路径、补缺失测试，还是重置上下文。

CI 健康检查

agenttrace --overview --fail-under-health 80 --fail-on-critical

CI 中已有 agent 会话日志、团队想要一道防严重异常/不健康运行的简单守卫时用。

注意事项

最佳实践：

• 会话发现不确定时，先 --doctor。
• 缺字段就如实报告，不要编造成本、模型、延迟、健康数据。
• 把 prompt、代码、会话内容当作私有本地数据。
• 自动化优先 JSON，人读优先 Markdown。
• 过程失败看 trace 指标，语义漂移靠 diff / 参照审查。

局限：

• 只能分析本地存在或作为导出提供的日志。
• 部分 agent 暴露字段不足，无法推断成本、模型、缓存使用或延迟。
• trace 指标健康 ≠ 代码正确，仍需测试 + 审 diff。
• CI 门禁初期应设为「建议性」，团队理解正常基线后再收紧。

安全：

• 未经用户明确同意，不要把私有会话日志上传到外部服务。
• 非用户指定的精确输出路径，不要覆盖其报告文件。
• 不要打印 prompt、工具输出、环境变量或日志中发现的密钥。

常见坑：

• 找不到会话 → 跑 agenttrace --doctor，再把 agenttrace 指向导出文件或日志目录。
• 运行看着又快又便宜，却产出了错误的重构 → 对比上一次尝试或已知良好 diff；仅看成本指标会漏掉语义漂移。
• 加了健康门禁后 CI 频繁失败 → 先用 JSON/Markdown 仅报告，观察正常基线，再逐步收紧阈值。

互见

• langfuse：生产级 LLM 应用链路追踪与评估。
• 可观测性工程（observability-engineer）：更广的服务监控、SLO 与事件响应流程。

---

采编自 sickn33/antigravity-awesome-skills（上游工具 luoyuctl/agenttrace，MIT 许可）。