跳转至

docs 目录代码验证报告

验证日期:2026-06-28 验证环境:conda 环境 lean(Python 3.11.13) 验证范围:docs/ 目录下全部 11 个 Python 示例文件 验证方式:字节码编译(语法)+ AST / pyflakes 静态分析 + 运行时导入探测


一、结论速览(TL;DR)

维度 结果
语法编译(py_compile) 11 通过 / 0 失败 ✅(4 文件、5 处 f-string Bug 已于 2026-06-28 修复)
静态分析(pyflakes) 原 4 个硬错误已全部修复;仅余若干低优先级风格提示(见第四节)
运行时导入(数据科学依赖) ✅ pandas / numpy / scipy / matplotlib 均可导入
运行时导入(Lean 符号) ⚠️ AlgorithmImports 在本环境为空命名空间包,QCAlgorithm 等符号不可用
完整回测执行 ⛔ 未执行(需 Lean 引擎 + Docker + 行情数据,见第六节)

关键发现(✅ 已修复):原 4 个文件存在多行 f-string SyntaxError(其中 06-indicators-demo.py 有 2 处,共 5 处编辑),已于 2026-06-28 全部修复,现 11/11 通过编译。 详见第三节。


二、环境搭建(可复现)

2.1 创建 conda 环境

conda create -y -n lean python=3.11

选用 Python 3.11:与教程大纲(docs/tutorial-outline.md 第 81-94 行「Python 环境配置」)以及 QuantConnect Lean 运行时所使用的 Python 版本一致。

2.2 安装验证依赖

# 激活环境后,或直接用环境内 pip:
/Users/henrylin/anaconda3/envs/lean/bin/python -m pip install \
    pandas numpy scipy matplotlib quantconnect-stubs pyflakes

已安装版本:

包 版本 用途
pandas 3.0.3 10-research-demo.py 数据处理
numpy 2.4.6 10-research-demo.py 数值计算
scipy 1.17.1 10-research-demo.py 概率图
matplotlib 3.11.0 10-research-demo.py 可视化
quantconnect-stubs 17877 Lean API 类型存根(仅 IDE/类型检查用)
pyflakes 3.4.0 静态分析

2.3 验证命令

LEAN_PY=/Users/henrylin/anaconda3/envs/lean/bin/python

# 语法编译
$LEAN_PY -m py_compile docs/**/*.py

# 静态分析(过滤来自 star import 的 F403/F405 噪音)
$LEAN_PY -m pyflakes docs/**/*.py

三、语法验证详情(py_compile / AST)

3.1 逐文件结果

# 文件 行数 语法 说明
1 01-introduction/01-hello-world.py 84 ✅ PASS Hello World 买持策略
2 01-introduction/03-sma-cross.py 250 ✅ PASS SMA 金叉/死叉 + 止损变体
3 02-strategy-basics/04-qcalgorithm-demo.py 397 ✅ PASS QCAlgorithm 生命周期
4 02-strategy-basics/05-order-management-demo.py 505 ✅ PASS 各类订单 / OrderTicket
5 02-strategy-basics/06-indicators-demo.py 512 ✅ PASS(已修复, 原 364 / 471) 多指标 + 自定义指标
6 02-strategy-basics/07-data-demo.py 503 ✅ PASS(已修复, 原 449) History / Universe / 自定义数据
7 03-advanced/08-framework-demo.py 702 ✅ PASS Alpha/组合/执行/风险 五模型
8 03-advanced/09-advanced-features-demo.py 622 ✅ PASS(已修复, 原 621) 期权 / 期货 / 自定义模型
9 03-advanced/10-research-demo.py 515 ✅ PASS QuantBook 研究脚本(notebook 风格)
10 04-backtesting-optimization/12-optimization-demo.py 470 ✅ PASS(已修复, 原 468) 可优化策略 / 滚动优化
11 06-data-management/15-data-demo.py 541 ✅ PASS 自定义数据 / 数据质量校验

3.2 失败根因:多行 f-string 替换字段被拆断

4 个失败文件全部是同一类错误:把一个 f-string 的 {...} 替换字段拆到了两个隐式拼接的字符串字面量之间。例如 06-indicators-demo.py:363-364:

# ❌ 错误写法:{ 在第一个字面量里打开,} 却在第二个字面量里关闭
self.Debug(f"  BB Position: {(price - self.bb_20_2.LowerBand.Current.Value) / "
          f"(self.bb_20_2.UpperBand.Current.Value - self.bb_20_2.LowerBand.Current.Value) * 100:.1f}%")

