128 lines
9.9 KiB
Markdown
128 lines
9.9 KiB
Markdown
# 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 | live mirror 只读盘点、scoped release、不可变 provider 与本地研究 | 同上 + `pyarrow==24.0.0`；本地镜像 | selected jobs double verified、仍 latest；独立 lineage 验证 221 jobs×6 fields、mismatch 0、converter current true；v2 verifier 通过：1,111 instruments、1,942 sessions、1,975,455 rows；97 observed/96 effective snapshots 严格 500 成分、次日生效；双次 JSON byte-identical | event-time/保守次日生效 PIT 近似，不是严格 knowledge-time PIT；不同 start 的首观测锚 provider 不可直接拼接；research-only、`gate_credit=[]`；ST/统一 9.5% 仍缺 |
|
||
| 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` 项目根目录运行：
|
||
|
||
```bash
|
||
# 核心和 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`](../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 成功不证明模型收益。
|