feat: operationalize local Tushare Qlib research

2026-07-31 01:26:49 +08:00
parent f81c116bfe
commit 6275370afc
21 changed files with 4438 additions and 401 deletions
@@ -1,225 +1,329 @@
-# Tushare 本地数据盘点、Qlib 接入与回测手册
+# Tushare 本地数据盘点、冻结边界与 Qlib 接入

-截至 2026-07-26，Quant OS 已能只读盘点另一个任务生成的 Tushare
-Parquet 镜像，校验已完成分区，并转换为不可变的 Qlib 0.9.7 provider。
-这条路径已经完成两次 byte-identical 的本地动量回测。
-
-当前证据的边界是：
+点时证据：2026-07-31 00:40 CST。原先“93 个 completed 文件、日线只到
+1993-10”的结论已经失效，不得再用于判断当前镜像。当前镜像约 7.7 GB，
+SQLite job ledger 在该点时已有 378,707 条 `completed` 版本记录、约
+1.80 亿行；同时仍有与本次中证 500 研究无关的指数任务处于 `running`。

 ```text
-completed_partitions_only_not_full_mirror
+tushare_daily_completed_partitions = 428
+tushare_daily_planned_partitions = 428
+tushare_daily_completed_rows = 18,041,386
+tushare_daily_market_data_from = 1990-12-19
+tushare_daily_market_data_through = 2026-07-28
 production_ready = false
 investment_value_claim = false
 gate_credit = []
 ```

-它证明“本地 Tushare 数据可以进入 Qlib 并可重放”，不证明镜像已经下载完整，
-也不证明策略收益有效或 Quant OS 已达到 `BASELINE_60`。
+这意味着数据已经足够做一条真实的 2018—2025 本地 Qlib 研究链，但不能把
+“live raw mirror 很大”直接等同于“已经有可复现、可用于发布结论的数据集”。
+正确边界是三层：

-## 1. 2026-07-26 点时盘点
+| 层 | 本机位置/产物 | 用途 | 是否可变 |
+| --- | --- | --- | --- |
+| live raw mirror | `$TUSHARE_MIRROR_ROOT` | 下载器持续落盘的 Parquet、权限探测和 job ledger | 是；不能直接作为可重放 run 的唯一引用 |
+| scoped frozen release | `tools/tushare_snapshot.py` 生成的范围化 manifest | 固定日期、API、指数代码、所选 job/file hash 和选择规则 | manifest 不变；引用的 raw bytes 仍需留存 |
+| Qlib provider | `data/qlib/...` + provider manifest | Qlib 0.9.7 可直接读取的 calendar/instruments/features | 否；是 frozen release 的派生物，不是原始数据备份 |

-镜像中共有 93 个状态为 `completed` 的 Parquet，均通过 SQLite 记录的文件大小、
-SHA-256 和 Parquet row count 校验；另有 1 个遗留 `running` job。
+`tools/tushare_qlib.py` 和冻结工具都只读镜像，不调用 Tushare，也不读取或保存
+token。snapshot 工具不复制 Parquet；manifest 能在源文件被覆盖时检测不一致，
+但若要长期从 raw bytes 重建，还需要后续接入 content-addressed archive。
+原始 Parquet、绝对路径、账号信息和本地运行 artifacts 不进入 Git。

-| 表 | 文件数 | 行数 | 当前范围/说明 |
-| --- | ---: | ---: | --- |
-| `daily` | 35 | 28,731 | 1990-12-19—1993-10-29，138 个代码、731 个交易日 |
-| `trade_cal` | 37 | 13,004 | SSE 1990—2026 日历，8,689 个开市日 |
-| `stock_basic` | 4 | 5,869 | 当前上市/退市/暂停上市等基础快照 |
-| `stock_company` | 3 | 6,294 | SSE/SZSE/BSE 公司资料 |
-| `index_basic` | 7 | 9,643 | CSI/SW/SSE/SZSE 等指数基础资料 |
-| `index_classify` | 6 | 870 | 申万 2014/2021 分类 |
-| `bse_mapping` | 1 | 248 | 北交所新旧代码映射 |
-| **合计** | **93** | **64,659** | **5,734,035 bytes Parquet** |
+## 1. 当前真实覆盖

