sanguo/sanguo_vnpy_v2
3
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cd1793c7c3b1ec4a88d07b4b8d46eb7beeb6ceb2
sanguo_vnpy_v2/docs/superpowers/specs/2026-09-22-research-to-trading-pipeline-design.md
T
claude_dev cd1793c7c3 feat(pipeline): 决策价直取——jq执行委托行[策略:]bar锚+行情价到达fallback（M5竞价段兼治） [vps] 
引擎「执行委托」行（live_engine.py 级，全策略覆盖）自带两个被掩埋的锚：
[策略:ts]=策略时钟=真决策 bar 时刻、行情价=派发时刻现价（plan.last_price）。

- order_log_parser：新增 _DISPATCH 行族（不产生 event，七态纯度零 schema 变更），
  pending 队列 (symbol,action,qty) 严格键相等+FIFO 挂到相邻 submit/norej-reject
  事件（decision_ts/dispatch_price 两键不在 _EVENT_COLS，append_events 自动忽略）；
  墙钟≤提交 ts 才配对；日志尾未匹配静默丢弃。
- ishortfall_daily：决策价主源=[策略:] 分钟键直查 price_fn（治派发滞后被
  「提交前上一根 bar」代理掩埋，实测 delay=+157s 例两根 bar 差）；到达价主源不变，
  缺当分钟 bar（竞价段 09:29/12:59，M5）回退行情价。行情价禁作决策价兜底
  （派发价当决策价会低估延迟成本——宁缺毋假，缺则照旧计 legs_no_anchor）。
  无 jq 行的腿（回测/无策略时钟）行为不变。_BASIS_NOTE 两行同步。
- spec §4.7 三价链第 2 条追加 2026-09-26 决策价直取注记（档随码走）。

测试：新增 8（parser 4+腿解析 4，RED→GREEN；含 FIFO 配对/qty 错配不互偷/
无 dispatch 旧行为回归护栏/run_day 端到端 207 vs 旧锚 23 实证）。
全量 tests/portfolio 730 passed / 2 skipped（基线 722+8）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-26 20:11:21 +08:00

44 KiB
Raw Blame History

投研→交易流水线总设计（Research-to-Trading Pipeline Design）

  • 定稿：2026-09-22（当日 brainstorming 全流程闭环：初始方案→用户视角走查→七项目借鉴复盘→九缺口逐项决议→P0 控制台增项，用户逐项拍板）
  • 档纪律（用户 2026-09-22 拍板）：流水线（编排层）只维护这一个 spec。因子/数据/部署三域的域内细节仍归各自唯一活文档（docs/factor_research/factor-system-design.md / docs/superpowers/specs/2026-07-21-data-source-fusion-design.md / docs/three-env-code-promote.md+docs/deployment/vps-production-runbook.md）。档随码走：流水线组件的设计变更同 push 更新本档，纯实现/修 bug 打 [no-doc]。
  • 实施顺序（用户拍板）：P0 高仿真控制台 = spec 定稿后第一实现项，此后 P1→P2→P3→P4（§8）。

§1 现状诊断：哑铃型

数据底座（136 财务 PIT+语料+质押/研报/情绪另类，每日链全自动）与交易执行（影子→QMT、三层防御、恒等式闸门）两端最厚最难的已建完；中间六环节薄但迭代快：因子工厂（缺定期全量重评）、晋级闸门（流程无模板）、合成层（等权 8 项刚起步）、策略工厂（四策略但孵化路径未标准化）、归因（只监控「没坏」不监控「没偏」）、投研入口（语料有流程无）。

定调：补中间、串两端、两端复用不重建。

§2 总纲：三不三要（宪法）

三不 三要
❌ 不引入 Qlib/RQAlpha 类新框架（BulletTrade+vnpy 已覆盖；七项目调研结论=借鉴范式不引系统） ✅ 胶水用现有 Gitea issue+cron，不建新平台
❌ LLM 不碰交易决策（只在 P4 做语料加工，晋级永远走 IC 数据闸门） ✅ 多 session 分工不变（定期任务走 cron，创作任务走 session 协作）
❌ 关键 promotion 永不自动化（最后一级永远用户口令，同推 vps 纪律） ✅ 合成层等权为基线，权重进化走考场晋级+版本化（决议 K；P3 归因贡献类权重再议）

§3 流水线全景

假设卡片 ──→ 因子工厂 ──→ 晋级闸门 ──→ 合成层 ──→ 策略工厂 ──→ 孵化梯 ──→ 实盘 ──→ 归因反哺
(+墓园)      (版本化/成熟度门/  (判定五问     (等权起点/    (组合规则×     (回测→paper  (不动)   (偏差+贡献
              双机月度批评)      模板工件)     版本钉住/      因子暴露)      →影子→口令             两半拆分)
                                             判别门/研判卡)               +初始资金分配)
                                                                  ↑__________________________________|
                                                                     （F 环归因反哺→新假设卡片）

六循环：

循环 周期 触发 用户在吗 新增防线
A 数据扩域 按需 假设缺数据 只在花钱时 完整性门验收（落盘≠可用）
B 因子迭代 周 IC 弱/换口径 看报告 版本化保血统，墓园防复活
C 策略调参 天 参数扫描 读图判读 —
D 影子观察 日 tick/周判 偏差超阈 读周报 孵化梯 gate 数值起步默认+首年校准
E 衰减降权 月 IC 跌破阈 处理告警 成熟度门+双条件+连续性
F 归因反哺 季 实盘偏差/新发现 收新假设卡片 集体衰减判别门+七档研判卡

F 环是「管道」与「飞轮」的分界：归因发现→可能=衰减触发重评/可能=回测假设错修引擎/可能=市场变了催生新假设→回到输入口。

§4 组件设计

§4.1 假设卡片与墓园

  • 假设输入即持久工件：来源（研报/调研/直觉）、逻辑、预期方向、数据需求；落 Gitea issue 卡片，与 session 会话寿命解耦。
  • **墓园只收「评过且判死」**的负结果，可检索防重复造轮；未长成熟的因子不进墓园（§4.2-E）。

