AI交易员

中文版说明 (Chinese Subpage)

基于Backtrader构建的专业、配置驱动的算法交易回测框架。可在股票、加密货币和外汇市场上无缝测试、优化并集成大型语言模型（LLMs）的交易策略。

核心功能

• 配置驱动的工作流：通过可版本控制的YAML文件定义和管理回测，实现结果的可重复性。
• 无缝LLM集成：内置MCP（模型上下文协议）服务器，允许像Claude这样的AI助手运行回测、获取数据并分析策略。
• 多市场支持：可在美股、台股、加密货币和外汇市场上测试策略。
• 丰富的策略库：自带超过20种内置策略，从经典指标到先进的自适应模型。
• 强大的命令行界面：提供丰富的命令行工具，用于运行回测、获取市场数据和列出策略。
• 开发者友好：通过简单的辅助工具和清晰的结构，轻松创建和测试自定义策略。

快速开始

1. 安装

选项A：从PyPI安装（推荐使用CLI）

pip install ai-trader

如果您希望：

• 使用CLI命令：ai-trader run、ai-trader fetch、ai-trader quick
• 在您自己的数据文件上运行回测
• 将其作为库集成到您的Python项目中

选项B：从源码安装（推荐用于示例和配置模板）

git clone https://github.com/whchien/ai-trader.git
cd ai-trader

# 安装依赖（选择一种方式）
uv sync        # 推荐（最快、现代工具）
# poetry install   # 或者使用Poetry
# pip install -e .  # 或者传统的pip可编辑安装

如果您希望：

• 运行config/backtest/中的基于配置的示例
• 使用data/中的示例数据文件
• 运行scripts/examples/中的示例脚本
• 贡献或自定义策略

2. 通过CLI运行回测

如果您是从源码克隆的，可以使用配置文件运行预定义的回测：

# 使用配置文件运行回测（需要源码安装）
ai-trader run config/backtest/classic/sma_example.yaml

或者，您可以对任何数据文件进行快速回测（适用于pip和源码安装）：

# 对您自己的数据文件进行快速回测
ai-trader quick CrossSMAStrategy your_data.csv --cash 100000

3. 获取市场数据

下载任何受支持市场的历史数据：

# 美国股票（默认保存为CSV）
ai-trader fetch TSM --market us_stock --start-date 2020-01-01

# 台湾股票
ai-trader fetch 2330 --market tw_stock --start-date 2020-01-01

# 加密货币
ai-trader fetch BTC-USD --market crypto --start-date 2020-01-01

# 使用SQLite持久化缓存（新功能！）
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite

# 同时保存为CSV和SQLite
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage both

使用SQLite进行持久化数据存储

默认情况下，ai-trader fetch会将数据保存为CSV文件。为了加快重复回测的速度，可以使用SQLite：

# 首次获取：从API下载并缓存在SQLite中（约2-3秒）
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite

# 重复获取：直接从缓存加载（约50毫秒，无需调用API）
ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite

# 查看缓存数据
ai-trader data list
ai-trader data info

# 清理旧数据
ai-trader data clean --market us_stock --before 2020-01-01

了解更多关于SQLite存储的信息 →

核心工作流程

1. 基于配置的回测

运行回测最可靠的方式是使用YAML配置文件。

my_backtest.yaml:

broker:
  cash: 1000000
  commission: 0.001425

data:
  file: "data/us_stock/TSM.csv"
  start_date: "2020-01-01"
  end_date: "2023-12-31"

strategy:
  class: "CrossSMAStrategy"
  params:
    fast: 10
    slow: 30

sizer:
  type: "percent"
  params:
    percents: 95

运行它：

ai-trader run my_backtest.yaml

更多示例请参见config/backtest/。

2. 基于Python的回测

适用于更精细的控制或与其他Python脚本集成。

简单方法：

from ai_trader import run_backtest
from ai_trader.backtesting.strategies.classic.sma import CrossSMAStrategy

# 使用示例数据运行回测
results = run_backtest(
    strategy=CrossSMAStrategy,
    data_source=None,  # 使用内置示例数据
    cash=1000000,
    strategy_params={"fast": 10, "slow": 30}
)

逐步控制： 详细示例请参见scripts/examples/02_step_by_step.py。

3. LLM集成（MCP服务器）

将ai-trader作为服务器运行，使AI助手能够与您的回测引擎交互。

启动服务器（用于测试）：

python -m ai_trader.mcp

使用Claude Desktop配置（推荐）：

1. 找到您的Claude Desktop配置文件：

   • macOS/Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 将ai-trader MCP服务器添加到mcpServers部分：

{
  "mcpServers": {
    "ai-trader": {
      "command": "python3",
      "args": ["-m", "ai_trader.mcp"],
      "cwd": "/path/to/ai-trader"
    }
  }
}

配置注意事项：

• 将/path/to/ai-trader替换为您实际的ai-trader项目目录
• 如果使用虚拟环境，请使用Python可执行文件的完整路径：/path/to/.venv/bin/python3
• 更新配置文件后重启Claude Desktop

配置完成后，您可以使用Claude以自然语言命令与您的回测引擎交互，例如：

