RQAlpha 项目研究站 · Mod 扩展体系

RQAlpha Mod 扩展：系统 Mod 列表与自定义 Mod 开发

本项目的扩展方式是 Mod：撮合、风控、税费、账户、分析输出、调度、进度条都是可启停的 Mod，官方文档明确建议「不要在 RQAlpha 项目里直接改，而是把 Mod 作为独立项目开发」。更进阶的用法是通过 register_api 给框架加自己的 API——内置的 FuncatAPIMod 就把通达信/同花顺的公式表达能力搬到了 Python 里。

下一步：回测指标回看运行参数

系统 Mod：7 个启停：rqalpha mod list/enable/disable依据官方 mod 文档（2026-09 核验）

账户与撮合
sys_accounts/simulation

风控与税费
sys_risk/transaction_cost

调度与进度
sys_scheduler/progress

分析输出
sys_analyser

依据官方 Mod 列表整理的模块分层示意；非官方架构图。

System mods

七个系统 Mod 各管什么

来自官方 README 与 index 文档的 Mod 列表，默认在 mod_config.yml 中全部启用。

Mod	职责	你会用到它的场景
`sys_accounts`	股票与期货的下单 API 实现、持仓模型、股票分红退市等行为控制	控制卖空、资金不足时是否自动使用剩余资金下单
`sys_simulation`	模拟撮合引擎与回测事件源，支撑回测与模拟交易	切换撮合引擎、设置滑点与手续费乘数、信号模式
`sys_risk`	对订单做事前风控校验	回测里模拟「下单前被风控拦下」的情形
`sys_transaction_cost`	股票与期货的交易税费计算逻辑	评估费用对策略收益的侵蚀；自定义合约费率
`sys_analyser`	记录每日下单、成交、组合、持仓，计算风险指标并输出 CSV / 图表	决定结果输出到哪、是否画图、基准怎么设
`sys_scheduler`	提供定时器：按特定周期执行指定逻辑	周频/月频调仓，不必自己在 `handle_bar` 里判断日期
`sys_progress`	在控制台输出回测进度条	长周期回测时判断「还在跑」还是「卡住了」

默认状态：仓库里的 rqalpha/mod_config.yml 顶部写着「WARNING: DO NOT EDIT」，七个系统 Mod 均为 enabled: true；要改行为，请用命令行 -mc 或用户配置文件，而不是改这个文件。

CLI

Mod 的查看、启停与传参

三条命令 + 一种传参方式，覆盖日常使用。

常用操作

1. rqalpha mod list 查看当前已安装的 Mod 及启用状态；
2. rqalpha mod enable xxx 启用某个 Mod（如第三方数据 Mod）；
3. rqalpha mod disable xxx 禁用；
4. 运行策略时用 -mc 传该 Mod 的配置项，例如官方示例：rqalpha run -rt p -fq 1m -f strategy.py --account stock 100000 -mc sys_accounts.auto_switch_order_value True。

配置位置	写法	优先级与注意点
命令行	`-mc mod_name.key value`（可多个）	临时试参数最方便；优先级低于策略内配置
用户配置文件	`config.yml` 的 `mod:` 段	适合长期固定；注意 `generate-config` 生成的模板不包含 Mod 配置项
代码调用	`run_file(strategy, {"mod": {"sys_analyser": {...}}})`	适合参数扫描：每次运行生成不同的 mod 配置

看运行参数与优先级

Build a mod

写自己的 Mod：标准结构与关键接口

官方 mod 文档用 rqalpha-mod-hello 做最小示例，结构固定、可照抄。

组成	内容	说明
项目命名	仓库/包名 `rqalpha-mod-<name>`，Python 包名 `rqalpha_mod_<name>`	官方推荐 Mod 作为独立项目开发，不改框架源码
`__init__.py`	定义 `__config__` 默认配置 + `load_mod()` 返回 Mod 实例	`load_mod` 是框架加载入口，返回你的 Mod 类实例
`mod.py`	继承 `AbstractMod`，实现 `start_up(env, mod_config)` 与 `tear_down(success, exception=None)`	start_up 里做注册与监听，tear_down 做收尾
自定义组合（Portfolio）	在 `start_up` 中监听 `EVENT.INIT_PORTFOLIO`，用 `env.set_portfolio()` 注册	官方说明该事件在数据源与 Broker 初始化完成后触发；注册后框架不再创建默认组合
扩展 API	在 `start_up` 中用 `register_api` 注册新 API	官方内置 `FuncatAPIMod` 用这种方式把通达信/同花顺公式表达能力搬进 Python
打包安装	写 `setup.py`、`VERSION.txt`、`requirements.txt`，然后 `pip install -e .`	开发态安装便于改代码即时生效

