optz

README.md

@@ -1,2 +1,39 @@
 # big-qmt
 
+量化交易工程：`py-client`（QMT 策略客户端，运行时） + `api` / `grpc` / `launcher` / `scripts`（服务端与工具）。
+
+## labs：所有试验与测试代码
+
+`labs/` 统一存放**非运行时**的试验、回测、审计与测试代码，运行时代码仍然只在
+`py-client` 及各服务目录内。
+
+```
+labs/
+├── run_tests.py            统一测试入口（把 py-client 挂上 sys.path 后跑 labs/tests）
+├── tests/                  离线单测（原 py-client/tests）
+├── benchmarks/             微基准（原 py-client/benchmarks）
+└── analysis/               回测与审计分析
+    └── etf/                ETF 网格策略回测（报告、参数扫描、对照脚本、日线缓存）
+```
+
+```powershell
+# 离线测试（仓库任意位置执行）
+py -3.14 -B labs/run_tests.py            # 全部
+py -3.14 -B labs/run_tests.py -v         # 详细
+py -3.14 -B labs/run_tests.py test_etf_signal   # 只跑某个模块
+
+# 微基准
+py -3.14 -B labs/benchmarks/hotpaths.py
+
+# ETF 网格策略回测与报告
+py -3.14 -B labs/analysis/etf/run.py            # 基准回测 → results.json / run_report.txt
+py -3.14 -B labs/analysis/etf/compare.py        # 旧 vs 新配置
+py -3.14 -B labs/analysis/etf/vs_hold.py        # 网格 vs 买入持有
+```
+
+报告：`labs/analysis/etf/REPORT-new-config.md`（当前配置）、
+`labs/analysis/etf/REPORT.md`（旧配置，含机会频率与参数敏感性专题）。
+
+> 测试模块内部使用 `from tests.zt_harness import ...` 这类绝对导入，因此**必须**走
+> `labs/run_tests.py`；直接用 `python -m unittest discover` 无法同时满足
+> "`labs` 作为顶层包 + `py-client` 在 sys.path 上"这两个条件。