Lumibot - 用于股票、期权、加密货币、期货、外汇等的回测与交易库！

Lumibot 是一个用于股票、期权、加密货币、期货等的回测与交易库。它设计为使您在回测中使用的代码可以直接用于实盘交易，从而轻松实现从回测到实盘的过渡。Lumibot 是一个高度灵活的库，允许您创建自己的策略和指标，并在历史数据上进行回测。同时，它还针对速度进行了高度优化，因此您可以快速高效地回测您的策略。

重要提示：此库需要数据来进行回测。我们推荐的数据源是 ThetaData，因为他们提供了我们所见过的最深度的历史数据覆盖，并且直接支持 BotSpot。在结账时使用促销码 BotSpot10 可享受首次订单九折优惠（该代码也会告知 ThetaData 您是由我们推荐而来）。

贡献者注意： 在运行任何与 Theta 相关的内容之前，请先阅读 AGENTS.md 文件。该文件明确规定了严格的规则——切勿在本地启动 ThetaTerminal 或共享下载器，始终将 LumiBot 指向 AWS 托管的下载器，并用 /Users/robertgrzesik/bin/safe-timeout 包裹所有长时间运行的命令。违反这些规则会导致唯一的授权 Theta 会话被终止。

引入 BotSpot：无代码 AI 交易机器人

BotSpot 是我们基于 Lumibot 构建的平台，让您无需编写任何代码即可构建、回测和部署交易策略。只需用简单的英语描述您的需求，BotSpot 的 AI 就会为您完成剩下的工作。

• 使用自然语言 构建 策略——AI 会为您编写可直接投入生产的 Lumibot 代码
• 仅需点击一下即可对多年的历史数据进行 回测
• 部署至真实经纪商进行 实盘交易（Alpaca、Interactive Brokers 等）
• 浏览由社区构建的成熟策略市场，立即运行这些策略

架构文档

• docs/BACKTESTING_ARCHITECTURE.md - 回测数据流的详细文档（Yahoo、ThetaData、Polygon 数据源、缓存及数据流图）
• docs/ACCEPTANCE_BACKTESTS.md - 手动端到端验收回测套件 + 性能门控（ThetaData）
• docsrc/environment_variables.rst - 环境变量的公开文档页面（环境变量变更时更新）
• CHANGELOG.md - 部署/发布说明（请保持更新）
• CLAUDE.md - 用于处理代码库的 AI 助手指令
• AGENTS.md - 关于 ThetaData 和生产安全的关键规则

发布/部署（内部）

对于生产部署（BotSpot / BotManager），请确保每次发布都可追溯：

• 每次部署都要更新 CHANGELOG.md（包含部署的提交哈希值）
• 将部署的提交标记为 vX.Y.Z 并推送该标签
• 使用 CHANGELOG.md 条目从该标签创建 GitHub Release

文档 - 👇 从这里开始 👇

要开始使用 Lumibot，您可以查看下面的文档。

请在此处查看项目文档：👉 http://lumibot.lumiwealth.com/ 👈

AI 交易代理与代理式回测

Lumibot 现在内置了用于策略的 AI 交易代理运行时。您可以通过 self.agents.create(...) 创建一个代理，在 initialize()、on_trading_iteration()、on_filled_order() 或其他生命周期方法中运行它，并在回测和实盘交易中重复使用同一策略。

• 直接在 LumiBot 策略中构建 AI 交易代理
• 使用 DuckDB 作为时间序列分析的查询接口，而不是将原始 K 线数据直接输入提示词
• 在 回测 中重放相同的代理决策，而无需再次付费调用模型
• 挂载外部 MCP 服务器 以获取新闻、宏观数据、公司公告或其他特定领域的工具
• 使用 LumiBot 内置的运行时提示词加上您自己的系统提示词，结合结构化追踪和默认的每轮摘要，便于调试
• 让策略负责时机选择、风险规则和执行

从这里开始：

