boat/quant-os
Public Access
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
6275370afc14ac5dec3b834647e8166c3e9724e3
quant-os/docs/getting-started/GETTING_STARTED_80.md
T

10 KiB
Raw Blame History

Quant OS 新架构上手

这份文档只给出当前真实可运行入口。每一步都标明它需要什么、产生什么，以及 不能证明什么。

0. 先认清当前声明

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. 本地路径和安装

独立仓：

$QUANT_OS_ROOT

推荐 Python 3.12：

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 内运行；从其他目录调用新命令时显式写：

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. 工程体检

状态：[已实现｜无需账号]

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 时可用：

PYTHONPATH=src:. python -m quant_os doctor

4. 无账号本地 demo

状态：[已实现｜无需账号]

完整验证：

make local

较短路径：

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 和 ../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。

典型流程：

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｜需要授权账号]

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 目标为：

https://git.gomars.fun/boat/quant-os.git

默认 cell 不需要账号。RUN_JQDATA=True 和 RUN_QLIB=True 是显式可选。 Colab 禁止上传券商凭据、账户号、持仓/成交、QMT userdata 或未获许可的行情。

本地先验证 notebook：

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：

python tools/bundle_platforms.py

TargetPackage consumer：

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 账号]

当前可做：

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 状态

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。

公开页只展示脱敏静态快照，不是实时健康页：

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 View Git Blame Copy Permalink