diagnose

诊断

仅在用户明确调用 diagnose 或 diagnose-fix-loop 后使用此工作流。一般的错误报告和修复请求不代表用户同意使用此工作流。

通过有区分力的证据，找出并解释用户所述症状的原因。只要实际可行的探查可能改变结论，就应继续寻找更有力的证据；无需等到达到某个数值置信度阈值，才提出可信且范围明确的修复方案。

从用户提供的具体线索入手：文件、路由、错误、日志、屏幕、分支、构建产物或复现步骤。查阅相关架构说明、ADR、术语表和测试文档。检查代码，运行安全的工具或测试，并分析现有产物。

用户明确调用 Diagnose，即表示批准在请求范围内进行不改变行为的临时埋点。对于范围明确的修复，沿用对话中或 diagnose-fix-loop 调用中已有的授权。仅当下一步操作未获授权、需要无法获得的访问权限，或涉及尚未解决的重大决策时，才询问用户。

参考资料

仅加载适用的资料：

• 浏览器或 React Web： browser-react.md
• iOS、Android、React Native、macOS、TV 或实体设备：app-device.md。macOS 应用会话默认使用 agent-device 的原生后端；打开应用前，先阅读其设置说明和 XCTest 后备方案。
• 日志、运行时探查、指标或调试钩子：instrumentation.md

证据循环

1. 定位可能的原因。 检查用户线索周边的代码路径和现有证据。列出最精简且有用的可能区域及可证伪的候选原因；适用时，纳入彼此独立或共同作用的原因。为每个原因给出可区分的预测，并指出这些预测在哪些方面有所不同。

2. 选择有区分力的证据。 优先使用现有测试、跟踪记录和日志。当它们无法区分主要候选原因时，加载 instrumentation.md，并在相关边界添加临时的结构化探查。如果一次复现即可区分多个原因，就同时为这些原因添加埋点。

   复现前，先定义探查约定：

   • 确切的触发条件和可见症状
   • 本次运行要回答的问题
   • 每个候选原因的区分性预测
   • 用于检验这些预测的事件、字段和关联 ID
   • 如何将证据关联到确切的可见故障
   • 适用时，预期的进程、构建、窗口、文档和运行时标识

   基线复现可先确认症状，再添加埋点。在将复现结果作为因果证据前，确保观测结果能区分主要候选原因，并确认症状完全一致。

3. 复现问题。 使用能代表所报告症状且速度最快、结果确定的信号：定向测试、脚本、浏览器测试、跟踪回放、测试工具框架、重复循环、性能分析器、应用/设备自动化或结构化人工复现。在安全且可观测时运行。如果故障是间歇性的，应运行足够多次，以便比较不同原因。

   如果复现需要无法访问的状态、凭据、设备、主观交互或有风险的操作，应先准备好捕获手段、确切步骤、预期观测结果和要检查的产物。请用户复现并回复 done；确认返回的证据与所报告的故障相符。

   如果用户修正了触发条件、受影响组件、生命周期或可见症状，则应废弃针对先前解释的证据和探查。再次复现前，返回原因定位和埋点步骤；不要继续使用相近但不匹配的复现方式。

4. 收集并分析。 收集完整输出，关联不同边界间的事件，将结果与各项预测进行比较，并记录支持和反驳每个原因的证据。如果日志不完整或含糊，应先明确再次复现前需要如何调整可能的原因范围或埋点方式。

5. 确定置信度。 按角色（根因、促成因素或替代原因）为每个原因排序，给出 0-100% 的置信度、支持和相悖的证据，以及可能改变其分数或排名的后续证据。将分数视为定性判断，而非经过校准的统计概率。只有满足以下条件时，才赋予 100% 的操作性置信度：

   • 精确复现了该症状
   • 观察到了从触发因素到故障的因果链
   • 控制疑似边界能够可靠地控制该症状
   • 该原因或原因组合能够解释所有相关观察结果
   • 合理的替代原因已被证伪，或已纳入促成因素
   • 对间歇性行为的重复次数足以区分因果关系与巧合

   如果证据不完整，请选择最安全、最有可能补充鉴别性证据的探测方式，并说明哪些结果会提高、降低或重新分配置信度。仅当存在这样的探测方式时，才修订可能涉及的区域或检测手段并重复这一循环；如果输入、边界或检测手段都没有变化，则不要重复等效的检查。

   当没有可用探测方式能够提高置信度、某次检查没有增加证据且不存在不同的边界，或所需证据需要无法获得的访问权限、用户操作、不可接受的风险或不成比例的投入时，请停止探测。如果现有证据足以支持可信的原因和范围明确的修复方案，则报告为“有证据支持”；否则报告为“尚不完整”。绝不要将尚未证实的结论标记为已证实。

输出

首先给出以下一种状态：

• 已证实 — 100%： 每个适用原因都符合证明标准，且没有尚未解决的合理替代原因。
• 有证据支持： 证据找到了可信的原因和范围明确的修复方案，但仍存在具体的不确定性。
• 尚不完整： 现有证据尚不足以支持可信的原因或修复方案。

对于已证实或有证据支持，请报告原因、因果链、决定性证据、代码或运行时边界，以及任何剩余的不确定性。对于尚不完整，请为候选原因排序，说明证据不足的原因，并指出最小且有用的下一步探测。务必指出验证信号。置信度分数是判断结果，并非测得的概率。

临时诊断信息

保留诊断日志，直到用户要求清理，或这些日志成为持久诊断信息。如果提交时仍有临时诊断信息，只暂存预期保留的更改，并报告仍有哪些内容未暂存。

委派

仅当用户明确要求委派、使用子 Agent、并行处理或优化 token 使用时，才使用子 Agent。将范围明确的机械式信息收集任务交给更快或成本更低的 Agent：已知命令或复现循环、日志、屏幕截图、跟踪记录、性能分析结果、提取工作或产物比较。为每项任务指定成功条件、输出格式、运行时边界；除非明确要求修改，否则要求不得编辑。

在主线程中完成反馈循环设计、假设排序、置信度评分、模糊信息的解读以及最终诊断。核实委派收集的证据，并检查工作树和后台进程后再继续。