agenttrace 会话审计
概述
使用此技能通过 agenttrace 检查本地 AI 编码代理会话。它专注于运行过程背后的指标：令牌和成本峰值、工具故障、重试循环、延迟差距、异常、健康评分以及会话间的差异。
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
在报告中，首先列出最高风险的会话，并解释其重要性：关键异常、重复的工具故障、令牌或成本浪费、长延迟差距、低健康评分以及可疑的浅层会话。
步骤 3：检查单个会话或目录
使用最新会话进行快速检查，或在用户提供显式导出路径时传递该路径。
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
步骤 4：在语义重要时比较尝试
即使代理自信地选择了错误的实现路径，令牌和延迟指标也可能看起来健康。当风险是语义漂移时，将跟踪审计与先前或已知的良好尝试的差异进行比较。
查找以下内容：
- 偏离预期任务的文件或命令更改
- 与参考尝试相比，缺少测试或验证步骤
- 对相同文件进行无明确原因的重复编辑
- 因跳过必要的探索而导致成本降低
步骤 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
在长时间的编码代理运行后使用，以确定下一个提示是否应拆分任务、避免失败的工具路径、添加缺失的测试或重置上下文。
CI 健康检查
agenttrace --overview --fail-under-health 80 --fail-on-critical
当 CI 中可用的代理会话日志，且团队希望设置一个简单的门控来防止关键异常或不健康运行时使用。
最佳实践
- 当会话发现不确定时，从
--doctor开始。 - 如实报告缺失字段；不要虚构成本、模型、延迟或健康数据。
- 将提示、代码和会话内容视为私有本地数据。
- 自动化优先使用 JSON 输出，人工审查优先使用 Markdown 输出。
- 使用跟踪指标处理流程失败，使用差异/参考审查处理语义漂移。
限制
- agenttrace 只能分析本地存在或作为导出提供的日志。
- 有些代理未提供足够的字段来推断成本、模型、缓存使用或延迟。
- 健康的跟踪指标不能证明最终代码是正确的；仍需运行测试和审查差异。
- CI 门控应首先作为建议性工具，直到团队理解正常的基线行为。
安全与注意事项
- 除非用户明确批准，否则不要将私有会话日志上传到外部服务。
- 除非用户要求确切的输出路径，否则不要覆盖用户报告。
- 避免打印在提示、工具输出、环境变量或日志中找到的机密信息。
常见陷阱
-
问题： 未找到会话。 解决方案： 运行
agenttrace --doctor，然后将 agenttrace 指向导出的文件或日志目录。 -
问题： 运行看起来便宜且快速，但产生了错误的重构。 解决方案： 将会话与之前的尝试或已知良好的差异进行比较；仅成本指标会遗漏语义漂移。
-
问题： 添加健康门控后，CI 失败过于频繁。 解决方案： 从 JSON 或 Markdown 报告开始，检查正常基线，然后逐步收紧阈值。
相关技能
@langfuse- 用于生产级 LLM 应用程序的跟踪和评估。@observability-engineer- 用于更广泛的服务监控、SLO 和事件工作流。