---
name: bi-causal-attribution
description: 从运营周报、活动文档、对话输入或文档工具 API 中提取业务事件，与指标异常时间窗口对齐，生成有证据支撑的因果归因假设并排序。当已知指标存在异常波动、需要从外部文档证据中解释"为什么"时调用。
---
# bi-causal-attribution

从外部证据源（运营周报、活动记录、产品发布文档、对话输入等）中发现业务事件，与指标异常时间窗口对齐，生成有证据支撑的因果归因假设并按可信度排序。

与相邻归因技能的关系：

| 技能 | 回答的问题 | 输入 |
| --- | --- | --- |
| `bi-attribution-analysis` | **哪个维度**对指标变动贡献了多少（量化） | 结构化 CSV |
| `bi-causal-attribution`（本技能） | **为什么**发生这种变动（因果） | 外部文档证据 |
| `bi-time-impact-attribution` | 已知具体事件后，**量化其影响度** | 结构化事件列表 |


典型场景：

- "人均GAAP这周为什么下降了" → 已有异常检测结论，需从周报/活动记录中找原因
- "企业用户 Token 消耗为什么上月明显增长" → 结合产品发布记录和运营文档解释驱动因素

## 前置条件

开始前确认以下信息已就绪：

- **指标异常信息**：异常指标名称、时间窗口（起止日期）、变动方向（上升/下降）、变动幅度，来自 `bi-anomaly-detection` 输出或用户描述
- **受影响维度**（可选）：已定位的关键维度（组）值，来自 `bi-attribution-analysis` 或 `bi-dimension-drilldown`；若无则留空，维度吻合度评分将降级为中性值
- **证据源**：至少一种可用的证据来源（见步骤 2）

若异常信息不完整，需先调用 `bi-anomaly-detection` 获取。

---

## 执行步骤

### 1：构建异常锚点

整理指标异常的关键信息，作为后续事件匹配的基准，落盘至 `data/processed/anomaly_anchor.csv`：

| 字段 | 说明 | 示例 |
| --- | --- | --- |
| 指标名 | 发生异常的指标 | 国内人均GAAP |
| 异常开始日期 | 异常时间窗口起始 | 2026-06-08 |
| 异常结束日期 | 异常时间窗口结束 | 2026-06-14 |
| 变动方向 | `上升` / `下降` / `波动` | 下降 |
| 变动幅度 | 环比/同比变化值或百分比 | -12% |
| 关键维度 | 已定位的受影响维度值（选填） | 企业用户 |

---

### 2：证据源接入

支持以下两类证据源，可同时使用：

#### 2a. 对话输入 / 文件上传

证据直接出现在对话上下文或用户上传的文件中，包括：

- 运营周报（文字粘贴或文档上传）
- 营销活动计划表
- 产品发布记录
- 用户直接描述的业务事件（如"这周 618 活动在做折扣"）

处理方式：从对话上下文或文件内容中直接提取，无需额外接口调用，进入步骤 3。

#### 2b. 文档工具 API

通过工具调用从外部系统检索业务事件信息（如活动日历接口、产品发布记录接口）。

查询时，以**异常时间窗口为中心，向前扩展 7 天**构建检索范围，覆盖事件通常在指标变动前已发生的情况：

```
检索范围 = [异常窗口开始日期 - 7天, 异常窗口结束日期]
```

按以下优先级取值，命中即停：

| 优先级 | 来源 | 示例 |
| --- | --- | --- |
| 1 | 用户显式指定的接口/工具 | 用户要求"查一下活动日历接口" |
| 2 | 域知识包（若存在） | 域知识包指定活动记录接口名称 |
| 3 | 语义层接口（若可用） | 通过语义层查询业务事件配置 |

若两类来源均可用，合并结果并去重（按事件名称+时间去重）；若均不可用，终止执行并提示用户提供证据源。

---

### 3：事件提取与标准化