• "对TSM数据在2020年至2022年期间运行CrossSMAStrategy的回测。"
• "列出所有可用的交易策略。"
• "获取2021年至2024年间的苹果股票数据。"

创建自定义策略

选项1：使用Claude Code技能（推荐）

创建新策略的最快方式是使用Claude Code中的/add-strategy技能。该技能会以交互式方式引导您完成整个过程：

/add-strategy classic

系统将提示您输入：

• 策略名称（如“MACDBBands”）
• 描述
• 带有默认值的参数
• 进出场条件
• 任何自定义指标

该技能会自动处理：

• 按照正确命名规范创建文件
• 生成全面的文档字符串
• 自动注册到__init__.py
• 语法验证

了解更多关于Claude Code技能的信息：https://code.claude.com/docs/en/skills

选项2：手动创建

在ai_trader/backtesting/strategies/classic/中创建一个新文件，并继承自BaseStrategy。

# ai_trader/backtesting/strategies/classic/my_strategy.py
import backtrader as bt
from ai_trader.backtesting.strategies.base import BaseStrategy

class MyCustomStrategy(BaseStrategy):
    params = dict(period=20)

    def __init__(self):
        self.sma = bt.indicators.SMA(self.data.close, period=self.p.period)

    def next(self):
        if not self.position and self.data.close[0] > self.sma[0]:
            self.buy()
        elif self.position and self.data.close[0] < self.sma[0]:
            self.close()

新的策略会自动在 CLI 和 run_backtest 函数中可用。

文档与资源

• 策略示例：详细介绍内置策略。
• 示例脚本：5 个针对不同用例的完整可运行示例。
• 配置模板：YAML 配置模板。
• 迁移指南：用于从 v0.1.x 版本升级。

参与贡献

我们欢迎任何贡献！您可以报告 bug、提出功能建议或提交 pull 请求。

表达支持

如果您觉得这个项目很有帮助，请为它点个赞！

许可证

本项目采用 GNU 通用公共许可证 v3（GPL-3.0）授权。详细信息请参阅 LICENSE 文件。

AI-Trader 快速上手指南

AI-Trader 是一个基于 Backtrader 构建的专业级、配置驱动的回测框架。它支持股票、加密货币和外汇市场，并无缝集成大语言模型（LLM），帮助开发者轻松测试和优化量化交易策略。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.11 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • git (用于源码安装)
  • (可选) uv 或 poetry (推荐的现代依赖管理工具，可加速安装)

2. 安装步骤

您可以根据使用需求选择以下两种安装方式之一：

方式 A：通过 PyPI 安装（推荐用于直接使用 CLI）

如果您只想使用命令行工具运行回测或在其他 Python 项目中作为库调用，请使用此方式。

pip install ai-trader

方式 B：从源码安装（推荐用于学习示例和自定义策略）

如果您需要运行官方提供的配置文件示例、修改策略代码或贡献代码，建议克隆仓库安装。

# 1. 克隆仓库
git clone https://github.com/whchien/ai-trader.git
cd ai-trader

# 2. 安装依赖 (任选其一)
uv sync        # 推荐：速度最快，现代化工具
# poetry install   # 或使用 Poetry
# pip install -e .  # 或使用传统 pip 进行可编辑安装

3. 基本使用

安装完成后，您可以通过命令行快速获取数据并运行回测。

第一步：获取市场数据

使用 fetch 命令下载历史数据。默认保存为 CSV 格式，也支持 SQLite 缓存以加速重复回测。

下载美股数据：

ai-trader fetch TSM --market us_stock --start-date 2020-01-01

下载台股数据：

ai-trader fetch 2330 --market tw_stock --start-date 2020-01-01

下载加密货币数据：

ai-trader fetch BTC-USD --market crypto --start-date 2020-01-01

启用 SQLite 持久化存储（加速二次读取）：

ai-trader fetch AAPL --market us_stock --start-date 2024-01-01 --storage sqlite

第二步：运行快速回测

使用内置策略对本地数据文件进行快速回测。

# 语法：ai-trader quick <策略名称> <数据文件> --cash <初始资金>
ai-trader quick CrossSMAStrategy your_data.csv --cash 100000

第三步：运行配置文件回测（进阶）

对于更复杂的场景，建议使用 YAML 配置文件。如果您是从源码安装的，可以直接运行示例：

ai-trader run config/backtest/classic/sma_example.yaml

您也可以创建自己的 my_backtest.yaml 文件：

broker:
  cash: 1000000
  commission: 0.001425

data:
  file: "data/us_stock/TSM.csv"
  start_date: "2020-01-01"
  end_date: "2023-12-31"

strategy:
  class: "CrossSMAStrategy"
  params:
    fast: 10
    slow: 30

sizer:
  type: "percent"
  params:
    percents: 95

然后执行：

ai-trader run my_backtest.yaml

额外功能：与大模型集成

AI-Trader 内置了 MCP (Model Context Protocol) 服务器，允许 Claude 等 AI 助手直接控制回测引擎。

启动服务器：

python -m ai_trader.mcp

配置完成后，您可以直接用自然语言指挥 AI，例如：“对台积电 2020 年至 2022 年的数据运行双均线策略回测”。