# Backtest.sh 使用指南

## 概述

`backtest.sh` 是一个用于自动化回测的脚本工具，支持多种参数配置方式，能够自动匹配策略和配置文件。

## 脚本位置

```bash
/Users/zhangkun/myTestFreqAI/tools/backtest.sh
```

## 环境配置

### .env 文件

脚本依赖 `.env` 文件设置默认参数，位于 `tools/.env`：

```bash
STRATEGY_NAME=freqaiprimer
CONFIG_FILE=freqaiprimer.json
TEST_BRANCH=theforce-noai-test
DRYRUN_BRANCH=theforce-noai-dryrun
```

### 可用策略和配置

#### 策略文件 (.py)
- 位置：`freqtrade/templates/`
- 当前可用：`freqaiprimer.py`

#### 配置文件 (.json)
- 位置：`config_examples/`
- 可用配置：
  - `basic.json` - 基础配置
  - `config.json` - 标准配置
  - `freqaiprimer.json` - FreqAI策略配置
  - `live.json` - 实盘配置
  - `theforcev7.json` - TheForceV7策略配置

## 使用方法

### 1. 使用默认配置（最简单）

```bash
cd tools/
./backtest.sh
```

**默认行为：**
- 策略：`freqaiprimer`
- 配置：`freqaiprimer.json`
- 时间范围：最近2天到明天
- 交易对：默认USDT交易对列表

### 2. 省略 --config 参数（推荐）

```bash
./backtest.sh --strategy MyStrategy
```

脚本会自动将策略类名转换为小写文件名，并匹配对应的配置文件：
- 策略类名：`MyStrategy`（保持不变）
- Python文件名：`mystrategy.py`（自动转换为小写）
- JSON配置文件名：`mystrategy.json`（自动转换为小写）

如果配置文件不存在，则使用 `basic.json`。

### 3. 完整参数配置

```bash
./backtest.sh --strategy freqaiprimer --config freqaiprimer.json --start-date "2024-01-01" --end-date "2024-12-31" --pairs "BTC/USDT ETH/USDT"
```

### 4. 位置参数方式

```bash
./backtest.sh "2024-01-01" "2024-12-31" freqaiprimer freqaiprimer.json
```

## 参数详解

### 命名参数

| 参数 | 简化参数 | 说明 | 示例 |
|------|----------|------|------|
| `--strategy` | `-t` | 策略类名（首字母大写），脚本会自动转换为小写文件名 | `--strategy MyStrategy` 或 `-t MyStrategy` |
| `--config` | - | 配置文件名称（可选） | `--config mystrategy.json` |
| `--start-date` | - | 开始时间 | `--start-date "2024-01-01"` |
| `--end-date` | - | 结束时间 | `--end-date "2024-12-31"` |
| `--pairs` | - | 交易对列表 | `--pairs "BTC/USDT ETH/USDT"` |
| `--pairRemoteList` | - | 远程交易对API | `--pairRemoteList http://api.example.com/pairs` |

### 策略命名约定

脚本遵循Freqtrade标准命名约定：
- **策略类名**：首字母大写（如 `MyStrategy`）
- **Python文件名**：小写（如 `mystrategy.py`）
- **JSON配置文件名**：小写（如 `mystrategy.json`）

当使用 `--strategy MyStrategy` 时，脚本会自动：
1. 保持类名 `MyStrategy` 不变
2. 生成小写Python文件名 `mystrategy.py`
3. 生成小写JSON配置文件名 `mystrategy.json`

### 时间格式支持

- **标准格式**：`"2024-01-01 00:00:00"`
- **简写格式**：`20240101`（自动转换为 `2024-01-01 00:00:00`）

### 交易对优先级

1. `--pairRemoteList` - 远程API获取交易对
2. `--pairs` - 手动指定交易对
3. 默认交易对列表

## 配置文件自动匹配

脚本支持智能配置文件匹配：

```bash
# 自动匹配 freqaiprimer.json
./backtest.sh --strategy freqaiprimer

# 如果 freqaiprimer.json 不存在，自动回退到 basic.json
./backtest.sh --strategy nonexistent_strategy
```

## 运行示例

### 示例1：测试自定义策略（使用简化参数）

```bash
# 使用 -t 简化参数
./backtest.sh -t MyStrategy

# 或者使用完整参数
./backtest.sh --strategy MyStrategy
```

脚本会自动：
- 策略类名：`MyStrategy`
- Python文件名：`mystrategy.py`
- JSON配置文件名：`mystrategy.json`

### 示例2：指定时间范围

```bash
# 使用 -t 简化参数
./backtest.sh -t freqaiprimer --start-date "2024-06-01" --end-date "2024-06-30"

# 或者使用完整参数
./backtest.sh --strategy freqaiprimer --start-date "2024-06-01" --end-date "2024-06-30"
```

### 示例3：指定交易对

```bash
# 使用 -t 简化参数
./backtest.sh -t freqaiprimer --pairs "BTC/USDT ETH/USDT SOL/USDT"

# 或者使用完整参数
./backtest.sh --strategy freqaiprimer --pairs "BTC/USDT ETH/USDT SOL/USDT"
```

### 示例4：从远程API获取交易对

```bash
# 使用 -t 简化参数
./backtest.sh -t freqaiprimer --pairRemoteList "http://api.example.com/pairlist"

# 或者使用完整参数
./backtest.sh --strategy freqaiprimer --pairRemoteList "http://api.example.com/pairlist"
```

## 运行步骤

1. **进入工具目录**
   ```bash
   cd /Users/zhangkun/myTestFreqAI/tools
   ```

2. **赋予执行权限**（首次使用）
   ```bash
   chmod +x backtest.sh
   ```

3. **运行脚本**
   ```bash
   ./backtest.sh [参数]
   ```

4. **查看结果**
   - 实时日志：`output.log`
   - 回测结果：`result/` 目录
   - 分析报告：`result/analytic.log`

## 输出文件

- `output.log` - 完整的回测日志
- `result/` - 回测结果文件
  - JSON格式的回测结果
  - 交易数据CSV文件
- `result/analytic.log` - 分析报告

## 注意事项

1. **Docker环境**：脚本使用Docker运行回测，确保Docker服务已启动
2. **配置文件加载**：脚本会自动加载 `config_examples/` 和 `freqtrade/templates/` 目录的配置文件
3. **时间格式**：支持多种时间格式，建议使用标准格式避免歧义
4. **交易对格式**：使用 `/` 分隔符，如 `BTC/USDT`
5. **错误处理**：如果配置文件不存在，脚本会自动回退到默认配置

## 故障排除

### 常见问题

1. **策略文件不存在**
   ```bash
   # 检查可用策略
   ls ../freqtrade/templates/*.py
   ```

2. **配置文件不存在**
   ```bash
   # 检查可用配置
   ls ../config_examples/*.json
   ```

3. **Docker命令失败**
   - 检查Docker服务状态
   - 确认Docker镜像已构建

4. **Python模块缺失**
   ```bash
   # 安装所需模块
   pip install pandas
   ```

### 调试模式

添加 `--dry-run` 参数查看命令而不执行：

```bash
./backtest.sh --strategy freqaiprimer --dry-run
```

## 版本信息

- 脚本版本：1.0
- 最后更新：2024年
- 支持系统：macOS/Linux

## 相关文档

- [策略开发指南](../docs/strategy-101.md)
- [配置文件说明](../docs/configuration.md)
- [回测结果分析](../docs/backtesting.md)