AgentTrace 会话审计

agenttrace-session-audit
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.90/5
使用4.1K

agenttrace 会话审计

概述

使用此技能通过 agenttrace 检查本地 AI 编程代理会话。它专注于运行背后的过程：Token 和成本激增、工具失败、重试循环、延迟缺口、异常情况、健康评分以及会话间的差异。

agenttrace 采用本地优先原则，可读取来自 Claude Code、Codex CLI、Gemini CLI、Aider、Cursor 导出文件、OpenCode、Qwen Code、Kimi 以及通用 JSON 或 JSONL 追踪文件的会话日志。

何时使用此技能

  • 当用户询问 AI 编程运行为何缓慢、昂贵、浅层或不可靠时。
  • 在重试失败或可疑任务之前，审查本地代理日志时。
  • 为 AI 辅助编程会话构建轻量级 CI 健康门禁时。
  • 比较两次尝试，寻找工具路径变化、重试情况或成本模式时。

工作原理

第一步：发现可用会话

优先使用 PATH 路径下已安装的 agenttrace 二进制文件。如果当前仓库是 luoyuctl/agenttrace，请改用 go run ./cmd/agenttrace。

bash
agenttrace --doctor
agenttrace --overview

如果没有检测到会话，请报告 --doctor 检查过的目录，并请求导出会话文件或日志目录。

第二步：生成可读的审计报告

当用户需要一份可检查或分享的简洁报告时，请使用 Markdown 格式。

bash
agenttrace --overview -f markdown -o agenttrace-overview.md

在报告中，优先列出风险最高的会话并解释原因：关键异常、重复的工具失败、Token 或成本浪费、长延迟缺口、低健康评分以及异常浅层的会话。

第三步：检查单个会话或目录

快速检查时使用最新会话，或者在用户提供具体路径时传递显式的导出路径。

bash
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir

第四步：在语义关键时比较尝试

即使代理自信地采取了错误的实现路径，Token 和延迟指标看起来可能依然健康。当存在语义漂移风险时，请将追踪审计与之前或已知正确的尝试进行 diff 对比。

重点关注：

  • 与预期任务相背离的修改文件或命令
  • 与参考尝试相比缺失的测试或验证步骤
  • 无明显原因地对同一文件进行重复编辑
  • 因跳过必要的探索而导致的成本降低

第五步：添加自动化门禁

对于 CI 或可重复的团队工作流，请使用 JSON 输出或健康度阈值。

bash
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15

根据项目调整阈值。严格的门禁适用于关键工作流；而在团队学习基准期间，仅报告模式更为合适。

示例

快速本地回顾

bash
agenttrace --overview
agenttrace --latest

在长时间运行 coding-agent 后使用此命令，以决定下一个提示词（prompt）是否需要拆分任务、避开失败的工具路径、补充缺失的测试或重置上下文。

CI 健康检查

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

当 CI 中可用 agent 会话日志，且团队希望简单地拦截严重异常或不健康的运行状态时，请使用此命令。

最佳实践

  • 当会话发现（session discovery）不确定时，先运行 --doctor。
  • 坦诚报告缺失字段；不要伪造成本、模型、延迟或健康数据。
  • 将提示词、代码和会话内容视为私有本地数据。
  • 自动化场景优先使用 JSON 输出，人工审查优先使用 Markdown 输出。
  • 使用追踪指标（trace metrics）分析流程失败，使用 diff/参考审查分析语义漂移（semantic drift）。

局限性

  • agenttrace 只能分析本地存在或通过导出提供的日志。
  • 部分 agent 暴露的字段不足，无法推断成本、模型、缓存使用情况或延迟。
  • 健康的追踪指标并不证明最终代码正确；仍需运行测试并审查 diff。
  • CI 门禁在团队了解正常基准行为之前，应先设置为“建议”模式。

安全与保障注意事项

  • 除非用户明确批准，否则不要将私有会话日志上传到外部服务。
  • 除非用户请求了特定的输出路径，否则不要覆盖用户报告。
  • 避免打印在提示词、工具输出、环境变量或日志中发现的密钥（secrets）。

常见陷阱

  • 问题： 未找到会话。
解决方案： 运行 agenttrace --doctor，然后将 agenttrace 指向导出文件或日志目录。
  • 问题： 运行结果看起来成本低且速度快，但重构结果错误。
解决方案： 将该会话与之前的尝试或已知正确的 diff 进行对比；仅凭成本指标无法发现语义漂移。
  • 问题： 添加健康门禁后，CI 失败过于频繁。
解决方案： 先使用 JSON 或 Markdown 报告，检查正常基准，然后逐步收紧阈值。

相关技能

  • @langfuse - 用于生产环境 LLM 应用的追踪与评估。
  • @observability-engineer - 用于更广泛的服务监控、SLO 和故障处理工作流。