§4.2 因子工厂（P1）

  • 版本化（决议 D）：同一假设换实现（换窗口/口径/标准化）= 升版本 f01@v2；换了假设本身（不同数据、不同经济逻辑）= 新因子。版本快照=参数+代码 commit+生效时间窗，存随代码走的 yaml 注册表（与 §4.4 合成层版本钉住共用同一设施）。回测/归因按日期解析到当时生效版本重算——pit_view 点时纪律延伸到因子定义本身。
  • 成熟度门（决议 E）：衰减告警只对已晋级因子生效（有晋级时 IC 基准可比）；未晋级因子只出观察报告（IC 出来了没/覆盖够不够），不告警不判死不进墓园。S 族前向积累型（首个有意义 IC 窗=10 月下旬）天然受此保护。
  • 月度批评（决议 H，双机同评+对拍）：
    • 同一脚本在 NAS（DSM 任务）与 VPS（schtask）各跑一次，数据截止日强制对齐=自然月末；
    • 跑位=每月首个周日白天（避开 NAS 周六 ak-weekly/ak-quarter 马拉松与 VPS 平日全窗：09:15-15:00 引擎、18:05 bs-daily、20:30 paper 回放、21:00 xt_eod）；首跑实测耗时后可调窗；
    • VPS 参与的理由=生产同环境验证（因子真实运行位的怪癖当场暴露）+双机天然背靠背对拍；
    • 对拍规则：关键指标（IC/t 值/rank）一致→结果落档进告警流程；分歧超阈→不出降权告警、只开排查 issue（宁可误报排查，不可错发告警——分歧大概率=数据版本漂移或环境差异，本身就该被抓）。
  • 衰减判定（决议 F，只对已晋级因子）：
条件 起步默认 防什么
① 相对降幅 滚动 12M IC t 值 < 晋级时 t 值的 50% 各因子基准不同，一刀切绝对值不公平
② 绝对地板 同时 t < 2.0 防「从很强掉到还算强」也叫衰减
③ 连续性 连续 3 个月满足①②才开告警；第 1~2 个月标黄预警 月度 IC 一年 12 个点，单月噪声大

告警 issue 自带处置菜单（降权/退役/豁免一周期再观察）——阈值只负责叫人，处置永远人选。数值写档措辞=「起步默认+首年校准点」（P1 首批评实跑分布回看后定终值，corpus rc 案方法论）。

§4.3 晋级闸门

判定五问固化成模板工件（生产先例=szneul_reb63）；评审记录与版本快照关联，血统不断。

§4.4 合成层

  • 等权=每个新合成层的基线（composite_fund8 现状）；权重进化走「考场晋级+版本化」（决议 K，09-24 辩论裁决）：ICIR 拟合形态=从等权基线在 h2 样外考场打赢在位者后以新版本上位（先例 quant12 v1 等权→v2a ICIR，09-11 收官），护栏=非负+单源≤2×等权+年频拟合+0.7 族压缩前置（均已测试锁死），档案铁律=新档案新名字+reason 必填+生产冠军定义永不改。P3 归因贡献类权重（第三形态）攒数据后再议。
  • 版本钉住+影子对照闸门（决议 A）：策略钉住合成层具体版本；合成层变更（晋级/退役/调权）→新旧版影子对照（起步默认 4 周，首年校准）→用户口令→各策略择期升级。可回滚、历史可复现，与推 vps 纪律同构。
  • 集体衰减判别门（决议 C）：月度批评输出两个指标——个别因子衰减（相对同侪，E 环照常机械告警）+集体水位（全体 IC 中位数）。**集体水位跌破阈→不开降权 issue，改开「市况研判」卡片上交用户裁决，因子权重冻结不动。**集体信号=判断题归人，个别信号=机械题归系统；防机械追涨杀跌。
  • 研判卡=带介入菜单的决策卡：七档介入阶梯（从轻到重）——
档 动作 业务含义 代价
0 不动，继续观察 信任纪律，接受回撤 判断错则回撤加深
1 降总仓位上限 账户层 100%→70% 之类，选股不动 反弹少赚
2 策略间挪钱 挨打策略→防御型/现金 挪错两头挨打
3 降调仓频率/只出不进 跳过调仓日或 N 期只卖不买 错过轮动起点
4 因子族豁免/降权 只对逆风族降权 精细判断易错
5 转研究响应 仓位不动，开假设卡片走 P1/P4 研究周期内继续承受
6 防御模式（最重） 全账户最小暴露/清仓观望 大概率卖在低点+再进场时点难题
  • 档 1（账户层总仓位）与策略自带仓位管理是两层：策略层规则在账户层硬顶下面自由，顶由人定。「空名单⇒全清仓」类耦合的正解位置=全清仓应是人选的档 6，不被空名单隐式触发。
  • 卡片自带历史回放（P3 归因副产品）：上次集体水位这么低是何时、之后三个月七档各选项事后看的结果——不要求用户现在就懂，要求决策时刻功课已摆好。
  • 七档全部是已存在配置项（仓位/分配/调仓日/因子权重）的人工触点，零新增自动决策路径。

§4.5 策略工厂与孵化梯（P2）

NAS 批量回测 ✅gate → paper 模拟盘(每日自动) → 影子期 ≥N 周(起步默认 4 周,首年校准)
                                              │周报:跟踪误差/成交质量/与回测偏差
                                              → promotion(用户口令)
  • 偏差超阈→退回策略工厂或延长影子期；不达标永远上不了实盘，梯子自己拦。
  • 资金分配（决议 B，用户口径）：分配是毕业仪式的一部分——影子/模拟毕业转入真实账户时，用户介入设置该策略的初始资金分配；可配置维度是「分配方式」（占账户比例/固定金额/其他），默认落地形态大概率=一个初始资金金额。不设中央动态预算层、不自动再平衡；后续调整同属用户决策（集体衰减研判卡档 2 是重新分配的合理触发时机）。

