bi-causal-attribution

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

调用示例：

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}% 尚无对应证据。

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