314 lines
10 KiB
Markdown
314 lines
10 KiB
Markdown
# 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
|
||
$QUANT_OS_ROOT
|
||
```
|
||
|
||
推荐 Python 3.12：
|
||
|
||
```bash
|
||
export QUANT_OS_ROOT=/path/to/quant-os
|
||
cd "$QUANT_OS_ROOT"
|
||
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 "$QUANT_OS_ROOT" 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
|
||
|
||
状态：`[v2 provider/run 已验证｜research-only]`
|
||
|
||
先阅读 [`../TUSHARE_LOCAL_DATA.md`](../TUSHARE_LOCAL_DATA.md) 和
|
||
[`../runbooks/TUSHARE_QLIB_LOCAL_RUN.md`](../runbooks/TUSHARE_QLIB_LOCAL_RUN.md)。
|
||
当前镜像已有复权因子、真实中证 500 benchmark/历史权重、停牌和涨跌停；
|
||
raw mirror 仍可变化，历史 `stock_st` 权限被拒，所以必须先冻结 scoped
|
||
release，再构建、验证 provider。2018—2025 provider 和双次 momentum run
|
||
已经完成；月末指数权重保守地从下一 provider 交易日生效，不做 same-session
|
||
使用，97 个 observed snapshots 形成 96 个 effective rosters，均严格 500
|
||
成分、weight sum 在 100±0.5 内、最大间隔 36 天。但统一 9.5% 涨跌停近似和
|
||
ST 缺口仍使其不能进入完整 production decision，`gate_credit=[]`。
|
||
冻结期间全 DB/WAL 可能因无关下载任务变化；验收看的是 221 个 scoped jobs
|
||
double verified、验证后仍为 latest；再用 `tools/tushare_lineage.py` 核对
|
||
221 jobs 的 6 个身份字段，要求 mismatch 0 且 converter current true。
|
||
历史权重没有单独验证的 `published_at`，所以 universe 是 event-time/保守
|
||
次日生效 PIT 近似，不是严格 knowledge-time PIT。复权使用首观测锚；不同
|
||
`start` 构建的 provider 不能直接拼接价格 level。
|
||
|
||
典型流程：
|
||
|
||
```bash
|
||
PYTHONPATH=src:. python tools/tushare_qlib.py inventory --help
|
||
python tools/tushare_snapshot.py --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。
|
||
|
||
任何时候发现“代码可以下单，但证据/规则/券商确认还没到”，正确行为都是让
|
||
系统保持停机。
|