LumiBot / 项目研究站
LumiBot：一个内置 AI Agent、能连 12 类券商把单子递出去的 Python 框架
LumiBot 是 Lumiwealth 维护的 Python 算法交易框架，GPL 系许可，仓库 2079 Star / 403 Fork。它与「只会算指标的库」不同：同一份 Strategy 子类既能跑历史回测，也能连上券商账户下真实委托，还内置了一套 AI trading agent 运行时——agent 可以看行情、读文件、查指标、写记忆，并在 allow_trading=True 时真的把订单提交到券商。
但「AI 能下单」这句话里藏着很多需要核对的东西。本站围绕三个问题展开：① agent 说它买了，怎么才算真的成交？② 回测里的指标有没有偷看未来？③ 你从 PyPI 装到的到底是哪一版、按哪套许可？每一个结论都标了出处与采集日期。
先把三件事说在前面，因为它们会直接改变你的操作步骤：① 仓库默认分支是 dev，main 分支并不存在（接口 404）；② PyPI 最新是 4.5.91，而仓库 setup.py 里已经写着 4.5.92，README 的 AI 快速上手让你直接从仓库分支安装；③ 许可有两套口径——GitHub 与 setup.py 写 GPL-3.0，PyPI 4.5.91 的元数据写 MIT，而同一个 wheel 里携带的 LICENSE 文件是 GPL v3 全文。
- 仓库：Lumiwealth/lumibot，默认分支
dev，HEAD 提交28afefe8（2026-09-18） - PyPI：
lumibot 4.5.91（2026-09-06T21:16:02Z 上传，wheel 37,810,900 字节） - 仓库
setup.py版本号：4.5.92（PyPI 上尚不存在） - 本机：Python 3.11.9 / Windows；EasyClaw 技能目录 29 个技能已核验
- 采集日期 2026-09-22；本站未实盘下单，不做收益声明
项目来源
Lumiwealth/lumibot（GitHub 仓库页截图）
打开仓库 ↗
你装的、你 clone 的、你以为的许可，可能不是同一件事
开源项目的中文教程最容易在「版本与许可」这两处失真。下面三条都能自己复现：打开仓库看默认分支、打开 PyPI 看最新版、把 wheel 解压看里面的 LICENSE。
| 观测项 | 具体值 | 出处 | 注意点 |
|---|---|---|---|
| 仓库默认分支 | dev | GitHub REST /repos/Lumiwealth/lumibot 的 default_branch | 直接查 /branches/main 返回 404；master 分支停在 2025-12-18，内容是 "Create CNAME"，是给 GitHub Pages 用的 |
| dev 最新提交 | 28afefe8，2026-09-18 | /commits | 提交信息是 Merge pull request #1165 from Lumiwealth/version/4.5.92 |
| PyPI 最新版 | 4.5.91，2026-09-06 上传 | pypi.org/pypi/lumibot/json | PyPI 上共 640 个发行版；只提供 wheel，没有 sdist |
| 仓库 setup.py 版本号 | 4.5.92 | raw/dev/setup.py 的 version= | PyPI 的发行版键集合里没有 4.5.92，即 PyPI 落后仓库一个版本 |
| README 的 AI 快速上手 | pip install "git+https://github.com/Lumiwealth/lumibot.git@version/4.5.92" | README「Run your first AI backtest」 | 官方自己也知道 PyPI 上没有这一版，所以 AI 示例直接指向仓库分支 |
| 许可（GitHub / setup.py） | GPL-3.0（GNU General Public License v3.0） | GitHub license.spdx_id；setup.py 的 license="GPL-3.0" 与 classifier | README 顶部徽章也写 GPL v3 |
| 许可（PyPI 元数据） | MIT | wheel 内 lumibot-4.5.91.dist-info/METADATA 的 License: MIT 与 classifier | 同一份 METADATA 里还写着 License-File: LICENSE |
| wheel 里真正携带的 LICENSE | GNU GPL v3 全文（35,130 字符） | 解压 wheel 读取 dist-info/licenses/LICENSE | 也就是说：元数据说 MIT，包里带的却是 GPL v3 正文——发布物自身两处口径不一致 |
pip install lumibot 拿到的是 4.5.91，而 README 的 AI 示例要求 4.5.92；许可口径冲突意味着「能不能商用」这件事不能照抄任何一篇博客的结论。本站只并置这两套口径与它们的文件位置，不提供法律意见。你怎么用，请以官方 LICENSE 文件与你的实际使用方式为准。setup.py，2026-09-22 采集）。示意图仅重述上述出处的事实，不代表官方时间线评价。「AI Agent 能下单」到底真在哪里？
官方描述的第一句是 AI agents that actually place the trade。这句话值得拆开看：能不能下单，取决于权限开关、就绪检查和状态核验三段机制，而不是取决于「有没有接大模型」。
权限是显式开关，不是默认能力
用 self.agents.create(name=..., allow_trading=False) 创建的 agent 会被摘掉 5 个变更类工具：orders_submit_order、orders_submit_multileg、orders_cancel_order、orders_modify_order、remember_decision。只读工具仍然保留，所以研究员 agent 照样能查行情、读文件、查记忆。
下单前必须自己看账
即使 agent 有交易权限，官方也要求它在同一次 run 内先看过账户组合、持仓和市价；缺任何一项，订单工具会返回结构化错误 ORDER_READINESS_REQUIRED 而不下单。框架不替你猜仓位，也不套用统一的保证金规则。
「提交了」不等于「成交了」
官方原文是 Never claim a fill unless is_filled is true。orders_wait_for_terminal 做的是有界轮询，上限 120 秒；超时、提交成功、接口返回 200，都不能当作成交证据。这条是判断「AI 交易演示」可信度的分水岭。
| 环节 | 机制 | 你能观察到什么 | 注意点 |
|---|---|---|---|
| 权限 | allow_trading 参数切换工具集合 | 关掉后 agent 的工具清单里不再出现下单类工具 | 「只读 agent 也能下单」是错的；反过来，开了权限的 agent 也仍受就绪检查约束 |
| 就绪检查 | 同一 run 内必须先调用 account_portfolio + account_positions + market_last_price | 缺检查时拿到 ORDER_READINESS_REQUIRED | 这是拒绝下单而不是自动补齐；框架明确不静默调整下单量 |
| 提交 | orders_submit_order / orders_submit_multileg | 返回订单标识符 | 多腿期权是原子提交：券商不支持整包提交时，在提交任何一条腿之前就拒绝，绝不拆成子订单 |
| 成交判定 | orders_get_status 读 is_filled | 真实的成交状态字段 | 提交成功或超时都不是成交证据 |
| 等待 | orders_wait_for_terminal，上限 120 秒 | 轮询期间挂单可被处理 | 超过 120 秒仍未终结，就要按「未知」处理，而不是按「已成交」处理 |
| 审计 | 记忆工具 + SQLite + 三个 Parquet 产物 | 可查 agent 名称、模型调用 ID、提案、风险笔记、最终决策 | 「回放」回放的是决策，不是市场结果，见记忆与回放 |
| 回测与实盘 | 同一份 Strategy 类 | 两处共用同一生命周期钩子 | 官方自己说明券商行为表仍需 smoke test 才能从「文档」变成「事实」，见一致性 |
它铺开的范围有多大：代码口径与官方口径分开看
官方描述里的数字（12 brokers、25+ 示例）和仓库里能数出来的东西并不总是同一个口径。下面这组数字全部来自本机对目录清单与 wheel 内容的清点，采集日期 2026-09-22。
| 维度 | 代码/包内可数的数量 | 官方口径 | 适用场景 | 注意点 |
|---|---|---|---|---|
| 券商类 | 11 个可实例化类（含面向开发者的 ExampleBroker） | 描述写「12 brokers」，README 列 9 条产品条目 | 判断自己的券商在不在名单 | 三个口径都对，但含义不同：类、产品、可自动识别的凭据路径是三种统计方式 |
| 数据源模块 | lumibot/data_sources/ 共 27 个文件（含 __init__.py 与 exceptions.py） | README 只列了名字 | 查某个数据源有没有实现 | 模块存在 ≠ 你的账号有权限；付费源要先有订阅 |
| 回测引擎 | lumibot/backtesting/ 共 16 个回测类模块 | README 举了 4 个（Yahoo/Polygon/ThetaData/Polymarket） | 选回测数据源 | 同名数据源常有 pandas / polars 两条实现，别把两条算成两个数据商 |
| 示例策略 | example_strategies/ 共 47 个 .py，其中 agent_* 10 个、ai_* 13 个 | README 写「25+ example strategies」 | 找可运行的最小样例 | 示例能跑通不等于策略有效；AI 类示例多数需要对模型 Key 才能运行 |
| 内置 agent 技能 | 3 个：options-trading、research-data、stock-trading | README 未单列 | 了解 agent 被要求先读什么 | 这是LumiBot 自带的运行时技能，和 EasyClaw 的技能体系完全是两套东西 |
| 依赖条目 | requirements.txt 与 setup.py 各 55 条 | README 只给一句 pip install lumibot | 评估装起来有多重 | 含 ibapi==9.81.1.post1 这类钉死版本与 Google ADK / LiteLLM / MCP 全家桶，见安装与依赖体量 |
| 包内资源 | wheel 共 231 个条目，含 ThetaTerminal.jar（39 MB） | README 只提 ThetaData 是可选 extras | 理解为什么 wheel 有 37.8 MB | 本机实测：pip 装完的包里确实带着这个 jar，也带着那 3 个 agent 技能 |
2079 Star / 403 Fork
仓库创建于 2020-09-10，最近一次 push 为 2026-09-21。Star 数随时间变化，本站标注采集日期，不做「最热门」这类比较。
640 个发行版
PyPI 上累计发行版数量，说明这是一个高频发布的商业团队项目，而不是个人周末项目。
AI 优先的仓库结构
仓库根目录直接放了 llms.txt、llms-full.txt、AGENTS.md、CLAUDE.md，并有专门的 agent 评测目录与 CI 工作流。
开源之外还有商业面
README 同时指向 BotSpot 托管平台（含免费挑战、训练营与市场），并声明部分 provider 链接与优惠码可能支持项目开发。开源代码与托管服务要分开看，见许可与商业边界。
三条路线：不联网的回测、连券商的实盘、不装环境的技能
选路线之前先确认三件事：你要不要连券商账户、你打算用哪个数据源、你能不能接受在 Windows 上解决依赖。这三件事决定你走哪条路。
| 你的情况 | 建议路线 | 理由 | 第一件该做的事 |
|---|---|---|---|
| 只想先跑一遍回测，不想申请任何账号 | pip install lumibot + Yahoo 免费日线 | 官方最简单的一条路径，不需要券商也不需要 API Key | 读安装与依赖体量确认 Python 版本与依赖重量 |
| 想试 AI Agent 策略 | 从仓库分支装 version/4.5.92，并准备模型 Key | README 的 AI 示例明确要求该分支；默认模型是 gemini-3.5-flash-lite | 先读权限分界，决定哪个 agent 允许下单 |
| 要接自己的券商账户 | 自托管 + 券商 API Key（paper 模式起步） | 官方支持 Alpaca / IBKR / Tradier / Schwab / Tradovate / ProjectX / Bitunix / Polymarket 与部分 CCXT | 读券商矩阵确认你的券商与资产类别 |
| 只想要数据或做指标研究，不想长期维护进程 | 先用 EasyClaw 技能路线 | 为看几个指标而部署一套常驻框架并不划算 | 先看本页「免部署 demo」段落，再看数据源与路由了解免费取数边界 |
| 目标是 A 股/国内市场的程序化交易 | 先不要用 LumiBot | 它的数据源与券商清单以美股、期权、期货、外汇、加密为主，不覆盖 A 股券商通道 | 先确认标的市场，再换工具组合 |
| 不想自己维护调度与日志 | 官方托管的 BotSpot | 数据、并行回测、券商连接、调度、监控、告警、kill switch 由平台承担 | 注意这是付费商业服务，与开源代码是两件事 |
| 想在期权上做多腿策略 | 自托管 + 支持整包提交的券商 | 多腿是原子提交、fail closed：券商不支持就整单拒绝 | 读下单与成交的多腿一节 |
如果只是想拿数据、算指标，交互长什么样
下面这张是本机 EasyClaw 的实际对话截图（与本站 TradingGym 研究站同一批实拍素材）。它演示的是「技能路线」的操作形态：不用建项目、不用装依赖、不用管进程。它不是 LumiBot 的运行结果，也不代表 LumiBot 的能力边界——LumiBot 侧要自己配置数据源与券商，并按策略代码去调用它们。
is_filled 判定、没有订单生命周期。另外提醒：不要把任何券商的真实 API Key 粘贴进对话或截图；LumiBot 侧的凭据也不要提交到公开仓库。谁适合用它，谁应该换别的工具
判断标准不是「它功能多不多」，而是「你的市场、账户类型和运维意愿是否匹配」。
适合：已经有明确的规则，需要一个能落地的执行框架
你写得出 Strategy 子类，也知道要在哪个生命周期钩子里下单。LumiBot 提供的是订单对象、券商适配、回测引擎和产物，而不是替你决定买什么。
适合：想研究 AI Agent 与确定性规则如何混合
官方示例里既有纯 Python 规则策略，也有「研究员 + 看多 + 看空 + 交易员」的团队形态，还有 5 份确定性 .rules.json 作为闸门。这类混合形态在别的框架里较少见。
适合：能接受美股/期权/期货/外汇/加密这套市场范围
券商与数据源都围绕这些市场。如果你要做的是 A 股，框架本身不提供对应通道。
不适合：把「回测曲线好看」当成结论的人
官方自己在指标时间安全的文档里写了「不要从前缀回归外推保证」。任何 AI 交易演示，只要没给出 is_filled 级别的成交证据，就还停留在「提示词演示」阶段。
不适合：不想读英文工程文档的人
真正有价值的信息（订单语义、现金会计、时间安全、券商行为表）都在仓库 docs/ 里以英文工程笔记形式存在，含大量「尚未验证」的自我限定。跳过这些直接看示例代码，很容易得到过度乐观的印象。
不适合：需要托管且不想付费的团队
官方托管 BotSpot 是商业服务；开源自托管意味着调度、日志、告警、密钥保管与进程守护都要自己解决。
关于 LumiBot 的高频问题
以下回答基于 2026-09-22 对官方仓库、PyPI 元数据与本机实测的核对；涉及代码行为的以官方仓库实现为准。本站未实盘下单，不做收益声明。
LumiBot 到底是什么？和 Backtrader 这类回测库差在哪？
它同时是回测框架和券商执行框架：同一份 Strategy 子类既能跑历史回测，也能连上券商账户提交真实委托；它额外内置了一套 AI trading agent 运行时，agent 可以在策略循环里被调用、可以持有记忆、也可以在权限允许时直接下单。Backtrader 一类的库主要解决「怎么回测」，LumiBot 还多了一层「怎么把订单递给券商、怎么记录 agent 的决策」。以上对照依据 README 的能力表与仓库目录结构，具体差异以官方文档为准。
为什么我 clone 下来的没有 main 分支？
因为它的默认分支就是 dev，直接查 /branches/main 返回 404。仓库里另有一个 master，最后提交停在 2025-12-18，提交信息是 "Create CNAME"，用途是 GitHub Pages，不是开发主线。所以「按惯例切 main」在这个项目上会失败——按 README 做就是对的。
PyPI 上的版本和 README 说的不一样，我该装哪个？
两个都是官方的，只是用途不同：pip install lumibot 拿到 PyPI 最新 4.5.91（2026-09-06 上传），适合跑传统规则策略的回测；README 的 AI 快速上手写的是从仓库分支 @version/4.5.92 安装，因为那一版当时还没发到 PyPI。建议：先在 venv 里装 PyPI 版跑通最小回测，确认环境没问题再决定要不要切到分支版。切之前把 commit 记下来，方便回退。
它到底是 GPL-3.0 还是 MIT？能商用吗？
本站核到的事实是：GitHub 与 setup.py 写 GPL-3.0，README 徽章也是 GPL v3；而 PyPI 4.5.91 的 wheel 元数据写 License: MIT 且带 MIT classifier；同一个 wheel 里实际携带的 LICENSE 文件内容却是 GPL v3 全文。这是发布物自身的口径不一致，不是本站的推断。本站不提供法律意见，也不替官方下结论。涉及商用、二次分发或修改后闭源，请以官方 LICENSE 文件与你所在法域的实际规定为准，必要时咨询专业人士。详见许可与商业边界。
AI Agent 说它买了，我怎么确认真的成交了？
看三个东西：①下单前 agent 是否在同一轮里读过账户组合、持仓和市价（缺了就只会得到 ORDER_READINESS_REQUIRED，不会下单）；②提交后是否有订单标识符；③最终状态里 is_filled 是否为真。提交成功、接口返回 200、轮询 120 秒超时，都不能当作成交。官方在工具文档里把这句话写成了硬规则，也是本站判断任何「AI 自动交易」演示的第一道筛子。
回测结果可信吗？会不会有未来函数？
官方自己公开过一个回归案例：旧实现按整个回测区间一次计算指标，只在策略时间取索引，一个 offset=-1 的 SMA 在「次日收盘从 30 变 3000」时从 25 变成 1510。现在的实现改成先按策略时间截取前缀再计算，并按观测值摘要缓存；独立时间窗要求显式时区偏移、且拒绝越过策略时间的 end。但官方同时列出仍未证明的部分（适配器相关的已完成 bar、多指标独立复算、真实模型推理、长历史性能）。结论：机制比过去安全，但不要把它当成「我的回测一定没有未来函数」的保证。详见未来函数与时间安全。
它支持哪些市场？能用来做 A 股吗？
官方描述覆盖股票、期权、期货、外汇、加密与预测合约（Polymarket）。券商与数据源清单都围绕这些市场组织。按本站核到的证据，它不提供 A 股券商通道，也没有 A 股数据源实现；如果你的目标市场是 A 股，需要换工具组合。这也是本站对比页要如实区分两件事的原因：EasyClaw 侧的技能路线里有富途 OpenAPI 委托与东财模拟组合，覆盖的市场与形态和 LumiBot 不同。
我需要付钱吗？
开源代码本身可以自己部署；但运行成本可能来自三处：①数据源——Yahoo 免费日线可用，更深的期权/期货历史要买（官方推荐 ThetaData，属可选 extras）；②模型调用——AI agent 每轮决策都会调用模型，默认 gemini-3.5-flash-lite，需要自己的模型 Key；③托管——官方 BotSpot 是付费商业服务。README 里有 affiliate 声明，说明部分 provider 链接与优惠码可能支持项目开发；本站不复制任何优惠码或推广链接，也不替官方算成本。