P2 落地设计六件（2026-09-24 拍板，决议 L）：

  1. strategy_registry 状态机（config/strategy_registry.yaml+sanguo_portfolio/strategy_registry.py，克隆 version_registry 范式）：stage=backtest→paper→shadow→live→retired（死因必填），退回工厂/延长影子期=带留痕转移；每条档案=血统必填（来源假设+钉住的合成层版本，决议 A+J2 同构）+stage 历史+晋级 gate 快照+评审 issue 号+资金分配快照+死因；转移走 CLI（J1 同构：转移即事件自动开 Gitea issue，无 token 则模板落盘降级）。
  2. gate 计算+阈值配置（纯函数模块，一处定义三处调用=转移 CLI 硬闸/梯子页展示/批量回测后报告）：回测 gate=夏普≥1.0+最大回撤≤30%（2022-2024 全窗）；影子毕业 gate=影子期 4 周+跟踪误差年化≤5%+fillRate≥95%+周均收益偏差≤3%。阈值两级=代码内默认常量（档随码走基线）+每机 pipeline 库运行值（控制台配置页可编辑+审计行：谁/何时/旧→新）；双机各生效，同步改走代码默认+部署。
  3. 周报三指标（空白新建；一份代码跑在数据所在机=VPS 生产，随每日 eod_replay 后幂等重算滚动 4 周窗）：trackingError=实际日收益 vs 回测基准日收益差 std×√252（年化）；fillRate=已成交委托/总委托（拒单计入分母，保守口径首年校准再细分）；vsBacktest=周收益差（基准=registry 挂的回测 run，按日对齐）。落本机库，本机控制台直读。
  4. 接真端点（前端零改动=逐条删 mock 路由）：GET /pipeline/ladder（registry+paper 账户+周报+gate 态拼成前端 LadderStrategy 形状）+GET/PUT /pipeline/gate-config（配置页）+POST /pipeline/promotion/graduate（口令+分配方式+初始值→转移+落档+开 issue）。IncubationLadder/PromotionReview 两页按钮从 disabled 变真。
  5. 判定五问模板工件：从散落三处（因子域档 §6.4/§7.1+前端硬编码）固化为 docs/pipeline/promotion-five-questions.md+评审 issue 模板，评审记录与版本快照关联（§4.3 落地）。
  6. 存量补录：在跑实例（szneul_reb63 等 live/shadow）带补录标注入 registry（gate 快照留空），梯子页不空转；paper_accounts/supervisor 等运行设施一行不动；promotion 执行（起实盘实例）仍是用户手动动作，档案只记录。

架构原则（B'，09-24 勘误后定案）：控制台与 /pipeline/* 后端双机部署同一份代码、各读各的本地数据（VPS=生产控制台读本机 paper/影子/成交；NAS=测试控制台读本机回测态与 test 实例），P2 零新增跨机推送；真要跨机印证复用 P1 对拍模式（两边各落 JSON 凑一起比=对照不是搬运）。promotion 口令=env 配置（SANGUO_PROMOTION_PASSPHRASE），值首班用户定。

P2 实现注记（2026-09-24 计划落档）：计划=docs/superpowers/plans/2026-09-24-p2-incubation-ladder.md（七任务 TDD）。env 契约：SANGUO_PIPELINE_DB（每机周报+阈值库,缺省 data/pipeline.db）/SANGUO_STRATEGY_REGISTRY/SANGUO_STRATEGY_EVENTS/SANGUO_FACTOR_REGISTRY+SANGUO_FACTOR_EVENTS（verdict 端点复用 P1 注册表）/SANGUO_FACTOR_MONTHLY_DIR（todos 聚合源）/SANGUO_PROMOTION_PASSPHRASE（毕业口令,首班用户定）/SANGUO_REGISTRY_ISSUE_DIR/SANGUO_GITEA_BASE_URL（开 issue 的 Gitea API 地址,缺省内网 IP;VPS 走 FRP 127.0.0.1:13000）。节律：周报重算=APScheduler pipeline_weekly_report 每日 20:45（晚于 20:30 live_step,双机各跑各的）+CLI python -m sanguo_portfolio.weekly_report。语义注记：因子评审「退回改造」=留观（五问留痕不改状态,升版本走 factor 域档流程,控制台不越权）；fillRate 分母=已落库委托行数（组合实走路径不落拒单行,首年校准点）。

§4.6 交易执行（不动）

现有全部复用：影子 broker、T+1 执法、三层防御、哨兵、恒等式闸门、晨检节律。

§4.7 归因反哺（P3，决议 I：拆两半各归既有域）

半边 归属 理由
偏差监控（实盘 vs 回测执行质量：fill/滑点/成交假设校准） strategy/live 域 执行质量度量，材料=台账+成交回执+恒等式，该域全套已有
因子贡献分解（组合收益→因子暴露归因） factor 域 评估管线延长（月度批评姊妹件），材料=因子暴露+合成权重

研判卡是两半的消费方（拼成七档菜单+历史回放）——接口归属原则「场景公共」判据：归因产物有多个第二消费方（研判卡/E 环/假设回放），管线长在材料所在域，接口公共化。

P3 实施顺序与业界参照（2026-09-25 拍板）：研判卡接真先行（生产页面现为空白断头路+量最小+不依赖归因两半），偏差日报/因子贡献分解随后各成刀。业界调研定口径：偏差日报采 Perold 落地差距四分解（延迟/冲击/机会/费用；P2 成交率=机会成本粗版同宗）；因子贡献分解=自家因子多空收益回归式归因（Barra 思想轻量版，不引 CNE5 数据依赖）；研判卡历史回放=情景回放范式（近似估算，业界压力测试同型；动手前用现有回测工具做精确验证，零新机器）。

