AKQuant 设计与开发指南¶

本文档详细介绍了 AKQuant 的内部设计原理、核心组件架构以及扩展开发指南。旨在帮助开发者深入理解项目结构，以便进行二次开发和功能扩展。本文属于 internal 文档，面向实现细节，不作为公开 API 命名规范来源。

1. 项目概览¶

1.1 设计理念¶

AKQuant 遵循以下核心设计原则：

核心计算下沉 (Rust Core): 所有的计算密集型任务（事件循环、订单撮合、风控检查、数据管理、绩效计算、历史数据维护）都在 Rust 层实现，以确保高性能和内存安全。
策略逻辑上浮 (Python API): 策略编写、参数配置、数据分析、机器学习模型定义等用户交互层保留在 Python 中，利用其动态特性和丰富的生态系统 (Pandas, Scikit-learn, PyTorch 等)。
模块化与解耦 (Modularity): 借鉴成熟的量化框架设计，将数据、执行、策略、风控、机器学习等模块严格分离，通过清晰的接口（Traits）交互。

1.2 项目目录结构¶

akquant/
├── Cargo.toml              # Rust 项目依赖与配置
├── pyproject.toml          # Python 项目构建配置 (Maturin)
├── Makefile                # 项目管理命令
├── src/                    # Rust 核心源码 (底层实现)
│   ├── lib.rs              # PyO3 模块入口，注册 Python 模块
│   ├── engine/             # 回测引擎模块
│   │   ├── core.rs         # 核心引擎：驱动时间轴与事件循环
│   │   ├── state.rs        # 引擎状态管理
│   │   └── python.rs       # Python 绑定
│   ├── execution/          # 执行层：模拟交易所撮合逻辑
│   │   ├── matcher.rs      # 撮合器 Trait 定义
│   │   ├── simulated.rs    # 模拟执行客户端
│   │   ├── realtime.rs     # 实盘执行客户端
│   │   └── slippage.rs     # 滑点模型
│   ├── market/             # 市场层：定义费率、T+1 规则、交易时段
│   │   ├── china.rs        # 中国市场规则 (A股/期货)
│   │   ├── simple.rs       # 简单市场规则 (7x24, T+0)
│   │   └── stock.rs/futures.rs # 具体资产逻辑
│   ├── portfolio.rs        # 账户层：管理资金、持仓与可用头寸
│   ├── data/               # 数据层：管理 Bar/Tick 数据流
│   │   ├── feed.rs         # 数据源
│   │   └── aggregator.rs   # K线合成器
│   ├── analysis/           # 分析层：计算绩效指标 (Sharpe, Drawdown)
│   ├── context.rs          # 上下文：用于 Python 回调的数据快照
│   ├── clock.rs            # 时钟模块：统一时间管理
│   ├── event.rs            # 事件系统：定义系统内部事件
│   ├── history.rs          # 历史数据：高效的环形缓冲区管理
│   ├── indicators.rs       # 技术指标：Rust 原生指标实现 (如 SMA)
│   └── model/              # 数据模型：定义基础数据结构
│       ├── mod.rs          # 模型模块定义
│       ├── order.rs        # 订单 (Order) 与成交 (Trade)
│       ├── instrument.rs   # 标的物信息 (Instrument)
│       ├── market_data.rs  # 市场数据 (Bar, Tick)
│       ├── timer.rs        # 定时器事件
│       └── types.rs        # 基础枚举 (Side, Type, PriceBasis/TemporalPolicy)
├── python/
│   └── akquant/            # Python 包源码 (用户接口)
│       ├── __init__.py     # 导出公共 API
│       ├── strategy.py     # Strategy 基类：封装上下文，提供 ML 训练与交易接口
│       ├── backtest/       # 回测结果处理
│       │   ├── engine.py   # 高级入口 run_backtest
│       │   └── result.py   # BacktestResult 分析与 DataFrame 转换
│       ├── config.py       # 配置定义：BacktestConfig, StrategyConfig, RiskConfig
│       ├── risk.py         # 风控配置适配层
│       ├── data.py         # 数据加载与目录服务 (DataCatalog)
│       ├── sizer.py        # Sizer 基类：提供多种仓位管理实现
│       ├── indicator.py    # Python 指标接口
│       ├── optimize.py     # 参数优化工具
│       ├── plot/           # 绘图工具包
│       ├── log.py          # 日志模块
│       ├── utils/          # 工具函数
│       ├── ml/             # 机器学习框架
│       │   ├── __init__.py
│       │   └── model.py    # QuantModel, SklearnAdapter, ValidationConfig
│       └── akquant.pyi     # 类型提示文件 (IDE 补全支持)
├── tests/                  # 测试用例
└── examples/               # 示例代码
    ├── 01_quickstart.py    # 快速上手
    ├── 09_ml_framework.py  # ML 框架基础示例
    └── ...                 # 其他示例

