Troubleshooting Methodology（问题排查方法论）

知识库位置：FDE Knowledge Base/03 Engineering/Troubleshooting/Troubleshooting-Methodology.md 本目录所有 Playbook（问题排查手册）统一采用：Symptoms（症状）→ Impact（影响）→ Possible Causes（可能原因）→ Diagnostic Steps（诊断步骤）→ Fixes（修复方式）→ Prevention（预防措施）→ Escalation Criteria（升级条件）。

FDE 面对的问题通常不是：

某一段代码报错了。

而更可能是：

整个业务流程结果不对，但不知道问题在哪一层。

因此 Troubleshooting（问题排查）必须采用端到端思维。

一个典型企业系统可能是：

User（用户）
↓
Frontend（前端）
↓
API（Application Programming Interface，应用程序编程接口）
↓
Authentication（身份认证）
↓
Business Logic（业务逻辑）
↓
AI / Database / External API（AI / 数据库 / 外部接口）
↓
Workflow（工作流）
↓
Result（结果）

任何一个环节都可能导致最终问题。

第一原则：先确认问题，不要直接猜原因

用户可能说：

AI 很慢。

但「慢」可能意味着：

页面加载慢
API 慢
Retrieval（检索）慢
Model Generation（模型生成）慢
Tool Call（工具调用）慢
External API（外部接口）慢
整个 Workflow（工作流）慢

因此第一步应该是：

Vague Complaint（模糊抱怨）
↓
Observable Symptom（可观察症状）
↓
Measurable Problem（可度量问题）

例如：

「系统很慢」
↓
P95 response time = 18 seconds（P95 响应时间 = 18 秒）
↓
其中 CRM API 占 13 seconds（客户关系管理系统接口占 13 秒）

这才是可处理的问题。

Troubleshooting 七步法

Step 1：Define the Symptom（定义症状）

明确：

什么失败了？
谁遇到了？
从什么时候开始？
每次都发生还是偶发？
能否复现？

Step 2：Define Expected Behavior（定义期望行为）

必须明确：

正确结果应该是什么？

没有 Expected Behavior（期望行为），就无法判断系统是否真的异常。

Step 3：Locate the Layer（定位层级）

先判断问题在哪一层：

UI（界面）
API（接口）
Application（应用）
Data（数据）
AI（AI 层）
Integration（集成层）
Infrastructure（基础设施）

Step 4：Check Recent Changes（检查最近变更）

很多 Production（生产）问题都与最近变化相关：

Deployment（部署）
Config（配置）
Prompt（提示词）
Model（模型）
Schema（数据结构）
Data（数据）
Permission（权限）
Vendor API（供应商接口）

因此应该问：

问题出现之前发生了什么变化？

Step 5：Use Evidence（使用证据）

优先使用：

Logs（日志）
Metrics（指标）
Traces（链路追踪）
Evaluation Results（评估结果）
Query Samples（查询样本）
Tool Calls（工具调用记录）

不要只靠猜。

Step 6：Form Hypothesis（形成假设）

例如：

Hypothesis（假设）:
Retriever is returning irrelevant chunks.（检索器返回了无关内容块）

然后设计最小实验验证。

Step 7：Fix + Prevent（修复并预防）

解决当前问题后还应该问：

为什么这个问题没有更早被发现？

最终应该增加：

Test（测试）
Alert（告警）
Validation（校验）
Guardrail（护栏）
Monitoring（监控）
Documentation（文档）

Troubleshooting Decision Tree（通用问题排查决策树）

System Problem（系统问题）
      ↓
Can reproduce?（能复现吗）
├─ No（不能）
│   ↓
│ Check logs / metrics / traces（查日志/指标/链路）
│
└─ Yes（能）
    ↓
Which layer?（哪一层）
    │
    ├─ Application（应用）
    ├─ Data（数据）
    ├─ AI（AI 层）
    ├─ Integration（集成）
    └─ Infrastructure（基础设施）
          ↓
Recent change?（有最近变更吗）
├─ Yes → Compare / Rollback / Validate（对比/回滚/验证）
└─ No
    ↓
Dependency problem?（依赖问题吗）
├─ Yes → Isolate / Retry / Escalate（隔离/重试/升级）
└─ No
    ↓
Data problem?（数据问题吗）
├─ Yes → Validate / Reconcile（校验/对账）
└─ No
    ↓
Logic / Model / Configuration（逻辑/模型/配置）

AI Troubleshooting Decision Tree（AI 问题排查决策树）

Bad AI Result（AI 结果错误）
↓
Is input correct?（输入正确吗）
├─ No → Input / Data issue（输入/数据问题）
└─ Yes
    ↓
Is correct knowledge available?（正确知识存在吗）
├─ No → Data coverage issue（数据覆盖问题）
└─ Yes
    ↓
Was correct knowledge retrieved?（正确知识被检索到了吗）
├─ No → Retrieval issue（检索问题）
└─ Yes
    ↓
Did model receive correct context?（模型收到正确上下文了吗）
├─ No → Context construction issue（上下文构建问题）
└─ Yes
    ↓
Did model follow instructions?（模型遵守指令了吗）
├─ No → Prompt / Model / Guardrail（提示词/模型/护栏）
└─ Yes
    ↓
Was output parsed correctly?（输出被正确解析了吗）
├─ No → Structured Output / Application（结构化输出/应用层）
└─ Yes
    ↓
Requirement / Evaluation mismatch（需求/评估不匹配）

这张树应该成为 AI 类 Troubleshooting 的主要入口。

Integration Troubleshooting Decision Tree（集成问题排查决策树）

Integration Failed（集成失败）
↓
DNS / Network reachable?（DNS/网络可达吗）
├─ No → Network（网络问题）
└─ Yes
    ↓
TLS works?（TLS 传输层安全正常吗）
├─ No → Certificate / Proxy（证书/代理）
└─ Yes
    ↓
Authentication works?（认证通过吗）
├─ No → Credential / Token（凭证/令牌）
└─ Yes
    ↓
Authorization works?（授权通过吗）
├─ No → Scope / Role / Policy（权限范围/角色/策略）
└─ Yes
    ↓
Request valid?（请求合法吗）
├─ No → Contract / Schema（契约/结构）
└─ Yes
    ↓
Rate limited?（被限流了吗）
├─ Yes → Backoff / Quota（退避/配额）
└─ No
    ↓
Dependency healthy?（依赖健康吗）
├─ No → Vendor / Customer System（供应商/客户系统）
└─ Yes
    ↓
Application logic（应用逻辑）