研判卡接真落地设计（P3 第一刀，2026-09-25）：

  1. 回放引擎（factor 域 sanguo_factor/verdict_replay.py，月度批评同班车）：触发点普查=月度批评 JSON 的 monthly_points（已晋级因子逐月 t 中位数 < 集体地板的月份；功课厚度随月度批评逐月累积，首月起步）→ 每触发点七档事后成绩（触发月末起 3 个月窗，近似估算）：载体=registry 在跑档案（live/shadow/paper）挂的 backtest_run 日收益等权混合；档 0/5=原曲线、档 1=×0.7、档 2=固定换权（all_weather×2 / momentum·small_cap×0.5，归一）、档 6=窗内现金（收益 0）、档 3/4=N/A「需精确验证」；每档报 3 月收益+最大回撤，页面打「估」标。CLI python -m sanguo_factor.verdict_replay --as-of <同月度批评>，产物 verdict_replay.json 落 monthly_dir（派生件可重建，文件名不中往月月报 glob）。
  2. 研判留痕（portfolio 域 sanguo_portfolio/verdict_records.py）：七档静态表唯一源（api 拼卡/回放打标/裁决校验三方共用）+ 裁决 JSONL append-only（月键一条重复拒；档位+理由+时间；env SANGUO_VERDICT_RECORDS 缺省 data/verdict_records.jsonl）。
  3. 端点（sanguo_api/routes_pipeline.py，router 已挂零注册改动）：GET /pipeline/research-card（最新月报 collective 触发才出卡：水位+衰减榜（alert 优先、ratio 升序、至多 3）+七档+回放视图+在途裁决；未触发→card=null）；POST /pipeline/research-card/verdict（month+level+reason 落档，同月重复 409、非法 422）；GET /pipeline/attribution（归因日报立骨架：liveVsBacktest=live 档案周报三指标真值+IS 四行占位「待接真」，factorContribution 留空待后续刀。2026-09-26 接线毕：IS 五行（四分量+价格移动参考行）读 pipeline_store.latest_is，factorContribution 直通 attribution CLI JSON——详见下方两刀落地设计与编排节）。
  4. 前端：删 mock 拦截两行（index.ts 的 attribution/research-card 条目）接真 + 研判卡加裁决控件（选档+理由+提交+已裁决态，提交后重拉卡）；七档全人工触点零自动执行（决议 C 不变）。
  5. 跑位：月度批评链后跟一条 verdict_replay（同 as-of 同机）；10-04 首班双机首跑。B' 双机各读各的（月报/registry/回测库均本机）。

偏差日报落地设计（P3 第二刀，2026-09-25 拍板；实现级调研=Perold 原教旨修正案+拒单两分法+FIX 式委托事件表）：

  1. 定性（Perold 原教旨）：纸面组合必须在决策时刻以决策价建仓——paper 腿=无摩擦基准组合，四分量定义在 live 腿事件流上；paper 定价点（20:30 收盘回放）与决策点之差不混入四分量，归 Kissell-Glantz「价格移动」独立参考行（防大盘漂移污染执行评价）。主表四行对齐 _IS_ROWS 占位 + 第五价格移动参考行。
  2. 三价链分量定义：决策价=决策时刻市场价（信号 bar；入库表 decision_price 列）；到达价=委托提交时刻分钟 bar close（IS 主基准，业界 pre-trade 标准）；成交价=逐笔按量加权。延迟=决策→到达；冲击=到达→成交；机会=未成交腿×(决策价−当日收盘)×方向（Perold EOD 口径）；费用=佣+印花+过户费 0.001% 双边（estimate_fee 微改补齐；柜台实测零费时估算值只当对照行）。paper 腿延迟/冲击=机制性零，显式标注非缺数。2026-09-26 决策价直取：引擎「执行委托」行自带 [策略:ts]（策略时钟=真决策 bar 时刻）与行情价（派发时刻现价）——决策价主源改 [策略:] bar close（治派发滞后被 bar 代理掩埋，实测 delay=+157s 例两根 bar 差）；到达价主源不变，缺当分钟 bar（竞价段 09:29/12:59，M5）时回退行情价。行情价不作决策价兜底（宁缺毋假）。
  3. 拒单两分法（A股 无公开惯例可抄，自定口径即结论）：reason 枚举 {T1, CASH, LIMIT_UP, LIMIT_DOWN, TIMEOUT}——T1/CASH=决策层违规（策略自己的账没算对）；LIMIT_UP/LIMIT_DOWN/TIMEOUT=市场层不可执行（真机会成本）；分标签报告。
  4. 委托入库（老 backlog 合并本轮，一债两清）：FIX ExecReport 式 append-only 事件表（order_id, event_seq, ts, event_type 七态[submitted/ack/partial/fill/cancel/reject/expire], price, qty, cum_qty, leaves_qty, avg_px, reason, raw_hash）+状态由重放推导（event sourcing，日志 regex 解析=周检已验证范式）+幂等键(order_id,event_seq)+raw 行 hash 保真；状态机照 FIX 4.4 App D 语义简化。日报从此不依赖日志挖掘。
  5. 工程形态：sanguo_portfolio/ishortfall（纯函数计算器）；产物落 pipeline_store（与周报同库同通道）；跑位=每日 20:45 后（避开 20:30 paper 回放与 21:00 xt_eod）；09-14 起归档日志可回放出首份真日报。与 10-04 首班零耦合。不借：Kissell-Glantz 全套大单成本模型/ISTAR/VWAP·TWAP 对拍体系/商业 TCA 平台（每日几十笔小单直打，拆单模型=想象问题，Linus 三问第一问）。