2. 核心组件架构详解¶

2.1 数据模型层 (`src/model/`)¶

为了保证跨语言交互的性能与类型安全，核心数据结构均在 Rust 中定义并导出。

types.rs:
- ExecutionPolicyCore:
  - price_basis: open / close / ohlc4 / hl2。
  - bar_offset: 0 / 1。
  - temporal: same_cycle / next_event。
- OrderSide: Buy / Sell。
- OrderType: Market (市价), Limit (限价), StopMarket (止损市价), StopLimit (止损限价)。
- TimeInForce: Day (当日有效), GTC (撤前有效), IOC/FOK。
- AssetType: Stock, Fund, Futures, Option, Crypto, Forex。
instrument.rs: Instrument 包含 multiplier (合约乘数), tick_size, margin_ratio 等。
market_data.rs: Bar (OHLCV) 和 Tick (最新价/量)。

2.3 市场数据处理与公司行为¶

AKQuant 在数据处理阶段集成了高级的市场特性支持：

数据对齐 (Data Alignment):
- 在 src/pipeline/stages.rs 的 DataProcessor 中实现。
- Late Fill Strategy: 当检测到某个标的数据缺失（如停牌）时，自动使用上一时刻的收盘价生成合成 K 线，成交量设为 0。
- 这保证了多标的回测时时间轴的严格对齐，方便进行矩阵运算。
公司行为 (Corporate Actions):
- 在 src/market/corporate_action.rs 的 CorporateActionManager 中实现。
- 支持 Split (拆股): 自动调整持仓数量 (quantity *= ratio) 和可用持仓。
- 支持 Dividend (分红): 自动增加账户现金 (cash += quantity * dividend_per_share)。
- 处理逻辑集成在每日数据更新流程中，确保在正确的除权除息日生效。

2.4 执行层 (`src/execution/`)¶

执行层负责处理订单的生命周期，包括验证、撮合和生成成交报告。

2.2.1 模拟执行 (`simulated.rs`)¶

订单队列: 维护一个 order_queue，确保订单按照提交时间的先后顺序进行处理。
资产分发: 根据 Instrument 的 asset_type，将订单分发给不同的 ExecutionMatcher (如 StockMatcher, FuturesMatcher, CryptoMatcher, ForexMatcher)。
动态风控: 在成交前一刻再次检查账户资金（Free Margin）。如果资金不足，会自动削减订单数量 (Partial Fill) 而不是直接拒单，这在资金利用率高的策略中非常有用。

2.2.2 股票撮合器 (`StockMatcher`)¶

StockMatcher 实现了高精度的撮合逻辑，以模拟真实交易所行为：

穿透检查 (Penetration Check):
- 限价买单: 只有当 Bar.Low <= Limit Price 时才成交。
- 限价卖单: 只有当 Bar.High >= Limit Price 时才成交。
价格改善 (Price Improvement):
- 如果买单限价 10.00，但市场开盘价为 9.80（低开），则以 9.80 成交。
- 遵循“以更有利的价格成交”原则。
止损单逻辑 (Stop Order):
- 跳空触发 (Gap Trigger): 如果开盘价直接跳过触发价（如止损卖单触发价 10.0，开盘 9.5），则以开盘价 9.5 成交。
- Bar 内触发 (In-Bar Trigger): 如果触发价在 High/Low 范围内，且未发生跳空，则以触发价成交（模拟触价即发）。
停牌检查:
- 如果 Bar.Volume <= 0，则视为停牌，不进行任何撮合。

