# Open-source design references

本项目采用“借鉴稳定语义、保留轻量实现”的策略。引入新量化能力前先检查成熟
开源案例；除非维护成本和许可证收益明确优于本地小型实现，否则不增加框架级依赖。

## 2026-08-21：成交后归因与相对绩效

| 项目 | 借鉴内容 | 当前决策 |
|---|---|---|
| [Qlib](https://github.com/microsoft/qlib) | 信号时间与交易时间分离、成本前后超额收益分开报告 | 借鉴语义；不引入完整框架 |
| [Zipline](https://github.com/quantopian/zipline) | Ledger / transaction / portfolio value 状态模型 | 以现有 `ExecutionSimulationResult` 承担事实源 |
| [empyrical](https://github.com/quantopian/empyrical) | beta 协方差口径、alpha 几何年化、年化因子 | 移植小型公式；不增加老旧运行时依赖 |
| [Riskfolio-Lib](https://github.com/dcajasn/Riskfolio-Lib) | Euler component risk 与分组/因子风险贡献 | 只实现当前需要的 pandas/numpy 标签安全封装 |
| [PyPortfolioOpt](https://github.com/PyPortfolio/PyPortfolioOpt) | 协方差估计与优化器解耦 | 留作未来风险模型适配器参考 |

当前核心不新增依赖。逐日收益归因必须从实际换仓前后持仓、成交记录、执行价和
收盘估值推导；因子分数与目标权重只是意图，不能作为成交后归因事实源。

## 2026-08-21：研究运行工件

- 借鉴 [Qlib Recorder / RecordTemplate](https://github.com/microsoft/qlib/blob/main/qlib/workflow/record_temp.py)
  将 signal、portfolio analysis 和 risk analysis 分成稳定事实，但不引入 Qlib 运行时；
- 借鉴 [MLflow Tracking](https://mlflow.org/docs/latest/tracking/) 的 run / params /
  metrics / artifacts 分层，但 MLflow 只保留为未来可选 exporter；
- HTML、PNG 和 tearsheet 是可再生展示物，不能替代 NAV、成交、持仓、归因和绩效事实。

因此 `ResearchRunArtifact` 使用显式 `schema_version`、`config_hash`、代码版本和数据
快照身份，并提供确定性 JSON / SHA-256 manifest；核心层仍不写数据库或 artifact store。

schema `1.1.0` 将 Qlib 的独立 risk-analysis artifact 思路与 Riskfolio-Lib 的 Euler
component-risk 语义结合，但只保留本项目需要的轻量合同：协方差快照必须声明
`snapshot_id`、`as_of_date`、收益频率和年化期数；风险从成交后的实际日末持仓计算，
component risk 闭合到年化组合波动，percentage contribution 闭合到 1。未来日期、资产
标签不完整和零方差组合都直接失败，不以默认值伪造结果。

## hikyuu 的定位

[hikyuu](https://github.com/fasiondog/hikyuu) 的 SG / MM / CN / PG 部件化思想、
A 股交易约束和系统组合方式仍有借鉴价值；但其完整 C++/Python 运行时、对象模型和
数据体系不适合作为本项目核心依赖。当前原则是按真实研究链路吸收边界设计，不复制
其框架层级，也不为了“架构完整”预先建设尚无端到端需求的抽象。