whchien/ai-trader

# AI-Trader [](https://www.python.org/downloads/) [](LICENSE) [中文版說明 (Chinese Subpage)](README_zh.md) 一个专业的、基于配置的量化交易回测框架，基于 Backtrader 构建。可无缝地跨股票、加密货币和外汇市场，测试、优化交易策略并将其与大型语言模型（LLM）集成。  ## 核心特性 - **基于配置的工作流**：使用可版本控制的 YAML 文件定义和管理回测，确保结果的可复现性。 - **无缝集成 LLM**：内置的 MCP (Model Context Protocol) server 允许像 Claude 这样的 AI 助手运行回测、获取数据并分析策略。 - **多市场支持**：支持在美股、台股、加密货币和外汇市场上测试策略。 - **丰富的策略库**：内置超过 20 种策略，涵盖从经典指标到高级的自适应模型。 - **强大的 CLI**：提供功能丰富的命令行界面，用于运行回测、获取市场数据和列出策略。 - **开发者友好**：通过简单的辅助函数和清晰的项目结构，轻松创建和测试自定义策略。 ## 快速开始 **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 # Recommended (fastest, modern tool) # poetry install # 或者使用 Poetry # pip install -e . # 或者使用传统的 pip 进行可编辑安装 ``` 如果你希望进行以下操作，请使用此方式： - 运行 `config/backtest/` 中基于配置的示例 - 使用 `data/` 中的示例数据文件 - 运行 `scripts/examples/` 中的示例脚本 - 贡献代码或自定义策略 **2. 通过 CLI 运行回测** **如果你是通过克隆源码安装的**，可以使用配置文件运行预定义的回测： ``` # 从 config 文件运行 backtest（需要源码安装） ai-trader run config/backtest/classic/sma_example.yaml ``` 或者，在任何数据文件上运行快速回测（适用于 pip 安装和源码安装）： ``` # 在您自己的数据文件上进行快速 backtest ai-trader quick CrossSMAStrategy your_data.csv --cash 100000 ``` **3. 获取市场数据** 下载任何受支持市场的历史数据： ``` # US Stock（默认：保存到 CSV） ai-trader fetch TSM --market us_stock --start-date 2020-01-01 # Taiwan Stock (台灣股票) ai-trader fetch 2330 --market tw_stock --start-date 2020-01-01 # Cryptocurrency 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 # 重复获取：从缓存加载（约 50ms，无 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 存储的信息 →**](agentic_ai_trader/trading-backtester/README.md#persistent-data-storage-with-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 # 使用示例数据运行 backtest results = run_backtest( strategy=CrossSMAStrategy, data_source=None, # Uses built-in example data cash=1000000, strategy_params={"fast": 10, "slow": 30} ) ``` **逐步控制：** 有关详细示例，请参见 `scripts/examples/02_step_by_step.py`。 ### 3. 集成 LLM（MCP Server） 将 `ai-trader` 作为 server 运行，让 AI 助手与你的回测引擎进行交互。 **启动 Server（用于测试）：** ``` 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 server 添加到 `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 与你的回测引擎进行交互，例如： - *“在 2020-2022 年的 TSM 数据上运行 CrossSMAStrategy 回测。”* - *“列出所有可用的交易策略。”* - *“获取 2021 年至 2024 年的苹果股票数据。”* ## 创建自定义策略 ### 选项 1：使用 Claude Code Skills（推荐） 创建新策略最快的方法是使用 Claude Code 中的 `/add-strategy` skill。该 skill 会以交互方式引导你完成整个过程： ``` /add-strategy classic ``` 它会提示你输入： - 策略名称（例如：“MACDBBands”） - 描述 - 带有默认值的参数 - 进入和退出条件 - 任何自定义指标 该 skill 会自动处理： - 符合命名规范的文件创建 - 全面的 docstring - 在 `__init__.py` 中自动注册 - 语法验证 了解更多关于 Claude Code skills 的信息：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` 函数可用。 ## 文档与资源 - **[策略示例](ai_trader/backtesting/strategies/README.md)**：有关内置策略的详细信息。 - **[示例脚本](scripts/examples/)**：针对不同用例的 5 个完整工作示例。 - **[配置模板](config/backtest/)**：YAML 配置模板。 - **[迁移指南](docs/MIGRATION_GUIDE.md)**：用于从 v0.1.x 升级。 ## 展示你的支持 如果你觉得这个项目有帮助，请给它点个 star ！ ## 许可证 本项目基于 GNU General Public License v3 (GPL-3.0) 授权。有关详细信息，请参阅 [LICENSE](LICENSE) 文件。

标签：AI辅助交易, Backtrader, 回测框架, 文档结构分析, 逆向工具, 量化交易, 金融科技