我们怎么筛因子

§00怎么用这份文档

这份手册是操作手册，回答"怎么做"。团队的 onboarding 报告 （onboarding_report_zlj/）是叙事报告，回答"为什么"。两份配套看，不重复。

一个因子的完整生命周期

§01前置：不干净的数据不配谈因子

这一节不是背景知识，是开工前的六条必检。历史上最贵的几次翻车 都不是因子设计错了，是环境不干净——整轮 V8 探索（83 组矩阵）的"+pp"几乎全是数据 bug 造出来的人工产物。

1. 时间窗：永远显式传 start / end

引擎默认 --start-date 2023-03-10、--end-date 2025-12-31， 两个默认值都会坑人。

2. 环境变量：guard 会静默 fail-open

回测脚本不读 .env，必须自己导出：

set -a; source .env; set +a   # 导出 MASSIVE_API_KEY

build 日志里必须出现 MASSIVE_API_KEY present: yes。拿不到 key 时 build_spy_guard_map 返回空 map，整个 SPY MA20 risk-off 层静默消失， 日志只留一行 guard disabled: Massive API key not found。

3. daily_bars：目标状态是"一票一文件"

daily_bars/ 按 {ticker}_{start}_{end}.parquet 存，增量拉取会堆多版本 （某只票堆过 49 个，SPY 约 40 个）。_pick_best_daily_file 按"实际数据结尾最新"挑， 于是窄窗口、end=今天的文件会遮蔽宽文件。

• 症状：当天跑不受害（end 打平、宽文件胜出），隔几天复现必爆。 2026-07-05 复现时 ret_5d 覆盖率从正常的 99.5%+ 掉到 90.3%，7,295 行被 warmup-drop，10f 少 256 笔。
• 修法：python3 claude_explore/daily_bars_prewarm_zlj.py --base <base.parquet> （预热 2022-12 至今的宽文件，让 picker 的 tiebreak 必胜，不删文件）。
• 验证：build 日志 history_short<300、Dropped ~1200。 修后 10f asof0623 对齐同事到 0.2%（1787 / 1790 笔，MaxDD 10.93 精确一致）。

4. massive_cache 的三类陷阱

排查顺序：先比 build_base_xy_meta.json 的 price_status_breakdown 七个字段定位 → 行数不对用 #1 / #2 → 行数对但收益差用 purge-year → 都做完才考虑找同事要 tarball。

5. delta build 的特征 NaN 陷阱

build_bigopen_v9_opportunities.py --start-date <窗口起点> 的增量模式下， stage1 按"该 ticker 在本次构建里的最早信号日"开始加载分钟线，不带 rolling 特征所需的 lookback：

判据：merge 后查窗口行 dvol_10d_ratio 的 NaN 率，>10% 即中招 （本底 NaN 率 6.9% / 4.5% 是设计内的"首 30 session"情况）。 修法：跑 fix_base_features_zlj.py（stage1 同款公式从本地分钟缓存补算，已验证与 live 在线函数逐位一致）， 或把 delta 起点提前 ≥40 个交易日再截取。8f 时代没有 dvol / rv3d，所以旧流程从没暴露过这个坑。

6. pandas 3 的 µs / ns 精度陷阱

pandas ≥3 默认 datetime64[us]。Series.astype("int64") 返回微秒， 但 Timestamp.value 恒为纳秒，两者进 np.searchsorted 差 1000 倍。

排查法：grep 所有作用在 datetime Series 上的 astype("int64")。 同事的 pandas 2.x 环境不触发，所以他们的报告数字没错，是复现环境炸。

还有一条：只信同会话 delta

§02基线、口径与生产数字

三阶段流水线

