StackOverFlow11 · StackOverFlow11 · Jun 19, 2026 · Jun 19, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -57,7 +57,7 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri
 
 ## 开发约定
 - **交流中文**；代码/注释/commit message 用**英文**。
-- **Git**：feature 分支 + PR。**PR #1（P0+P1）、#2（P2-1）、#3（P2-2）、#4（进度文档）、#5（P2-3）、#6（进度文档）、#7（P2-4）、#8（进度文档）、#9（P3-1）、#10（进度文档）、#11（P3-2）、#12（P3-3）、#13（进度文档）、#14（P3-4）、#15（进度文档）、#16（P3-5）、#17（进度文档）、#18（P3-6）、#19（P3-7）、#20（进度文档）、#21（P3-8）、#22（进度文档）、#23（P4-1）、#24（进度文档）、#25（P4-2）、#28（tushare 权限/限频探测 + capability registry）、#29（I1–I4 分钟级 intraday pipeline，4 commit 一 PR）、#30（进度文档）、#31（P4-3 因子支撑端点缓存 + 21:00 data updater，2 commit 一 PR）、#33（P-I5a 事件驱动回测架构重构 + opt-in 分钟尾盘 event model，4 commit 一 PR）、#35（P-I5b 分钟尾盘执行期 raw stk_limit 涨跌停可行性，4 commit 一 PR）、#37（P-I5c MMP 分钟因子端到端 opt-in alpha）、#39（P-I5d MMP 五分位分组回测 standalone，含 I5c plumbing）、#41（数据层 D1 契约文档 + token 解析去重）、#43（数据层 D2 TushareCache specs/parsers 拆分）、#45（数据层 D3 report-only 数据质量层）、#47（数据层 D3b default-off `data-update` 质量报告钩子）均已 merge 到 `main`**。commit 用 conventional 格式，**无 attribution**（不加 Co-Authored-By）。
+- **Git**：feature 分支 + PR。**PR #1（P0+P1）、#2（P2-1）、#3（P2-2）、#4（进度文档）、#5（P2-3）、#6（进度文档）、#7（P2-4）、#8（进度文档）、#9（P3-1）、#10（进度文档）、#11（P3-2）、#12（P3-3）、#13（进度文档）、#14（P3-4）、#15（进度文档）、#16（P3-5）、#17（进度文档）、#18（P3-6）、#19（P3-7）、#20（进度文档）、#21（P3-8）、#22（进度文档）、#23（P4-1）、#24（进度文档）、#25（P4-2）、#28（tushare 权限/限频探测 + capability registry）、#29（I1–I4 分钟级 intraday pipeline，4 commit 一 PR）、#30（进度文档）、#31（P4-3 因子支撑端点缓存 + 21:00 data updater，2 commit 一 PR）、#33（P-I5a 事件驱动回测架构重构 + opt-in 分钟尾盘 event model，4 commit 一 PR）、#35（P-I5b 分钟尾盘执行期 raw stk_limit 涨跌停可行性，4 commit 一 PR）、#37（P-I5c MMP 分钟因子端到端 opt-in alpha）、#39（P-I5d MMP 五分位分组回测 standalone，含 I5c plumbing）、#41（数据层 D1 契约文档 + token 解析去重）、#43（数据层 D2 TushareCache specs/parsers 拆分）、#45（数据层 D3 report-only 数据质量层）、#47（数据层 D3b default-off `data-update` 质量报告钩子）、#49（数据层 D4 coverage ledger 批量写 + 进程内查找缓存）均已 merge 到 `main`**。commit 用 conventional 格式，**无 attribution**（不加 Co-Authored-By）。
 - **不过度设计**：按路线图 MVP 先打通一条端到端链路，再加层（architecture.html §11，Phase 0→3）。
 - **secrets** 一律走外部 `.config.json`；repo `.gitignore` 已排除数据产物(`*.parquet`等)、缓存、`tmp/`（仅留架构文档）。
 - 文件小而专（<800 行），immutable 优先。
