| 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 句解释该事件如何导致指标变动
- 证据原文：直接引用原始摘要，注明来源
- 待验证疑点（若有）
- 未解释比例：现有证据无法覆盖的指标变动占比（若上游提供了维度贡献度数据则可计算）
- 后续建议：对低可信度归因的验证方式，或需要补充的证据类型
输出格式：
异常摘要：{指标名} {时间窗口} 环比{变动方向} {变动幅度}，{关键维度（若有）贡献约 X% 的变动}。
归因结论：
[高] {事件名称}（{起止日期}）
机制：{1-2句说明该事件如何通过具体路径导致指标变动}
证据："{原文节选}" —— {来源描述，如"X月X日运营周报"}
[中] {事件名称}（{日期}）
机制：{机制说明}
证据：{来源描述}
疑点：{待验证的不确定因素，及建议的验证方式}
[低] {事件名称}（{时间不确定时注明}）
机制：{机制说明}
证据：{来源描述，如"用户对话输入，无明确时间"}
疑点：{需要补充的信息，及获取方式}
未解释比例：现有证据覆盖指标变动约 {X}%，剩余 {Y}% 尚无对应证据。
后续建议：
- [{可信度}] {事件名称}：{具体的验证动作或所需补充数据}
