name: agenttrace-session-audit
description: “Audit local AI coding-agent sessions with agenttrace for cost, tool failures, latency, anomalies, health, diffs, and CI gates.”
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”
代理跟踪会话审计
概览
使用此技能检查本地 AI 编码代理会话
agenttrace。它专注于进程
运行背后：令牌和成本激增、工具故障、重试循环、延迟间隙，
异常、健康评分以及会话间差异。
agenttrace 是以本地为主的，并从诸如 Claude Code 的工具中读取会话日志，
Codex CLI、Gemini CLI、Aider、Cursor 导出、OpenCode、Qwen Code、Kimi，以及
通用 JSON 或 JSONL 跟踪。
何时使用此技能
- 当用户询问 AI 编码运行速度慢、成本高、表面化或不可靠时使用。
- 在重试失败或可疑任务之前，查看本地代理日志时使用。
- 在构建用于 AI 辅助编码会话的轻量级 CI 健康门时使用。
- 用于比较两次尝试并查看工具路径、重试或成本模式的变化。
运作方式
第1步：发现可用的会话
当PATH上可用时，优先使用已安装的agenttrace二进制文件。如果
当前仓库是luoyuctl/agenttrace，使用go run ./cmd/agenttrace
取而代之
agenttrace--doctoragenttrace--overview如果未检测到会话，请报告--doctor检查的目录并
请求导出的会话文件或日志目录。
步骤2：生成可供人类阅读的审计
当用户想要一个可以检查或分享的简明报告时，请使用 Markdown。
agenttrace--overview-fmarkdown-oagenttrace-overview.md在报告中，以风险最高的会议开头，并解释它们为什么重要：
关键异常、重复的工具故障、代币或成本浪费、长延迟
差距、低健康评分，以及可疑地浅显的课程。
步骤 3：检查一个会话或目录
使用最新的会话进行快速检查，或在使用时传递一个明确的导出路径
用户提供一个。
agenttrace--latestagenttrace--latest-fjson agenttrace path/to/session-or-export.json agenttrace--overview-dpath/to/session-dir第4步：在语义重要时比较尝试
即使代理自信地采取行动，令牌和延迟指标看起来也可能很健康
错误的实施路径。当风险是语义漂移时，将跟踪配对
针对之前的或已知良好尝试进行差异审核。
查找：
- 更改的文件或偏离预期任务的命令
- 与参考尝试相比，缺少测试或验证步骤
- 在相同的文件上反复编辑而没有明确的理由
- 来自跳过必要勘探的较低成本
第5步：添加自动化门
对于持续集成或可重复的团队工作流程，使用 JSON 输出或健康阈值。
agenttrace--overview-fjson-oagenttrace-overview.json agenttrace--overview--fail-under-health80--fail-on-critical --max-tool-fail-rate15根据项目调整阈值。严格的门控对关键工作流程很有用；
在团队了解其基线时，仅报告的命令更好。
例子
快速本地评论
agenttrace--overviewagenttrace--latest在长时间的编码代理运行后使用此来决定下一个提示是否应该
分解任务，避免失败的工具路径，添加缺失的测试，或重置上下文。
CI 健康检查
agenttrace--overview--fail-under-health80--fail-on-critical当代理会话日志在 CI 中可用且团队想要一个简单方式时使用此方法
防范严重异常或不正常的运行。
最佳实践
- 当会话发现不确定时，请从
--doctor开始。 - 明确报告缺失的字段；不要编造成本、型号、延迟或健康数据。
- 将提示、代码和会话内容视为私有本地数据。
- 对于自动化，优先使用 JSON 输出；对于人工审阅，优先使用 Markdown 输出。
- 对于过程失败使用跟踪指标，对于语义漂移使用差异/参考审查。
限制
- agenttrace 只能分析本地存在的日志或作为导出提供的日志。
- 一些代理没有暴露足够的字段来推断成本、型号、缓存使用或延迟。
- 健康的跟踪指标并不能证明最终代码是正确的；仍然要运行测试并审查差异。
- CI 门应该先作为建议性使用，直到团队了解正常的基线行为。
安全与防护注意事项
- 除非用户明确批准，否则不要将私人会话记录上传到外部服务。
- 除非用户明确要求使用该输出路径，否则不要覆盖用户报告。
- 避免打印在提示、工具输出、环境变量或日志中发现的秘密。
常见陷阱
问题:未找到会话。
解决方案：运行agenttrace --doctor，然后将 agenttrace 指向导出的文件或日志目录。问题:一次运行看起来既便宜又快，但产生了错误的重构。
解决方案：将本次会话与之前的尝试或已知良好的差异进行比较；仅依靠成本指标将无法发现语义漂移。问题：在添加健康检查后，持续集成失败得太频繁。
解决方案：从 JSON 或 Markdown 报告开始，检查正常基线，然后逐步收紧阈值。
相关技能
@langfuse- 用于生产级 LLM 应用的跟踪和评估。@observability-engineer- 用于更广泛的服务监控、SLO 和事件工作流程。
