# Maycur AI Root Cause Analyzer

> 根因分析（AI 平台）。消费 bug-clue 的 clue.md + log-analyzer 的 logs/*.json + code-analyzer 的 code-analysis.md，证据矩阵交叉验证 → 构建根因链 → 给分级解决方案，产出 root-cause/root-cause.md。由 bug-killer 编排器调度，也支持独立模式。触发词：根因分析、根因定位、root-cause、为什么出错、排查结论。

- Skill: `jeandoom/maycur-ai-root-cause-analyzer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jeandoom/maycur-ai-root-cause-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jeandoom/maycur-ai-root-cause-analyzer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Jeandoom (https://skillmd.com/u/jeandoom)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jeandoom/maycur-ai-root-cause-analyzer

---


# 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）**：止血动作（回滚配置 / 临时加防御代码）
- **根治**：改源码 + 测试覆盖 + 监控告警

每个方案含：改动位置、影响范围、预估风险。

## 执行流程

1. 接收 `{bug_dir}` 或独立模式用户输入
2. **模式探测**：检查 `{bug_dir}/code/code-analysis.md`
   - 存在 → 编排模式，读全部上游物料
   - 不存在 → 独立模式，AskUserQuestion 收集现象/日志/代码片段
3. 编排模式：读 `clue/clue.md` + `logs/*.json` + `code/code-analysis.md`
   独立模式：基于用户输入
4. 对 code-analysis.md 的每个疑似根因点：
   - 在 logs 找支持/反驳证据
   - 三态标注（✅/⚠️/❌）
5. 构建根因链（每环节标证据来源）
6. 给分级解决方案（临时 + 根治）
7. 标注缺失信息 + 复盘建议（可选）
8. 写 `root-cause/root-cause.md`
9. 流程结束

## 物料产出 `root-cause/root-cause.md`

```markdown
# 根因分析：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 编排器汇总报告）