@@ -230,6 +230,12 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri
   - **接线**:`update_endpoints` 加可选 `capture` sink(默认 None → 暖路径字节级不变:feed 调用/参数/顺序/summary 全不变);`run_data_update` 仅 enabled 时跑钩子;`UpdateResult` +`quality_report_path`/`quality_findings_count`/`quality_hard_count`;CLI enabled 才打 `quality:` 行(disabled 输出不变)。
   - **report-only 不变量**:不过滤/修复/改数据、不让 job 失败、不改 cache coverage / 每端点请求 summary、无新端点、无质量专用 live 调用、不写 `PanelStore`、不动 ledger schema;日频 close-to-close 不漂移;报告不含 secret 路径/token/无界 symbol dump(继承 D3 redaction)。
   - **测试**(`tests/test_data_update_quality.py`,network-free fake feeds):默认禁用 / clean 报告 / bad 日频+分钟帧 → hard findings 且不抛异常不改 summary / 端点选择被尊重(未暖面绝不检查)/ `report_name` 路径校验 / 报告无 secret。真实 token 值扫描 **0 hits**;**未跑 live `data-update`**(network-free 验收)。
-- ✅ 质量门：`pytest` **643 passed**（P0=97 / P1=78 / P2-1=22 / P2-2=22 / P2-3=14 / P2-4=8 / P3-1=10 / P3-2=18 / P3-3=16 / P3-4=15 / P3-5=22 / P3-6=27 / P3-7=25+1 throttle / P3-8=8 / P4-1=28 / P4-2=17 / **intraday I1 schema=14 + feed=9 / I2 cache=10 / I3 aggregate=13 / I4 execution=10 / P4-3 cache=10 + updater=7 / P-I5a event-backtest=19 / P-I5b exec-feasibility=16 / P-I5c mmp-minute=18 / P-I5d mmp-quintile=19 / D1 token-dedup index-feed +2 / D2 cache-modularization +5 / D3 data-quality market=15 + intraday=12 + report=14 / D3b data-update-quality=18**）；`ruff` clean；`validate-config`（全部 17 配置含 data_update + phase_i5a + phase_i5b + phase_i5c + phase_i5d）+ `run-phase0`（demo）均 OK（**ic 0.9600 / annual 0.8408 不变**）。
+- ✅ **数据层 D4 — coverage ledger 批量写 + 进程内查找缓存**（**PR #49 已 merge 到 `main`**，Codex 验收;行为保持的缓存内部扩展,降低重复全表读写开销）：给日频 `CoverageLedger` 与分钟 `IntradayCoverageLedger` 加批量 API + 查找缓存。**公开方法/路径/列/coverage 语义全不变**。
+  - **`record_many(rows)`**(两个 ledger):一次归一化 + 一次原子 parquet 写;空输入 no-op;每行与单行 `record` 逐字归一;写后 reindex 到公开列契约;无 secret 字段。**`record()` 委托给 `record_many([row])`**,单行路径与批量路径一致。
+  - **进程内查找缓存**:每实例帧缓存 + 按 `(endpoint, key[, raw_freq])` 的 memo,使重复 `covered_intervals`/`snapshot_fetched_at`/`covered_day_intervals` 不再重读重过滤整张 parquet;按文件 `st_mtime_ns` 失效(**外部写绝不被当陈旧服务**),写入后原地刷新;三个 lookup **先 `_load()` 再查 memo**(外部变更总清陈旧 memo);`read()` 返回 copy 防外部污染内部缓存。
+  - **缓存接线**:`TushareCache._record_gap_coverage` 的 not-ready 拆分用**一次** `record_many` 写其 1–2 行(经 `_record_rows`),`not_ready` 计数/状态不变;其余 call site 仍 `record()`(单行批量)——成功 gap 照常记录,后续失败 fetch 绝不反记成功。分钟缓存(每 gap 一行)未改;无明显安全批量。
+  - **不变量守住**:公开构造/方法(`read`/`covered_intervals`/`snapshot_fetched_at`/`record`/intraday `covered_day_intervals`)、parquet 路径(`manifest/coverage.parquet`/`coverage_intraday.parquet`)、`LEDGER_COLUMNS`/`INTRADAY_LEDGER_COLUMNS` 名序、coverage 语义(仅 ok/empty 算覆盖;failed/not_ready 不算;snapshot 取最新成功 fetched_at;not_ready_days 不变)全不变;无 config 旋钮 / 无 cache-root 布局变更;phase0 `0.9600/0.8408` 不变。
+  - **测试**(`tests/test_coverage_ledger_scaling.py`,network-free,13):`record_many` ≡ 重复 `record`(名序/值)/ `record_many([])` no-op / `covered_intervals` 仅 ok·empty / `snapshot_fetched_at` 取最新成功 / 分钟镜像 / **重复 lookup 不重读 parquet**(spy load 路径,非计时)/ **外部写失效缓存** / `read()` 返 copy / not-ready 拆分一次批量 / 平凡 gap 单行 / ledger 列无 secret 字段。
+- ✅ 质量门：`pytest` **656 passed**（P0=97 / P1=78 / P2-1=22 / P2-2=22 / P2-3=14 / P2-4=8 / P3-1=10 / P3-2=18 / P3-3=16 / P3-4=15 / P3-5=22 / P3-6=27 / P3-7=25+1 throttle / P3-8=8 / P4-1=28 / P4-2=17 / **intraday I1 schema=14 + feed=9 / I2 cache=10 / I3 aggregate=13 / I4 execution=10 / P4-3 cache=10 + updater=7 / P-I5a event-backtest=19 / P-I5b exec-feasibility=16 / P-I5c mmp-minute=18 / P-I5d mmp-quintile=19 / D1 token-dedup index-feed +2 / D2 cache-modularization +5 / D3 data-quality market=15 + intraday=12 + report=14 / D3b data-update-quality=18 / D4 coverage-ledger-scaling=13**）；`ruff` clean；`validate-config`（全部 17 配置含 data_update + phase_i5a + phase_i5b + phase_i5c + phase_i5d）+ `run-phase0`（demo）均 OK（**ic 0.9600 / annual 0.8408 不变**）。
 - ⚠️ 剩余（已显式披露）：日线 only、demo 路径非真数据、旧三因子无信号（P3-3/P3-4 实证;但其组合在 2024-2026 holdout 上 SSE50/CSI300/CSI500 全正、CSI500 高达 +17.8%——小样本/regime 翻转的持续例证）;value/低波信号获得**独立样本符号级确认**（P3-7 SSE50/CSI300 量级衰减;P3-8 CSI500 泛化成立且更强），组合级盈利能力仍未确立（排名跨 cell 翻转）;subset 报告文件名已可配置（P3-8 起不再互覆盖）。