已存在的外部 Mod（官方文档提及）：rqalpha-mod-tushare（用 Tushare 数据）、rqalpha_mod_sys_stock_realtime（股票实时数据）等；官方也欢迎把自研 Mod 提交进列表，但发布需要遵守约定的格式。

Checklist

要不要写 Mod：四个判断

Mod 是设计给「替换框架行为」的，不是所有个性化需求都值得写。

该写 Mod

要换数据源、事件源、撮合与风控规则，或给框架加通用 API。

不必写 Mod

只是改参数（滑点、费率、基准、日志）——用 -mc 或配置文件即可。

先看现成的

先 rqalpha mod list 看看是否已有系统 Mod 覆盖；再查生态里是否已有第三方 Mod。

注意维护成本

Mod 与框架版本耦合，升级 RQAlpha 后需要回归测试；接口变更以官方文档为准。

下一步：回测指标

Troubleshooting

Mod 相关排查表

Mod 的问题多半是「加载顺序/启用状态/配置层级」三类。

现象	原因	处理
`rqalpha mod enable` 后没生效	Mod 未安装成功，或名称写错（命令里用的是 mod 名，不含 rqalpha-mod- 前缀）	先 `rqalpha mod list` 确认在列表里；再看是否 enabled
`pip install -e .` 失败	setup.py 与 requirements.txt 不匹配，或 pip 版本导致 parse_requirements 报错	按官方示例处理 pip 兼容分支；确认在 Mod 项目目录内执行
自定义 Portfolio 后回测报错	自定义实现与框架 Portfolio 接口不兼容	继承官方 Portfolio 类再覆写；通过 `EVENT.INIT_PORTFOLIO` 注册而不是手工 new
注册的 API 在策略里找不到	注册发生在 start_up 之前/之后时机不对，或策略未使用 `from rqalpha.api import *`	在 `start_up` 内注册；确认导入方式与官方示例一致
配置项写了不生效	与参数优先级冲突（策略内 > 命令行 > 配置文件 > 默认）	按优先级逐层排查，见运行策略页
升级框架后 Mod 失效	接口或事件名变化	对照目标版本的官方文档修正；锁定版本后再升

FAQ

常见问题

Mod 和插件有什么区别？

在这套体系里 Mod 就是插件：以独立 PyPI 包发布，通过 load_mod() 被框架加载，能替换账户、撮合、数据源、事件源等核心部件，也能注册新 API。区别在于它更贴近框架内部接口，能力大、耦合也更深。

可以直接改 RQAlpha 源码吗？

技术上可以，但官方文档明确不建议：建议把 Mod 作为独立项目开发。直接改源码会让后续升级与协作变困难。

能否用 Mod 接入自己的行情数据？

可以，这正是 Mod + 数据层接口的典型用途：实现数据源/事件源接口后用 Mod 注册接管。官方文档的 development 章节（data_source / event_source）给出了接口说明。

系统 Mod 可以关掉吗？

可以（mod disable），但要清楚后果：例如关掉 sys_analyser 就没有指标输出，关掉 sys_simulation 就没有撮合。除非你在做底层替换，否则建议保持默认全开。

FuncatAPIMod 提供什么？

官方描述为「将通达信、同花顺的公式表达能力移植到 Python」，是内置 Mod 中通过 register_api 扩展 API 的实例。若你熟悉通达信公式，可研究它的实现方式来减少改写成本。

写 Mod 能商用吗？

注意框架本身的许可边界：非商业用途按 Apache 2.0，商业用途需要米筐科技授权；自研 Mod 的许可由你自己决定，但调用框架的部分仍受其许可约束。详见许可与数据边界页。