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