联调阶段最容易让人焦虑，因为问题往往既不像纯代码 bug，也不像纯配置错误。前端说“返回不对”，后端说“我这边能跑”，日志里有信息但不成体系，群里消息越来越多，排查路径却越来越散。AI 在这个阶段最有用的地方，不是替你宣布根因，而是帮助你把证据整理清楚、把假设空间压小。
真实研发场景
真正拖慢排查的，往往不是“问题太难”，而是“信息太散”
一个典型的联调问题可能同时包含这些碎片：
- 一个失败请求的参数
- 一个响应体或错误码
- 几段零散日志
- 一份并不完全同步的接口说明
- 一段相关控制器代码
- 一个“本地复现不了”的口头结论
这些碎片各自都不算少，但因为没有被放在同一张证据图里，排查就会很容易变成“谁声音大听谁的”。
本课要建立的是“证据包 -> 假设 -> 验证”的排障秩序
AI 在排障时最稳的作用，是先做事实整理，然后再根据事实列出可能原因与优先排查顺序。只要这个顺序被打乱，模型就会开始补脑，把某个偶然线索扩写成“看起来很像根因”的解释。
传统做法的痛点
排查发散通常来自四类割裂
| 割裂点 | 常见表现 | 后果 |
|---|---|---|
| 日志与请求割裂 | 只有报错，没有对应请求上下文 | 无法判断问题发生条件 |
| 契约与实现割裂 | 接口说明和真实返回结构不一致 | 前后端互相怀疑 |
| 配置与环境割裂 | 本地、测试环境、CI 配置不同步 | “我本地没问题”失去意义 |
| 结论与证据割裂 | 大家先说猜测，再补证据 | 排查顺序被情绪带偏 |
排障效率低，很多时候不是因为团队没有能力，而是没有先建立统一的问题组织方式。
最常见的三个排查误区
- 只把一段报错文本贴给 AI，不附上请求、响应和上下文
- 让 AI 直接判断根因，而不是先做事实整理
- 问题修好了，但复现路径和最终结论没有沉淀
AI 能提效到哪一步
AI 最适合做的排障辅助
- 事实整理：把请求、响应、日志、代码片段按时间和层级整理
- 差异对照：对比“期望返回”和“实际返回”之间的差别
- 假设排序：根据现有证据给出优先排查项
- 复现说明草稿：整理稳定复现步骤和修复前后差异
AI 不该替代的动作
| 动作 | 为什么不能直接外包 |
|---|---|
| 宣布根因成立 | 根因必须被真实验证，而不是被合理化 |
| 决定先改哪段代码 | 需要结合业务影响和环境事实 |
| 判断问题是否完全解决 | 需要再次联调、测试或复现 |
一个关键原则是：AI 可以帮你收敛排查路径，但不能代替证据完成证明。
推荐工作流
先准备一份证据包
一个最小可用的排障证据包通常应包含：
- 出问题的请求样本
- 实际响应或错误堆栈
- 相关日志片段
- 相关代码路径
- 相关配置或环境信息
- 期望行为描述
五步联调排障法
| 步骤 | AI 产出 | 人工要做什么 | 验证方式 |
|---|---|---|---|
| 1. 组证据包 | 事实整理稿 | 删除噪音，补缺关键证据 | 是否还存在关键信息空洞 |
| 2. 分事实与推测 | 两栏问题说明 | 防止把猜测当结论 | 是否能清楚区分已知和未知 |
| 3. 排优先级 | 假设清单与排查顺序 | 去掉不值得先查的项 | 是否优先验证高概率 / 高影响项 |
| 4. 逐项验证 | 复现步骤与核对点 | 不跳步、不并行乱改 | 每次验证是否能缩小范围 |
| 5. 沉淀结论 | 最终根因与修复记录 | 写清前提、证据和修复结果 | 后续能否快速复用 |
一个适合排障阶段的输入模板
md
问题现象：
期望结果：
请求与响应：
关键日志：
相关代码路径：
相关配置或环境差异：
请输出：
1. 事实整理
2. 待验证假设
3. 建议排查顺序
4. 复现步骤草稿
与仓库代码和模板的映射
- 请求日志锚点：
../demo/src/main/java/com/example/ainative/ops/logging/RequestLogFilter.java适合说明请求方法、URI、状态码和耗时为什么要成组出现。 - 健康检查基线：
../demo/src/main/java/com/example/ainative/common/health/HealthController.java适合建立“先确认服务基本可用”的排障起点。 - 接口与流式响应：
../demo/src/main/java/com/example/ainative/chat/controller/ChatController.java适合讨论同步接口和流式接口联调关注点为何不同。 - 环境与配置：
../demo/src/main/resources/application.yml适合检查 provider、模型、基础设施地址等环境差异。 - 对应练习：
../课后练习/第6课/练习.md
常见误用与风险
误用一：只把异常文案丢给 AI
没有请求上下文、日志和代码片段时，模型只能猜。
误用二：AI 说了一个根因，就直接开始改代码
排障最怕跳过验证，把“合理解释”误当成“已证实事实”。
误用三：没有记录复现路径
问题哪怕修好了，如果团队不能复现，就很难确认是否真的根除。
误用四：把契约问题误判成实现问题
很多联调争议并不是逻辑错，而是双方对契约理解不一致。
课后练习
建议直接在 ../课后练习/第6课/练习.md 中完成本课练习，并使用 ../课后练习/通用提交模板.md 保留 AI 输入、人工删改和验证结果。
如果你只做最小版交付，也至少保留四样东西：结构化输入、AI 产出摘要、人工判断记录、最终验证结果。
基础题
选一个接口异常或测试失败场景，整理一份最小证据包。
进阶题
让 AI 基于证据包输出“事实 / 推测 / 优先排查项”三栏说明，再人工修订。
挑战题
产出一份可以交给他人复现的问题记录，包含现象、证据、根因、修复和验证结果。