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，无账号	标准库套件、smoke + exact manifest verifier 可运行	synthetic 不代表真实市场/收益
Local synthetic research	五层 vertical slice：Universe/Ridge Alpha/risk+cost Portfolio/post-risk/reference Execution	Python ≥3.10，无账号	冻结 model bundle、TargetPackageV1、layer trace + manifest verifier 可运行；风险/成本扰动必须改变 target	仍是 synthetic；当前只接对角风险与 deterministic optimizer，未做授权长样本 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，无账号	动量 smoke 与 TargetPackage 消费模式均有 fake lifecycle；目标包缺失/篡改不回退	不证明 JoinQuant
JoinQuant hosted bundle	hosted backtest	JoinQuant 登录/数据权限	动量 smoke 的真实 2024 全年 run 已完成；FINAL4 的单个 synthetic-research TargetPackage 已在真实 hosted 环境按 day_open 命中并产生 3 单/3 fill	只观察 execution consumer；无授权真实长样本/OOS、上游四层 hosted 执行、QMT peer 或逐层真实数据 parity
QMT local harness	built-in wrapper 合同	Python ≥3.10，无账号	Python 3.6 source、ContextInfo 回滚模拟、动量 smoke 与 TargetPackage 合同	不证明 QMT
QMT built-in bundle	GUI backtest-only	授权 QMT 客户端/历史数据	两种模式都硬限制 backtest；TargetPackage 模式不重算上游四层；模块全局 g	尚无 TargetPackage 真实 QMT run/export；10% GUI 配置和执行时钟待取证
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；Baseline 60 至少 20 个交易日，Production 80 当前缺口为同一冻结候选至少 60 个交易日；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 TargetPackage run 支持且只支持 execution.real_platform_observed=true；输入仍是 synthetic-research， Universe/Alpha/Portfolio/Risk 的真实平台观察均为 false。它与旧 momentum smoke、Qlib fixture 一样，不是市场有效性或跨平台 Gate 通过证据。

Stable strategy boundary

portable-momentum-v1 当前只作为 smoke 冻结：

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

本地 Ridge 已能冻结为 versioned model bundle，并通过 TargetPackageV1 把 post-risk 权重移交给 JoinQuant/QMT；平台不需要、也 不应重新运行训练栈。一个 synthetic 包已通过真实 JoinQuant execution consumer，但没有授权真实 OOS、真实校准、多期逐层 parity 和 QMT peer， 仍不能称为已部署 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

# 默认只构建 portable momentum smoke
python tools/bundle_platforms.py

# 显式构建无 fallback 的 TargetPackage 消费器
python tools/bundle_platforms.py \
  --target-package artifacts/research-smoke/target_package.json \
  --output-dir dist/target-package
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 成功不证明模型收益。