# zvt

**Repository Path**: gypfebpy/zvt

## Basic Information

- **Project Name**: zvt
- **Description**: ZVT是对fooltrader重新思考后编写的量化项目，其包含可扩展的数据recorder，api，因子计算，选股，回测，交易,以及统一的可视化，定位为中低频 多级别 多因子 多标的 全市场分析和交易框架。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: https://zvt.readthedocs.io/en/latest/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 323
- **Created**: 2026-03-22
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZVT 初学者量化实战手册（单文档可操作）

这个仓库用于“从 0 到 1”学习量化回测工程：  
用本地 CSV 数据，完成 **数据准备 -> 策略回测 -> 可视化 -> 报告分析** 的完整闭环。

> 说明：仅用于学习与策略原型验证，不构成投资建议。

---

## 1. 你先选哪种运行方式

- `TypeScript 动态版`（推荐本地研发）
  - 实时回测、参数可调、图表交互完整、支持聚合分析与报告。
- `Python Flask 版`（推荐学习回测逻辑）
  - 代码直观、便于理解策略与回测引擎。
- `static-demo 静态版`（推荐腾讯云静态托管）
  - 不依赖后端 API，直接托管静态文件即可访问。

---

## 2. 项目结构（关键目录）

```text
zvt/
├── simple_backtest/
│   ├── app.py                          # Python Flask 回测页面
│   ├── backtest.py                     # Python 回测引擎
│   ├── strategy.py                     # MA + ADX 策略
│   ├── data_reader.py                  # 读取本地 CSV
│   ├── minimal_backtest.py             # 最简命令行回测
│   ├── requirements.txt
│   ├── ts-app/                         # TypeScript 动态版
│   │   ├── src/server.ts
│   │   ├── src/backtest.ts
│   │   ├── src/symbol_resolver.ts
│   │   └── data/symbol_map.json
│   └── static-demo/                    # 静态托管版（腾讯云可直接用）
│       ├── index.html
│       ├── package.json
│       └── data/                       # 由脚本生成
├── stock_data/                         # 本地股票数据与聚合缓存
│   ├── a/
│   ├── hk/
│   ├── us/
│   └── llm_reports/
├── config/
│   ├── stock_codes.ini
│   ├── hk_stocks.ini
│   ├── us_stocks_alltick.ini
│   └── stock_codes_dict.py
├── scripts/
│   ├── generate_aggregate_backtest_cache.py
│   └── build_static_demo_data.py
└── docs/
```

---

## 3. 数据来源说明

回测读取的是本地目录：

- `stock_data/a`
- `stock_data/hk`
- `stock_data/us`

这些 CSV 主要由以下脚本生成（参考实现）：

- `skills/stock-data-download/references/stock_data_downloader.py`
- `skills/stock-data-download/references/hk_stock_downloader.py`
- `skills/stock-data-download/references/us_stock_downloader_alltick.py`
- `skills/stock-data-download/references/universal_stock_downloader.py`

---

## 4. 本地运行（动态版）

## 4.1 TypeScript 动态版（推荐）

```bash
cd simple_backtest/ts-app
npm install
npm run dev
```

访问：`http://localhost:5173`

可用能力：

- 单标的回测
- 全市场聚合（A/HK/US 分 tab）
- 开/不开 ADX 对比
- 市场独立 LLM 报告缓存
- 手续费/滑点参数（更接近真实交易）

## 4.2 Python Flask 版

```bash
pip install -r simple_backtest/requirements.txt
python simple_backtest/app.py
```

访问：`http://localhost:5000`

## 4.3 最简命令行

```bash
python simple_backtest/minimal_backtest.py --csv stock_data/a/A_SHARE_600519.csv --short 5 --long 20
```

---

## 5. 预计算与缓存（建议）

## 5.1 生成聚合回测缓存

不开 ADX：

```bash
python scripts/generate_aggregate_backtest_cache.py --short-ma 5 --long-ma 20
```

开 ADX：

```bash
python scripts/generate_aggregate_backtest_cache.py --short-ma 5 --long-ma 20 --use-adx
```

输出示例：

- `stock_data/aggregate_backtest_results_s5_l20_adx0.csv`
- `stock_data/aggregate_backtest_results_s5_l20_adx1.csv`