• Sphinx 文档：https://lumibot.lumiwealth.com/agents.html
• 回测文档：https://lumibot.lumiwealth.com/backtesting.html
• 股票示例：lumibot/example_strategies/agent_stock_backtest.py
• 期权示例：lumibot/example_strategies/agent_option_backtest.py
• 仓库指南：docs/AI_TRADING_AGENTS.md

关于 BotSpot 的更多信息

BotSpot 是一个基于 Lumibot 构建的平台，任何人都可以使用 AI 构建、回测和部署交易策略。请访问 BotSpot.trade 开始使用。

了解更多

请查看我们的博客中的示例策略和教程，或者使用我们的 AI 代理为您构建策略：

博客： https://lumiwealth.com/blog/ AI 策略构建器： https://www.botspot.trade/?utm_source=github&utm_medium=referral&utm_campaign=lumibot_readme

运行回测

要运行回测，您可以使用以下代码片段：

python -m lumibot.example_strategies.stock_buy_and_hold

回测数据源（环境变量覆盖）

您可以通过 BACKTESTING_DATA_SOURCE 环境变量选择回测数据源（这会覆盖代码中任何显式的 datasource_class 设置）。当您的环境已经指定了提供商时，请在调用 Strategy.backtest(...) 或 Strategy.run_backtest(...) 时将 datasource_class 设置为 None：

MyStrategy.backtest(
    datasource_class=None,
    backtesting_start=None,
    backtesting_end=None,
)

环境驱动的路由仍然以相同的方式工作：

# 单一提供商回测（示例）
export BACKTESTING_DATA_SOURCE=thetadata
export BACKTESTING_DATA_SOURCE=ibkr

多提供商路由（按资产类型）则可通过设置 JSON 映射来实现：

# 示例：股票/期权/指数使用 ThetaData，期货/加密货币使用 IBKR
export BACKTESTING_DATA_SOURCE='{"default":"thetadata","stock":"thetadata","option":"thetadata","index":"thetadata","future":"ibkr","crypto":"ibkr"}'

示例：将加密货币数据通过特定的交易所 ID 路由到 CCXT（如果需要）

export BACKTESTING_DATA_SOURCE='{"default":"thetadata","crypto":"coinbase"}'

## 运行一个示例策略

我们在这个 GitHub 仓库中创建了一个小型示例策略，以展示如何使用 Lumibot：[示例算法 GitHub](https://github.com/Lumiwealth-Strategies/stock_example_algo)

要运行此示例策略，请点击下方的“Deploy to Render”按钮将其部署到 Render（我们的推荐）。你也可以点击下方的“Run on Repl.it”按钮在 Repl.it 上运行该策略。

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/Lumiwealth-Strategies/stock_example_algo)