对每份证据内容，提取其中描述的业务事件，按以下字段标准化，落盘至 `data/processed/extracted_events.csv`：

| 字段 | 说明 | 示例 |
| --- | --- | --- |
| 事件名称 | 简洁描述事件 | 618活动折扣 |
| 开始日期 | 事件生效起始（不确定则留空，推断值需加 `[推测]`） | 2026-05-22 |
| 结束日期 | 事件生效结束（持续中则填异常窗口末尾，留空规则同上） | 2026-06-22 |
| 预期方向 | 事件对目标指标的预期效果：`正向` / `负向` / `双向` / `不确定` | 双向 |
| 影响维度 | 事件主要影响的用户群或业务维度（不确定则留空） | 企业用户 |
| 来源类型 | `结构化文档` / `周报` / `对话输入` | 周报 |
| 原文摘要 | 支撑提取结论的原文片段（100字以内） | "【来源原文节选，100字以内，直接引用，不改写】" |

**提取规则**：

- **时间不明确**：尽量从上下文推断（如"本周上线"→ 结合文档日期推算）；推断结果在日期字段加 `[推测]` 标注；完全无法推断则留空
- **方向不确定**：同一事件预期方向存在歧义（如折扣活动既拉低人均 GAAP 又拉高付费人数），标注 `双向`，不武断判断单一方向
- **重复事件**：同一事件出现在多个来源，合并为一条；`来源类型` 取可信度最高的那个
- **不相关内容**：与指标或业务无关的信息（如纯流程记录、人事通知）不提取

---

### 4：事件评分与排序

按以下优先级选择计算方式，命中即停：

#### 方式一：使用脚本

路径：`scripts/event_evidence_scorer.py`

**参数**：

| 参数 | 说明 |
| --- | --- |
| `--anomaly-file` | 异常锚点文件路径（必填，来自步骤 1） |
| `--events-file` | 标准化事件列表文件路径（必填，来自步骤 3） |
| `--output-file` | 评分结果输出路径（可选） |

**调用示例**：

```bash
python scripts/event_evidence_scorer.py \
    --anomaly-file data/processed/anomaly_anchor.csv \
    --events-file data/processed/extracted_events.csv \
    --output-file data/processed/causal_attribution_result.csv
```

**评分维度**：

| 维度 | 权重 | 计算方式 |
| --- | --- | --- |
| 时间覆盖度 | 25% | 事件时间窗口与异常时间窗口的重叠天数 / 异常窗口总天数；事件无日期信息则为 0 |
| 方向一致性 | 25% | 负向（异常为下降）或正向（异常为上升）= 1.0；双向/不确定 = 0.5；方向相反 = 0 |
| 维度吻合度 | 25% | 与关键异常维度完全匹配 = 1.0；部分匹配或事件维度未知 = 0.5；不匹配 = 0；关键维度未指定时一律 = 0.5 |
| 证据明确度 | 25% | 事件在证据中有明确记录且与异常直接对应 = 1.0；事件存在但描述模糊或为推测性关联 = 0.5；仅用户口头提及、无任何证据佐证 = 0 |

综合评分 → 可信度分级：

| 综合评分 | 可信度 |
| --- | --- |
| ≥ 0.7 | 高 |
| 0.4 ~ 0.7 | 中 |
| < 0.4 | 低 |

**输出格式**：

```
异常窗口: {开始日期} ~ {结束日期} | 方向: {上升/下降} | 关键维度: {维度值或"未指定"}

事件名称              可信度  综合评分  时间覆盖  方向一致  维度吻合  证据明确  原文摘要
{事件A}（高覆盖）       高     0.7+    0.x      0.x     0.x      0.x    "原文节选..."
{事件B}（部分匹配）     中     0.4~0.7  0.x      0.x     0.x      0.x    "原文节选..."
{事件C}（证据薄弱）     低     <0.4    0.x      0.x     0.x      0.0    "用户口头提及"
```