Stage 1-1  stage1_1_fetch_minute_bars.py   →  massive_cache/*.parquet   (唯一的网络 I/O)
Stage 1-2  build_bigopen_v9_opportunities  →  base_xy.parquet           (离线确定性, 含标签 y_2d)
Stage 2    build_factors.py                →  signal_table.parquet      (因子打分, 秒级)
Stage 3    run_backtest_v9.py              →  portfolio_report.json     (SPY MA20 guard)

标签 y_2d 与 entry_price / exit_price / exit_reason 在 Stage 1-2 就定死， 因子永远不重算标签。score_raw 只在 Stage 2 产生。

探索基线：8 核

iv  stock_price  otm  asset_type  rule_hit  time_slot  nbp3d_low  ret_5d_roll_deep

按年：2023 +25.16% / 2024 +104.29% / 2025 +197.40% / 2026（1–4 月）+15.51%。 窗口必须 --start-date 2023-04-20 --end-date 2026-04-27。

当前生产口径（asof0810, 全部同一底表 + 同一张 scored 表，可跨档直接比）

score_raw 实测区间：10f [−9, +11] / 11f [−10, +11]（68,923 行）。准入门槛 min_score = 6。

数字为什么会漂：一定要标 asof

§03五层抽象与"一次只改一层"

动手之前先把策略拆成五层，想清楚这次改的是哪一层。 这是通用研究工作流（skills/youthquant-strategy-research/SKILL.md）的开篇， 也是最常被跳过、代价最大的一步。

版本四分类

每轮实验结束后，把结果明确归到一档，不要含糊：

只在样本内提升收益、却带来大量实现复杂度或一致性风险的实验，默认停在 candidate 或 research-only。

§04四阶段漏斗

固化在 /explore-factor 里。判官是 8 核生产基线。 任一关不过即停——不要"再调调看"。

Phase 1 — 单因子分层检验

用 base_xy + builder 输出的 feature cache，做四件事：

1. 过滤：可交易资产 + OTM 5%–50%
2. 分桶（quintile）：每桶 mean(y_2d)、N、t-stat
3. ANOVA F 检验
4. Spearman 相关性矩阵：对 score_raw、nbp3d_score_low、ret_5d_score_low、stock_price_score

Phase 2 — 信号层对比

baseline = 8 核 score_raw。新因子加进去之后，看它能不能把 score ≥ 6 / 7 的 边缘信号"提拔"成真正值得交易的票。这一步是为 Phase 4 的"真 promote ratio"做铺垫。

Phase 3 — 8 核组合回测（关键判官）

# 1. build 含新因子的 signal_table
python3 claude_explore/build_factors_zlj.py \
  --base exp_result/bigopen_v9_base_asof0427/bigopen_v9_stage1_base_xy.parquet \
  --factors iv stock_price otm asset_type rule_hit time_slot nbp3d_low ret_5d_roll_deep <new_factor> \
  --out-dir claude_explore/scored_v9_8core_with_<new>_zlj

# 2. 回测 + baseline 对照（注意时间窗）
python3 run_backtest_v9.py \
  --signals claude_explore/scored_v9_8core_with_<new>_zlj/signal_table.parquet \
  --factors iv stock_price otm asset_type rule_hit time_slot nbp3d_low ret_5d_roll_deep <new_factor> \
  --min-score 6 --capital 5000000 --leverage-ratio 1.0 \
  --start-date 2023-04-20 --end-date 2026-04-27 \
  --out-dir results/bt_v9_8core_<new>_zlj

Phase 3.5 — build 前必答的一句

Phase 4 — 九维严格审视

见 §06。工具 claude_explore/critical_analysis_v2_zlj.py。

完整落地步骤

1. 数据探索写 analyze_*_zljcc.py 做 Phase 1 检验（做完即弃的小脚本）
2. Builder放 claude_explore/utils_zlj/，必须用 codex global dedup 模式（见 §05 关 3）
3. Factor 类放 claude_explore/factors_zlj/，继承同款 FactorBase / RollingIcFactor，签名照抄主干 factors/
4. 注册在 claude_explore/factor_registry_zlj.py 注入主 registry，主干 factor_registry.py 不动
5. Build + 回测用 wrapper（自动注入 zlj 因子）
6. Phase 4 审视跑 critical_analysis_v2_zlj.py
7. 报告写成 reports/<topic>_exploration.md 风格的活模板（见 §09）
8. 若全绿写 PR 描述给用户确认，由用户提 PR 迁入主干

§05判据电池 · 9 关

§04 是流程，这 9 关是判据。核心只有一个问题： 这个 +pp 是真 alpha，还是过拟合、伪装、或者单年异象？ 任一关塌了就毙。每一关下面都挂着一个在这关上摔死的真实因子。

# Step 1+2: streaming hash dedup（7.6GB 内存机器友好）
seen = set()
for chunk in chunks:
    df = pd.read_csv(chunk, dtype=str, usecols=DEDUP_KEY)
    hashes = pd.util.hash_pandas_object(df[DEDUP_KEY].fillna(""), index=False).values
    new_mask = np.fromiter((h not in seen for h in hashes), dtype=bool, count=len(hashes))
    ...

# Step 4: 按 ticker 分组（不是按 (ft, fd)！），双时间条件 AND
mask = ((flow_time_utc >= sig.signal_time_utc - 14d) &
        (flow_time_utc <  sig.signal_time_utc) &
        (flow_time_et_day < sig.signal_time_et_day))

pd.Series([pd.Timestamp('2023-03-10 09:30:00').tz_localize('US/Eastern')]).values[0]
# 输出 14:30（UTC naive），不是 09:30（ET）→ 立刻意识到陷阱

§05b判据阶梯 · 10 级

9 关是原则，这 10 级是硬线——每一条都是被某个具体因子逼出来的， 按它们出现的时间排。复查别人的 PR 时对着这张表走最快。

§06九维健康度与判决

Phase 3 只证明"组合数字变好"。Phase 4 回答"变好的方式健不健康"。 工具：claude_explore/critical_analysis_v2_zlj.py（解析 base 与 +factor 两份 executed_trades.csv，输出九项指标）。

单独说一句：真 promote ratio（最难的一项）

这一项问的是：因子新提拔上来的信号（5→6 分），和原本就 6 分的信号一样好吗？ 如果新提拔的明显更差，说明因子在往门槛里塞垃圾，即使总 PnL 上去了也是靠数量堆的。

十条最常踩的陷阱（/explore-factor 原表）

§07阈值与 rolling 校准（反数据窥探）

整数纪律：两位小数的阈值一律怀疑

响应：对 [0.70, 0.85] 跑 robustness sweep，看是 plateau（信号 robust）还是 sharp peak（过拟合）。

最终选 0.80，四条理由：(a) 整数物理含义清晰——"低于历史基线的 80%"； (b) 跨 asof 一致，不踩任何一个 in-sample 峰（asof0511 的峰是 0.78，特意不取； 0.85 在 asof0511 塌过但在 asof0601 最好）；(c) MaxDD 改善幅度与 plateau 其他点一致； (d) 跨四年 mean_pnl 三正一负且总体改善。

rolling 因子的两段式构造

1. Stage 1 — 每日 IC 搜阈值训练窗 [D−97, D−7)。 那个 7 天 gap 是关键：2 日标签需要时间 settle，不留 gap 就是前瞻。 训练池只用 STOCK/ADR，min_samples=50，候选分位必须窄。
2. Stage 1.5 — 桥接成 ratiorv_ratio = rv3d / date_threshold[D]， 横截面而非逐票（单票 90 天样本太稀疏；逐票会让 KO 的"自己的高"和 TSLA 的"自己的高" 拿到同一个 +1）。ratio 化不是可选项：rv3d 中位数四年从 18.8 漂到 33.0（+76%）， 不归一化的固定阈值必然失效。

dvol_10d_ratio 反过来是自归一化的 （mean(dollar_vol[T-10..T-1]) / mean(dollar_vol[T-30..T-11])，四年中位稳定在 1.04）， 所以它可以直接用固定阈值，不需要 rolling。这也是为什么它的 rolling 对照只是 sanity check。

方向选错就塌房：band(+1) vs gating(−1)

同一个 dvol_10d 特征，两个方向的结果完全相反：

为什么 +1 败：booster 把 score=5 的边缘信号推上 score=6 的准入线， 其中相当一部分是"其他因子分数不够、只能靠 dvol band 凑过门槛"的低质信号，稀释组合质量、抬高回撤。 同样的失败模式在 rv10d（−32%）、gamma_abs（−23%）、chain_ba+1（−30%~−56%）上重复出现。

为什么 −1 成：(a) 受影响一边 ≤ 20%；(b) 离散硬定义； (c) trades 减少而非增加——gating 只改 admission 门槛，不引入新的边缘信号。

dvol 那一天一共探索了 8 个新因子，7 个否决、1 个通过—— 而唯一通过的那个方向是 gating，不是任何 +1 booster。

§08对抗式多智能体证伪

重要因子上线前的标配。方法：每个 agent 负责试图推翻一个论点， 不是验证它。产出不是"能涨就上"，而是 ship-with-caveats + 信心分数。

八维裁决表（dvol_10d_low_pen 第 10 因子，2026-06-03）

综合裁决：SHIP WITH CAVEATS，信心 ~0.80（方向高、绝对幅度低）。

真证据 vs 夸大之处（两边都要写进报告）

对抗验证真正的价值：抓出差点漏掉的前瞻

exit 方式 sweep（35+ 变体，7 个 agent 对抗验证）里，初版的 walk-forward gate 按 prod-exit 过滤 trailing 交易，但它需要的 day2_marginal 依赖 2td_close 的结果—— 这个结果晚于 prod 的周一开盘出场（周五入场的情况晚 +30 小时）。 结果是 约 6% 的决策偷看了未实现价格。

仓库里并存 codex_explore/ · minimax_explore/ · claude_explore/ 三个 AI 探索工作区——多智能体是研究方法论，不是噱头。

§09因子坟场 · 判例库

一个团队的成熟度，看它敢不敢枪毙自己做出来的"好结果"。 这些否定性结论全部归档在 reports/ 与 claude_explore/。 看"哪一关塌了"比看结论更有用——它决定了换基线之后还值不值得重验。

死法四分类（决定重验价值）

判例总表

三个最贵的教训（各自生出一条项目硬规则）

§10现役因子、打分规则与角色

注册表里共 62 个因子，CORE_FACTORS 6 个。 每个因子对一条信号产出一个整数分项，求和 = score_raw，门槛 min_score = 6。 生产线是 6 核 → 8f → 9f → 10f 逐步长出来的。查命令：python3 factor_registry.py list / show <key>。

核心 6 因子 — 刻画"信号本身的质量"（静态分箱，−2 ~ +2）

核心 6 分理论上限 +9、下限 −8。五个分箱因子都走 score_numeric()，NaN → "MISSING" → 记 0 分。

后加的 4 个因子 — 补上"时机与环境"的边际

这 4 个不是静态分箱，而是按交易日滚动、用 IC 自动找最优阈值、严格无前瞻 （训练窗 [D−97, D−7)，留 7 天 gap 让 2 日收益完全 settle）。

因子角色三分法 —— 决定 IC 漂移该怎么读

这是第二层过滤的核心纪律：不同角色的腿，IC 漂移的含义完全不同。 别对着 IC 乱开药。

写因子的代码契约

输入 df 必须含 signal_id / signal_date_et / ticker / y_2d。 输出值域由因子自定（−1/0/+1 或 0/1）。热身期（历史不足）的行输出 NaN，由调用方决定怎么处理。

官方因子集

§11上线与上线之后

Phase 4 全绿只是研究结束。一个因子真正"活着"，要走完 PR → shadow → 分阶段 era → 逐笔对账 → 月度体检这条链。

1. PR 描述模板

命名沿用 <topic>_pr_des.md（现有范本 14_flow_factore_pr_des.md， 注意 factore 这个拼写是用户定的，不要擅自改）。骨架八段：

2. 分阶段 era 上线（对账的前提）

因子是一个一个加进实盘的，实盘日志标题却一直写同一个版本号。对账必须按 era 切信号表， 否则会把"评分函数不同"误判成 bug 或数据延迟。

2026 年的 era 同理，而且三个账户各不相同：4061 从 6/4 起 10f； 4001 是 8f→6/18、10f→6/22、11f→7/7；4081 在 4/28–7/5 停跑、7/6 复跑即 10f。 所有锚点记在 era_config_zlj.json。

3. 组合层：分数怎么变成一笔交易

1. 准入（三个条件同时满足）score_raw ≥ 6 且 otm_admission_ok（OTM ∈ [5,50]）且 不是 ETF_ETN。 同一时点排序按 score_raw 降序——高分票优先抢稀缺资金。
2. 动态基础仓位base_pct = max(2%, target_util / 过去 10 个交易日的中位合格信号数)。 正常 target_util = 0.60 × leverage，guard 触发时 0.30（不乘杠杆）。
3. 分数权重score 6 → ×1.00，7 → ×1.10，8+ → ×1.20。
4. 级联约束（任一不过就跳过这笔）同票同日去重 → gross cap（权益 × 有效杠杆 − 已开敞口） → 行业 cap（正常 50%，guard 时 25%，"Unknown" 行业豁免）→ 单票 cap 20% → 单笔上限 15% → 最小 $500。 中间任何一层不够都允许部分成交。
5. SPY MA20 guard今日 SPY 开盘 < 昨日 MA20 → 杠杆降到 0.5、行业上限收窄到 25%。

摩擦：滑点 5bp、佣金 $0.005/股（最低 $1），PnL 已扣双边佣金。权益只认已实现 PnL。

4. 出场规则

出场在 Stage 1-2 就烤进 base_xy，回测只是回放，不做决策。

• 止损 −15%，gap-aware（开盘价已破线就按开盘价成交），优先于 max-hold。
• max hold = 入场起 2 × 86,400 秒挂钟时间，但只能落在真实存在的分钟 bar 上。 因为 bar 只在交易时段存在，周四 / 周五入场的 48 小时点落在周末缺口里， 第一根合格 bar 就是周一 09:30；monday_open_max_hold=True 让它取该 bar 的 开盘价而不是收盘价。这就是所谓"周一卖出"。周中入场则取 48 小时后第一根 bar 的收盘价。
• 止盈生产关闭（TP disabled）。

5. 实盘 vs 回测逐笔对账

其它对账要点：SELL → lot 分配优先用 position_id，7 天 FIFO 兜底， 别用朴素 FIFO；close_reason 里的 sync_correction / sync_rescue 是券商同步纠错，要排除（已结案：纯记录问题，零经济影响，病根是 trades 写入丢失）； 一致性核对实盘侧直接 ssh 上生产机看日志，RDS positions 不可信。

典型对账产出（全窗口 4/27–8/11，三账户，链乘）：live 全面 ≥ bt 是执行层现象 （同信号 sizing 更大 + 人工收缩），不是 alpha；信号层价差约 10bp、平仓匹配 93–99.5%、 vintage 漂移三组全 0。

6. 月度因子健康仪表盘

python factor_health_dashboard.py \
    --signals exp_result/scored_v9_10f_asof0810/signal_table.parquet \
    [--factors iv stock_price otm asset_type rule_hit time_slot ret_5d_roll_deep rv3d_band_15_30 dvol_10d_low_pen] \
    [--with-ablation] [--history exp_result/factor_health_history.json]

三层证据，各自回答不同问题：

每次跑完追加进 factor_health_history.json，可以对比 IC 趋势。 建议再加一项监控：逐年"被踢单质量"（某门型因子踢掉的信号 median y_2d vs 当年全体）——见 §12 的 atr 案例，那是漂移前兆。

7. 被否因子的重验

只重验 B（共线残差层） 和 C（回测容量层） 两类—— 基线换了，共线对手和容量对手才会变。A 类（特征层无信号）与基线无关，不值得重跑。 重验必须用 harness 先在旧基线上复现已知数字（atr_reexam_job/harness.py 就是先用 USAGE 的六格数字精确复现，排除口径假象），再上新基线。

§12后来才写下的硬规则 + 已核实的口径不一致

两条方法论硬规则

已核实的口径不一致（读代码确认，待团队决定是否开工单）

§13附录：命令速查与源文件索引

命令速查

# 0. 每次开 shell 必做（否则 SPY guard 静默 fail-open）
set -a; source .env; set +a

# 1. 看有哪些因子 / 看某个因子的打分表
python3 factor_registry.py list
python3 factor_registry.py show dvol_10d_low_pen

# 2. Stage 2 打分（10f 生产基线）
python3 build_factors.py \
  --base exp_result/bigopen_v9_base_asof0810/bigopen_v9_stage1_base_xy.parquet \
  --factors iv stock_price otm asset_type rule_hit time_slot nbp3d_low ret_5d_roll_deep rv3d_band_15_30 dvol_10d_low_pen \
  --out-dir exp_result/scored_v9_10f_asof0810

# 3. Stage 3 回测（唯一引擎 run_backtest_v9.py；时间窗必须显式传）
python3 run_backtest_v9.py \
  --signals exp_result/scored_v9_10f_asof0810/signal_table.parquet \
  --factors iv stock_price otm asset_type rule_hit time_slot nbp3d_low ret_5d_roll_deep rv3d_band_15_30 dvol_10d_low_pen \
  --start-date 2023-04-20 --end-date 2026-08-10 \
  --capital 5000000 --leverage-ratio 1.0 --min-score 6 \
  --out-dir exp_result/bt_v9_1x_10f_asof0810

# 4. 缓存体检与修复
python3 utils/cache_repair_zlj.py scan-truncated              # 默认 dry-run
python3 utils/cache_repair_zlj.py purge-year 2026 --apply     # vintage 漂移的决定性一招
python3 utils/cache_repair_zlj.py dedupe-daily-bars
python3 claude_explore/daily_bars_prewarm_zlj.py --base <base.parquet>

# 5. 月度因子健康体检
python3 factor_health_dashboard.py \
  --signals exp_result/scored_v9_10f_asof0810/signal_table.parquet --with-ablation

全链路刷新已收敛成 /refresh-backtest（.claude/commands/refresh-backtest.md）： 上传新 CSV 后一句话触发，自动推导 asof、后台连跑、自动验收与自愈，默认范围 10f + 11f 的 1x。

验收三件套（每次刷新后必做）

1. 复跑一致：同 base + 同 scored 表重跑，portfolio_report.json 三文件应逐位一致。 不一致说明差异来自缓存内容，不是引擎随机性。
2. guard 在位：检查 guard_active 的笔数不为 0（asof0810/0824 都是 505 笔）。
3. NaN 本底正常：dvol 约 6.9% / rv3d 约 4.5%；base ok 率约 82%。

源文件索引