-`daily` 原计划覆盖 1990-12—2026-07，共 428 个月；当前完成 35 个月，约
-8.2%。下载进程已停止，SQLite 仍遗留
-`daily/month=1993-11` 的 `running` 状态。日志显示首先发生 DNS 解析失败，
-错误处理阶段又发生 `sqlite3.OperationalError: unable to open database
-file`。因此不能把这个状态解释为仍在后台下载，也不要在 Quant OS
-转换过程中修改或自动恢复原下载器。
+下面同时区分“自然分区文件”和 SQLite 的“completed 版本记录”。下载器在
+2026-07 月内多次刷新同一个分区，所以 `daily` 和 `adj_factor` 都是 428 个
+自然月文件，却各有 430 条 completed 版本记录。job 行数求和会重复计算旧版
+2026-07，不能当作当前文件行数。

-尚未落盘的生产关键表包括：
+| 数据 | 当前自然文件 | 当前行数 | 实际可见范围 | 可直接支持什么 |
+| --- | ---: | ---: | --- | --- |
+| `daily` | 428 | 18,041,386 | 1990-12-19—2026-07-28 | OHLC、前收、成交量额、收益与本地撮合输入 |
+| `adj_factor` | 428 | 18,868,457 | 1990-12—2026-07；最大 `trade_date=20260729` | 区间内累计复权 |
+| `trade_cal` | 39 completed 版本 | 13,423 | SSE 1990—2026 | 交易日历与完整性检查 |
+| `stock_basic` | 4 | 5,869 | 当前上市、退市、暂停上市等快照 | 代码、上市/退市日期；不是 PIT 成分表 |
+| `daily_basic` | 331 | 17,335,584 | 1999-01-04—2026-07-28 | 市值、换手、估值与横截面特征 |
+| `stk_limit` | 235 | 17,878,521 | 2007-01-04—2026-07-29 | 逐股逐日真实涨跌停价格 |
+| `suspend_d` | 37 | 641,379 | 非空记录 1999-05-04—2026-07-29 | 停复牌与可交易性 |
+| `index_daily`，`000905.SH` | 37 年 job | 5,239 | 2004-12-31—2026-07-29 | 真实中证 500 benchmark |
+| `index_weight`，`000905.SH` | 37 年 job | 129,000 | 2005-01-31—2026-06-30 | 中证 500 的历史定期成分/权重快照 |
+| `index_member_all` | 1 | 3,000 | 申万行业层级及进出日期 | 行业分类；不能冒充中证 500 历史成分 |

- `adj_factor`、`index_daily`；
- `index_member_all`、`index_weight`；
- `stk_limit`、`suspend_d`、`stock_st`；
- `daily_basic`。
+`daily` 原计划覆盖 1990-12—2026-07，共 428 个月；当前完成
+428 个月，约 100.0%。这里的
+“完成”只指自然月文件覆盖，不代表 live mirror 已冻结，也不代表
+production-ready。

-其中历史 `stock_st` 权限探测被拒绝。即使其他下载完成，历史 ST 仍需要新的
-授权数据源或明确的降级门禁。
+另外已有 `income`、`balancesheet`、`cashflow`、`fina_indicator`、
+`disclosure_date`、`moneyflow` 等数据。它们可以用于下一阶段的基本面、质量、
+资金流特征，但财务报表必须按公告/披露可得日做 as-of join，不能直接按报告期
+回填到历史日期。

-## 2. 已确认的数据质量
+### 仍然存在的硬缺口

