aifinlab/a-share-risk-attribution

数据源

SCRIPTS="$SKILLS_ROOT/cn-stock-data/scripts"

# 各持仓股K线（计算区间收益）
python "$SCRIPTS/cn_stock_data.py" kline --code [CODE] --freq daily --start [起始日期] --end [结束日期]

# 各持仓股实时行情
python "$SCRIPTS/cn_stock_data.py" quote --code [CODE1],[CODE2],[CODE3],...

# 各持仓股财务指标（风格因子：PE/PB/市值/ROE等）
python "$SCRIPTS/cn_stock_data.py" finance --code [CODE]

# 基准指数K线（沪深300/中证500/中证全指）
python "$SCRIPTS/cn_stock_data.py" kline --code SH000300 --freq daily --start [起始日期] --end [结束日期]
# 中证500: SH000905  中证全指: SH000985  创业板指: SZ399006

Workflow (5 steps):

Step 1: 输入确认 — 组合与基准

收集归因所需信息：

• 组合持仓：代码、权重（或持仓市值）、所属行业
• 基准：默认沪深300，用户可指定中证500/中证全指等
• 归因区间：起止日期（默认最近一个季度）
• 归因类型：Brinson行业归因（默认） / 风格因子归因 / 两者都做

汇总为输入表： | 代码 | 名称 | 组合权重(%) | 行业(申万一级) | |------|------|-----------|--------------|

如果用户未提供行业分类，通过 finance 接口获取后自动映射。

Step 2: Brinson 行业归因

通过 cn-stock-data kline 获取组合各股和基准在归因区间的收益率，按行业汇总：

| 行业 | 组合权重 Wp | 基准权重 Wb | 组合收益 Rp | 基准收益 Rb | 配置效应 | 选股效应 | 交互效应 | 合计 | |------|-----------|-----------|-----------|-----------|---------|---------|---------|------|

Brinson-Fachler 模型（参考 references/attribution-guide.md）：

• 配置效应 = (Wp,i - Wb,i) x (Rb,i - Rb)
• 选股效应 = Wb,i x (Rp,i - Rb,i)
• 交互效应 = (Wp,i - Wb,i) x (Rp,i - Rb,i)
• 超额收益 = 配置效应 + 选股效应 + 交互效应

汇总：

• 总超额收益 = 组合收益 - 基准收益
• 配置效应合计 / 选股效应合计 / 交互效应合计
• 最大贡献行业 / 最大拖累行业

Step 3: 风格因子归因

通过 finance 获取各股财务指标，构建因子暴露矩阵，用回归法拆解收益：

常用因子： | 因子 | 代理变量 | 说明 | |------|---------|------| | 市场(Beta) | 组合 vs 基准 | 系统性风险 | | 规模(Size) | ln(总市值) | 大/小盘偏离 | | 价值(Value) | 1/PE 或 BP | 价值/成长风格 | | 动量(Momentum) | 过去3-6月涨幅 | 追涨/逆向 | | 波动率(Volatility) | 近期日收益率标准差 | 高/低波偏好 | | 质量(Quality) | ROE | 盈利质量 |

输出因子归因表： | 因子 | 组合暴露 | 基准暴露 | 主动暴露 | 因子收益(%) | 因子贡献(%) | |------|---------|---------|---------|-----------|-----------|

残差项 = 超额收益 - 各因子贡献之和（代表个股 alpha）

Step 4: 时间序列分解（仅 formal 模式）

将归因区间按月拆分，展示归因效应的时间演变： | 月份 | 组合收益 | 基准收益 | 超额收益 | 配置贡献 | 选股贡献 | 交互贡献 | |------|---------|---------|---------|---------|---------|---------|

识别：

• 超额收益的持续性 vs 偶发性
• 归因效应的稳定性（是否依赖单月大幅超额）
• 投资能力评估（配置能力 vs 选股能力）

Step 5: 输出

风格说明

| 维度 | formal（机构绩效归因报告） | brief（快速归因摘要） | |------|--------------------------|---------------------| | 篇幅 | 4-8 页 | 1-2 页 | | Brinson 归因 | 完整行业归因表 + 瀑布图描述 | Top 3 贡献/拖累行业 | | 因子归因 | 完整因子暴露与贡献表 | 主要因子贡献一句话 | | 时间分解 | 按月归因表 + 趋势分析 | 省略 | | 投资能力评估 | 配置能力/选股能力/IR评价 | 一句话定性评价 | | 可视化 | 瀑布图/堆叠图/热力图描述 | 省略 | | 免责声明 | 需要 | 不需要 |

关键规则

1. 数据完整性：归因区间内所有持仓股必须有完整K线数据，缺失时提示用户
2. 基准一致性：行业分类标准需与基准成分股行业分类一致（默认申万一级行业）
3. 权重归一化：组合权重和基准权重需分别归一化至100%
4. 区间要求：归因区间至少1个月，建议1个季度以上以获得有意义的结果
5. 残差控制：Brinson 归因中配置+选股+交互应精确等于超额收益，不应有残差
6. 因子归因局限性：明确说明回归法因子归因受样本量和多重共线性影响，结果为近似
7. 与其他 skill 联动：对选股贡献突出的行业可用 a-share-sector 深入分析，对个股 alpha 可用 a-share-earnings-analysis 追溯
8. 多期归因：如区间超过1个季度，采用 Carino 链接法进行多期归因，确保各期可加性

使用示例

示例 1: 基本使用

# 调用 skill
result = run_skill({
    "param1": "value1",
    "param2": "value2"
})

示例 2: 命令行使用

python scripts/run_skill.py --input data.json