为什么是 Bug(与 Python 版本无关):

  • Python ≤ 3.11(即 Lean 运行时所用的版本):解析阶段即抛 SyntaxError: f-string: expecting '}',文件根本无法被加载。
  • Python 3.12+(PEP 701 重写了 f-string tokenizer):虽能编译,但运行时抛 TypeError: 'str' object is not callable(已实测复现),语义仍错误。

结论:无论哪个 Python 版本,这都是确定的运行期/加载期 Bug。由于 Lean 使用 Python 3.11,原代码在 Lean 中加载就会失败。

✅ 状态:上述全部错误已于 2026-06-28 修复(共 5 处编辑,06-indicators-demo.py 含 2 处),4 个文件现均通过 py_compile,详见 3.3。

3.3 错误定位与修复(✅ 已于 2026-06-28 应用)

共 5 处编辑、涉及 4 个文件。注意 06-indicators-demo.py 有 2 处(363-364 与 470-471,后者此前被首个语法错误遮挡,修复前者后才暴露)。修复方式统一为「先求值到局部变量,再放入 f-string」。

① 06-indicators-demo.py:363-364(EnterLong 内的 BB 位置)

# 已应用:先算出值再格式化(可读性最好)
bb_pos = ((price - self.bb_20_2.LowerBand.Current.Value) /
          (self.bb_20_2.UpperBand.Current.Value - self.bb_20_2.LowerBand.Current.Value)) * 100
self.Debug(f"  BB Position: {bb_pos:.1f}%")

② 06-indicators-demo.py:470-471(OnEndOfAlgorithm 内的总收益)

# 已应用
total_return = (self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1) * 100
self.Debug(f"Total Return: {total_return:.2f}%")

③ 07-data-demo.py:448-449

# 已应用
total_return = (self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1) * 100
self.Debug(f"Total Return: {total_return:.2f}%")

④ 09-advanced-features-demo.py:620-621

# 已应用
final_return = (self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1) * 100
self.Debug(f"Final Return: {final_return:.2f}%")

⑤ 12-optimization-demo.py:467-468

# 已应用
total_return = self.Portfolio.TotalPortfolioValue / self.Portfolio.StartingCash - 1
self.Debug(f"Total Return: {total_return:.2%}")

通用修复原则:f-string 的 {...} 替换字段必须在同一个字符串字面量内闭合;若表达式过长,先赋值给局部变量再放进 f-string,或用括号在单行内换行。


四、静态分析详情(pyflakes)

已过滤 from AlgorithmImports import * 带来的 F403/F405(star import)噪音——这是 Lean 算法的标准写法,非问题。

4.1 低优先级风格提示(不影响运行)

(a) F541 — f-string 无占位符(f"..." 里没有 {},f 前缀多余) 出现文件:03-sma-cross.py、04-qcalgorithm-demo.py、05-order-management-demo.py、10-research-demo.py、15-data-demo.py。 示例:self.Debug(f"Fast MA: 50 days") → 去掉 f 即可。纯风格问题,运行无碍。

(b) F401 — 导入未使用 - 04-qcalgorithm-demo.py:13、08-framework-demo.py:13:from datetime import timedelta, datetime 未使用。 - 10-research-demo.py:22:timedelta 未使用。

(c) F841 — 局部变量赋值后未使用 - 04-qcalgorithm-demo.py:spy_volume、spy_bid、spy_ask、is_invested、spy_quantity、spy_total_cost、total_margin_used、atr_value、price 等。 - 05-order-management-demo.py:ticket、order。 - 15-data-demo.py:513:risk_on。

说明:教学示例中这类「取了值但没用」的写法多为刻意演示 API 访问方式(展示「如何拿到成交量/买卖价」),属正常教学代码;若要消除告警,可在 Debug 中输出这些变量,或加 # noqa。

4.2 结构摘要(AST)

文件 导入 定义的类(基类)
01-hello-world AlgorithmImports.* HelloWorldAlgorithm(QCAlgorithm)
03-sma-cross AlgorithmImports.* SimpleMovingAverageCrossAlgorithm、SMAWithStopLossAlgorithm(均 QCAlgorithm)
04-qcalgorithm-demo AlgorithmImports.* QCAlgorithmBasicsAlgorithm、SimpleQCAlgorithmExample(QCAlgorithm)
05-order-management-demo AlgorithmImports.* OrderManagementDemoAlgorithm(QCAlgorithm)、OrderManager
06-indicators-demo AlgorithmImports.* TechnicalIndicatorsDemoAlgorithm、SimpleMultiIndicatorStrategy(QCAlgorithm)+ 2 个 PythonIndicator
07-data-demo AlgorithmImports.* DataAndHistoryDemoAlgorithm、SimpleHistoryExample(QCAlgorithm)+ SentimentData(PythonData)
08-framework-demo AlgorithmImports.* 12 个类:覆盖 AlphaModel/PortfolioConstructionModel/ExecutionModel/RiskManagementModel/QCAlgorithm
09-advanced-features-demo AlgorithmImports.* 期权/期货策略 5 个 + AdvancedFeaturesDemo(QCAlgorithm)+ FeeModel/SlippageModel
10-research-demo QuantConnect.*、pandas、numpy、matplotlib notebook 风格脚本,无类定义
12-optimization-demo AlgorithmImports.*、numpy OptimizableMovingAverageStrategy、RobustOptimizationStrategy、WalkForwardOptimizationStrategy(QCAlgorithm)
15-data-demo AlgorithmImports.* PythonData×2 + 3 个 QCAlgorithm

