设计：量化工作流全景 + 目录结构精修

2026-06-25。统一约定本项目的数据 / 因子研究 / 策略研究 / 效果检测 / 报告 / 实盘各工作流,以及支撑它们的目录结构与"积木抽离"重构。仅研究学习,不构成投资建议。

1. 背景与目标

项目已有可用的内核(src/quant)、研究脚本、VitePress 报告站、3.10 venv(skfolio/rqalpha)。本设计要解决三件事:

1. 明确工作流:数据底座之上,分"研究环"(因子/策略研究)和"实盘环",以验证过的策略类为支点连接。
2. 结构能承载多策略:加第二个策略(如均值回归)时不靠复制粘贴,而是组合共享积木。
3. 研究入口统一为 notebook,报告经 nbconvert 导出 markdown → VitePress。

2. 工作流全景

数据底座(共享): tushare → 缓存parquet → PIT对齐 → 池子构建
        │
   ┌────┴────┐
   ▼         ▼
① 因子研究   ② 策略研究        (notebook,import 内核,不重写)
 IC/分层      信号+组合+风控+回测+消融
 → 因子库      → ③ 验证(walk-forward) → ④ 报告(nbconvert→docs→VitePress)
                       │
                ✓ 策略类 src/quant/strategy  ← 研究/实盘支点
                       │ ⑤ 冻结(pin/.pyz)
                       ▼
                ⑥ 实盘(Windows): 调度→取数→算权重→xtquant→miniQMT
                       │
                ⑦ 监控 · 对账(上线后补)

3. 目录结构(精修后;🆕=新增,★=重构)

notebooks/                 研究主体(每研究一个 .ipynb,含输出进 git)
src/quant/
  data/                    取数/池子/日历(现有)
  factors/                 因子: base/registry/preprocess(含 neutralize)/library/(现有)
  research/                因子效果检测: ic/layering/single_factor/fundamental/correlation(现有)
  strategy/
    signals.py        🆕   通用信号: 动量·z-score·RSI·突破 + 选择助手(从 momentum_rotation 抽出)
    risk_layers.py    🆕   可复用风控: 趋势过滤·波动目标·熔断·cap·regime降仓·★止损(抽出)
    regime.py              ER/ADX 行情识别(现有)
    risk_parity.py / skfolio_opt.py / herc.py / dynamic.py   加权/优化(现有)
    momentum_rotation.py ★ 瘦身: 只留 MomentumRotationStrategy,组合上面积木
    mean_reversion.py 🆕   新策略示范: z信号 + 反向regime门 + 止损,组合同样积木
  backtest/
    portfolio.py           日历再平衡回测(现有)
    event.py          🆕   阈值/信号触发回测(均值回归进出场)
    evaluate.py       🆕   策略效果检测编排: 回测→指标表+消融+基准+tearsheet
    validation.py     🆕   防过拟合: walk-forward/样本外/参数稳健
    cost.py / engine.py    A股费用·涨跌停 / qlib topk(现有)
  reports/                 metrics(指标原语)/factor_research/factor_report/plots(现有,只管渲染)
scripts/                   收敛为工具: 取数缓存、nbconvert 导出助手(不再是研究主体)
live/                  🆕   实盘: 薄入口 + 配置 + 冻结/打包脚本 + (Windows)调度模板
docs/                      报告(notebook 导出)+ specs

核心动作:把 momentum_rotation.py 里的通用函数(risk_adjusted_momentum/select_top_capped/trend_filter/vol_target_scale/cap_weights/CircuitBreaker)抽到 signals.py 与 risk_layers.py。 抽完后任何策略都从同一套积木组合。

4. 关键契约(各流程之间靠什么衔接)

• 因子研究 → 因子库:通过检验(|RankIC|>0.03 + ICIR + 分层单调)的因子注册进 factors/library。
• 策略研究 → 策略类:产物是 strategy/ 下一个纯类,统一接口 __call__(date, nav) → {code: weight};放行需验证过关 + 消融证明风控加分。
• 支点:策略类是研究与实盘唯一共用的东西——研究 import 它探索,实盘冻结同一个类 + 执行适配器。接口不变 → "一份逻辑两个外壳"。
• 冻结:实盘 pin 发布版本 / 打 .pyz,永不跟随研究分支变动。

5. 因子研究流程

