# 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。

任何时候发现“代码可以下单，但证据/规则/券商确认还没到”，正确行为都是让
系统保持停机。