## 5.2 报告缓存机制

- 报告按 **数据签名 + 市场 + 模型** 生成唯一缓存。
- 缓存位置：`stock_data/llm_reports/*.md`
- 默认优先读缓存，不重复生成。

---

## 6. static-demo（腾讯云静态托管专用）

## 6.1 生成静态数据

```bash
python scripts/build_static_demo_data.py
```

会生成：

- `simple_backtest/static-demo/data/manifest.json`
- `simple_backtest/static-demo/data/aggregate_s5_l20_adx0.json`
- `simple_backtest/static-demo/data/aggregate_s5_l20_adx1.json`
- `simple_backtest/static-demo/data/reports_s5_l20_adx0.json`
- `simple_backtest/static-demo/data/reports_s5_l20_adx1.json`

## 6.2 本地预览静态版

```bash
cd simple_backtest/static-demo
python -m http.server 8080
```

访问：`http://localhost:8080`

---

## 7. 腾讯云静态托管（可直接照填）

目标：部署 `simple_backtest/static-demo` 目录到 `/qd-trade/`

建议配置：

- 目标目录：`simple_backtest/static-demo`（不要前导 `/`）
- 安装命令：`npm install`
- 构建命令：`npm run build`
- 构建产物目录：`./`
- 部署路径：`/qd-trade`

路由重写（如有该配置项）：

- 来源：`/qd-trade/*`
- 目标：`/qd-trade/index.html`

---

## 8. 常见问题（按报错定位）

## 8.1 `ENOENT: ... static-demo/package.json`

原因通常是：

- 代码没 push 到远端最新提交
- 部署分支不是最新
- 目标目录写错（尤其前导 `/`）

排查：

1. `git push origin master`
2. 腾讯云确认分支和最新提交
3. 目标目录改为 `simple_backtest/static-demo`

## 8.2 `不允许的命令: echo`

原因：平台命令白名单限制。  
解决：不要用 `echo "skip install"`，改成：

- `npm install`
- `npm run build`

## 8.3 打开 404（`/qd-trade/`）

优先检查：

- 部署路径是否是 `/qd-trade`
- 是否配置了 `/qd-trade/* -> /qd-trade/index.html` 重写
- 上传目录是否包含 `index.html` 和 `data/*.json`

## 8.4 页面有表格没数据

排查：

1. 先执行 `python scripts/build_static_demo_data.py`
2. 检查 `simple_backtest/static-demo/data/manifest.json` 是否存在
3. 刷新浏览器（必要时清缓存）

## 8.5 动态版端口冲突

```bash
lsof -nP -iTCP:5173 -sTCP:LISTEN
lsof -nP -iTCP:5000 -sTCP:LISTEN
kill <PID>
```

---

## 9. 策略与指标（当前版本）

当前核心策略：

- MA 交叉（短期均线 vs 长期均线）
- 可选 ADX 趋势过滤

主要指标：

- 总收益率
- 基准收益（Buy & Hold）
- 超额收益（策略 - 基准）
- 年化收益率
- 最大回撤
- 夏普比率
- 胜率 / 交易次数 / 盈亏比

---

## 10. 推荐操作顺序（新同学照做）

1. 先跑动态版（理解策略与页面）
2. 生成聚合缓存（adx0 + adx1）
3. 生成 static-demo 数据
4. 本地静态预览确认无误
5. 上传 `simple_backtest/static-demo` 到腾讯云静态托管
6. 配置 `/qd-trade` 路径并验证访问

---

## 11. 相关文档

- `docs/BACKTEST_ASSUMPTIONS.md`（回测口径：Python 教学版 vs TypeScript 参考版）
- `docs/STRATEGY_SET.md`（策略集合与权威实现说明）
- `docs/CACHE_SCHEMA.md`（缓存与 `llm_reports/index.json` 格式）
- `docs/VALIDATION_PROTOCOL.md`（发版前验证清单）
- `docs/BEGINNER_QUANT_CODE_REVIEW_AND_UPGRADE_PLAN.md`
- `docs/README.md`（文档索引）
- `docs/要求.md`（若存在）

运行回测黄金样本测试：

```bash
cd simple_backtest/ts-app && npm test
cd simple_backtest && python -m unittest test_golden_python -v
```