证据优先的 Bug 分析：先找到第一处错误状态

看到报错日志后直接定位某个仓库，是自动化分析最容易犯的错误。日志只能证明某个时间、某个组件记录了现象，不能单独证明代码根因。可靠的 Harness 会先建立证据链，再寻找第一处错误状态。

固化原始输入

记录问题发生时间、时区、环境、客户端版本、复现步骤和原始附件摘要。压缩包与日志先计算摘要值，派生文件放到独立工作区，不能覆盖用户原件。缺少字段时标记未知，不从文件名或经验猜测。

建立 ID 语义账本

一次请求可能同时出现 HTTP 请求号、业务任务号、消息号、会话号和 Trace 号。格式相似不代表语义相同。应为每个候选 ID 保存来源字段、首次出现位置、关联证据和当前判定，再用第二个维度交叉验证。

按阶段排列时间线

将事件分为客户端产生、网关接收、业务处理、外部能力调用、持久化与客户端展示。对每个阶段记录“通过、合法绕过、缺失或不可用”。第一处从正常转为异常的位置才是候选责任边界；后续报错往往只是连锁反应。

代码只能验证假设

先用运行证据缩小仓库与版本，再查看对应提交的源码和调用链。当前分支代码、搜索命中和架构图都不能替代受影响版本。要同时检查正常路径或反事实路径：如果修正候选条件，原始失败是否真的消失？

分级输出

A级结论需要完整链路、精确版本和可复现验证；B级允许少量非关键缺口；C级只能列候选假设。报告要分开写事实、推断、缺失证据和下一步可证伪动作。这样即使暂时不能定因，也不会把一个听起来合理的故事当成结论。

第二轮实践复核

可复用交付物： 原始输入摘要、ID 语义账本、分层时间线和证据等级。这些内容是从工程实践抽象出的通用方法，不包含内部仓库、真实工作项、业务数据、凭据、地址或实现源码。

最低验收： 任意结论都能回指时间、来源和精确版本；缺关键阶段时只输出候选假设。验收记录必须分开事实、推断、缺口和授权范围；只读检查不能自动扩展为提交、推送、评论或发布。

一份可复核的证据包

case_id: BUG-241
time_window: ["2026-08-22T08:10:00+08:00", "2026-08-22T08:20:00+08:00"]
environment: production-cn
artifacts:
  - name: gateway.log
    sha256: "<digest>"
    source: "exported read-only query"
identifiers:
  - value_hash: "hmac:..."
    type: request_id
    first_seen: gateway.access.request_id
hypotheses:
  - id: H1
    statement: "支付依赖在 deadline 后返回"
    supporting: [E3, E5]
    contradicting: [E7]
    status: open

真实 ID 如含个人或租户信息，证据包使用受控摘要；原始映射只留在权限更严格的系统。每条证据带来源查询、时间、时区、版本和摘要，派生图表也回指原始材料。

从“最后一条错误”回到“第一处偏差”

阶段	预期	观测	判定
客户端	发送一次请求	request_id=A	pass
网关	2 秒 deadline	2.01 秒返回 504	symptom
订单服务	1.8 秒内取消下游	未发送 cancel	first deviation
支付适配器	取消后停止工作	3.2 秒后完成	consequence

这时“网关返回 504”是现象，“订单服务未传播取消”才是候选根因。再做反事实实验：在同版本、同输入、同延迟下注入取消传播，若下游工作停止且资源恢复，H1 得到更强支持；若 504 仍发生，则继续寻找更早偏差。

证据等级和停止条件

A级需要受影响版本、完整关键阶段和可复现/反事实验证；B级允许不影响结论的缺口；C级只排列候选。日志时间明显漂移、关键服务无数据、版本无法定位或样本被覆盖时，必须降级，不能用架构经验补齐时间线。

验收分析 Harness 时注入相似格式的不同 ID、跨时区日志、重复重试、采样缺口和当前代码已修复但生产仍旧版等陷阱。指标包括错误归因率、结论被撤回率、平均证据缺口和从现象到首处偏差的时间。更正报告保留原结论与撤回原因，不能覆盖历史。

公开规范

OpenTelemetry Traces

规范复核日期：2026-08-22。

小规模演练

先保存原始输入摘要，再建立 ID 账本和分层时间线；只有链路完整后才验证对应版本代码。

失败注入： 故意提供一个缺字段、过期版本或无权限目标，确认流程停在预定门禁。
观测指标： 阶段覆盖率、未判定 ID 数、被后续证伪的结论数。
回滚方法： 证据缺失时降级为候选假设，不回写正式根因；错误结论应撤回并保留更正记录。