- 已完成 Parquet 自然键无重复，核心日线字段无空值；
- 无负成交量或负成交额，日线日期与同期 SSE 开市日完全对应；
- 17 条早期 OHLC 包络异常；默认拒绝，只有显式
-  `--ohlc-policy expand-range` 才按原始 `open/high/low/close` 四价的
-  min/max 修复，并记录数量与异常键 hash；
- 2 条 `pct_chg` 与保存精度下重算结果的偏差超过 0.02 个百分点；
- 日线代码 `000022.SZ` 不在当前 `stock_basic` 快照；
- `stock_basic` 存在遗留非标准代码 `T600018.SH`，转换器不会把它当成
-  A 股代码；
- `index_basic.base_point` 存在分区类型漂移，后续 canonical 合并时必须
-  显式 cast。
+- 2026-07-26 的权限探测明确显示 `stock_st` 为 `denied`。在获得授权历史
+  ST 源之前，不能声称完整复现 ST 股票的逐日交易限制；
+- live ledger 在本次点时仍有 24 个 `running`：19 个
+  `931632CNY04.CSI` 的 `index_daily` 年任务和 5 个 `931632.CSI` 的
+  `index_weight` 年任务。它们与 `000905.SH` 的 2018—2025 release 无关，
+  但说明全镜像仍是移动目标；
+- `daily` 的最新 completed 请求元数据包含 `20260729`，但当前 Parquet
+  的最大实际日期是 `20260728`；任何冻结工具都必须验证 Parquet 内容，而不能
+  只相信请求参数或 job 状态；
+- 多个 completed 版本可指向同一个最终路径。冻结时必须按明确规则选择当前
+  canonical 版本并复核 size/SHA-256/Parquet row count，不能把所有
+  `completed` 盲目拼接；
+- `stock_basic` 是当前快照，不得用它反向构造历史指数 universe。

-Tushare 的 `daily` 是未复权行情，停牌期间不返回记录；`vol` 单位为手，
-`amount` 单位为千元。转换器固定执行：
+## 2. 数据如何进入 Quant OS
+
+第一条可用研究路径是中证 500 横截面研究：
+
+```text
+daily + adj_factor + trade_cal
+  + index_daily(000905.SH)
+  + index_weight(000905.SH)
+  -> scoped frozen release (2018-01-01—2025-12-31)
+  -> managed Qlib provider
+  -> momentum / Alpha158 / LightGBM
+  -> evidence JSON + provider verifier
+```
+
+第二条是本地事件回测输入：
+
+```text
+raw daily/pre_close + stk_limit + suspend_d
+  + PIT universe + signal/target
+  -> Quant OS reference execution
+  -> ledger / replay / platform parity
+```
+
+两条路径不能混为一谈。Qlib 负责因子、模型和组合研究；Quant OS 的
+Signal/Target/Order/Broker 合同、涨跌停、停牌、T+1、成交和对账仍由本地
+事件链负责。历史 ST 未补齐时，本地执行链必须保留显式缺口或 fail-closed，
+不能静默按普通股票处理后再把结果标为完整市场仿真。
+
+### 复权口径
+
+新 provider 对每个 symbol 使用 release 区间内第一个有效 `adj_factor` 作为
+锚点：
+
+```text
+factor_t = adj_factor_t / first_valid_adj_factor
+adjusted_OHLC_t = raw_OHLC_t * factor_t
+adjusted_volume_t = raw_volume_in_shares_t / factor_t
+money_t = raw_amount_in_CNY_t
+```
+
+这是“首个有效因子锚定的区间累计复权”，文档和证据中不要把它简写成
+`qfq`。不用区间末因子做归一化，是为了避免研究区间末端信息参与早期价格的
+缩放。停牌缺口保留为 `NaN`，不会伪造 K 线。
+
+固定单位仍为：

 ```text
 600000.SH -> SH600000
 000001.SZ -> SZ000001
 430047.BJ -> BJ430047
-volume = vol * 100
-money = amount * 1000
-factor = 1
+raw_volume_in_shares = Tushare vol * 100
+raw_amount_in_CNY = Tushare amount * 1000
 ```