取数(PIT) → factors/ 算因子 → preprocess 中性化 → research/fundamental 组面板 → research/single_factor(或 alphalens)检验 → notebook 叙事+图 → nbconvert 导出 docs/ → VitePress。产物=因子入库。

6. 策略研究流程(通用;动量/均值回归同一条)

定edge → 取数+池子 → signals 构造信号 → regime 适用性 → 选择+加权 → risk_layers 风控 → backtest 回测 → evaluate 消融/基准 → validation 验证 → 报告。

同一条流程,每个策略只换"插槽":

插槽	动量(已做)	均值回归(新)
edge	趋势持续	过度反应、偏离拉回
信号	风险调整动量(60日,跳5日)	z-score=(价−MA)/std、RSI、布林%b、配对价差z
选择	top-N 最强	bottom-N 最超卖 / 阈值进场(z<−2)
regime 门	趋势满仓、震荡降仓	反过来: 只在震荡态做、趋势态空仓
加权	风险平价	等权/逆波动、仓位更小
风控重点	趋势过滤·波动目标·熔断	止损必须·时间止损·单仓限额
调仓/回测	周频日历(portfolio.py)	信号事件触发(event.py)

7. 策略效果检测(放哪)

• 指标原语(年化/夏普/回撤/换手):reports/metrics.py(已有)+ quantstats(额外专业指标)。
• 效果检测编排(回测→指标表+消融+基准对比+tearsheet):backtest/evaluate.py(对应因子侧 research/single_factor.py)。把现在散在 run_momentum_rotation.py 的 perf()/消融循环/write_report 抽进来。
• 验证/防过拟合(walk-forward/样本外/参数稳健):backtest/validation.py;skfolio 的 walk_forward 已在 strategy/skfolio_opt.py。

对称:research/=因子效果检测;backtest/{evaluate,validation}=策略效果检测;reports/只渲染。

8. 报告与 VitePress

notebook 是源 → nbconvert --to markdown 导出 docs/analysis/<名>.md + <名>_files/(图天然 co-locate、相对路径)→ VitePress 渲染。重型 tearsheet(quantstats HTML)作附件链接。.ipynb 进 git 时由 nbstripout 自动剥输出(原计划"含输出直接提交",改用 nbstripout:本地保留输出看、git 只存干净代码,报错/图/计数不进库)。

9. 实盘流程

冻结(pin/.pyz) → live/ 薄入口 + 执行适配器(xtquant→miniQMT,Windows同机) → Windows Task Scheduler 周一开盘前触发 → 判交易日→取数→用冻结策略类算权重→幂等下单→回报 → 监控/对账。宿主=常开 Windows 云服务器。ops 清单:交易日判断、幂等防重、失败告警、状态持久化、对账、kill-switch、先纸面跑。

10. 重构动作清单(实现计划据此展开)

1. 抽 strategy/signals.py + strategy/risk_layers.py,momentum_rotation.py 改为 import 它们(行为不变,测试全绿)。
2. backtest/evaluate.py + validation.py:抽离脚本里的绩效/消融/验证逻辑。
3. backtest/event.py:事件触发回测路径 → 实现时发现不需要:事件驱动(均值回归进出场)= 日频调仓 + 有状态 weight_fn,现有 run_rebalance_backtest 即可承载,不另建引擎(YAGNI)。
4. notebook 迁移:先把 run_momentum_rotation 转成范例 notebooks/,打通"import→回测→inline图→nbconvert→VitePress",其余脚本按同模板增量迁移。
5. .venv 加 [notebook] extra(jupyterlab + nbconvert)。
6. 新策略 mean_reversion.py 作为第二个范例,验证"组合积木"。
7. CLAUDE.md 据本设计重写工作流各段。

11. 其他工作流(YAGNI 取舍)

工作流	判断
验证/防过拟合	✅ 现在做(=backtest/validation.py)
数据质量监控	✅ 现在做(取数加校验,轻量)
复盘/对账、风险监控告警	⏳ 实盘上线后补
多策略配权	🚫 暂不(等 ≥2 个实盘策略)
实验/参数追踪(mlflow)	🔵 可选(现在 notebook+CSV 够)

12. 非目标(YAGNI)

不做:实时高频/分钟级框架、多券商抽象、自动调参/AutoML、把回测引擎换成 vectorbt/zipline(自研 + rqalpha 够用)、metrics 强行换 empyrical(口径透明的自研保留)。