quant-os/docs/PLATFORM_MATRIX.md

Quant OS platform capability matrix

“有入口”与“已在目标平台验证”必须分开。Quant OS 共享的是冻结计算合同， 不是四个平台完全相同的时钟、行情和成交模型。

Path	Intended use	Runtime / prerequisite	Current verified fact	Missing release evidence
Local synthetic execution	确定性事件回测、ledger/replay	Python ≥3.10，无账号	标准库套件最近记录为 224 tests、OK、6 skip；smoke + exact manifest verifier 可运行	synthetic 不代表真实市场/收益
Local synthetic research	PIT/features/walk-forward/Ridge/risk/cost/target	Python ≥3.10，无账号	research smoke + manifest verifier 可运行	Ridge 未冻结部署，未做授权长样本 OOS
JQData ingestion	授权数据到 canonical immutable snapshot	jqdatasdk==1.9.8 + 授权账号	fake-provider 测试覆盖 raw/factor/pre-close/limits/paused/PIT is_st/membership、24:00 完整收盘约束和语义 verifier	尚未登录真实账号保存快照、许可与 lineage
Snapshot local backtest	PIT membership 的 provider-data 本地回测	semantic verifier 通过的 snapshot	snapshot-backtest 复用 production decision path，输出普通 run manifest	尚无授权真实 snapshot；仍是本地 fill model
Snapshot decision	某决策日 Signal/Target/Order Delta	snapshot + equity 或完整 broker snapshot	fail-closed broker state 与 exact decision manifest verifier 已实现	未接真实账户 snapshot，未冻结生产模型
Colab	clone、测试、bundle、本地两条 synthetic 链；可选 JQData/Qlib	Colab runtime	notebook 已可本地逐 cell 执行	可选账号/依赖 cell 仍需运行时授权；不是平台证据
JoinQuant local harness	wrapper API 合同	Python ≥3.10，无账号	fake lifecycle 与 mock parity 可运行	不证明 JoinQuant
JoinQuant hosted bundle	hosted backtest	JoinQuant 登录/数据权限	真实 2024 全年 run 已完成且可见日志 0 ERROR；单文件、PIT index/ST、批量 history、费率/滑点/10% 参与率、科创板保护价/200 股约束已运行	尚无完整输入/plan/orders/fills 导出和同输入本地比较
QMT local harness	built-in wrapper 合同	Python ≥3.10，无账号	Python 3.6 source、ContextInfo 回滚模拟和 mock parity	不证明 QMT
QMT built-in bundle	GUI backtest-only	授权 QMT 客户端/板块与历史 ST 数据	bundle 硬限制 backtest；毫秒 timetag PIT 成分/ST；固定中证 500、费率/滑点；模块全局 g	尚无真实 QMT run/export；10% GUI 配置与历史 ST 正例探针待取证
qmttools runner	native-Python QMT backtest/history	券商分发 xtquant + 已登录 terminal	固定中证 500/10% 参与率、参数、只读 preflight 和 hard backtest/history 合同已测	尚无专有运行时实跑
XtTrader read-only shadow	账户绑定 target-diff 与 broker observation	MiniQMT/QMT、账户查询权限、既有本地 HMAC key	HMAC 账户绑定 + authenticated evidence envelope、decision/observation semantic replay、资产/持仓/委托/成交恒等式、fail-closed exact verifier 与 fake broker 合同	HMAC 不是 broker attestation；仍缺官方 query 失败/空结果合同、callback/restart、20 日真实 shadow；not live-ready
Qlib native momentum	signal/model research	CPython 3.12 + exactly pyqlib==0.9.7	真实本地 fixture 成功，24 signal；保存 signal/report hash、表边界和重算 portfolio 指标	synthetic 两股票；无真实数据/OOS，无 L3/L4 parity
Qlib Alpha158/LightGBM	model fit + Recorder workflow	同上 + LightGBM/MLflow stack	真实 fixture 完成 model/Recorder；读取 portfolio report，保存表 hash、边界、重算指标与 artifact path	synthetic 两股票性能无意义；真实 provider/OOS 和冻结模型缺失
Tushare local → Qlib	completed Parquet 的只读盘点、不可变 provider 与本地研究 smoke	同上 + pyarrow==24.0.0；本地镜像	93 个 completed 文件全部通过 size/SHA/row-count；v4 provider verifier 成功；同一动量命令连续两次 evidence JSON 逐 byte 相同	daily 仅完成约 8.2%，缺复权、真实 benchmark、PIT 成分/ST/停牌/涨跌停；production_ready=false
Mock parity exporter	JoinQuant/QMT wrapper 的 L2—L4 合同回归	Python ≥3.10	mock_contract_only、real_platform_pass=false、gate_credit=[]	不计 G9；必须换成真实平台导出

