Bi Causal Attribution

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 | 评分结果输出路径（可选） |

调用示例：

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 句解释该事件如何导致指标变动
• 证据原文：直接引用原始摘要，注明来源
• 待验证疑点（若有）

1. 未解释比例：现有证据无法覆盖的指标变动占比（若上游提供了维度贡献度数据则可计算）
2. 后续建议：对低可信度归因的验证方式，或需要补充的证据类型

输出格式：

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

归因结论：

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

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

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

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentscope-ai
• Source: agentscope-ai/QwenPaw-Data
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.