---

name: agenttrace-session-audit description: "使用 agenttrace 审计本地 AI 编码智能体会话，包括成本、工具失败、延迟、异常、健康度、差异和 CI 门控。" category: development risk: safe source: community source_repo: luoyuctl/agenttrace source_type: community date_added: "2026-05-10" author: luoyuctl tags: [ai-coding, observability, cost-tracking, session-analysis] tools: [claude, cursor, gemini, codex-cli] license: "MIT" license_source: "https://github.com/luoyuctl/agenttrace/blob/master/LICENSE"

agenttrace 会话审计

概述

使用此技能通过 agenttrace 检查本地 AI 编码智能体会话。它聚焦于运行背后的过程：token 和成本峰值、工具失败、重试循环、延迟间隙、异常、健康分数和会话间差异。

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

在报告中，以最高风险会话开头并解释其重要性：关键异常、重复工具失败、token 或成本浪费、长延迟间隙、低健康分数和可疑的浅层会话。

步骤 3：检查单个会话或目录

使用最新会话进行快速检查，或在用户提供时传递明确的导出路径。

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

步骤 4：当语义重要时比较尝试

即使智能体自信地走了错误的实现路径，token 和延迟指标看起来也可能健康。当风险是语义漂移时，将追踪审计与之前或已知良好尝试的差异配对。

寻找：

• 偏离预期任务的已更改文件或命令
• 与参考尝试相比缺少的测试或验证步骤
• 围绕相同文件的重复编辑而没有明确原因
• 因跳过必要探索而降低的成本

步骤 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 门控应在团队了解正常基线行为之前作为建议性使用。

安全与安全说明

• 除非用户明确批准，否则不要将私有会话日志上传到外部服务。
• 除非用户请求了确切的输出路径，否则不要覆盖用户报告。
• 避免打印在提示词或会话内容中发现的密钥。