diagnose 是一个根因隔离技能,用于从缺陷描述、错误、日志、堆栈跟踪或复现信息出发,查明故障的因果机制。它的产出是一份根因报告,而不是直接修复代码。
用途与边界 该技能接收预期行为、实际行为、相关环境与执行接缝,区分“证据缺失”和“证据矛盾”。即使暂时没有可执行的红灯复现,也会基于现有证据开始调查。对每个可辩护的假设,先给出预测:若某原因是成立的,则某个受控探针会改变某个观察。调查结束时止于根因报告,生产修复、永久测试和修复变更集留给后续工作。
主要能力
- 因果证据处理:从缺陷描述、错误信息、日志、堆栈跟踪或复现步骤中提取预期行为、实际行为、环境和执行接缝。
- 区分触发条件与机制:把触发条件和上下文同产生故障的机制分开,逐条检验竞争性解释,一次只改变一个因果因素。
- 构造最小反馈循环:按接缝选择调查方法,包括运行聚焦的现有测试、调用 CLI 或 HTTP 路径、构建最小临时夹具、在 scratch 中重放脱敏的负载、日志或 HAR 数据、在隔离检出中比较版本,以及为仅交互触发的缺陷改编本地循环模板。
- 处理间歇性故障:在可行时控制随机种子、时钟、事件顺序或并发,用有界重复而不是单次侥幸通过作为证据。
- 结论状态:CONFIRMED(证据验证了因果机制)、INFERRED(证据支持特定假设,但存在已说明的缺口)、REJECTED(有区分度的证据在声明范围内证伪了被调查的因果主张)、UNRESOLVED(证据不支持任何可辩护原因,或存在阻碍)。
使用方式与约束 调查只读取生产源码和现有测试;临时探针、夹具、跟踪重放和报告文件只写入 .agents/scratch/。保留工作区已有改动和临时产物,探针尽量在隔离副本或只读接缝上运行,插桩不进入生产源码;临时探针以 [DEBUG-<hex>] 标记,收集证据后只清理本次会话拥有的插桩。记录前对敏感信息脱敏,不检查 .env*、.key、.pem 等密钥文件;执行环境以 .agents/environment.md 为依据,严格限制在本地 scratch 边界内。
输出契约 最终输出一份紧凑的根因报告,包含状态、结论、范围、证据、条件与证明限制;如有竞争性解释则列出其假设、探针、观察与支持或证伪结果;如建立了可执行或交互循环则附上复现路径、所需设置、断言与观察到的症状。必要时保留脱敏的复现产物,并确认生产文件未被改动。
适用场景 适合缺陷根因分析、故障复现、日志与堆栈追踪、间歇性问题排查,以及需要为后续修复或架构决策提供依据的工程调查。根因结论可路由到设计、方案验证、架构决策或环境诊断等后续步骤。
限制 该技能不负责实施修复、编写永久测试或提交修复变更集;若缺少输入、环境或访问权限,可能只能给出 INFERRED 或 UNRESOLVED 结论并说明证明缺口。