feat: operationalize local Tushare Qlib research

README.md

@@ -70,7 +70,7 @@ python3 tools/build_public_status.py --check
 | 聚宽 hosted | 默认动量 smoke；显式注入 TargetPackage 后只消费本地 post-risk 权重并绑定平台账户/价格 | 动量模式已有一次 2024 全年 run；一个 synthetic-research TargetPackage 已真实命中、绑定 `day_open` 并产生 3 笔委托/成交 | 只观察 execution consumer；无授权真实长样本/OOS、上游四层 hosted 执行、QMT peer 或逐层真实数据 parity |
 | QMT built-in/qmttools | 默认动量 smoke；TargetPackage 模式为 Python 3.6 backtest-only 消费器 | Python 3.6 语法、TargetPackage/fake/qmttools 合约 | 需要已授权 QMT 客户端、历史数据权限与 TargetPackage 实跑导出 |
 | Qlib 0.9.7 | native momentum backtest；Alpha158/LightGBM CLI/Recorder 工作流 | Python 3.12 两条 fixture 已真实跑通，并保存表级 hash、行列/时间边界和重算指标 | synthetic 两股票没有投资价值；无真实 OOS、L3/L4 parity |
-| Tushare → Qlib | 只读盘点 completed Parquet、校验 checksum、构建/验证不可变 provider、运行本地回测 | 93 个 completed 文件已验证；早期未复权 provider 与两次 byte-identical momentum run | 下载仅到 1993-10；缺复权、真实 benchmark、历史成分/ST/停牌/涨跌停，不能进入生产 decision |
+| Tushare → Qlib | 只读盘点 live mirror、冻结 scoped release、构建/验证不可变 provider、运行本地回测 | 2018—2025 v2 verifier 通过；1,111 instruments、1,942 sessions；97 observed/96 effective 月末 snapshots 严格 500 成分、次日生效；lineage 221 jobs×6 fields mismatch 0、converter current true；双次 run byte-identical | event-time/保守次日生效 PIT 近似，不是严格 knowledge-time PIT；不同 start 的首观测锚 provider 不可直接拼接；research-only、`gate_credit=[]`、ST/统一 9.5% 仍缺 |
 | XtTrader shadow | 只读账户查询、HMAC 账户绑定、broker observation/snapshot、零下单 target-diff 计划与完整 verifier | fake broker/QMT 合约；所有 broker mutation 均不可达 | 需要授权 QMT 环境的账户合同探针、恢复/对账和券商确认；Baseline 60 至少 20 个交易日，Production 80 当前缺口为同一冻结候选至少 60 个交易日 |
 
 `portable-momentum-v1` 只是当前真实跑过聚宽的跨引擎连通性 smoke，不是
@@ -477,37 +477,70 @@ python -c "import qlib; assert qlib.__version__ == '0.9.7'"
 
 ### 使用本地 Tushare 镜像
 
-`tools/tushare_qlib.py` 不调用 Tushare、不读取 token，也不修改镜像。它只接受
-SQLite 中状态为 `completed` 且文件大小、SHA-256、Parquet 行数一致的分区；
-生成新 Qlib provider 时保存 source job、build parameter、converter hash、
-tree hash 与可重算 `data_version`，并拒绝覆盖已有目录。
+`tools/tushare_snapshot.py` 和 `tools/tushare_qlib.py` 不调用 Tushare、不读取
+token，也不修改镜像。先从仍可变化的 raw mirror 冻结一个日期/API/指数范围
+明确的 source manifest，再生成新 Qlib provider。provider 保存 source job、
+build parameter、converter hash、tree hash 与可重算 `data_version`，并拒绝
+覆盖已有目录。当前 build 不直接读取 scoped manifest，所以验收时还要确认
+两份 manifest 的 source job/file hashes 完全一致。
+
+推荐使用 Makefile 固定同一组路径和参数：
+
+```bash
+export TUSHARE_MIRROR_ROOT=/path/to/tushare-mirror
+export TUSHARE_PROVIDER=data/qlib/tushare-csi500-2018-2025-next
+export TUSHARE_SNAPSHOT=artifacts/local-tushare/scoped-source-manifest.json
+
+make tushare-snapshot
+make tushare-build
+make tushare-verify
+make tushare-lineage
+make tushare-backtest
+make tushare-replay
+```
+
+`TUSHARE_PROVIDER` 指向的 build 输出目录必须不存在；工具拒绝覆盖已有
+provider。`tushare-replay` 会先生成第一份 run，再生成第二份并用 `cmp`
+检查逐 byte 重放。
 
 ```bash
 export TUSHARE_MIRROR_ROOT=/path/to/tushare-mirror
 
 PYTHONPATH=src:. python tools/tushare_qlib.py inventory \
   --mirror-root "$TUSHARE_MIRROR_ROOT" \
+  --skip-file-verification \
   --output-json artifacts/tushare-inventory.json
 
+python tools/tushare_snapshot.py \
+  --mirror-root "$TUSHARE_MIRROR_ROOT" \
+  --start 2018-01-01 \
+  --end 2025-12-31 \
+  --apis daily adj_factor trade_cal stock_basic index_daily index_weight \
+  --index-codes 000905.SH \
+  --output artifacts/local-tushare-20260731/scoped-source-manifest.json
+
 PYTHONPATH=src:. python tools/tushare_qlib.py build \
   --mirror-root "$TUSHARE_MIRROR_ROOT" \
-  --output-dir data/qlib/tushare-early-v1 \
-  --start 1990-12-19 --end 1993-10-29 \
+  --output-dir data/qlib/tushare-csi500-2018-2025-v2 \
+  --start 2018-01-01 --end 2025-12-31 \
+  --market-name tushare_csi500 \
+  --benchmark-index-code 000905.SH \
+  --universe-index-code 000905.SH \
   --minimum-observations 60 \
-  --allow-unadjusted \
-  --ohlc-policy expand-range \
+  --ohlc-policy fail \
   --output-json artifacts/tushare-qlib-build.json
 
 PYTHONPATH=src:. python tools/tushare_qlib.py verify \
-  data/qlib/tushare-early-v1
+  data/qlib/tushare-csi500-2018-2025-v2
 ```
 
-当前镜像只有 1990-12—1993-10 日线，且没有 `adj_factor`、真实指数行情、
-历史成分、ST、停牌和涨跌停数据。因此 `--allow-unadjusted` 是显式技术
-smoke 降级，provider 固定 `production_eligible=false`、
-`investment_value_claim=false`、`gate_credit=[]`。盘点、字段口径、完整命令、
-v4 hash 与两次本地回测结果见
-[`docs/TUSHARE_LOCAL_DATA.md`](docs/TUSHARE_LOCAL_DATA.md)。
+当前镜像已有 1990-12—2026-07 日线和复权因子、真实中证 500 指数行情与历史
+权重、停牌和涨跌停数据；但 raw mirror 是移动目标，且历史 `stock_st` 权限被
+拒。v2 provider verifier 和两次 byte-identical 真实本地 run 已完成，但
+结果仍为 `production_ready=false`、`investment_value_claim=false`、
+`gate_credit=[]`。完整盘点、字段口径和本机
+命令见 [`docs/TUSHARE_LOCAL_DATA.md`](docs/TUSHARE_LOCAL_DATA.md) 与
+[`docs/runbooks/TUSHARE_QLIB_LOCAL_RUN.md`](docs/runbooks/TUSHARE_QLIB_LOCAL_RUN.md)。
 
 native momentum smoke：