-- 路线图下一步：**I5d 独立泛化**（MMP 五分位单调性是项目首个正向 intraday 信号,但只一个重叠 5 年窗口/一个 universe → 在第二个 universe（CSI300/中证1000）和/或 disjoint 窗口上机器冻结复跑分组回测,使单调性可归因于因子而非该 regime,沿 P3-7/P3-8 独立确认先例）；**I5b/执行 follow-up**（执行期 feasibility 可再扩 partial-fill / liquidity / volume cap，size-aware 读数前补）；**P4-3 follow-up**（fina 按 ann_date 建披露日历 ledger 以去掉启发式 tail / updater 加 stk_mins 历史回填 / data-update summary 落 cache-stats artifact）；**数据层 D4**（D1+D2+D3+D3b 已 merge：契约文档化 + token 解析收敛 + `TushareCache` specs/parsers 拆分 + report-only `data/quality/` 质量层 + default-off `data-update` 质量报告钩子；下一步 **D4**=`CoverageLedger` 存储扩展 / batch 写入；之后 **D5** 并发 / endpoint schema registry——均尚未实现）；研究侧：更长 holdout 滚动复检 / 成本模型细化。
+- 路线图下一步：**I5d 独立泛化**（MMP 五分位单调性是项目首个正向 intraday 信号,但只一个重叠 5 年窗口/一个 universe → 在第二个 universe（CSI300/中证1000）和/或 disjoint 窗口上机器冻结复跑分组回测,使单调性可归因于因子而非该 regime,沿 P3-7/P3-8 独立确认先例）；**I5b/执行 follow-up**（执行期 feasibility 可再扩 partial-fill / liquidity / volume cap，size-aware 读数前补）；**P4-3 follow-up**（fina 按 ann_date 建披露日历 ledger 以去掉启发式 tail / updater 加 stk_mins 历史回填 / data-update summary 落 cache-stats artifact）；**数据层 D5**（D1+D2+D3+D3b+D4 已 merge：契约文档化 + token 解析收敛 + `TushareCache` specs/parsers 拆分 + report-only `data/quality/` 质量层 + default-off `data-update` 质量报告钩子 + coverage ledger `record_many` 批量写 + 进程内查找缓存；下一步 **D5**=并发 / 线程池 / 全局限频器,以及 endpoint schema registry——均尚未实现）；研究侧：更长 holdout 滚动复检 / 成本模型细化。