因子贡献分解落地设计（P3 第三刀，2026-09-25 拍板；实现级调研=控制集一次上全套+0.7 族压缩升默认回归元）：

  1. 方法：日度 Fama-MacBeth 截面回归（个股日收益 ~ 标准化因子暴露 + 控制集）→ 因子日收益序列 f_k(t)；组合贡献 r_p(t)=Σ 暴露·f_k + 特质残差；恒等式可加和验证（Barra 形式：市场+Σ因子贡献+特质≡组合收益，接恒等式测试文化；特质项单列——占比高=解释力弱，结论降权）。
  2. 控制集（不分期，一次上全套；开工前置=行业表）：市场截距（country factor 显式单列，A股 全市场漂移大）+ log 市值（SIZE_LOG_EXPRESSION 库内现成）+ 申万 31 行业哑变量（去一/和零处理；依赖 data 线行业表入 manifest+开出口——本刀开工前置）。管道 sanity 锚点：组合层已 size 中性化 ⇒ size 贡献应≈0，非零=size 泄漏报警。
  3. 共线处置：决议 K 的 0.7 族压缩=默认回归元（代表源入回归，quant12 纯量价 12 源零 size/行业——不加控制集则小票潮汐系统性泼给 vol/量能代表源）；VIF/条件数诊断披露；代表后仍 VIF>10 触发 ridge 对照跑（固定 λ 一档，双估计结论翻转才报警——同月度批评「分歧开排查」精神）。不借 PCA/lasso。
  4. 加权与披露：sqrt(市值) WLS 默认+等权敏感性对照（固定双跑无旋钮）；报月度累计+滚动 12m/24m IR（不报单日显著性）；R²+特质占比必披露。产物 schema [{factor, month, contribution_ret, cum_ret, exposure_avg}]，按族行组织（代表名+成员清单+月贡献+滚动 IR+暴露均值），size/行业/特质三桶殿后；前端=月度贡献瀑布条形（正负色）。
  5. 持仓源与跑位：factor_topn 持仓=截面确定性函数重建（不走回测引擎[落库只存末日]、不走台账；paper/live 台账=影子起跑后第二持仓源，live 侧归因待影子起跑=#69 口令问题非本件阻塞）；sanguo_factor/attribution.py（月度批评姊妹件），JSON 落 attribution 目录，CLI 独立跑位（与 10-04 首班零耦合）；数据准备=源级截面全窗批导出（现有 batch 工具零新代码，NAS 数小时级）。

P3 两刀编排（2026-09-25）：两域并行各走 writing-plans（subagent 执行）；偏差日报刀无数据前置可先动，因子贡献刀等 data 行业表出口；接线与部署统一归 infra 收尾（routes_pipeline 两处 _IS_ROWS/factorContribution 读真数据，一次 CI、一次「推vps」、一次冒烟）；跨域要料一件=data session 行业表（确认落盘+入 manifest+开出口）。

§4.8 投研入口（P4，决议 G：漏斗分诊）

corpus 新增语料 → 第一层确定性加工(词表/规则,S 族范式,零成本,处理大头)
                        ↓ 词表 miss/需结构化抽取的事件段落
                 第二层 LLM(只碰漏下来的) → 事件快照 parquet(append-only)
                        ↓
                 因子只读快照——因子计算路径永远没有在线 LLM 调用
  • 增量只前向（watermark 之后）；历史回填按预算分批；词表升级用词表重放（确定性零成本），LLM 结果落快照永不重算——防编数快照同时=成本控制。
  • 跑位=VPS 夜间 schtask 限速；单次预算上限+超限断路停摆下次续（AK_STATIC 限流断路器范式复用）。
  • 开工前置纪律（七项目调研折入）：①TradingAgents 确定性验证快照——LLM 产出的任何数字必须回源验证；②UZI 完整性门 20 项+覆盖率<40% 阻断——新数据域/新语料覆盖的验收门。此二者为 P4 安全开工的必要条件。
  • 卡片向导+分解器（2026-09-24 拍板，决议 M——用户钦定 P4 重心）：⭐「一句话拆解成因子/因子组合」是整个流水线的入口和地基——拆错了，后边算得再好也没有意义；P4 阶段必须把此功能完善掉。两件：①卡片向导=控制台输入一句话→LLM 结构化五字段草稿（假设陈述/依据/预期方向/可证伪声明/关联域）→用户确认落卡（LLM 只做文字→结构，不碰数据不碰决策）；②分解器=卡片上生成候选因子清单，硬约束=算子白名单+数据域白名单+每条 justification→全部自动挂血统进 incubating→月度批评自动考→考不过自动进墓园并回写卡片。三条护栏：白名单（LLM 物理上编不出新数据）、防编数（LLM 只写表达式不产数字，数字全由评估管线算）、零特权（生成因子与手写因子同考场同淘汰）。数据缺口=候选因子声明所需域→gap_check 自动比对→缺口自动开单进 data 待办→补上后月度批评自动重试（仅全新数据源需人工接入，那是开发活）。

§5 用户触点（四→五，全部守门题）

触点 内容 类型
① 假设输入 一句话/研报链接→持久卡片 生产
② 因子晋级判定 判定五问+IC/族分析报告 判断
③ 合成层升级口令（新增） 新旧影子对照 N 周后择期升级 判断
④ 策略 promotion 口令+初始资金分配 口令+分配方式设置（决议 B） 判断
⑤ 告警响应 个别衰减=处置菜单；集体衰减=研判卡七档+历史回放 判断

周期阅读：晨检（已有 08:10 自动）/影子周报/归因日报。其余时间流水线不需要用户。

§6 与七项目调研的关系（2026-09-22 复盘）

指标面增量已兑现（P0 九因子 9741a69+P1 九因子 574808c，pledge_net_chg 已入合成）；架构面零可借。折入本设计的工程范式：防 LLM 编数快照→§4.8、完整性门→循环 A 验收、vintage 钉扎=底座已符合的旁证。负样本（UZI fork 负 PE bug 等）=墓园种子与 TDD+IC 闸门防线的攻防实证。

§7 P0 控制台高仿真原型（第一实现项）

设计点 方案
定位 全流程体验+设计验证+未来驾驶舱；spec 定稿后第一实现项
风格 与 vnpy.mysanguo 完全一致：同栈（Vue+TS，随 nas-frontend 构建）、同组件库、同布局语言与主题
数据 高仿真 mock：真实因子名（pledge_net_chg/res_target_upside…）、真实策略名（value/all_weather/momentum/channel）、IC/告警量级仿真真值
边界 数据层=adapter 接口（mock 实现↔未来真后端实现可切换），页面代码不因换数据源重写

