323 lines
17 KiB
Markdown
323 lines
17 KiB
Markdown
# Quant OS architecture and trust boundaries
|
||
|
||
Quant OS 是项目；`quant60` 是第一版 A 股 Baseline 内核、CLI namespace
|
||
和 artifact 协议前缀。当前形态是模块化单体：共享可移植计算和稳定合同，但把
|
||
数据供应商、hosted 平台、QMT 专有运行时与券商事实放在不同信任边界内。
|
||
|
||
```text
|
||
JQData (authorized account)
|
||
get_bars(raw OHLCV/money, factor, pre_close, limits, paused)
|
||
+ daily PIT is_st + daily PIT index membership
|
||
|
|
||
v
|
||
canonical immutable snapshot
|
||
exact-set/hash + semantic reconstruction
|
||
|
|
||
+----------------------+
|
||
|
|
||
v
|
||
snapshot-backtest / snapshot-decision
|
||
portable-momentum-v1 compatibility path (smoke only)
|
||
|
||
local Baseline authority:
|
||
Universe
|
||
-> frozen Ridge model bundle / Alpha
|
||
-> risk + cost-aware Portfolio
|
||
-> post-risk TargetPackageV1 (weights, no account quantities)
|
||
-> five-layer hash trace
|
||
|
|
||
+------------+-------------+
|
||
| |
|
||
JoinQuant consumer QMT consumer
|
||
T+1-open account bind completed-close bind + quickTrade=0
|
||
order_target passorder (backtest-only)
|
||
|
||
Current TargetPackage fixture is synthetic research evidence, not market proof.
|
||
|
||
Qlib 0.9.7:
|
||
Tushare completed/checksummed Parquet -> immutable managed provider
|
||
native portable-momentum signal bridge
|
||
Alpha158 + LightGBM + Recorder research workflow
|
||
(no L3 target / L4 order-intent parity)
|
||
|
||
XtTrader:
|
||
read-only broker observation -> HMAC account-bound shadow plan
|
||
callback/mutation boundary remains uncertified and operator-inaccessible
|
||
```
|
||
|
||
箭头表示数据或合同流，不表示平台能力等价。hosted 引擎拥有自己的时钟、行情
|
||
和成交语义；broker snapshot/callback 才是现金、持仓、可卖量、订单和成交的
|
||
事实权威。本地 ledger 不能用预测持仓覆盖券商事实。
|
||
|
||
## Runtime split
|
||
|
||
| Layer | Runtime | Rule |
|
||
| --- | --- | --- |
|
||
| Quant OS / `quant60` | Python ≥3.10 | 本地回测、snapshot pipeline、research、ledger、CLI |
|
||
| JQData ingestion | 独立 Python 环境，`jqdatasdk==1.9.8` | 只从授权账户获取数据；凭据不进入快照 |
|
||
| Qlib research | CPython 3.12.x，`pyqlib==0.9.7` | 与本地/QMT 环境隔离；provider 必须授权且版本化 |
|
||
| Portable strategy core | Python 3.6-compatible source | 无第三方依赖；bundler 内联到 hosted 策略 |
|
||
| JoinQuant hosted | 平台管理 | 上传生成的单文件；不能假设安装本地包 |
|
||
| QMT built-in | QMT Python 3.6 | 只上传 bundle；模块全局 `g` 持久状态，避免 `ContextInfo` 用户属性回滚 |
|
||
| qmttools / XtTrader | 券商分发的 native Python | `xtquant` 专有且 lazy import，不进入仓库 |
|
||
| Colab | notebook runtime | 默认只跑无账号流程；JQData/Qlib 是显式可选 cell |
|
||
|
||
不要用一个 Python 环境强行兼容所有路径。
|
||
|
||
## Data plane and point-in-time semantics
|
||
|
||
本地 Tushare live mirror 是独立只读输入边界。scoped snapshot 在一次 SQLite
|
||
读事务中选择目标日期/API/指数的 canonical completed job，并重新核对文件
|
||
大小、SHA-256、Parquet 行数/footer；Qlib provider 发布到新目录，manifest
|
||
绑定 source job、build parameter、converter source、完整 provider tree 和
|
||
可重算 `data_version`。当前已有复权因子、真实 `000905.SH` benchmark/历史
|
||
权重、停牌和涨跌停数据，但 live mirror 仍可变化，且 `stock_st` 权限被拒；
|
||
因此必须先冻结、再验证，不能直接进入完整 canonical production decision。完整合同见
|
||
[`TUSHARE_LOCAL_DATA.md`](TUSHARE_LOCAL_DATA.md)。
|
||
|
||
JQData adapter 的输入合同是逐交易日历史指数成员和 `get_bars` 日线字段：
|
||
|
||
- 未复权 `open/high/low/close`、`volume`、`money`；
|
||
- 复权因子 `factor`；
|
||
- `pre_close`、`high_limit`、`low_limit`、`paused`；
|
||
- 每个 member-date 的严格布尔 PIT `is_st`；
|
||
- `skip_paused=False`，保留停牌日语义。
|
||
|
||
快照保存 `bars.jsonl`、`memberships.jsonl`、`quality.json` 和
|
||
`manifest.json`。发布期间存在 incomplete marker；完成后 verifier 要求目录
|
||
是精确 artifact 集、每个文件 hash 正确，并从 JSONL 重建领域对象，重算质量
|
||
汇总、内容 hash 和 `data_version`。这比“下载成功”更强，但在授权真实账户运行
|
||
并保存许可/lineage 前，仍不构成 G1 证据。
|
||
|
||
JQData 日线在 24:00 完成，因此 adapter 拒绝把 Asia/Shanghai retrieval
|
||
当日作为 `T_CLOSE_COMPLETE`；请求 `end` 必须早于抓取日期。字段、ST 或成员
|
||
覆盖不完整也不会被当成默认 false/空集合。
|
||
|
||
`snapshot-decision` 只用 `as_of` 当日精确 PIT 成员和截至当日的数据。
|
||
执行/名义价格保持 raw；动量把每个历史 close 乘以当日可见 factor，再归一到
|
||
决策日因子，因此后续公司行动不会改写已经形成的历史决策。held but
|
||
untradable 标的不会从 Universe 消失，而会进入 frozen / hold-only /
|
||
sell-only 状态。
|
||
|
||
若目标用于下一交易日开盘前 shadow，Signal 时钟仍是 T 日 15:00。snapshot
|
||
冻结 JQData `get_trade_days` 与 `get_all_trade_days` 一致性校验后的完整
|
||
交易日序列，并显式保存 end 日后的唯一 `next_trading_session`。decision、
|
||
broker snapshot 和 shadow plan 必须绑定同一个相邻 session，以及
|
||
Asia/Shanghai `[09:00,09:30)` 的 `first_executable_window`；elapsed-day
|
||
阈值和 weekday 近似都不是权威。周末、T 日 15:01、错过 09:30、错误 session 或
|
||
迟到多日全部 fail closed，国庆等长假只要下一 session 来自冻结日历即可。
|
||
|
||
账户绑定后还必须保持决策规模有效。shadow 对 `decision.equity` 和当前
|
||
`total_asset` 使用固定的
|
||
`max(1 元, 0.01% × abs(decision equity))` 包含边界容差；缺失、负数、
|
||
非有限值或超差都不能进入 ready，超差原因码为
|
||
`DECISION_EQUITY_DRIFT`。该合同进入 plan hash，verifier 会从原始两个权益值
|
||
重新计算差额、阈值和 blocker。
|
||
|
||
QMT shadow verifier 使用 semantic replay，而不把 plan 当成事实来源。
|
||
`broker_observation.json` 保存 query 后 adapter state、live flag、callback
|
||
error/live-authorization history 计数、query 起止、原始记录数、校验结果及
|
||
脱敏资产/持仓/委托/成交事实。原始 decision manifest 是 verify 的必需输入。
|
||
纯 replay 从这两个输入独立重建 account binding、clock gate、资产和现金
|
||
恒等式、open/order-stability、trade/fill identity、完整 blocker 集、
|
||
snapshot-valid、完整 broker snapshot、逐 symbol target/weight/lot、
|
||
board-lot/sellable feasible delta、proposal、portfolio 和 status，再与 plan
|
||
exact compare。因而 plan 中同步改写多个派生字段或删除 blocker 不能形成新的
|
||
`SHADOW_READY`；READY 也强制存在可重建 snapshot。
|
||
|
||
普通 artifact hash 之外，planner 使用既有 account HMAC key 和独立 domain
|
||
签署 `QMT_SHADOW_EVIDENCE_V1` envelope。envelope 绑定完整 plan、
|
||
broker observation、broker snapshot 的 canonical 内容 hash 和三份实际发布
|
||
bytes 的 SHA-256、原始 decision manifest hash、planner/engine 及 operator
|
||
entrypoint `tools/qmt_shadow_plan.py` source hash，以及 semantic version、
|
||
10 秒/1 元 policy ceiling 和 equity drift policy。四个发布 JSON（包括
|
||
不参与自签名的 manifest）还必须逐 byte 符合唯一 deterministic writer
|
||
encoding。verifier 从当前真实输入与磁盘实际 bytes 重建
|
||
envelope 并 constant-time 比较 MAC；缺失、错误或轮换后的 key 全部失败。
|
||
这提供的是 Quant OS 本地 evidence publisher authenticity/完整性，不是
|
||
QMT/券商对 query result 的原生签名，也不把 adapter 升级成 broker-certified。
|
||
|
||
策略安全阈值是 canonical policy：query window 上限 10 秒，资产/持仓市值和
|
||
`cash + market_value = total_asset` 的绝对容差上限 1 元。CLI 只能使用等于
|
||
或更严格的值，builder 与 replay 都拒绝更宽值。目标权重总和还必须不超过
|
||
1，作为无报价条件下可独立证明的决策现金预算；实时 buying power（含成交价、
|
||
费用和卖出先后）仍不作证明。
|
||
|
||
持仓 drift 不会复用旧持仓：每次 target diff 都从当前券商 positions 和
|
||
sellable quantity 重算，且 open/变化中订单会阻断。因此数量 residual 不会
|
||
因旧持仓静默失真。由于 shadow 没有实时执行价，现金购买力仍不能被证明；
|
||
plan 明示该限制，ready 仅供人工审阅，不能升级为 live submission。
|
||
`trade.amount` 当前会被标准化、认证和重放，但在缺少真实
|
||
terminal/xtquant build 探针时不假设它与 `price × quantity` 的精确误差
|
||
合同；它不参与 target diff，正式券商验收必须记录 build 并冻结字段容差。
|
||
|
||
`snapshot-backtest` 在每个历史决策日重新调用同一 decision path，并使用：
|
||
|
||
- 第一实际交易日完整收盘形成计划；
|
||
- 紧接着下一实际交易日开盘尝试成交；
|
||
- 当日供应商停牌/涨跌停/前收字段；
|
||
- 上一交易日成交量参与率；
|
||
- T+1、百股交易单位、显式费用和未成交撤销。
|
||
|
||
这是本地 fill model，不是 JoinQuant 或 QMT 的成交事实。
|
||
|
||
## Research and model boundary
|
||
|
||
synthetic research vertical slice 当前实际接通：
|
||
|
||
- PIT table 和未来值拒绝；
|
||
- Universe 原因码；
|
||
- 透明价量特征与 T+1-open 标签时钟；
|
||
- train-only winsor/impute/standardize；
|
||
- purge/embargo walk-forward；
|
||
- deterministic Ridge、OOS IC/RankIC 与可重放 model bundle；
|
||
- 60 日对角 realized variance；
|
||
- dated explicit fee + spread + square-root impact/capacity；
|
||
- deterministic constrained portfolio、独立 post-risk gate；
|
||
- reference execution binding、完整五层 hash trace 与 TargetPackageV1。
|
||
|
||
`factor_risk.py`、CVXPY 路径和 guarded TWAP/POV 仍是有单测的独立组件，
|
||
不在上述 vertical slice 中。Ridge 已能冻结预处理、系数、标签、训练截止日
|
||
和 lineage，但目前只有 synthetic 候选；没有授权真实长样本 OOS、真实风险/
|
||
成本校准、多期逐层 parity 或 QMT peer，因此不是生产 champion。已有的单包
|
||
JoinQuant run 只观察 execution consumer。
|
||
|
||
Qlib 路径固定为 `0.9.7`。CPython 3.12 实际 fixture smoke 已得到：
|
||
|
||
- native momentum：24 条 signal；
|
||
- Alpha158 + LightGBM：完成 fit、SignalRecord、SigAnaRecord、
|
||
PortAnaRecord 和 model 保存；
|
||
- 两条 workflow 都保存表级 hash、行列/时间边界和从 portfolio report
|
||
重算的有限值指标，明确 `investment_value_claim=false`；
|
||
- local MLflow file store 使用时，runner 以
|
||
`os.environ.setdefault("MLFLOW_ALLOW_FILE_STORE", "true")` 显式确认。
|
||
- 旧 Tushare 早期未复权 managed provider/momentum smoke 在
|
||
`PYTHONHASHSEED=0` 下连续两次得到逐 byte 相同的 evidence JSON；它只证明
|
||
旧转换器和运行时可重放；
|
||
- 2018—2025 v2 managed provider 已使用真实复权、`SH000905` benchmark 和
|
||
PIT index-weight universe，通过 verifier；同一 momentum run 两次 JSON
|
||
byte-identical。月末权重保守地从下一 provider 交易日生效，
|
||
`same_session_membership_use=false`；97 个 observed snapshots 形成 96 个
|
||
effective rosters，每个严格 500 成分、weight sum 100±0.5，最大间隔 36 天。
|
||
live DB/WAL 可被无关下载任务修改，但 221 个 scoped jobs double verified、
|
||
验证后仍为 latest；独立 lineage 工具对 221 jobs 的 6 个身份字段得到
|
||
mismatch 0，并确认 converter source 为 current。它仍是
|
||
event-time/保守次日生效 PIT 近似，不是严格 knowledge-time PIT；不同
|
||
`start` 的首观测锚 provider 不可直接拼接。它仍是 research-only、
|
||
`gate_credit=[]`，不表达历史 ST 和逐股逐日涨跌停。
|
||
|
||
该 fixture 只有两只股票和一个 benchmark，性能没有投资意义。Qlib 的单一
|
||
`limit_threshold` 也不能表达逐日板块/ST 规则，所以它只参与 L1/L2 和诊断
|
||
L6，不声称 L3 target 或 L4 order-intent parity。
|
||
|
||
## Portable strategy and platform boundary
|
||
|
||
hosted artifact 有两个互斥模式：
|
||
|
||
- `portable_momentum_smoke`：保留历史连通性回归，平台端计算动量；
|
||
- `target_package`：本地唯一权威已完成 Universe/Alpha/Portfolio/Risk，
|
||
hosted wrapper 只验证包、精确匹配 `signal_as_of + next_session`、读取账户
|
||
事实并构造 execution plan，绝不回退到 momentum。
|
||
|
||
`portable-momentum-v1` 不是生产 Baseline。TargetPackage 只有权重，没有股数、
|
||
现金、订单或成交；这些属于下一交易日平台账户绑定后的 execution layer。
|
||
|
||
canonical 股票代码采用 JoinQuant 形式：
|
||
|
||
| Canonical | QMT/XtQuant | Qlib |
|
||
| --- | --- | --- |
|
||
| `600000.XSHG` | `600000.SH` | `SH600000` |
|
||
| `000001.XSHE` | `000001.SZ` | `SZ000001` |
|
||
| `830799.XBSE` | `830799.BJ` | `BJ830799` |
|
||
|
||
转换权威是 `quant60.portable_core.normalize_symbol`。当前 XtTrader mutation
|
||
边界只接受 `.SH` / `.SZ`，不能从转换覆盖推导北交所实盘覆盖。
|
||
|
||
QMT built-in bundle 和 qmttools runner 都硬限制为 backtest/history。built-in
|
||
状态存放在模块全局 `g`，不写入可能在下个 `handlebar` 回滚的
|
||
`ContextInfo` 用户属性。动量 smoke 路径固定中证 500 benchmark、PIT 历史
|
||
成分/ST 与费率；TargetPackage 路径消费本地冻结 Universe/权重，不重新计算
|
||
Alpha/Portfolio/Risk。built-in 的 10% 参与率由 QMT GUI 设置，qmttools
|
||
程序化传入。live mutation 只存在于外部 XtTrader adapter，并且默认关闭、
|
||
未认证、没有 live 启动命令；operator 可运行的 shadow CLI 只接受查询边界。
|
||
|
||
## Stable artifacts and release integrity
|
||
|
||
最低交换合同是：
|
||
|
||
- [`model_bundle.schema.json`](../schemas/model_bundle.schema.json)；
|
||
- [`target_package.schema.json`](../schemas/target_package.schema.json)；
|
||
- [`release_reachability.schema.json`](../schemas/release_reachability.schema.json)；
|
||
- [`signal.schema.json`](../schemas/signal.schema.json)；
|
||
- [`target.schema.json`](../schemas/target.schema.json)；
|
||
- [`order_event.schema.json`](../schemas/order_event.schema.json)；
|
||
- [`broker_snapshot.schema.json`](../schemas/broker_snapshot.schema.json)。
|
||
|
||
`verify-manifest` 不仅检查 ledger hash chain，还检查 incomplete marker、
|
||
精确 artifact 集、SHA-256、ledger head、report/manifest identity、
|
||
saved/current source aggregate、saved/current schema aggregate 和 payload
|
||
schema。`verify-snapshot-decision` 与 data snapshot semantic verifier 承担
|
||
各自边界的同类职责。
|
||
|
||
`release_reachability` 对每层分别记录 `implemented`、`unit_tested`、
|
||
`local_entrypoint_reachable`、`jq_entrypoint_reachable`、
|
||
`qmt_entrypoint_reachable` 和 `real_platform_observed`，并逐文件验证路径与
|
||
SHA。源文件总 hash 不能冒充真实运行。测试结果仍不能替代 schema 迁移演练、
|
||
真实平台导出或券商回调认证。当前只有
|
||
`execution.real_platform_observed=true`，由一个真实 JoinQuant
|
||
TargetPackage smoke 支持；其他四层及 all-layer summary 仍为 false。
|
||
|
||
## Clocks and reconciliation
|
||
|
||
canonical weekly clock 是：
|
||
|
||
```text
|
||
ISO 周第一实际交易日：完整 close
|
||
-> 使用 as_of 之前实际可得信息形成 signal/target/order intent
|
||
紧接着下一实际交易日：open executable window
|
||
-> 刷新市场规则与 broker snapshot
|
||
-> pre-trade gate
|
||
-> backtest/shadow submit 或 fail closed
|
||
-> callback append + reconciliation
|
||
```
|
||
|
||
“紧接着下一日”是交易日关系，不是固定星期几。每个真实平台 run 必须记录
|
||
`signal_as_of`、`last_feature_bar`、`first_executable_time`、
|
||
price adjustment 和 fill model。
|
||
|
||
完整 reconciliation 要同时比较 cash、positions、sellable quantities、
|
||
open orders 和带时区的新鲜 `as_of/source_time`。legacy/partial snapshot
|
||
即使数值碰巧平衡，也不能把 `safe_to_open` 设为 true。
|
||
|
||
## Facts and current claim
|
||
|
||
| Fact | Authority |
|
||
| --- | --- |
|
||
| canonical symbol、portable calculation | versioned source + config |
|
||
| snapshot 内容 | semantic verifier 通过的 immutable snapshot + manifest |
|
||
| historical provider entitlement | 实际数据账户许可与保存的 lineage 记录 |
|
||
| hosted 回测时钟/成交 | 平台真实导出 |
|
||
| cash、position、order、fill | broker snapshot/callback |
|
||
| 程序化交易权限与报告 | 实际券商书面确认 |
|
||
| Gate 状态 | [`gate_scorecard.json`](../gate_scorecard.json) |
|
||
|
||
synthetic/fake 数据是合同测试，不是市场证据；Qlib synthetic fixture 的真实
|
||
运行是运行时证据，不是收益证据；mock parity exporter 是 wrapper 合同证据，
|
||
不计 G9。
|
||
|
||
## Remaining production gaps
|
||
|
||
当前还缺：
|
||
|
||
- 授权 JQData 真实快照、基本面公告 PIT、完整公司行动/Security Master；
|
||
- 授权真实数据训练的冻结模型包和真实 OOS 证据；
|
||
- 真实数据校准的风险、冲击、容量和 TCA；
|
||
- 授权真实数据的多期 JoinQuant 导出、逐层本地对账与真实 QMT peer；
|
||
- 券商状态映射、restart recovery daemon、连续对账，以及 Production 80
|
||
要求的同一冻结候选 60 日 shadow（Baseline 60 的前置门槛为 20 日）；
|
||
- 运维监控、kill-switch 演练和券商程序化交易报告/核查确认。
|
||
|
||
所以 Quant OS 已具备本地五层 vertical slice 与 TargetPackage 平台边界，
|
||
但仍只是可继续填证据的候选骨架，不是已经达到整体 60 分的实盘系统。证据政策见
|
||
[`AUDIT_2026-07-25.md`](AUDIT_2026-07-25.md)。
|