quant_engine/docs/OPEN_SOURCE_REFERENCES.md

Open-source design references

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

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

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

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

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

• 借鉴 Qlib Recorder / RecordTemplate 将 signal、portfolio analysis 和 risk analysis 分成稳定事实，但不引入 Qlib 运行时；
• 借鉴 MLflow 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。未来日期、资产 标签不完整和零方差组合都直接失败，不以默认值伪造结果。

2026-08-21：协方差快照估计

项目	借鉴内容	当前决策
PyPortfolioOpt risk models	将收益输入、协方差估计器和组合优化解耦；sample / EWM / shrinkage 使用统一标签输出	借鉴可替换估计器边界，不引入完整包
scikit-learn covariance	维护成熟的 Ledoit–Wolf / OAS shrinkage 实现	未来作为可选 adapter；不复制统计公式
Qlib structured risk model	PCA/FA 结构化协方差和固定随机状态	留作因子风险模型阶段，不进入当前 baseline

当前 estimate_covariance_snapshot 只编排 pandas 的 sample covariance：先按 as_of_date 截断，再取固定 session 窗口，使用 complete-case 行并拒绝历史不足；禁止 pandas 默认的 pairwise 样本集合产生含义不一致的矩阵。snapshot ID 对窗口数据、缺失掩码、上游数据 快照身份和估计参数做 SHA-256，追加未来数据不会改变历史快照。

市场适配层现以 AssetReturnSnapshot 固化 simple-return 输入：上游 ingestion snapshot ID、 数据源、价格字段、复权口径、规范化价格值和缺失掩码共同形成内容寻址 ID；不前向填充 停牌/缺失价格。该 ID 同时传入协方差快照和研究运行工件，避免同一研究链出现两套数据 身份。

可选 shrinkage adapter 的评估结论是“保留边界，暂不实现”：当前运行依赖没有声明 scikit-learn，本切片也不修改版本或锁文件。未来只有在依赖治理接受后，才以延迟导入 直接调用 scikit-learn 的 LedoitWolf / OAS，并让估计器名称、库版本与参数进入 snapshot identity；不复制成熟统计公式，也不让环境中偶然存在的包改变 baseline 行为。

hikyuu 的定位

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