七页清单：

页面 内容 触点/循环
驾驶舱首页（我的待办） 汇聚五触点所有「等你决策的事」 全触点总入口
假设池 卡片全生命周期状态流+墓园 tab（可检索） ①，A/B
因子工厂看板 注册表（版本/状态：孵化/可判/晋级/预警/退役）+月度批评报告（IC 两窗图，双机对拍结果）+衰减告警 ②，B/E
晋级评审 判定五问模板工件+IC/族分析数据，成评审记录 ②
合成层版本树 composite_fund8@v1/v2…版本、成员因子+权重、新旧影子对照进度、升级口令位 ③，E
孵化梯 策略列表+梯级位置+影子周报+promotion 面板（口令+初始资金分配方式） ④，D
归因+研判 归因日报（偏差+因子贡献分解）；集体衰减弹出研判卡（七档菜单+历史回放） ⑤，F

契约先行逻辑：看板立起来=P1 后端必须产出的数据结构定型，后端照图施工；原型期纯 mock 短，P1 不久等。

§8 实施顺序与交付物

期 内容 首个交付物
P0 控制台高仿真原型（第一实现项） 七页可走通全流程的 mock 原型（前端域执行，风格随 vnpy.mysanguo）
P1 因子工厂流水线化 版本注册表+月度批评脚本（双机）+衰减判定+观察报告+墓园格式；唯一「不做有现实风险」项（50+ 因子晋级后无人盯衰减）
P2 孵化梯标准化 strategy_registry+周报三指标+gate+两页接真+驾驶舱接真（§4.5 六件，决议 L）
P3 归因反哺 偏差日报（strategy 域）+因子贡献分解（factor 域）+研判卡历史回放接真
P4 投研入口 LLM 端 卡片向导+分解器（决议 M，入口地基）+漏斗分诊管线+事件快照；前置=防编数快照+完整性门落地

每期开工走各自 writing-plans 出实现计划；P1 的衰减阈值等数值按「起步默认+首年校准」执行。

§9 治理与协作

  • 口令纪律：所有 promotion 类动作（合成层升级/策略上实盘）沿用 vps-deploy 口令闸门范式——用户原话，不得代填/推断/沿用旧授权。
  • session 归属：因子工厂+因子贡献分解=factor 域；数据扩域=data 域；孵化梯+偏差监控+控制台=strategy/前后端域；编排与跨域验收=infra+用户。跨域最多提醒不接手。
  • 告警通道：Gitea issue（个别衰减/数据排查）+研判卡（集体衰减，上交用户）。

§10 决策记录（2026-09-22，均用户拍板）

# 决议 用户口径要点
A 合成层=版本钉住+影子对照闸门 选推荐案；变更走口令，策略择期升级
B 资金分配=毕业仪式一部分 「注意是分配方式而不是资金金额，但大概率是一个初始资金金额」；不设动态预算
C 集体衰减=判别门 「大概率是 1，但也希望有人工介入的可能性」→研判卡七档菜单+历史回放
D/E/F 版本化/成熟度门/衰减阈值 全按默认写档
G LLM=漏斗分诊+快照落盘 全按默认写档
H 月度批评=NAS+VPS 双机同评 用户提出双机+非密集期窗口；对拍分歧开排查不开告警
I 归因拆两半各归既有域 全按默认写档
J P1 补丁六件（2026-09-23 拍板，「这 6 件可以」） §11.3 三件（先批后评两段调度链/数据缺口自动比对/batch_eval 薄 CLI）+§12.3 高优三件（J1 转移即事件/J2 血统硬闸/J3 pre-gate 机械前置）；细则见 §12.4，P1 计划档同步在执行前进行
P0 高仿真控制台=第一实现项 「需要一整套高仿真 UI 感受全流程，风格与 vnpy.mysanguo 一致；spec 定稿后要实现的第一步」
档 流水线只维护本 spec 「写在项目 docs 下单独设计文档，记录到项目级 CLAUDE.md 和记忆」
K 等权=基线，权重进化=考场晋级+版本化（09-24 辩论裁决） ICIR v2a=在位生产（带考场履历），等权 v1 挂 szneul 同参影子 A/B 当挑战者，4 周+数据判；ICIR 拟合护栏（≤2×等权/年频/0.7 族压缩）测试锁死；L2 人工微调走新档案+reason 必填，无路径绕过考场改生产
L P2 六件+判决报告原则（09-24 拍板） gate 起步默认全套（回测夏普≥1.0/回撤≤30%；影子 4 周+TE≤5%+fillRate≥95%+偏差≤3%）+阈值可配置页面；B'=双机各读各的本地数据零跨机推送；驾驶舱接真纳入 P2=聚合总入口；报告按「你要做的判断」组织，功课在闸门前摆好
M P4 入口地基强化（09-24 拍板） 「一句话拆解成因子/因子组合」必须在 P4 完善掉——入口+基础，拆错了后边算得再好也没意义；卡片向导+分解器+三条护栏（白名单/防编数/零特权）

§11 晨间走查增补（2026-09-23，用户七页走查后的概念澄清与缺口确认）

用户在 vnpy.mysanguo(NAS test, 192.168.2.154:8000)走查七页后连续追问,以下口径经用户确认或由追问揭示,均为本 spec 当前版本的组成部分。

§11.1 术语金字塔（四层，纠正「合成层=策略」混称）

因子(截面打分器,如 pledge_net_chg) → 晋级(判定五问,触点②)
  → 合成因子(多因子加权平均的更强打分器,如 composite_fund8——不是策略)
  → 策略(打分器→交易动作的翻译器: top_n×调仓日×缓冲带×仓位,如 szneul_reb63)

合成层的产物是合成因子(评委团加权总分),策略在下一层(招生办按总分录取)。两层各有生命周期:合成层版本树管打分器版本,孵化梯管策略 gate→影子→毕业。

§11.2 模块联合与设计边界（用户确认「多模块联合才成全通路」）