2.2.3 加密货币与外汇撮合器 (`CryptoMatcher` & `ForexMatcher`)¶

这些撮合器复用了通用的撮合逻辑 (CommonMatcher)，但针对各自市场特性进行了调整：

7x24小时交易: 不受传统市场收盘限制。
小数位支持: 允许非整数数量的成交 (Fractional Trading)。
费率计算: 支持按成交金额比例计算手续费。

2.3 市场层 (`src/market/`)¶

ExecutionClient Trait 定义了执行层的标准接口，支持模拟和实盘的无缝切换。

SimulatedExecutionClient (simulated.rs):
- 负责回测时的订单撮合。
- 内置 ExecutionMatcher，支持多种撮合逻辑。
- 滑点模型 (slippage.rs): 支持 FixedSlippage (固定金额) 和 PercentSlippage (百分比)。
撮合机制 (matcher.rs):
- 限价单 (Limit): 买入需 Low <= Price，卖出需 High >= Price。
- 市价单 (Market): 根据三轴 fill_policy 决定成交价格与时序。
- 触发机制: 支持 trigger_price (止损/止盈单)。

2.3 市场规则层 (`src/market/`)¶

通过 MarketModel Trait 实现不同市场的规则隔离。

ChinaMarket (china.rs):
- 实现 A 股和国内期货的市场规则。
- 交易时段: 支持集合竞价 (CallAuction)、连续竞价 (Continuous)、休市 (Break) 等状态管理。
- 费率计算: 支持股票 (印花税、过户费、佣金) 和期货 (按手或按金额)。
- T+1/T+0: 严格的可用持仓管理 (昨仓/今仓)。
SimpleMarket (simple.rs):
- 7x24 小时交易，T+0，无税，适用于加密货币或外汇回测。

2.4 风控层 (`src/risk/`)¶

RiskManager 独立于执行层，拦截每一笔订单：

检查规则: 限制名单、最大单笔数量/金额、最大持仓比例。
配置: Python 端 RiskConfig 自动注入 Rust 引擎。
支持针对不同资产类型 (Stock/Futures/Option/Crypto/Forex) 的特定风控规则。

2.5 账户层 (`src/portfolio.rs`)¶

Portfolio 结构体维护账户状态：

cash: 可用资金。
positions: 总持仓。
available_positions: 可卖持仓 (T+1 逻辑的核心)。
权益计算: 实时 Mark-to-Market 计算。

2.6 引擎层 (`src/engine/` & `src/history.rs`)¶

Engine 是系统的驱动器：

事件循环: 消费 Bar 或 Tick 事件。
历史数据管理: Engine 内部维护 History 模块，这是一个高效的环形缓冲区，用于存储最近 N 个 Bar 的数据，供策略通过 get_history 快速访问，无需在 Python 端累积数据。
日切处理: 触发 T+1 解锁、过期订单清理、公司行为处理 (分红/拆股)。

2.7 分析层 (`src/analysis/`)¶

遵循标准 PnL 计算：Gross PnL (毛利), Net PnL (净利), Commission (佣金)。 BacktestResult 包含详细的绩效指标 (PerformanceMetrics) 和交易记录 (ClosedTrade)。

2.8 Python 抽象层 (`python/akquant/`)¶

Strategy (strategy.py):
- 历史数据访问:
  - set_history_depth(depth): 开启 Rust 端历史数据记录。
  - get_history(count) / get_history_df(count): 获取最近 N 个 Bar 的 OHLCV 数据 (Numpy/DataFrame)。
- ML 集成:
  - set_rolling_window(train, step): 配置滚动训练参数。
  - on_train_signal(context): 周期性触发模型训练。
  - prepare_features(df): 特征工程接口。
