迭代 139：核心稳定性与工程治理收敛计划

计划日期：2026-03-24 适用分支：dev / development 计划定位：在迭代 138 完成 Tick 级架构推进之后，优先收敛核心运行链、工程工具链和仓库治理债务，为后续功能迭代提供稳定底座。

1. 迭代目标

本轮迭代不再继续扩张功能面，重点解决以下四类问题：

  1. 核心引擎文件过大、职责交叉，维护成本持续抬升。

  2. 关键交易路径仍有遗留 TODO / FIXME，部分已触及正确性和运行语义。

  3. 文档、CI、发布元数据存在漂移，工具链可用性不足。

  4. 仓库中存在示例输出和大体量测试数据，工程治理边界不清晰。

本迭代的目标是把这些问题从“已识别”推进到“可执行、可验收、可持续维护”的状态。

2. 当前基线

2.1 代码结构基线

当前核心模块已经出现明显的单文件膨胀：

文件

行数

backtrader/strategy.py

2349

backtrader/plot/plot.py

2191

backtrader/lineiterator.py

2166

backtrader/linebuffer.py

2145

backtrader/cerebro.py

2066

backtrader/lineseries.py

1732

backtrader/parameters.py

1702

backtrader/stores/btapistore.py

1663

backtrader/metabase.py

1656

backtrader/brokers/bbroker.py

1529

这些模块同时也是 mypy 规则放宽最集中的区域，说明复杂度已经影响到静态分析有效性。

2.2 质量债务基线

  • docs/TODO_FIXME_TRACKER.md 当前记录了 34 个源码级 TODO / FIXME。

  • 遗留项集中在 backtrader/cerebro.py、backtrader/brokers/bbroker.py、backtrader/feed.py、backtrader/dataseries.py 等关键路径。

  • 其中多项并非纯注释清理，而是涉及循环条件、执行语义、佣金计算、未解释分支等问题。

2.3 测试与 CI 基线

  • tests/ 目录下当前有 354 个 test_*.py 文件。

  • pytest --collect-only -q tests 输出 1820 行，说明测试规模已经显著高于 README 中“478+ tests”的表述。

  • .github/workflows/test.yml 目前在 Ubuntu、macOS、Windows 上对 Python 3.8 到 3.13 跑全量测试矩阵，覆盖面高，但 PR 反馈成本也高。

2.4 文档与工具链基线

  • tools/doc_coverage_scanner.py 可以打印覆盖率，但在生成报告阶段会抛出 KeyError: 'module'，当前无法稳定产出报告文件。

  • 同一脚本对顶层函数的识别逻辑存在误判风险，统计结果可信度不足。

  • .github/workflows/docs-auto-build.yml 已依赖该脚本做文档覆盖检查，意味着当前文档 CI 有失效风险。