全通路=编排(cron/Gitea issue)+数据(data session)+因子(factor session)+策略(strategy session)+LLM(研究协作+P4 语料加工)多 session 分工。本轮明确的设计边界:

边界 口径
系统第一入口=假设卡片 卡片之前(灵感酝酿/聊天/研报)系统不可见——故意设计(会话态须结晶为持久工件,类比 git 只认 commit);P4 只降低结晶摩擦,不改入口形态
卡片不自动分解因子 分解=研究 session(人+Claude 协作);卡片的作用是纪律三件套:锚点(防研究漂移,涨了但逻辑不符不算成功)/防重复(墓园检索)/血统(registry 的 hypothesis 字段挂回卡片)
因子出生在研究 session,流水线管生命周期 无假设的自动发掘=data mining 扫描器,墓园会被填满
半自动发掘两形态(P3 后) ①归因催生:系统发现族集体失效/残差异常→自动开假设卡片(研究方向,非因子)给人筛;②变体扫描:窗口/中性化变体批量生成→产出候选卡片人筛
权重:等权为宪法默认 调整两玩法:①直接调(改权重→升版本→影子对照→口令);②多版本并存对比(v3/v4 各自跑评估+影子,报告摆对比人挑转正)。建议族级权重(财务/量价/另类三档)为第一档粒度(参数少不过拟合);「降财务扩量价」类风格判断的天然触发位=研判卡档 4
策略两形态,都走孵化梯 模板型(factor_topn 配参数,系统可批量生成)/非标型(strategy session 手写,如轮动埋伏);出生不同,生长同梯(回测 gate→paper→影子→毕业口令一视同仁)
归因的假设特有验证 如「提前量是否真提前」(信号日 vs 板块启动日时差统计)=因子孵化时定义的自定义评估指标——评估管线可扩指标框架,指标逻辑本身是研究产物

§11.3 走查揭示的真缺口（P1 计划补丁方向,调研后一并落）

缺口 现状 补丁方向
定期全量重评缺位(用户抓出:既有引擎人触发,流水线建在「人曾跑过的结果」上=逻辑矛盾) batch_eval 无 CLI 纯人触发;factor_topn 回测人触发;daily_section 日更仅覆盖单影子因子 月度批评日=先批后评两段调度链:batch_eval 全量重评批(12M 窗,数据截止=上月末,范围=注册表全量)→monthly_review 读刚落库的批判定。跑批触发从「人点」变「日历」
数据扩域无系统件 现状=对话确认(data session 勘测接源+完整性门) 编排小件:假设卡片「数据需求」字段自动比对底座 manifest→生成缺口清单开 issue(接源本身仍归 data session+人)
备料时效性三防线 月度批(及时性)+双机对拍(准确性,防「当时就是错的」)+版本钉住/pit(可复现) 已在 P1 设计内,缺口仅在批的调度

§11.4 行业实践调研→已完成,结论折入 §12

用户明确:「需要 llm/因子/策略/数据多模块联合才全通路,说实话还是有一些割裂」→调研于 2026-09-23 完成,四条线:七系统编排复盘(自有材料)/量化平台(WorldQuant BRAIN+Qlib+聚宽/BigQuant/果仁+Barra)/LLM 因子循环(RD-Agent+Alpha-GPT+QuantAgent+TradingAgents)/MLOps(Dagster 资产编排+MLflow registry+Feast+dbt)。结论、割裂感五类治法对照、可落地借鉴清单(J1-J10)与 P1 补丁最终形态见 §12。

§12 行业实践调研结论（2026-09-23，治「割裂感」）

§12.1 总体判断：割裂感的重构

四条调研线的核心发现：

  • 七系统均无积累型研究流水线。TradingAgents/ai-hedge-fund=决策时刻编排（LangGraph 状态图/函数组合，每次决策重新开始，无历史积累）；FinRobot=分层库但层间靠开发者手工集成（同样割裂）；UZI=读路径工具集（无流水线概念也无积累）。它们的「不割裂」是因为「不积累」。
  • 国内平台（聚宽/BigQuant/果仁）是反面教材：无因子生命周期状态机、无自动全量重评、失效判断与环节衔接全留给人——用户体感的割裂感在这些商业平台上同样存在，不可照抄。
  • 对上我们的只有两家：WorldQuant BRAIN（alpha 池全周期状态机+自动门+OS 每日跟踪，人只出 idea）与 Qlib（一条声明式 YAML 贯穿数据→因子→模型→回测，人与系统的界面=一份声明文件）。

由此得出本 spec 最重要的认知重构：割裂感是「积累型系统」的固有税——管理长期研究资产（衰退/版本/血统）必然产生环节，环节必然要衔接。问题不是「怎么消灭割裂」，而是把衔接从人脑挪到落盘工件，人只在闸门出现（与 §5 五触点设计完全吻合）。

行业共识一句话（MLOps 线总结）：衔接靠资产新鲜度比较（文件 mtime 即可）、晋级靠受守门的状态机+指针切换（yaml+git 即可）、一致性靠单一计算定义+值级对拍（sqlite 即可）。全程无新框架，与三不宪法兼容。

§12.2 割裂感五类×行业治法×我们的落地件

# 断裂类型 行业治法（出处） 我们的落地件
1 触发断裂（跑分旧了/回测要人点） BRAIN OS 期每日自动增量跟踪；Qlib RollingGen 声明式滚动重评；Dagster 资产新鲜度驱动 P1 先批后评两段调度链（§11.3 已定）
2 衔接断裂（晋级后下游靠人想着推） MLflow「转移即事件」webhook；RD-Agent 工件文件链；TradingAgents 节点后 checkpoint 落盘 J1：状态转移自动开下游 issue（P1 补丁）
3 可见性断裂（跨模块状态无统一视图） Dagster 血缘图 UI；materialization 事件日志表 P0 驾驶舱后端化（读注册表+评估库+事件），P1 事件日志已有雏形（monthly_points JSON）
4 入口分散（做一事跨多模块） Alpha-GPT「人守两端」（想法层+入库层，中间全自动）；RD-Agent Copilot 双模式 P4 LLM 漏斗分诊+研究 session=人的统一界面（定位获佐证，无需新件）
5 概念割裂 — ✅ 已解决（§11.1 术语金字塔）

