quant-os/docs/TUSHARE_LOCAL_DATA.md

Tushare 本地数据盘点、Qlib 接入与回测手册

截至 2026-07-26，Quant OS 已能只读盘点另一个任务生成的 Tushare Parquet 镜像，校验已完成分区，并转换为不可变的 Qlib 0.9.7 provider。 这条路径已经完成两次 byte-identical 的本地动量回测。

当前证据的边界是：

completed_partitions_only_not_full_mirror
production_ready = false
investment_value_claim = false
gate_credit = []

它证明“本地 Tushare 数据可以进入 Qlib 并可重放”，不证明镜像已经下载完整， 也不证明策略收益有效或 Quant OS 已达到 BASELINE_60。

1. 2026-07-26 点时盘点

镜像中共有 93 个状态为 completed 的 Parquet，均通过 SQLite 记录的文件大小、 SHA-256 和 Parquet row count 校验；另有 1 个遗留 running job。

表	文件数	行数	当前范围/说明
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

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 转换过程中修改或自动恢复原下载器。

尚未落盘的生产关键表包括：

• adj_factor、index_daily；
• index_member_all、index_weight；
• stk_limit、suspend_d、stock_st；
• daily_basic。

其中历史 stock_st 权限探测被拒绝。即使其他下载完成，历史 ST 仍需要新的 授权数据源或明确的降级门禁。

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。

Tushare 的 daily 是未复权行情，停牌期间不返回记录；vol 单位为手， amount 单位为千元。转换器固定执行：

600000.SH -> SH600000
000001.SZ -> SZ000001
430047.BJ -> BJ430047
volume = vol * 100
money = amount * 1000
factor = 1

未上市、退市后和停牌缺口在 Qlib feature 中保留为 NaN。字段语义来源见 Tushare 日线接口与 复权因子接口。

3. Quant OS 如何使用这些数据

当前已经实现的链路是研究/引擎验证路径：

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 还需要第二条生产数据路径：

完整 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：

export QUANT_OS_ROOT=/path/to/quants-strategies/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 文件：

python tools/tushare_qlib.py inventory \
  --mirror-root "$TUSHARE_MIRROR_ROOT" \
  --output-json artifacts/tushare-inventory.json

当前未复权数据只能显式构建技术验证 provider；每次必须使用新目录，工具拒绝 覆盖已有 provider：

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 \
  --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

运行 Qlib 0.9.7 本地回测：

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

Qlib simulator 会消费结束日后的下一 provider session，所以 backtest end 必须早于 provider 最后一个交易日。Quant OS 对受管 provider 会在 Qlib 初始化前检查 market、benchmark、起始边界和这个终点条件。

artifacts/ 与 data/qlib/ 均被 Git 忽略。原始 Parquet、token、绝对镜像 路径和回测临时产物不得提交到仓库。

5. 本次真实本地运行证据

最终 v4 provider：

证据	值
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

回测参数为 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 相同：

证据/指标	值
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

这些收益数字没有投资解释。原因包括未复权早期行情、没有真实指数 benchmark、 没有历史成分/ST/停牌/涨跌停、按全区间至少 60 条观测筛选带来的非 PIT 偏差，以及 1992—1993 特殊市场阶段。极端 synthetic benchmark 恰好说明 为什么“程序跑完”不能等价为“回测有效”。

6. 何时可以升级为正式研究数据

至少完成以下步骤后，才能新建 production-eligible provider：

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 差异报告。

Qlib provider 的目录格式和缺失值/复权约定参见 Qlib Data Layer 文档。