agent-trace-diagnoser

Agent Trace Diagnoser

中文速查

• 中文名：Agent trace 诊断器 / 日志根因定位
• 英文稳定名：agent-trace-diagnoser
• 分类：工程实践
• 你可以这样叫我：看下这个 trace、根据日志定位根因、只说明问题不要改文件、具体到哪个文件哪行可能导致
• 适合：从 agent trace、日志 JSON、执行记录、工具调用序列中定位主链路失败点，用流程图展示主链路、分支和 fallback，并给出证据链、可能代码位置和修复建议。
• 不适合：直接修复代码、普通代码解释、没有日志证据的新功能设计。

Overview

使用这个 Skill 诊断 agent 执行 trace，而不是直接进入代码修改。目标是说明核心根因，用可复核的流程图呈现实际执行路径，区分主链路失败和 fallback 噪声，在仓库可用时映射到具体文件/行，并给出修复建议。

默认模式是只读分析。除非用户在诊断后明确要求实现修复，否则不要修改文件。

最终诊断内容必须使用中文输出；只有用户明确要求英文或其它语言时，才切换输出语言。

Workflow

1. 确认输入材料和用户约束。
   • 接收 trace JSON、复制的日志、终端片段、工具调用记录、网络 trace，或从截图转换出的文本。
   • 如果用户说“不要修改文件”“只说明问题”等，只做只读分析，不生成代码改动。
   • 如果用户提供 trace 文件路径，只读取足够重建事件顺序的内容。
2. 重建执行时间线。
   • 识别用户意图、被选中的 capability/skill、第一个失败步骤、重试、fallback 工具、终端错误和最终用户可见失败。
   • 分离直接原因和下游症状。
   • 除非后续证据推翻，否则把“预期主链路里最早失败的步骤”作为第一根因候选。
3. 绘制可复核的执行流程图。
   • 默认输出 Mermaid flowchart，从用户意图或输入开始，展示实际发生的 routing、主链路、首个失败、重试/fallback 和最终结果。
   • 给关键节点加 E1、E2 等证据编号，并与后面的证据链逐项对应；不要画无法被 trace 或本轮代码检查支持的步骤。
   • 把首个主链路失败标成“主因”，把 fallback 限制或后续错误标成“放大因素”，让读者能一眼区分因果层级。
   • 实际发生的转换使用实线；推断出的转换使用虚线并标注“推断”；重复调用合并成一个节点并注明次数。
   • 当延迟、并发或等待关系是诊断重点时，可改用 Mermaid sequenceDiagram；其它情况保持 flowchart。
   • 如果载体不支持 Mermaid，输出等价的纯文本箭头流程；如果 trace 连两个有效事件都不足，明确写“证据不足，无法可靠成图”，不要补造流程。
   • Read references/visualization-guide.md before drawing the diagram.
4. 分类失败层级。
   • 规划或路由：选错 skill/tool、能力边界错误、缺少 policy guardrail。
   • Skill/tool 实现：输入处理错误、解析失败、依赖问题、路径问题、不支持的媒体、脆弱 fallback。
   • 环境：权限、缺少二进制、只读目录、网络限制、临时目录归属、凭证。
   • 输出策略：误导性总结、隐藏失败、不安全下一步、遗漏限制说明。
5. 建立证据链。
   • 引用或转述 trace 中的精确事实：命令、状态码、异常码、文件 URL、content type、大小、fallback 转换、缺少依赖。
   • 如果最终错误发生在 fallback 之后，不要把最终错误过度放大成主因。
   • 每条证据使用与流程图一致的 E# 编号，并标记为已确认、推断或待验证。
6. 映射可能的代码位置。
   • 在当前仓库中搜索 trace 里的唯一字符串：skill 名、CLI 入口、错误码、fallback 命令、函数名、配置键、输出消息。
   • 只有当前轮实际读过代码，才报告精确文件和行号。
   • 如果 runtime 路径和本地仓库路径不同，标记为“可能源码位置”，并说明路径不一致。
7. 给出不改文件的修复建议。
   • 先推荐最小概念修复。
   • 包含能防止回归的测试或 eval。
   • 必要时补充运行 guardrail，例如不要用 webfetch 读取二进制 PDF，或不要在只读 skill 安装目录里运行构建。