G1—G10 当前都未通过。JoinQuant hosted smoke 与 Qlib fixture smoke 是真实 runtime 证据，但不是市场有效性或跨平台 Gate 通过证据。

Stable strategy boundary

当前四引擎共同可冻结的是 portable-momentum-v1：

• canonical symbol normalization；
• momentum score/rank；
• capped target weights；
• lot-rounded target quantity；
• T+1/sellable-aware order delta。
• 科创板 200 股最小申报、余额一次性卖清与 hosted 最坏价保护。

本地 Ridge 与 Qlib Alpha158/LightGBM 是研究候选。没有 versioned model bundle、授权真实 OOS 和跨引擎推理结果前，不能称为已部署 champion。

Qlib 的单一 limit_threshold 是市场级近似，不能表达逐日板块/ST 限制； 因此它只参加 L1/L2 和诊断 L6。XtTrader mutation 边界目前只接受 .SH 和 .SZ，北交所 symbol conversion 覆盖不等于北交所实盘覆盖。

Platform terms

• QMT built-in：init / handlebar 在 QMT 管理的 Python 3.6 环境执行。 用户状态放在模块全局 g，避免 ContextInfo 用户属性在下个 handlebar 回滚。
• qmttools：native Python 通过 run_strategy_file 驱动策略文件。 supplied runner 固定 backtest/history，不能等同于 XtTrader OMS。
• XtTrader：连接 MiniQMT 的查询、报单/撤单与异步推送 API。存在 guarded mutation path 不代表券商认证或 live-ready；本项目对 operator 暴露的 shadow CLI 严格只读，没有报单/撤单命令。
• fake harness：函数名和生命周期匹配的本地对象，只用于合同回归。
• Qlib Recorder：研究 artifact 记录机制。两股票 synthetic Recorder 成功不等于模型有投资价值。

Minimum verification commands

从 quant-os 项目根目录运行：

# 核心和 Colab 默认流程
make local

# JQData 快照与 semantic verifier（会交互式无回显读取密码）
PYTHONPATH=src:. python tools/jqdata_snapshot.py \
  --index 000905.XSHG --start 2024-01-02 --end 2024-12-31 \
  --output data/snapshots/csi500-2024
PYTHONPATH=src:. python -c \
  "from quant60.data_snapshot import verify_data_snapshot; verify_data_snapshot('data/snapshots/csi500-2024/manifest.json')"

# 快照回测和决策
PYTHONPATH=src:. python -m quant60 snapshot-backtest \
  --snapshot data/snapshots/csi500-2024/manifest.json \
  --config configs/baseline.json --output artifacts/csi500-2024-backtest
PYTHONPATH=src:. python -m quant60 snapshot-decision \
  --snapshot data/snapshots/csi500-2024/manifest.json \
  --config configs/baseline.json --as-of 2024-12-31 \
  --equity 1000000 --output artifacts/csi500-2024-decision

# hosted bundle 和 mock-only parity
python tools/bundle_platforms.py
PYTHONPATH=src:. python tools/export_mock_parity.py \
  export --output artifacts/mock-parity/report.json
PYTHONPATH=src:. python tools/export_mock_parity.py \
  verify artifacts/mock-parity/report.json

# Colab notebook 本地合同/执行
python tools/run_colab_notebook.py notebooks/quant_os_colab.ipynb
python tools/run_colab_notebook.py notebooks/quant_os_colab.ipynb --execute

# QMT 环境就绪后：先运行未绑定账户的只读 bootstrap（预期 exit 2），再用
# 输出的非 null broker_snapshot.json 重建同一 Signal 日 decision；
# broker observation 本身仍来自唯一下一交易日盘前窗口。完整步骤见 runbook
PYTHONPATH=src:. python tools/qmt_shadow_plan.py plan \
  --decision artifacts/latest-decision/manifest.json \
  --output artifacts/qmt-shadow-bootstrap

后续 verify 必须同时提供原始 decision，并读取 plan 时使用的既有 QMT_ACCOUNT_HASH_KEY_FILE；verify 不会补建丢失 key。manifest HMAC envelope 绑定 plan/observation/snapshot 的内容与发布 byte hash、 decision/source（含 operator CLI）/policy；四个 JSON 必须保持唯一 writer encoding。但信任主体是本地 Quant OS key holder，不是 QMT/券商。

Qlib 和真实平台的完整命令见 runbooks/PLATFORM_DEPLOYMENT.md。

Version and evidence policy

每个真实 run 都要记录 JoinQuant environment、QMT client/build、 xtquant、broker plugin、Qlib/Python、bundle hash、data version、 config/rules hash 和实际日历。文档说明 API 存在不证明当前账号有权限； mock/fake/synthetic 成功不证明真实平台；Qlib synthetic 成功不证明模型收益。