#### 方式二：LLM 自行推理评分

**触发条件**（满足任一即走本方式）：

| 场景 | 说明 |
| --- | --- |
| 脚本不存在 | `scripts/event_evidence_scorer.py` 文件不在项目目录中 |
| 环境无法执行脚本 | 无 Python 环境、脚本报错、无文件系统写权限 |
| 数据未落盘 | 步骤 1/3 未生成 CSV（如用户直接在对话中提供异常描述和事件，跳过了文件落盘） |
| 事件数量极少 | 提取事件 ≤ 3 条，逐条推理比调用脚本更高效 |

**执行方式**：

对步骤 3 提取的每个事件，按以下维度逐一推理打分，最终加权汇总：

**① 时间覆盖度（25%）**

事件时间窗口与异常时间窗口的重叠程度。重叠越多、越居中，得分越高；事件无日期信息或完全不重叠得分最低；完整覆盖整个异常窗口得分最高。在 0-1 之间打分。

**② 方向一致性（25%）**

事件预期对目标指标的影响方向与异常变动方向的吻合程度。方向明确一致得分最高；方向模糊（双向/不确定）居中；方向明确相反得分最低。在 0-1 之间打分。

**③ 维度吻合度（25%）**

事件影响的用户群或业务维度与已定位的异常关键维度的匹配程度。完全匹配得分最高；部分匹配或维度不明得分居中；明确不匹配得分最低；若步骤 1 未指定关键维度，则一律取中性分。在 0-1 之间打分。

**④ 证据明确度（25%）**

事件被找到、记录并与本次异常关联的清晰程度。在证据中有明确记录且可直接对应本次异常得分最高；有记录但描述模糊或关联为推测性的得分居中；仅为用户口头提及、无任何文档佐证得分最低。在 0-1 之间打分。

**综合评分计算**：

```
综合评分 = 时间覆盖度 × 0.25 + 方向一致性 × 0.25 + 维度吻合度 × 0.25 + 证据明确度 × 0.25
```

按综合评分从高到低排序，划分可信度等级后，输出与方式一相同的表格格式，进入步骤 5。

---

### 5：归因结论输出

基于步骤 4 的评分结果，生成结构化归因结论，按以下格式输出：

1. **异常摘要**：一句话描述（指标名、时间窗口、变动方向与幅度、关键维度）
2. **归因列表**（按可信度降序排列）：每条包含：
   - 可信度标注：`[高]` / `[中]` / `[低]`
   - 事件名称与时间范围
   - 因果机制说明：1-2 句解释该事件如何导致指标变动
   - 证据原文：直接引用原始摘要，注明来源
   - 待验证疑点（若有）
3. **未解释比例**：现有证据无法覆盖的指标变动占比（若上游提供了维度贡献度数据则可计算）
4. **后续建议**：对低可信度归因的验证方式，或需要补充的证据类型

**输出格式**：

```
异常摘要：{指标名} {时间窗口} 环比{变动方向} {变动幅度}，{关键维度（若有）贡献约 X% 的变动}。

归因结论：

[高] {事件名称}（{起止日期}）
     机制：{1-2句说明该事件如何通过具体路径导致指标变动}
     证据："{原文节选}" —— {来源描述，如"X月X日运营周报"}

[中] {事件名称}（{日期}）
     机制：{机制说明}
     证据：{来源描述}
     疑点：{待验证的不确定因素，及建议的验证方式}

[低] {事件名称}（{时间不确定时注明}）
     机制：{机制说明}
     证据：{来源描述，如"用户对话输入，无明确时间"}
     疑点：{需要补充的信息，及获取方式}

未解释比例：现有证据覆盖指标变动约 {X}%，剩余 {Y}% 尚无对应证据。

后续建议：
- [{可信度}] {事件名称}：{具体的验证动作或所需补充数据}
```