HFT-Python

基于 Listener 树形架构的全异步高频交易策略框架。

架构概览

所有组件继承 Listener，形成统一生命周期的树形结构：

AppCore (根节点)
├── UnhealthyRestartListener           # 不健康自动重启
├── StateLogListener                   # 状态日志输出
│
├── ExchangeGroup                      # 交易所分组管理
│   └── BaseExchange                   # 单个交易所实例（OKX / Binance / Simulated）
│       ├── ExchangeStateListener           # 余额快照写入数据库
│       ├── ExchangePositionListener        # 持仓监控（仅合约）
│       ├── ExchangeFundingRateBillListener  # 资金费率账单（仅合约）
│       ├── ExchangeBalanceListener         # 余额监控
│       └── ExchangeOrderBillListener       # 订单状态监控
│
├── ScopeManager                       # Scope 作用域管理（变量继承、层级求值）
│
├── IndicatorGroup                     # 指标管理（扁平结构，所有指标为直接子节点）
│   ├── GlobalExchangeFundingRateIndicator   # ExchangeClass 级别批量数据
│   ├── FundingRateIndicator                 # TradingPairClass 级别（从 Global 读取）
│   ├── TickerDataSource                     # WebSocket 实时行情
│   ├── OrderBookDataSource                  # WebSocket 盘口
│   └── [ComputedIndicators...]              # 计算型指标（基差、公允价格、曲线拟合等）
│
├── BaseStrategy               # 策略（StaticPositionsStrategy / MarketNeutralPositionsStrategy）
│
└── BaseExecutor               # 执行器（DefaultExecutor，数据驱动）

类继承链

Pickleable → Node → Listener → [AppCore, BaseExchange, BaseIndicator, BaseStrategy, BaseExecutor, ...]

• Pickleable：__getstate__/__setstate__ + initialize() 恢复
• Node：父子树结构，class-indexed 查找
• Listener：生命周期（open/close/tick）、后台任务、健康检查

Listener 状态由布尔属性组合表示：enabled、running、ready、healthy、finished。

核心设计

数据驱动执行

Exchange → DataSource.on_tick() → HealthyDataArray
                                       ↓
                              Indicator.get_vars() → Context Variables
                                       ↓
                              Strategy (flow 表达式求值) → 目标仓位
                                       ↓
                              Executor (表达式驱动) → Orders

• Indicator 统一架构：DataSource 是特殊的 Indicator，统一通过 IndicatorGroup 管理
• 表达式求值：VirtualMachine 基于 simpleeval，安全函数白名单
• 组合模式：Strategy 定义目标 + Executor 定义执行方式，自由组合

Scope 系统

分层变量作用域，支持层级化的数据流和聚合计算：

GlobalScope → ExchangeClassScope → ExchangeScope → TradingPairClassGroupScope → TradingPairClassScope → TradingPairScope

策略和执行器通过 YAML flow: 配置定义计算流程，每个 Phase 可以：

• 加载 Indicator（requires）
• 计算变量（vars）
• 过滤节点（filter / condition）
• 排序（sorted_var）

配置系统

conf/
├── app/           # 应用配置（入口）
├── exchange/      # 交易所配置（API 密钥、代理等）
├── strategy/      # 策略配置（flow 定义、参数）
└── executor/      # 执行器配置（下单逻辑、表达式）

• Pydantic 模型，从 YAML 加载
• BaseConfigPath 提供惰性加载 + 缓存
• Indicator 在 app config 中内联定义

持久化

• Listener 树通过 pickle 序列化，__pickle_excludes__ 排除不可序列化字段
• initialize() 在 pickle 恢复时重建运行时状态
• AppFactory.get_or_create() 实现"有缓存恢复，无缓存新建"语义

交易所支持

类型	实现	用途
真实交易所	hft/exchange/okx/, hft/exchange/binance/	生产环境
模拟交易所	hft/exchange/simulated/	回测、策略验证
Mock 交易所	tests/demo/mock_exchange.py	单元测试、性能测试

策略

策略	说明
StaticPositionsStrategy	静态目标仓位，维持配置的持仓量
MarketNeutralPositionsStrategy	市场中性套利，跨交易所 funding rate 对冲

快速开始

# 安装依赖
pip install -r requirements.txt

# 运行（指定 app 配置名 和 策略配置名）
hft run main app

# 调试模式（不下单）
hft -p null run main app

# 数据预热（收集 funding rate / mark price / index price）
hft --log-file -p null run main warmup

# 测试
pytest                    # 单元测试
pytest -m ""              # 全部测试（含集成）
pytest -m integration     # 仅集成测试

项目结构

hft/
├── core/               # 核心：Listener、Node、Pickleable、Scope、App
├── config/             # 配置系统：Pydantic 模型、路径解析、加密
├── exchange/           # 交易所：BaseExchange、OKX、Binance、Simulated
├── indicator/          # 指标：DataSource + Computed，统一 BaseIndicator
├── strategy/           # 策略：BaseStrategy、StaticPositions、MarketNeutral
├── executor/           # 执行器：BaseExecutor、DefaultExecutor
├── database/           # 数据库：ClickHouse 客户端和控制器
└── plugin/             # 插件系统：pluggy hooks

conf/                   # YAML 配置文件
tests/                  # pytest 测试

文档

• 代码级文档：各模块的 docstring（Google 风格）
• AI 辅助指南：CLAUDE.md（包含架构细节、测试命令、调试方法、实盘验证清单）