所有 10 个算法文件均正确 from AlgorithmImports import *;10-research-demo.py 正确使用 QuantConnect + 数据科学库。导入写法全部正确。


五、运行时导入探测

5.1 数据科学依赖:✅ 全部可用

import pandas, numpy, scipy, matplotlib   # 均成功
# pandas 3.0.3 | numpy 2.4.6 | scipy 1.17.1 | matplotlib 3.11.0

因此 10-research-demo.py 中纯 pandas/numpy 的部分(指标计算、收益统计、参数网格搜索)在该环境可独立运行;但其 QuantBook()、qb.History() 等 Lean 调用仍需研究环境。

5.2 Lean 符号:⚠️ AlgorithmImports 是「空壳」

在安装了 quantconnect-stubs 的 lean 环境中:

from AlgorithmImports import *     # 不报错
'QCAlgorithm' in dir()             # False —— 没绑定任何名字!
import AlgorithmImports as ai
dir(ai)                            # [] 空
ai.__file__                        # None(namespace package)

原因:quantconnect-stubs 在 site-packages 下放置了一个空的 AlgorithmImports 命名空间包目录(仅含 .pyi 类型存根,供 IDE 补全/类型检查),不含真实运行时符号。

后果:若直接 python 01-hello-world.py 执行,class HelloWorldAlgorithm(QCAlgorithm) 会抛 NameError: name 'QCAlgorithm' is not defined。这些文件不能脱离 Lean 引擎单独运行——这是设计使然,不是 Bug。

换言之:本 conda 环境适合做语法 + 静态 + 类型层面的验证(已覆盖),但不能直接运行策略。直接运行需要下一节的完整 Lean 运行时。


六、如何完成「完整运行验证」(回测)

当前静态验证已覆盖「代码本身是否正确」。若要进一步验证策略真能回测出结果,需 Lean 运行时,二选一:

方式 A:Lean CLI + Docker(官方推荐,最省事)

# 1. 安装 Lean CLI
pip install lean

# 2. 初始化(会拉取 quantconnect/lean 镜像,需要 Docker)
lean init

# 3. 把示例复制进一个项目目录,配置 main.py / config.json 指定 algorithm-type-name
# 4. 本地回测(示例)
lean backtest --project MyStrategy
  • 依赖:本机已有 Docker 27.4.0 ✅、dotnet 10.0.201 ✅;缺 lean CLI(pip install lean 即可)。
  • 数据:默认用 QuantConnect 云端数据;本地数据需 lean data download。

方式 B:本地编译 Lean Engine(Pythonnet)

dotnet build QuantConnect.Lean.sln
# 配置 PYTHONNET_PYDLL 指向 libpython3.11,运行 Launcher
  • 适合深度二次开发;配置较繁琐。

✅ 第三节列出的 5 处 SyntaxError 已全部修复,11/11 文件通过编译,可直接进入回测。回测仍需 Lean 运行时本身(Docker / 编译引擎)。


七、建议与后续行动

优先级 行动 涉及文件
✅ 已完成 修复多行 f-string SyntaxError(共 5 处编辑,06 含 2 处) 06、07、09、12
🟡 中 清理无占位符 f-string、未用导入(可选) 03、04、05、08、10、15
🟢 低 修复后用 lean backtest 跑一次 Hello World / SMA 交叉,确认端到端可运行 全部

附录:本次验证未覆盖的内容

  • 真实行情回测结果(收益、夏普、回撤等)——需 Lean 引擎 + 数据。
  • Lean API 用法的语义正确性(如某指标参数是否合理、订单逻辑是否符合预期)——需在运行时结合实际数据人工复核。
  • C# 示例代码(tutorial-outline.md 等文档中内嵌的 C# 代码片段)——本次仅验证 docs/ 下的 .py 文件。

本报告由 lean conda 环境(Python 3.11.13)下的 py_compile / pyflakes / ast 自动生成并人工核对。