run_backtest (backtest/engine.py): 高级入口函数，统一处理配置注入、策略实例化和引擎启动。
BacktestResult (backtest/result.py):
- 封装 Rust 返回的 BacktestResult。
- 提供 metrics_df, positions 等便捷属性。
- 支持 plot() 方法直接生成分析图表。

2.9 机器学习框架 (`python/akquant/ml/`)¶

AKQuant 提供了一套标准化的 ML 接口，旨在简化“滚动训练-预测”流程。

QuantModel (model.py):
- 所有模型的抽象基类。
- 接口: fit(X, y), predict(X), save(path), load(path)。
- set_validation: 配置 Walk-forward Validation 参数 (训练窗口、测试窗口、滚动步长)。
SklearnAdapter:
- 封装 Scikit-learn 风格的模型 (如 RandomForest, LinearRegression)，使其适配 QuantModel 接口。

2.10 公司行为处理模块 (`src/market/corporate_action.rs`)¶

负责处理除权除息 (Ex-Rights/Ex-Dividend) 逻辑：

拆股 (Split):
- 调整持仓数量：Quantity *= Ratio。
- 调整平均成本：AvgCost /= Ratio。
- 保持总市值 (Market Value) 不变。
分红 (Dividend):
- 增加账户现金：Cash += Quantity * DividendPerShare。
触发时机: 在每日日切 (Day Switch) 时，检查当日是否有公司行为并执行。

3. 关键工作流详解¶

3.1 回测主循环与三轴执行语义¶

Engine::run 的流程依赖三轴执行语义：

price_basis + bar_offset: 决定使用当前/下一根 Bar 的 open/close/ohlc4/hl2 价格基准。
temporal: 控制 timer 订单在当前周期或下一事件撮合。

3.2 订单全生命周期¶

Signal -> Creation -> Submission -> Risk Check (Rust) -> Matching (Rust) -> Settlement (Rust) -> Reporting。

4. 扩展开发指南¶

4.1 如何添加新的订单类型¶

src/model/types.rs: 添加枚举。
src/model/order.rs: 更新结构体。
src/execution/matcher.rs: 实现撮合逻辑。
akquant.pyi: 更新类型提示。

4.2 如何自定义指标¶

Python 侧 (快速原型): 继承 akquant.Indicator，在 on_bar 中计算。
Rust 侧 (高性能):
- 在 src/indicators.rs 中实现 Indicator Trait。
- 通过 #[pyclass] 导出到 Python。

4.3 如何接入新的数据源¶

将数据转换为 pandas DataFrame，构造 akquant.Bar 对象列表，调用 engine.add_feed 即可。

5. Rust 与 Python 交互注意事项¶

GIL: Rust 仅在回调 Python 时获取 GIL，计算密集型任务释放 GIL (视实现而定，目前主要是单线程模型)。
数据拷贝: 尽量减少 Python 与 Rust 之间的大规模数据传输。get_history 返回的是 Numpy 视图或拷贝，效率远高于 Python list。

AKQuant 设计与开发指南¶

1. 项目概览¶

1.1 设计理念¶

1.2 项目目录结构¶

2. 核心组件架构详解¶

2.1 数据模型层 (src/model/)¶

2.3 市场数据处理与公司行为¶

2.4 执行层 (src/execution/)¶

2.2.1 模拟执行 (simulated.rs)¶

2.2.2 股票撮合器 (StockMatcher)¶

2.2.3 加密货币与外汇撮合器 (CryptoMatcher & ForexMatcher)¶

2.3 市场层 (src/market/)¶

2.3 市场规则层 (src/market/)¶

2.4 风控层 (src/risk/)¶

2.5 账户层 (src/portfolio.rs)¶

2.6 引擎层 (src/engine/ & src/history.rs)¶

2.7 分析层 (src/analysis/)¶

2.8 Python 抽象层 (python/akquant/)¶

2.9 机器学习框架 (python/akquant/ml/)¶

2.10 公司行为处理模块 (src/market/corporate_action.rs)¶