Jeandoom maycur-ai-root-cause-analyzer — 根因分析
链路第四环（终点）：消费全部上游物料（clue + logs + code-analysis），综合三方证据构建根因链，给出分级解决方案，产出 root-cause/root-cause.md 供 bug-killer 编排器汇总。
Claude vs 脚本分工
| 角色 | 职责 |
|---|---|
| Claude | 读 clue/logs/code-analysis → 证据交叉验证 → 构建根因链 → 分级解决方案 → 写 root-cause.md |
| 无 Python 脚本 | 综合推理、证据矩阵构建都是 Claude 强项 |
输入源（消费全部上游物料）
| 来源 | 提取什么 |
|---|---|
clue/clue.md |
现象描述、entCode、env、traceId、时间窗、异常关键字 |
logs/sls-logs.json |
实际日志内容、堆栈、异常发生时间点 |
logs/langfuse-trace.json |
trace observation、LLM 调用链、错误节点 |
code/code-analysis.md |
定位文件、数据流、疑似根因点（输入候选） |
| 用户输入（独立模式） | 现象描述 + 粘贴的日志/堆栈 + 代码片段 |
核心动作：对 code-analysis.md 列出的每个疑似根因点 → 在 logs 找支持/反驳证据 → 三态标注 → 构建根因链 → 给解决方案。
核心推理流程
① 证据矩阵（对每个疑似根因点）
| 候选点 | 状态 | 日志证据 | 代码证据 |
|---|---|---|---|
baz.py:88 save 未判空 |
✅ 确认 | sls 日志含 NPE 堆栈命中此行 | code-analysis 数据流终点 |
bar.py:42 入口未校验 |
⚠️ 待证 | 无直接日志 | 代码结构推断 |
| 其他候选 | ❌ 排除 | 日志时间窗不符 | ... |
三态标准：
- ✅ 确认：日志 + 代码双重证据支持
- ⚠️ 待证：单一证据（仅代码或仅日志推断），缺关键证据
- ❌ 排除：证据反驳（时间窗不符 / 堆栈未命中 / 数据流不通）
② 根因链构建
[触发] 用户传入 null 参数（依据：trace observation input）
→ [传播] ServiceA 未校验直接传给 RepoA.save（依据：code-analysis 数据流）
→ [爆发] DB 写入抛 NPE @ baz.py:88（依据：sls 日志 NPE 堆栈）
每环节必须标注证据来源（来自哪个上游物料）。
③ 解决方案分级
- 临时（hotfix）：止血动作（回滚配置 / 临时加防御代码）
- 根治：改源码 + 测试覆盖 + 监控告警
每个方案含：改动位置、影响范围、预估风险。
执行流程
- 接收
{bug_dir}或独立模式用户输入 - 模式探测：检查
{bug_dir}/code/code-analysis.md- 存在 → 编排模式，读全部上游物料
- 不存在 → 独立模式，AskUserQuestion 收集现象/日志/代码片段
- 编排模式：读
clue/clue.md+logs/*.json+code/code-analysis.md独立模式：基于用户输入 - 对 code-analysis.md 的每个疑似根因点：
- 在 logs 找支持/反驳证据
- 三态标注（✅/⚠️/❌）
- 构建根因链（每环节标证据来源）
- 给分级解决方案（临时 + 根治）
- 标注缺失信息 + 复盘建议（可选）
- 写
root-cause/root-cause.md - 流程结束
物料产出 root-cause/root-cause.md
# 根因分析：bug-{id}
## 结论摘要
- **根因**：一句话描述
- **置信度**：高/中/低
- **影响范围**：entCode / 单据号 / 时间段 / 用户量
## 根因链
[触发] xxx（依据：来源）
→ [传播] xxx（依据：来源）
→ [爆发] xxx（依据：来源）
## 证据矩阵
| 候选点 | 状态 | 日志证据 | 代码证据 |
|--------|------|----------|----------|
| ... | ✅/⚠️/❌ | ... | ... |
## 解决方案
### 临时（hotfix）
- 立即动作：xxx
- 止血范围：xxx
### 根治
- 改动 1：`file:line` 加 xxx（影响：本路径 / 风险：低）
- 改动 2：`file:line` 入口参数校验（防御性 / 风险：低）
- 测试：补 xxx case
- 监控：建议加 xxx 告警
## 缺失信息
- 缺 xxx 日志 → 建议补埋点（下次复现时收集）
- 缺 xxx trace → 无法 100% 确认传播路径
## 复盘建议（可选）
- 测试覆盖：xxx
- 监控告警：xxx
- 流程改进：xxx
字段说明：
- 结论摘要：下游 bug-killer 编排器汇总报告直接引用
- 根因链：含证据来源标注（可追溯到上游物料）
- 证据矩阵：每个候选点的状态 + 双重证据
- 解决方案：分级（临时/根治）+ 影响范围 + 风险
- 缺失信息：诚实标注证据缺口 + 补全建议
- 复盘建议：可选，预防同类问题
边界
- 不重新查日志/trace（log-analyzer 职责，用上游物料）
- 不重新定位代码（code-analyzer 职责，用上游物料）
- 不做代码修复（code-dever 职责，P1）
- 不做 git 提交/MR（code-manager 职责，P1）
- 不写 Python 脚本（纯 Claude 综合推理）
依赖
- bug-clue-analyzer（上游）：
clue/clue.md - log-analyzer（上游）：
logs/sls-logs.json+logs/langfuse-trace.json - code-analyzer（上游）：
code/code-analysis.md（核心输入：疑似根因点候选） - 无下游 analyzer 依赖（产物给 bug-killer 编排器汇总报告）