§12.3 可落地借鉴清单（J1-J10，全部宪法内）

# 借鉴 来源 落地位 优先级
J1 转移即事件：version_registry 状态转移（尤其→promoted）由脚本统一写入并自动开/更新 Gitea issue「合成层跟进+策略生成待办」，带证据链接（IC 报告/评审 issue 号） MLflow webhook+alpha 转移事件 P1 Task 2 补丁 高（治衔接断裂，小件）
J2 血统硬闸：注册表因子无 hypothesis 字段→全量批跑仍跑但 monthly_review 标警告+不进晋级候选（Alpha-GPT「人的想法作为搜索空间约束」=假设先行从纪律变闸门） Alpha-GPT P1 种子 yaml+monthly_review 高
J3 pre-gate 机械前置：晋级报告自动算硬指标清单（t_stat/IC/族内共线矩阵/子池稳健），判定五问只审「机械过但存疑」的门边案例——IC 共线 0.961 教训（盈利质量影子淘汰）的直接防线 BRAIN check submission P1 monthly_review 报告增强 高
J4 先批后评两段调度链+批次配置声明式化（窗长/步长/数据截止进 config，不散在命令行） Qlib RollingGen/segments P1 设计已覆盖，补「批次 yaml」表述 已在计划
J5 假设卡片=workspace 工件三件套：卡片挂「因子代码指纹+评估结果+反馈摘要」，成为唯一接力工件 RD-Agent workspace-per-hypothesis P4 卡片结构（远期） 中
J6 feedback trace 压缩回注：归因产物=「结论+归因+下轮建议」结构化摘要，非原始 JSON 回注 RD-Agent feedback trace P3 归因设计 中
J7 只沉淀已验证洞见：归因/批评结论带验证状态（已实证/待验证）入档，防下轮把臆测当事实 QuantAgent 知识库 P3/P4 中
J8 值级对拍：生产因子值落痕+pit_view 重算 diff（training-serving skew 检测的文件版） Feast 月度双机对拍器未来增强（当前报告级已够） 低
J9 Semi-OS 隐藏窗：最近 N 月只累积不参与晋级判定（防迭代过拟合） BRAIN Semi-OS 首年校准后再议 低（暂不上）
J10 assets.yaml 资产清单+mtime 扫描器（Dagster 声明式自动化的纯文件版） Dagster/make/dbt freshness 若未来环节>10 再上 低（YAGNI）

克制说明（Linus 三问）：J9 对个人系统偏重（BRAIN 是千级 consultant 迭代的防过拟合设施）；J10 在环节数<10 且已有 cron 链+月度批的当下是想象问题。均记录不实施。

§12.4 P1 补丁六件（2026-09-23 用户拍板，决议 J）

P1 补丁=§11.3 三件+J1/J2/J3 三件小增强，全部加在既有六任务内，不新增任务（P1 计划档 plans/2026-09-22-p1-factor-factory.md 的同步在执行前进行，设计以本节为准）：

  1. 先批后评两段调度链（§11.3 已定）
  2. 数据缺口自动比对小件（§11.3 已定）
  3. batch_eval 薄 CLI 入口（§11.3 已定）
  4. J1：version_registry 转移→自动开 issue（落 Task 2+部署节）
  5. J2：种子 yaml hypothesis 字段必填+monthly_review 无血统标警告（落 Task 6+种子节）
  6. J3：monthly_review 报告增 pre-gate 硬指标表含共线矩阵（落 Task 4 报告格式）

§12.5 P4 定位佐证（不改设计）

Alpha-GPT「人守两端」（想法层+一键入库层，中间搜索-回测-筛选全自动）与 RD-Agent Copilot 双模式（介入层级可配置：只在假设层介入或深入实验设计层），共同佐证我们的 LLM 漏斗分诊+研究 session 定位：人的统一界面=研究 session（假设卡片入口+晋级/毕业闸门），中间全自动。割裂第 4 类（入口分散）的行业治法即此，P4 原设计无需修改。（09-24 修正口径，决议 M）「研究 session=统一界面」细化为两层：浅路径=控制台卡片向导/分解器（P4 产品化，标准路径不经 session）；深路径=session 对话（深聊选项，非必经）——对话是选项不是工序。

§12.6 开发态/运行态分离原则（2026-09-24，用户 gap 反馈定型）

割裂感的治法终点=区分两个态：开发态（现在）多 session 协作+人当部分总线=脚手架，属正常；运行态（终态）日常运转零 session、零人肉协调、零 LLM 决策——cron/schtask+确定性代码自转，session 只在新需求/维修时出现。P0→P4 路线图=逐段拆脚手架换常设构件（P1 因子盯守已换、P2 梯子+聚合展示、P3 归因、P4 语料加工+入口产品化）。

运行态用户的全部入口只有三个：①控制台驾驶舱（日常，所有报告/信号/待办聚合一屏可跳转）；②闸门时刻（低频，功课已摆好，判断+口令）；③研究对话（随时；浅=向导按钮，深=session 深聊）。

判决报告原则（用户钦定，同日）：报告按「你要做的判断」组织，不按系统模块组织；信息在系统里但要去五个地方找=设计失败。每个闸门一份预整合功课：月度批评全景摘要（factor 域扩展待办）+梯子一卡通/毕业功课页（P2）+驾驶舱聚合（P2 接真=总入口）。跨域聚合归控制台层（读各域落盘工件拼接），域报告保持域内纯净。

issue 的双重角色：开发态=session 间协作单（脚手架，房子建好即拆）；运行态=确定性代码自动开的告警通知栏（月度批评 exit 2/J1 转移事件/数据缺口），写给人看、非 AI 对话通道——运行态不需要任何 session 发 issue 给另一 session。

Reference in New Issue View Git Blame Copy Permalink