反事实推理引擎

要解决什么问题

政策或干预发生后，你往往既想知道「效应有多大」，又想知道「机制上可能怎么起作用」。纯问大模型「要是没发生会怎样」容易把缺口和机制混在一起猜；只做合成控制又很难把溢出、均衡调整等机制讲清楚。CounterfactAgent 把定量估计和定性叙事放在同一条分析链路里：有面板时先算反事实轨迹，再用 LLM 按机制类型组织解释，并对每条论断打置信度与证据等级。

双通道如何工作

定量通道用纯 numpy/scipy 实现 Abadie 等人（2010）的合成控制法：你指定干预时点、处理单元、结果变量，并提供可比单元的捐赠池（干预前协变量与结果序列）。引擎在权重非负且和为 1 的约束下用 scipy.optimize.minimize 拟合合成对照，处理效应即观测与合成反事实轨迹的缺口；并对捐赠池内各单元做安慰剂检验，便于对照效应是否异常。

定性通道由 LLM 生成结构化机制叙事，按类型划分：直接效应、溢出效应、均衡调整、异质性响应。每条主张带四级置信标签（HIGH_CONF / MED_CONF / LOW_CONF / SPECULATIVE），并在 A/B/C/D 证据质量尺度上评级。最终由 Reporter 汇总为 AnalysisResult：事件框架、捐赠权重、效应估计、安慰剂结果、机制叙事与整体置信讨论。

边界与注意点

• 这不是通用因果推断库（不含 DiD、RDD、IV 等）；也不自动从外部拉数构建捐赠池，数据需你自备或构造。
• 除安慰剂检验外，不做正式假设检验；不适合实时流式场景。
• 定量部分不依赖 LLM；捐赠池过稀或干预前观测过少时，会更多依赖定性通道，置信标签会如实反映这一点。
• LLM 叙事是推理辅助，不能替代领域专家判断；应与定量缺口和外部证据交叉验证。