feat: establish Quant OS production-80 architecture
This commit is contained in:
@@ -0,0 +1,299 @@
|
||||
# Quant OS 新架构上手
|
||||
|
||||
这份文档只给出当前真实可运行入口。每一步都标明它需要什么、产生什么，以及
|
||||
不能证明什么。
|
||||
|
||||
## 0. 先认清当前声明
|
||||
|
||||
```text
|
||||
Baseline 60: NOT_BASELINE_60 (0/10 gates)
|
||||
Production 80: BLOCKED_FROM_LIMITED_LIVE (0/100 verified evidence points)
|
||||
Broker mutation: disabled
|
||||
Investment value claim: false
|
||||
```
|
||||
|
||||
这是 fail-closed 结论，不妨碍运行本地工程 smoke。
|
||||
|
||||
## 1. 本地路径和安装
|
||||
|
||||
独立仓：
|
||||
|
||||
```text
|
||||
~/boat-workspace/Code/quant-os
|
||||
```
|
||||
|
||||
推荐 Python 3.12：
|
||||
|
||||
```bash
|
||||
cd ~/boat-workspace/Code/quant-os
|
||||
python3.12 -m venv .venv-core
|
||||
source .venv-core/bin/activate
|
||||
python -m pip install -e .
|
||||
```
|
||||
|
||||
核心无第三方运行依赖。JQData、Qlib 和 QMT 必须使用各自独立环境。
|
||||
当前 CLI 的 profile、配置和 bundle 是仓库资产，不嵌入 wheel。已安装的
|
||||
`quant-os` 应在 checkout 内运行；从其他目录调用新命令时显式写：
|
||||
|
||||
```bash
|
||||
quant-os --project-root ~/boat-workspace/Code/quant-os doctor
|
||||
```
|
||||
|
||||
wheel 不是独立的数据/runtime 分发包。
|
||||
|
||||
## 2. 十分钟理解三平面
|
||||
|
||||
- Control plane：选择 RunSpec、编排 use case、做发布判定。
|
||||
- Data plane：不可变 PIT 数据 → 特征/模型 → 权重 → execution intent。
|
||||
- Evidence plane：记录 hash、来源、平台事实、差异和 Gate；不能修改决策。
|
||||
|
||||
平台和供应商只通过 adapter/port 进入。读券商与下单是两个独立接口。
|
||||
|
||||
## 3. 工程体检
|
||||
|
||||
状态：`[已实现｜无需账号]`
|
||||
|
||||
```bash
|
||||
quant-os doctor
|
||||
quant-os architecture check
|
||||
quant-os standard validate
|
||||
quant-os standard evaluate
|
||||
```
|
||||
|
||||
预期：
|
||||
|
||||
- `doctor.ok = true`：目录、入口、profile 和新 namespace 边界有效；
|
||||
- `standard evaluate.ok = true`：评估过程有效；
|
||||
- `qualified = false`：当前没有达到 80，属于正确结果。
|
||||
|
||||
`doctor.architecture.scope = new_namespace_only` 表示 AST checker 只覆盖
|
||||
`src/quant_os/`；legacy `quant60` 和根级 adapter/platform/tool 仍在迁移。
|
||||
它证明工程和标准可验证，不证明全部旧代码已经分层、策略有效或平台可用。
|
||||
|
||||
没有 editable install 时可用：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src:. python -m quant_os doctor
|
||||
```
|
||||
|
||||
## 4. 无账号本地 demo
|
||||
|
||||
状态：`[已实现｜无需账号]`
|
||||
|
||||
完整验证：
|
||||
|
||||
```bash
|
||||
make local
|
||||
```
|
||||
|
||||
较短路径：
|
||||
|
||||
```bash
|
||||
quant-os smoke \
|
||||
--config configs/baseline.json \
|
||||
--output artifacts/local-smoke
|
||||
|
||||
quant-os verify-manifest artifacts/local-smoke/manifest.json
|
||||
|
||||
quant-os research-smoke --output artifacts/research-smoke
|
||||
quant-os verify-research-manifest artifacts/research-smoke/manifest.json
|
||||
```
|
||||
|
||||
`quant-os` 在这些命令上调用兼容的 `quant60` V1 内核。产物仍使用 V1 identity，
|
||||
因此历史 verifier 不会失效。
|
||||
|
||||
本地 demo 证明：
|
||||
|
||||
- 核心规则、ledger、manifest 和 hash 可重放；
|
||||
- synthetic 五层链能够生成 ModelBundle 和 TargetPackage；
|
||||
- 平台 bundle 可生成并通过 fake contract。
|
||||
|
||||
它不证明：
|
||||
|
||||
- 真实市场收益；
|
||||
- 真实 JQData 完整性；
|
||||
- 真实 QMT 或券商执行；
|
||||
- 60/80 达标。
|
||||
|
||||
## 5. Tushare 数据与 Qlib
|
||||
|
||||
状态：`[已实现到技术 smoke｜真实镜像仍不完整]`
|
||||
|
||||
先阅读 [`../TUSHARE_LOCAL_DATA.md`](../TUSHARE_LOCAL_DATA.md)。当前盘点表明
|
||||
completed Parquet 能校验并转换为 managed Qlib provider，但缺复权、真实
|
||||
benchmark、历史成分、ST、停牌和涨跌停，不能进入生产 decision。
|
||||
|
||||
典型流程：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src:. python tools/tushare_qlib.py inventory --help
|
||||
PYTHONPATH=src:. python tools/tushare_qlib.py build --help
|
||||
PYTHONPATH=src:. python tools/tushare_qlib.py verify --help
|
||||
PYTHONPATH=src:. python -m platforms.qlib_runner --help
|
||||
```
|
||||
|
||||
具体参数以 Tushare 文档和本机 inventory 为准。不要为了跑通而静默补缺失字段。
|
||||
|
||||
这条路径证明数据桥和 Qlib runtime 可用，不证明 Ridge Baseline、G1/G2 或
|
||||
投资价值。
|
||||
|
||||
## 6. JQData → 本地 PIT
|
||||
|
||||
状态：`[已实现 adapter｜需要授权账号]`
|
||||
|
||||
```bash
|
||||
python3.12 -m venv .venv-jqdata
|
||||
source .venv-jqdata/bin/activate
|
||||
python -m pip install -r requirements/jqdata.txt
|
||||
|
||||
PYTHONPATH=src:. python tools/jqdata_snapshot.py \
|
||||
--index 000905.XSHG \
|
||||
--start 2024-01-02 \
|
||||
--end 2024-12-31 \
|
||||
--output data/snapshots/csi500-2024
|
||||
|
||||
quant-os snapshot-backtest \
|
||||
--snapshot data/snapshots/csi500-2024/manifest.json \
|
||||
--config configs/baseline.json \
|
||||
--output artifacts/csi500-2024-backtest
|
||||
```
|
||||
|
||||
凭据只通过无回显登录或本地 secret source 注入，不进入命令历史、Git、OB、
|
||||
notebook 或 artifact。
|
||||
|
||||
重要限制：当前 snapshot backtest/decision 仍走
|
||||
`portable-momentum-v1` compatibility path；它尚未接入真实 Ridge 五层权威。
|
||||
|
||||
## 7. Colab
|
||||
|
||||
状态：`[默认流程已实现｜JQData/Qlib cell 需对应授权/运行时]`
|
||||
|
||||
打开 `notebooks/quant_os_colab.ipynb`。独立仓 clone 目标为：
|
||||
|
||||
```text
|
||||
https://git.gomars.fun/boat/quant-os.git
|
||||
```
|
||||
|
||||
默认 cell 不需要账号。`RUN_JQDATA=True` 和 `RUN_QLIB=True` 是显式可选。
|
||||
Colab 禁止上传券商凭据、账户号、持仓/成交、QMT userdata 或未获许可的行情。
|
||||
|
||||
本地先验证 notebook：
|
||||
|
||||
```bash
|
||||
python tools/run_colab_notebook.py notebooks/quant_os_colab.ipynb
|
||||
python tools/run_colab_notebook.py notebooks/quant_os_colab.ipynb --execute
|
||||
```
|
||||
|
||||
## 8. 聚宽
|
||||
|
||||
状态：`[bundle 已实现｜上传/导出需要登录聚宽]`
|
||||
|
||||
动量 smoke：
|
||||
|
||||
```bash
|
||||
python tools/bundle_platforms.py
|
||||
```
|
||||
|
||||
TargetPackage consumer：
|
||||
|
||||
```bash
|
||||
python tools/bundle_platforms.py \
|
||||
--target-package artifacts/research-smoke/target_package.json \
|
||||
--output-dir dist/target-package
|
||||
```
|
||||
|
||||
上传 `dist/target-package/joinquant_strategy.py` 后，必须保存平台运行参数、日志、
|
||||
订单、成交和同输入 hash。当前已有一次 synthetic-research package 的真实
|
||||
execution smoke，只证明 execution consumer，不计 G9/60/80。
|
||||
|
||||
## 9. QMT
|
||||
|
||||
状态：`[bundle/fake/read-only 框架已实现｜真运行需要 Windows QMT 账号]`
|
||||
|
||||
当前可做：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
取得 QMT 后按顺序启用：
|
||||
|
||||
1. built-in 历史回测；
|
||||
2. qmttools 回测导出；
|
||||
3. XtTrader 只读 contract probe；
|
||||
4. broker snapshot 与 shadow plan；
|
||||
5. callback/restart/reconcile；
|
||||
6. 完成券商程序化交易报告确认后，才讨论 TradeBrokerPort。
|
||||
|
||||
账号、userdata 路径和账户标识不放进 Git/OB。当前没有任何 operator 可运行的
|
||||
实盘下单命令，这是有意的安全边界。
|
||||
|
||||
## 10. 如何读 60/80 状态
|
||||
|
||||
```bash
|
||||
quant-os standard evaluate
|
||||
```
|
||||
|
||||
重点字段：
|
||||
|
||||
- `raw_score`：只有达到最低 evidence tier 且 hash 有效的控制项得分；
|
||||
- `effective_score`：应用 60/canary cap 后的分数；
|
||||
- `hard_gate_failures`：任何一项都阻断上线；
|
||||
- `domain_floor_failures`：防止用文档/单一领域堆分；
|
||||
- `prerequisites`：60、QMT、券商确认、shadow、canary、P0/P1；
|
||||
- `standard_canonical_sha256`：本次评估解释所使用的精确标准版本；
|
||||
- `pre_canary_authorization`：授权 ID/hash、有效期和 verifier/issuer provenance；
|
||||
- `pre_canary_authorization_valid_as_of_assessment`：授权在评估日是否仍可开始或继续
|
||||
canary；过期后为 false，但不会否定期限内已完成的历史 canary chain；
|
||||
- `canary_authorization_chain_verified`：E4 canary 是否引用同一有效授权、处于合法
|
||||
时间窗，并以实际最大资本/notional、标的、流量和 breach/stop 记录证明未突破
|
||||
hard caps；
|
||||
- `verification_environment` / `test_only`：测试 verifier 永远不能冒充生产信任；
|
||||
- `pre_canary_authorized`：只有生产 issuer registry 核验后才可能为真；
|
||||
- `trusted_attestation_verified`：最终 promotion attestation 是否由信任边界核验；
|
||||
- `qualified`：唯一可用于 promotion policy 的布尔值。
|
||||
|
||||
当前 CLI 没有注入 production trust provider / issuer registry，所以它只能
|
||||
诚实评估当前全负状态，不能接受手工伪造的 `passed` 或自行颁发 60/80。
|
||||
单元测试即使构造满分证据，也只能得到 `TEST_ONLY_STRUCTURAL_PASS`；
|
||||
production verifier 是明确 backlog。
|
||||
|
||||
公开页只展示脱敏静态快照，不是实时健康页：
|
||||
|
||||
```text
|
||||
https://gomars.fun/quant-os/status/
|
||||
```
|
||||
|
||||
## 11. 新策略如何接入
|
||||
|
||||
状态：`[目标 API｜本轮只定义边界，尚未完成 Strategy SDK]`
|
||||
|
||||
策略最终应留在 `quants-strategies`，通过版本化 StrategySpec/port 进入 Quant OS。
|
||||
策略只提供特征、预测或目标权重逻辑，不能自行：
|
||||
|
||||
- 读取券商 secret；
|
||||
- 调用 TradeBrokerPort；
|
||||
- 修改 evidence；
|
||||
- 绕过独立风险；
|
||||
- 把 hosted 平台变成第二个 Alpha 权威。
|
||||
|
||||
当前新增策略仍按现有 `quant60` 实验接口工作，待 V2 StrategySpec 和 golden
|
||||
vectors 完成后迁移。
|
||||
|
||||
## 12. 建议的学习顺序
|
||||
|
||||
1. 跑 `doctor` 和 `standard evaluate`；
|
||||
2. 跑 `make local`，打开 manifest 看 hash/identity；
|
||||
3. 对照 60/80 文档解释为什么 synthetic 不得分；
|
||||
4. 阅读三平面架构和 ReadBroker/TradeBroker 拆分；
|
||||
5. 盘点 Tushare provider，再跑 Qlib technical smoke；
|
||||
6. 获得 JQData 后生成真实 snapshot；
|
||||
7. 先做真实聚宽多期导出，再接真实 QMT；
|
||||
8. 最后才累计 shadow/canary。
|
||||
|
||||
任何时候发现“代码可以下单，但证据/规则/券商确认还没到”，正确行为都是让
|
||||
系统保持停机。
|
||||
Reference in New Issue
Block a user