agent-trace-diagnoserlisted

# 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。 - 环境：权限、缺少二进制、只读目录、网络限制、临时目录归属、凭证。 - 输出策略：误