[![Run on Repl.it](https://oss.gittoolsai.com/images/Lumiwealth_lumibot_readme_26e23a0dcf49.png)](https://replit.com/new/github/Lumiwealth-Strategies/stock_example_algo)

**有关此示例策略的更多信息，请查看示例策略仓库中的 README：[示例算法](https://github.com/Lumiwealth-Strategies/stock_example_algo)**

## 贡献者

如果你想为 Lumibot 做贡献，可以查看下面的入门指南。我们一直在寻找愿意帮助我们的贡献者！

这里有一段视频可以帮助你开始为 Lumibot 做贡献：[观看视频](https://youtu.be/Huz6VxqafZs)

**贡献步骤：**

0. 观看视频：[观看视频](https://youtu.be/Huz6VxqafZs)
1. 将仓库克隆到你的本地机器
2. 为你的功能创建一个新的分支
3. 运行 `pip install -r requirements_dev.txt` 来安装开发依赖项
4. 安装 setup.py 中的所有依赖：`pip install -e .`
5. 进行更改
6. 运行 `pytest` 确保所有测试都通过
7. 创建一个拉取请求，将你的分支合并到主分支

## 运行测试

我们使用 pytest 作为测试框架。某些测试需要在根目录下的 `.env` 文件中设置 API 密钥。要运行测试，可以执行以下命令：

```bash
pytest

要运行单个测试文件，可以执行以下命令：

pytest tests/test_asset.py

远程缓存配置

当启用新的回测缓存管理器时，Lumibot 可以将其本地 Parquet 缓存镜像到 AWS S3。此功能是可选的，默认使用本地存储。要配置环境变量、了解密钥命名规范并遵循手动验证清单，请参阅 docs/remote_cache.md。

显示代码覆盖率

要显示代码覆盖率，可以运行以下命令：

coverage run; coverage report; coverage html

在 Linux 或 macOS 上添加别名

这会在终端中显示代码覆盖率，并创建一个名为 “htmlcov” 的文件夹，其中包含一个名为 “index.html” 的文件。你可以在浏览器中打开该文件，以更易读的方式查看代码覆盖率。

如果你不想每次都输入完整的命令，可以在 bash 中为其添加一个别名。为此，可以运行以下命令：

alias cover='coverage run; coverage report; coverage html'

现在你只需在终端中输入 “cover” 即可运行该命令。

cover

如果你想将其添加到你的 .bashrc 文件中，可以运行以下命令：

echo "alias cover='coverage run; coverage report; coverage html'" >> ~/.bashrc

在 Windows 上添加别名

如果你使用的是 Windows，可以通过运行以下命令来添加别名：

将以下内容添加到你的 PowerShell 配置文件 (profile.ps1)：

function cover { 
 coverage run
 coverage report
 coverage html
}

在 VS Code 中设置 PyTest

要在 VS Code 中进行调试设置，可以将以下内容添加到 launch.json 文件的 “configurations” 部分。这样你就可以进入 “Run and Debug” 并从那里运行测试，同时使用断点等功能。

注意：你可能需要将 args 更改为你的测试文件夹路径。

{
    "name": "Python: Pytest",
    "type": "python",
    "request": "launch",
    "module": "pytest",
    "args": [
        "lumibot/tests"
    ],
    "console": "integratedTerminal",
}

以下是一个实际的 launch.json 文件示例：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Pytest",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": [
                "lumibot/tests"
            ],
            "console": "integratedTerminal",
        }
    ]
}

数据源说明

下表指出了我们在 Lumibot 中使用的不同数据源之间的一些差异。这些差异指的是从 get_historical_prices 调用返回的 Bars 实体中所包含的数据。

data_source	类型	OHLCV	是否已调整拆股	是否包含股息	是否计算收益	是否已调整股息收益
yahoo	股票	是	是	是	是	是
alpaca	股票	是	是	否	是	否
polygon	股票	是	是	否	是	否
Tradier	股票	是	是	否	是	否
Pandas*	股票	是	是	是	是	是

*Pandas 本身并不是一个数据源，但它可以加载与 Yahoo 数据框格式相同的 CSV 文件，这些文件可能包含股息信息。

我们贡献者可能会用到的一些 Git 命令

创建新分支并从 main 拉取最新代码：

git checkout -b my-feature
git fetch origin
git merge origin/dev

将工作提交到你的功能分支：

git add .
git commit -m "my changes"
git push -u origin my-feature

如果你在另一个分支上工作时，main 分支已经更新了内容，你可以通过变基操作将其合并到你的分支中。请注意，由于你已经对本地分支进行了变基，因此需要强制推送更改以更新远程分支。--force-with-lease 选项比 --force 更安全，因为它会在远程分支上有任何尚未合并到你本地分支的新提交时中止推送。

git checkout dev
git fetch origin
git merge origin/dev
git checkout my-feature
git rebase dev
git checkout my-feature
git push --force-with-lease origin my-feature

当准备好将分支合并到 main 时，进入 GitHub 创建一个拉取请求并等待审核。一旦 PR 被批准，它就会自动合并到远程的 dev 分支。此时，你可以删除本地分支和远程分支。

git checkout dev
git fetch origin
git merge origin/dev
git branch -D my-feature
git push origin --delete my-feature

社区

如果你想深入了解 Lumibot 或算法交易，那么我们的社区一定会让你爱不释手！你可以通过 Discord 加入我们。

加入我们的 Discord：https://discord.gg/TmMsJCKY3T

在 BotSpot.trade 上构建 AI 驱动的交易机器人 — 我们的平台支持使用 AI 辅助创建、测试和部署交易策略！

AI 训练营

需要实战指导来构建你的交易机器人吗？加入我们的 AI 训练营，你将学习如何利用 AI 构建、回测并部署交易策略——无需编写任何代码。

你将学到：

• 使用简单的英文指令构建股票、加密货币、期权和期货交易机器人
• 掌握专业工具，如带有 Copilot 和 Cursor 的 VS Code
• 对你的策略进行回测，并将其部署到真实交易账户
• 加入我们超过 2,400 名交易者的社区

了解更多关于 AI 训练营的信息

---

只想试用 AI 功能吗？ 立即在 BotSpot.trade 开始免费试用 — 几分钟内即可构建策略，无需任何编程。

许可证

本库采用 MIT 开源软件许可证，详情请见：https://github.com/Lumiwealth/lumibot/blob/master/LICENSE

Lumibot 快速上手指南

Lumibot 是一个用于股票、期权、加密货币、期货和外汇的回测与实盘交易库。其核心优势在于代码复用：编写一次策略代码，即可同时用于历史回测和实盘交易。

1. 环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python 版本：建议 Python 3.8 及以上
• 前置依赖：
  • pip (Python 包管理工具)
  • git (用于克隆代码库)
• 数据源准备（重要）：
  • 回测需要历史数据。官方推荐数据源为 ThetaData（提供最深度的历史覆盖）。
  • 如需使用 ThetaData，请在结账时使用优惠码 BotSpot10 获取首单九折优惠。
  • 注意：若涉及 ThetaData 相关操作，请务必阅读项目中的 AGENTS.md 文件以遵守安全规则。

2. 安装步骤

方式一：通过 PyPI 安装（推荐用于开发策略）

直接使用 pip 安装最新稳定版：

pip install lumibot

方式二：从源码安装（推荐用于贡献代码或使用最新特性）

如果您需要修改库本身或使用开发分支功能，请按以下步骤操作：

1. 克隆仓库：

   git clone https://github.com/Lumiwealth/lumibot.git
   cd lumibot
   

2. 安装开发依赖：

   pip install -r requirements_dev.txt
   

3. 以编辑模式安装：

   pip install -e .
   

3. 基本使用

运行内置示例策略

安装完成后，您可以直接运行官方提供的“买入并持有”示例策略来验证环境是否正常：

python -m lumibot.example_strategies.stock_buy_and_hold

配置回测数据源

Lumibot 支持通过环境变量灵活切换数据源，无需修改代码。

设置单一数据源（例如 ThetaData）：

export BACKTESTING_DATA_SOURCE=thetadata

设置多数据源路由（根据资产类型自动切换）：

# 示例：股票/期权使用 ThetaData，期货/加密货币使用 IBKR
export BACKTESTING_DATA_SOURCE='{"default":"thetadata","stock":"thetadata","option":"thetadata","index":"thetadata","future":"ibkr","crypto":"ibkr"}'

在代码中调用回测时，若已通过环境变量配置，请将 datasource_class 设为 None：

MyStrategy.backtest(
    datasource_class=None,
    backtesting_start=None,
    backtesting_end=None,
)

进阶：AI 交易代理 (AI Trading Agents)

Lumibot 内置了 AI 代理运行时，允许您在策略中直接集成 AI 决策逻辑，并支持在回测中重放相同的 AI 决策以节省 Token 成本。

• 文档入口：AI 代理文档
• 股票示例代码：agent_stock_backtest.py
• 期权示例代码：agent_option_backtest.py

无代码替代方案：BotSpot

如果您希望不编写代码即可构建策略，可以尝试基于 Lumibot 构建的 BotSpot 平台。只需使用自然语言描述策略，AI 即可自动生成代码、回测并部署到实盘。

---

更多详细教程和策略示例，请访问官方博客：https://lumiwealth.com/blog/