2.5 元数据与仓库治理基线

  • README.md 声明 Python 3.9+，但 setup.py、pyproject.toml 与测试矩阵实际支持 3.8 到 3.13。

  • README.md 与 LICENSE 明确为 GPLv3，但 setup.py classifier 仍写成 MIT License。

  • 仓库当前跟踪了 examples/output/*.html|json|pdf 这类生成产物。

  • 仓库还跟踪了多个大体量测试/示例数据文件，例如：

    • tests/datas/bond_merged_all_data.csv 约 70 MB

    • tests/datas/FG889.csv 约 31 MB

    • examples/DOGEUSDT_15m_20200710_20260126.csv 约 24 MB

3. 关键问题归纳

3.1 核心引擎耦合过深

当前 Cerebro、Strategy、Line* 系列和 Broker 相关实现都承担了多重职责：运行循环、通知路由、兼容分支、历史包袱和新功能桥接同时存在，导致：

  • 代码阅读门槛高；

  • 小改动的回归半径大；

  • 静态检查需要大量例外；

  • 新功能只能通过“继续打补丁”进入，而不是通过清晰扩展点进入。

3.2 观察器体系存在特化耦合

TradeLogger 已经从普通 observer 演变为带有专属分支的特殊组件。backtrader/strategy.py 中存在按类名字符串识别 TradeLogger 的逻辑，这说明：

  • observer 扩展边界被打破；

  • 日志能力和策略运行链耦合过深；

  • 后续继续扩展日志、监控、告警能力时会进一步放大侵入性。

3.3 工具链“可见但不可用”

文档覆盖扫描、质量文档、README 指标、发布元数据之间已经出现明显漂移。问题不在于“没有工具”，而在于：

  • 工具结果不稳定；

  • 指标口径不统一；

  • 文档承诺和实际工程状态不一致；

  • CI 虽然覆盖广，但没有分层策略来平衡速度与成本。

3.4 仓库资产边界不清晰

示例输出、超大样例数据、长期保留的历史规划文档共同存在于主仓库中。虽然部分资产有合理性，但当前没有明确分层：

  • 什么必须进 Git；

  • 什么应该转为生成物；

  • 什么应该压缩、裁剪或改为外部下载；

  • 什么应该迁移到更适合的存储方式。

4. 迭代范围

4.1 本轮要做

  1. 清理关键运行链上的高风险遗留项。

  2. 为 observer/logging 建立更清晰的扩展边界。

  3. 修复失效的文档工具链并统一发布元数据。

  4. 建立测试矩阵分层和仓库资产治理规则。

4.2 本轮不做

  1. 不启动新一轮 Tick 架构大重构。

  2. 不新增大型外部数据源或交易接入。

  3. 不在本轮引入新的可视化前端系统。

  4. 不做以 Cython/Numba 为主线的性能重写。

5. 工作流与任务拆解

5.1 工作流 A：核心运行链稳定性清理

优先级：P0

目标：关闭关键运行路径上的解释不清、分支冗余和语义不确定问题。

任务：

  1. 审核 cerebro.py 中 run loop 相关历史 TODO，逐项给出“删除 / 修复 / 文档化保留”的结论。

  2. 审核 bbroker.py 中佣金、持仓价值和执行分支相关 TODO，补充回归测试。

  3. 审核 feed.py、dataseries.py 中已标记 FIXME，清理无效状态字段和不稳定兼容逻辑。

  4. 为本轮处理过的每个遗留项补充对应测试或注释说明，禁止“只删 TODO 不补约束”。

交付物：

  • 关键遗留项清单与处理结论

  • 新增/修复的回归测试

  • 清理后的运行链说明文档

5.2 工作流 B：Observer / Logging 解耦

优先级：P1

目标：把 TradeLogger 从“特殊 observer”还原成“通过显式接口接入的 observer 扩展”。

任务：

  1. 梳理 Strategy 对 TradeLogger 的直接识别和专属通知路径。

  2. 提炼 observer 事件接口，避免通过类名字符串做特殊分支。

  3. 将日志、监控、阈值告警等运行时能力下沉到独立适配层。

  4. 保持现有 TradeLogger 对外 API 不破坏，必要时通过 shim 兼容旧路径。

交付物：

  • Observer 事件接口设计

  • TradeLogger 解耦实施方案

  • 兼容性回归测试

5.3 工作流 C：工具链与发布元数据修复

优先级：P0

目标：让质量工具和发布口径重新可信。

任务：

  1. 修复 tools/doc_coverage_scanner.py 的报告生成异常。

  2. 修正文档覆盖统计逻辑，保证模块、类、函数、方法口径准确。

  3. 统一 README、setup.py、CI、类型检查中的 Python 版本描述。

  4. 统一许可证声明，消除 GPL 与 MIT classifier 冲突。

  5. 明确 requirements.txt、setup.py、开发依赖之间的职责边界，减少多源维护漂移。

交付物：

  • 可运行的文档覆盖报告工具

  • 一致的发布元数据

  • 工具链基线检查清单

5.4 工作流 D：测试矩阵与仓库资产治理

优先级：P1

目标：缩短反馈链路，同时控制仓库膨胀。

任务：

  1. 将 CI 拆分为 PR 快速矩阵与夜间/手动全矩阵。

  2. 明确 smoke / core / full / docs 四层验证策略。

  3. 清理 examples/output/ 这类生成产物的版本管理策略。

  4. 盘点大体量测试数据，标注“核心保留 / 可压缩 / 可外置 / 可生成”。

  5. 建立新增大文件的准入规则和审查标准。

交付物：

  • 分层 CI 方案

  • 仓库资产治理清单

  • 大文件与生成物管理规范

6. 里程碑

Milestone 1：基线固化（1 周）

  • 完成问题审计与优先级分级

  • 修复文档覆盖扫描工具

  • 确认 README / setup / CI 元数据差异清单

Milestone 2：关键路径收敛（1~2 周）

  • 关闭 cerebro.py / bbroker.py / feed.py 中的 P0 问题

  • 补齐关键回归测试

  • 输出运行链语义说明

Milestone 3：边界解耦（1 周）

  • 完成 TradeLogger 相关通知链梳理

  • 引入显式 observer 事件接口或适配层

  • 保证现有日志功能兼容

Milestone 4：工程治理落地（1 周）

  • CI 分层方案生效

  • 生成产物和大文件治理规则落地

  • 形成下一轮迭代的可度量基线

7. 验收标准

7.1 稳定性验收

  1. 本轮纳入范围的关键 TODO / FIXME 均有结论，不保留“含义未知但继续放着”的状态。

  2. 关键运行链改动必须具备回归测试覆盖。

  3. TradeLogger 相关运行时测试全部通过。

7.2 工程化验收

  1. tools/doc_coverage_scanner.py 可稳定输出报告文件。

  2. README、CI、包元数据中的 Python 版本与许可证信息保持一致。

  3. CI 至少形成一套“快速反馈”路径，PR 不再默认跑全部 18 组全量矩阵。

7.3 仓库治理验收

  1. examples/output/ 等生成产物有明确的版本管理结论。

  2. 大文件清单完成分级，并给出后续迁移策略。

  3. 新增资产准入规则形成文档并纳入评审要求。

8. 风险与应对

风险

影响

应对

清理历史分支时引入行为回归

核心回测结果变化

先补测试，再动逻辑；对关键策略建立基线对比

TradeLogger 解耦破坏现有用户用法

日志功能不可用

保留旧 API，先引入适配层，再逐步迁移

CI 分层后出现“快测通过，慢测失败”

质量信号延迟暴露

保留夜间/手动全矩阵，并将失败结果回灌到 PR 模板

大文件治理牵涉历史数据依赖

测试/示例不可复现

先做分级和替代方案，不一次性删除

9. 建议的执行顺序

  1. 先修工具链和元数据一致性，建立可信基线。

  2. 再处理 cerebro / bbroker / feed 等关键路径遗留项。

  3. 然后做 observer/logging 解耦，减少后续侵入式改动。

  4. 最后推进 CI 分层和仓库资产治理，将本轮成果制度化。

10. 本轮完成后的预期收益

完成本轮后，项目会得到以下直接收益：

  • 核心运行链更可读、更可测；

  • 日志与监控能力不再持续侵入策略主链；

  • 文档和发布信息对外口径一致；

  • PR 反馈速度和仓库治理质量都有明确改善；

  • 为后续性能优化、实盘接入和新功能迭代提供更稳的工程基础。