analyze_root_cause

根因分析：异常指标 → 多步推理 → 结构化归因报告 + 透明推理轨迹。

5-Phase 编排： Phase 1: 异常确认（compute_metric × 2 取当前值 + 基线） Phase 2: 上游血缘下钻（asyncio.gather 并发，受 max_upstream_branches 限制） Phase 3: SOP 关联（可选，依据 include_sop） Phase 4: Critic+Researcher 综合（复用 Sprint 1 deep_query_service） Phase 5: 装配结构化归因报告

设计来源: design-sprint3.md v3 §4 (C13)

输入 Schema

用途

最强大 tool — RCA Agent 5-phase 编排：自动调 compute_metric + get_metric_lineage + Critic+Researcher 多轮推理 → 输出结构化归因报告。给"X 为什么下降" 这类深度问题用。

调用示例

Claude Desktop 中说："graphforge 帮我分析下准交率最近为什么下降"

JSON-RPC payload：

{
  "method": "tools/call",
  "params": {
    "name": "analyze_root_cause",
    "arguments": {
      "metric_id": "on_time_delivery_rate",
      "graph_id": "kg_xxxxxx",
      "time_range": { "from": "2024-11-01", "to": "2024-11-30" },
      "dimensions": ["region", "product_category"],
      "symptom": "准交率从 96% 跌到 91%"
    }
  }
}

返回示例

{
  "report": {
    "headline": "准交率下降 5pp 主因：华南区物流时效退化 + 高价值订单聚集",
    "root_causes": [
      {
        "rank": 1,
        "cause": "华南区物流时效从 36h 拉到 52h",
        "contribution_pct": 60,
        "evidence": "compute_metric(平均物流时效, region=华南) 历史对比"
      },
      {
        "rank": 2,
        "cause": "高价值订单聚集在末周引发产能瓶颈",
        "contribution_pct": 25,
        "evidence": "compute_metric(订单聚集度, time_grain=week)"
      }
    ],
    "recommendations": [
      "复盘华南区物流商 SLA",
      "把高价值订单产能拆周均衡"
    ]
  },
  "trace": [
    { "phase": "context", "duration_ms": 230 },
    { "phase": "metrics",  "duration_ms": 1420 },
    { "phase": "lineage",  "duration_ms": 380 },
    { "phase": "critic",   "duration_ms": 8500, "rounds": 2 },
    { "phase": "synthesis","duration_ms": 1200 }
  ],
  "rounds_used": 2,
  "total_duration_ms": 11730
}

何时用

• 用户问"X 为什么变 / 谁导致 X / 怎么修复 X"等深度问题
• 想要结构化报告（不是简单回答）
• 客户演示场景：体现"AI 不只是查询，能推理"

注意

• 单次调用 30-180s（5 阶段串行 + Critic LLM 多轮）；自研 client 必须设 200s+ timeout
• 单 phase 失败不阻塞全流程（设计 v3 §14 O4 部分失败叙事）
• 涉密客户启用 SMOKE_PII_REDACTION=on 时报告会按用户密级脱敏
• 不要在循环里调用（每次很贵）