-未上市、退市后和停牌缺口在 Qlib feature 中保留为 `NaN`。字段语义来源见
-[Tushare 日线接口](https://tushare.pro/document/2?doc_id=27)与
-[复权因子接口](https://tushare.pro/document/2?doc_id=28)。
+### universe 与 benchmark 口径

-## 3. Quant OS 如何使用这些数据
+- benchmark 使用 `index_daily(000905.SH)`，Qlib symbol 为 `SH000905`；
+- universe 使用 `index_weight(000905.SH)` 的历史快照，并按“只向未来
+  carry-forward、绝不从未来 backfill、月末权重下一交易日生效”生成时变
+  成分区间。这是 event-time / 保守次日生效 PIT 近似；源数据没有单独验证的
+  `published_at`，不能声称严格 knowledge-time PIT；
+- `index_member_all` 是申万行业数据，不参与中证 500 universe；
+- 研究报告必须分别披露 benchmark、universe、价格复权和可交易性过滤来源。

-当前已经实现的链路是研究/引擎验证路径：
+## 3. 现有代码基线与 v2 接口

-```text
-Tushare mirror
-  -> 只读取 SQLite completed jobs
-  -> 文件大小 + SHA-256 + Parquet row count/footer 校验
-  -> 新目录原子发布 Qlib binary provider
-  -> provider tree hash + data_version + manifest verifier
-  -> Qlib momentum / Alpha158 research runner
-```
+### 现有基线

-正式 Quant OS 还需要第二条生产数据路径：
-
-```text
-完整 Tushare/JQData PIT 数据
-  -> canonical immutable snapshot
-  -> Quant OS 本地事件回测 / decision
-  -> 聚宽、QMT、Qlib 的同输入分层比较
-```
-
-Qlib 适合因子、模型和组合研究，不拥有原始数据，也不替代 Quant OS 的
-Signal/Target/Order/Broker 合同。当前 Tushare adapter 只实现第一条链路；
-在复权、真实 benchmark、历史成分、停牌、涨跌停和 ST 数据补齐前，不会把它
-接入生产 decision。
-
-## 4. 可运行命令
-
-从 Quant OS 根目录执行。镜像路径只放在当前 shell 环境变量中，不写入 Git：
+仓库当前基线的 `build` 只消费 `daily/trade_cal/stock_basic`，必须显式传
+`--allow-unadjusted`，会生成 synthetic equal-weight benchmark，并按整个
+研究区间的最少观测数筛选股票。它只能用于转换器/运行时技术验证：

 ```bash
-export QUANT_OS_ROOT=/path/to/quant-os
-export TUSHARE_MIRROR_ROOT=/path/to/tushare-mirror
-cd "$QUANT_OS_ROOT"
-
-python3.12 -m venv .venv-qlib312
-source .venv-qlib312/bin/activate
-python -m pip install -r requirements/research-py312.txt
-export PYTHONPATH=src:.
-```
-
-盘点并验证全部 completed 文件：
-
-```bash
-python tools/tushare_qlib.py inventory \
+PYTHONPATH=src:. python tools/tushare_qlib.py build \
  --mirror-root "$TUSHARE_MIRROR_ROOT" \
-  --output-json artifacts/tushare-inventory.json
-```
-
-当前未复权数据只能显式构建技术验证 provider；每次必须使用新目录，工具拒绝
-覆盖已有 provider：
-
-```bash
-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-legacy-2018-2025 \
+  --start 2018-01-01 \
+  --end 2025-12-31 \
  --minimum-observations 60 \
  --allow-unadjusted \
-  --ohlc-policy expand-range \
-  --output-json artifacts/tushare-qlib-build.json
-
-python tools/tushare_qlib.py verify \
-  data/qlib/tushare-early-v1 \
-  --output-json artifacts/tushare-qlib-verify.json
+  --ohlc-policy fail \
+  --output-json artifacts/tushare/legacy-build.json
 ```

-运行 Qlib 0.9.7 本地回测：
+不要用这个结果回答“中证 500 策略是否有效”，也不要给它任何发布门禁分数。
+
+### 已验证的 v2 接口
+
+v2 已消费 `adj_factor`、真实指数行情和历史指数权重，并完成 provider
+构建、验证和两次本地 run。实际构建命令为：

 ```bash
-PYTHONHASHSEED=0 python -m platforms.qlib_runner \
-  --provider-uri data/qlib/tushare-early-v1 \
-  --market tushare_a \
-  --benchmark SH999999 \
-  --start 1992-01-02 \
-  --end 1993-10-28 \
-  --feature-start 1991-01-02 \
-  --lookback 20 \
-  --topk 10 \
-  --n-drop 2 \
-  --rebalance weekly \
-  --output-json artifacts/tushare-qlib-momentum.json
+PYTHONPATH=src:. python tools/tushare_qlib.py build \
+  --mirror-root "$TUSHARE_MIRROR_ROOT" \
+  --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 \
+  --ohlc-policy fail \
+  --output-json artifacts/tushare/csi500-2018-2025-build.json
 ```

-Qlib simulator 会消费结束日后的下一 provider session，所以 backtest `end`
-必须早于 provider 最后一个交易日。Quant OS 对受管 provider 会在 Qlib
-初始化前检查 market、benchmark、起始边界和这个终点条件。
+这条命令不再传 `--allow-unadjusted`。provider manifest 必须记录复权口径、
+真实 benchmark、时变 universe、所有 source job/file hash、转换器 hash、
+质量统计和可重算 `data_version`。

-`artifacts/` 与 `data/qlib/` 均被 Git 忽略。原始 Parquet、token、绝对镜像
-路径和回测临时产物不得提交到仓库。
+`tools/tushare_snapshot.py` 是独立的 raw scoped freeze 入口。Qlib 核心输入
+可以这样冻结：

-## 5. 本次真实本地运行证据
+```bash
+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
+```

-最终 v4 provider：
+默认会验证 size、SHA-256 和 Parquet row count。需要研究
+`daily_basic/stk_limit/suspend_d` 时应再冻结一个明确包含它们的扩展
+release；不要把未列入 manifest 的表暗中加入既有 run。当前 `build` 仍从
+mirror 重新选择 source jobs，并不接受这份 manifest 作为参数，因此 run
+验收还必须比较 provider manifest 与 scoped manifest 的 source
+job/file hashes。

-| 证据 | 值 |
+snapshot 工具在请求 `index_weight` 时会自动包含 `start.year-1` 的 pre-start
+PIT anchor。本次 scoped manifest 与 provider 均为 221 个 source jobs，
+全字段比对零差异，已经覆盖有效 roster 日期 `2017-12-29`：
+
+```text
+scoped_manifest_sha256 = 744a69828f527594e9f2787280095368c50deffa2f269c359ae65e2e0ac2d5f2
+scoped_selection_sha256 = 66e91fffecba5fa042922c49e339f24212c3febf5b874279866fdca660f54fb5
+scoped_source_jobs = 221
+provider_source_jobs = 221
+source_job_full_field_diff = 0
+provider_source_jobs_before_read = 221
+provider_source_jobs_after_read = 221
+provider_selected_jobs_still_latest = true
+provider_post_read_file_verification = true
+```
+
+冻结期间 SQLite 主文件/WAL 仍被无关下载任务更新：
+`changed_through_file_verification=true`。这不是 selected scope 未冻结：
+SQLite 事务读取期间 `changed_while_reading=false`，221 个 selected jobs
+均完成两次 size/SHA-256/Parquet row-count 校验，验证后仍是各自 partition
+的 latest，并与 provider 的 221 个 source jobs 全字段零差异。这里的证据边界
+是“scoped jobs 稳定”，不是“整个 live DB/WAL 静止”。
+
+scoped manifest 与 provider 的正式 lineage 由独立工具核对：
+
+```bash
+python tools/tushare_lineage.py \
+  --source-manifest artifacts/local-tushare-20260731/scoped-source-manifest.json \
+  --provider-dir data/qlib/tushare-csi500-2018-2025-v2 \
+  --output-json artifacts/tushare/csi500-2018-2025-lineage.json
+```
+
+结果为 221 个 jobs、6 个逐 job 字段
+`id/path/row_count/byte_count/sha256/request_sha256` 全部一致，
+`mismatch_count=0`、`converter_source_matches_current=true`。lineage artifact
+同样明确 `investment_value_claim=false`、`gate_credit=[]`。
+
+## 4. 2018—2025 provider 与双次回测实证
+
+managed provider 已构建在新目录，并由独立 verifier 通过：
+
+| 证据 | 实测值 |
 | --- | --- |
-| adapter source SHA-256 | `2228c23af176a0f2fcf311e88dca9bdc5d63fd36fa5a3c2d3e42808a405e7243` |
-| data version | `3378aa75a5601bde476ad07bea90418966a66a037ca59195dec93d77b41cc3f8` |
-| provider tree SHA-256 | `dc85b8daf692a66641afef64398700264c6054f1dac84b1211cb258a06b62948` |
-| manifest SHA-256 | `862e7435bb0be7c8a3c66180e49761c110056c1a3cc02c1618e70d9eb566d945` |
-| provider 文件/大小 | 975 / 1,085,886 bytes |
-| calendar | 1990-12-19—1993-10-29，731 sessions |
-| market | 107 个至少有 60 条记录的 A 股代码 |
-| selected rows | 27,998 |
+| data version | `5bf19d2da064357ad1802bca4bfa0c0505ed63fe2b24785ec6c56ecff1724963` |
+| provider tree SHA-256 | `f173b8095fd9a62a63807324fa48bad83f0c282eea3abba871d0b0efd30b199f` |
+| provider manifest SHA-256 | `27fb6fedb6a4b114eae2aba44505fb6c4d32c7a9ae81e58c724dfadb8dd10ed0` |
+| provider files / bytes | 10,011 / 71,707,194 |
+| source stability | 221/221 jobs 在消费前后稳定；读取后重新校验文件且仍为 latest |
+| calendar | 2018-01-02—2025-12-31，1,942 sessions |
+| event-time PIT 近似 market | 1,111 个曾进入 `000905.SH` roster 的 instruments |
+| snapshot coverage | 97 observed / 96 effective；最大日历间隔 36 天 |
+| roster quality | 每个 observed snapshot 严格 500 constituents；weight sum 容差 ±0.5 |
+| availability | 月末权重从下一 provider 交易日生效；`same_session_membership_use=false` |
+| selected daily rows | 1,975,455 |
+| price adjustment | 完整；0 个缺失 daily/adj keys；首个有效因子锚定 |
+| OHLC quality | `--ohlc-policy fail`；0 个 envelope anomalies |
+| benchmark | 真实 `index_daily(000905.SH)` / `SH000905` |
+| release flags | `production_ready=false`、`investment_value_claim=false`、`gate_credit=[]` |

-回测参数为 1992-01-02—1993-10-28、20 日动量、周频、Top 10、每期 drop 2，
-初始资金 1,000 万，Qlib 0.9.7、Python 3.12.13、`PYTHONHASHSEED=0`。
-相同命令连续执行两次，结果 JSON 逐 byte 相同：
+周频 20 日动量参数为 2019-01-02—2025-12-30、Top 50、每期 drop 5、
+初始资金 1,000 万、开仓费 0.03%、平仓费 0.08%、最低费用 5 元、
+`PYTHONHASHSEED=0`。相同命令连续执行两次，两个 JSON 逐 byte 相同：

-| 证据/指标 | 值 |
+| 证据/指标 | 实测值 |
 | --- | ---: |
-| result JSON SHA-256 | `92ff9b8cea746e9c89ddf62fcfe3feb21248ca9112d9e10d24e0639058a86020` |
-| runner source SHA-256 | `fa8118819252c55e99e67de356cc961d8a4a22f82256b4d62579a45426d96167` |
-| signal | 4,700 行；hash `cfad4087d68b7f71e33f0f46fc5bb97db985e02ac2515f01857e2ab6813a5909` |
-| portfolio report | 466 行；hash `5f8606fb64963d3e2618f66503e6ae94048c24b62c5d8e1806ff44ec57558b04` |
-| strategy cumulative return | -52.5251% |
-| max drawdown | -87.7604% |
-| synthetic benchmark cumulative return | 196,302.0822% |
-| total cost / turnover | 0.016013 / 29.567521 |
+| run JSON SHA-256 | `803035a95ee9cf6f90af20cdf7e7024149b97e0113b585209a80f80048be87d3` |
+| signal rows | 176,615 |
+| portfolio report rows | 1,698 |
+| strategy cumulative return | 0.253151986388197（25.3152%） |
+| benchmark cumulative return | 0.789559383530678（78.9559%） |
+| max drawdown | -0.6041641365538415（-60.4164%） |
+| total cost / turnover | 0.03579348112198462 / 65.51393782463258 |

-这些收益数字没有投资解释。原因包括未复权早期行情、没有真实指数 benchmark、
-没有历史成分/ST/停牌/涨跌停、按全区间至少 60 条观测筛选带来的非 PIT
-偏差，以及 1992—1993 特殊市场阶段。极端 synthetic benchmark 恰好说明
-为什么“程序跑完”不能等价为“回测有效”。
+这组数字证明真实 Tushare → event-time/保守次日生效 PIT 近似 universe →
+复权 Qlib provider →
+momentum runner 的链路可重放，不证明策略可投资。策略显著跑输 benchmark，
+且最大回撤超过 60%，不能把正累计收益单独拿出来宣传。

-## 6. 何时可以升级为正式研究数据
+最终身份变化来自 verifier/转换器源码绑定；provider tree 与回测数值未变。
+verifier 已确认 recorded/current converter SHA-256 一致。由于 run evidence
+绑定 provider identity，两个 run JSON 的 SHA-256 随之更新。

-至少完成以下步骤后，才能新建 production-eligible provider：
+## 5. 验证顺序

-1. 修复下载器错误状态并完成目标日期的 `daily`；
-2. 补齐 `adj_factor`，冻结复权基准日和公式；
-3. 使用 `index_daily` 替换合成 benchmark；
-4. 指数策略补齐 `index_member_all/index_weight`；
-5. 补齐 `suspend_d/stk_limit`，为历史 `stock_st` 找到授权来源或保持硬阻断；
-6. 冻结下载 job、请求 hash、Parquet hash、转换器 hash 和新 `data_version`；
-7. 运行真实长样本 walk-forward/OOS，而不是复用本次早期 smoke；
-8. 同一冻结输入进入 Quant OS 本地回测、聚宽和可用 QMT，生成 L1—L4
-   差异报告。
+1. 对 live mirror 做快速元数据盘点，确认目标 API 和 `000905.SH` 范围；
+2. 生成 2018—2025 scoped frozen release，并验证所选文件的 size、
+   SHA-256、Parquet footer/row count、自然键和日期边界；
+3. 在冻结后从同一 source state 构建新 provider，绝不覆盖已有目录，并核对
+   provider/scoped manifest 的 source hashes；
+4. 运行 `tools/tushare_qlib.py verify`，核对 manifest、tree hash、
+   calendar、instrument 和 feature 文件；
+5. 运行同一条 Qlib momentum 命令两次，比较 evidence JSON 的关键输入、
+   signal/report hash 和重算指标；
+6. 再进入 walk-forward、Alpha158/LightGBM、成本/风险扰动和本地事件回测。

-Qlib provider 的目录格式和缺失值/复权约定参见
-[Qlib Data Layer 文档](https://qlib.readthedocs.io/en/latest/component/data.html)。
+完整可复制命令见
+[`runbooks/TUSHARE_QLIB_LOCAL_RUN.md`](runbooks/TUSHARE_QLIB_LOCAL_RUN.md)。
+
+## 6. 结果边界
+
+2018—2025 的真实行情、复权、指数行情和历史权重会让回测比旧的
+1990—1993 technical smoke 有意义得多，但仍只是一条研究证据：
+
+- momentum smoke 的收益不能证明投资价值；
+- Qlib 的成交模型不能替代 A 股逐股涨跌停、停牌、T+1 和真实容量仿真；
+- 本次 Qlib run 使用统一 `limit_threshold=0.095`，只是 9.5% 市场级近似；
+  它没有消费已有 `stk_limit` 的逐股逐日价格，也不能表达不同板块、日期和
+  ST 股票的真实限制；
+- `stock_st` 缺口没有因为已有 `namechange` 或 `stk_limit` 就自动消失；
+- `index_weight` 没有单独验证的 `published_at`，因此这里不是严格
+  knowledge-time PIT；
+- 复权以每个 symbol 在 provider 区间内的首个有效因子为锚。不同 `start`
+  构建的 provider 归一化基准不同，不能直接拼接其价格 level；需要统一起点
+  重建或显式重新归一化；
+- 必须做时间切分、walk-forward/OOS、参数稳定性、成本压力和跨引擎差异；
+- 本文不据此声称 Quant OS 已达到 60 分或 80 分标准。
+
+相关字段语义参见
+[Tushare 日线接口](https://tushare.pro/document/2?doc_id=27)、
+[复权因子接口](https://tushare.pro/document/2?doc_id=28)和
+[Qlib Data Layer](https://qlib.readthedocs.io/en/latest/component/data.html)。