ssquant: 专业的期货CTP量化交易框架

代码拉取完成,页面将自动刷新

扫描微信二维码支付

取消

支付完成

richgiteeai

Watch

不关注关注所有动态仅关注版本发行动态关注但不提醒动态

1 Star 0 Fork 31

cdma669/ssquant

forked from 松鼠Quant/ssquant

代码 Issues 0 Pull Requests 0 Wiki 统计流水线

服务

加入 Gitee

与超过 1400万开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)

免费加入

已有帐号? 立即登录

克隆/下载

HTTPS SSH SVN SVN+SSH 下载ZIP

提示

下载代码请复制以下命令到终端执行

为确保你提交的代码身份被 Gitee 正确识别,请执行以下命令完成配置

git config --global user.name userName 
git config --global user.email userEmail

初次使用 SSH 协议进行代码克隆、推送等操作时,需按下述提示完成 SSH 配置

1 生成 RSA 密钥

2 获取 RSA 公钥内容,并配置到 SSH公钥中

在 Gitee 上使用 SVN,请访问使用指南

使用 HTTPS 协议时,命令行会出现如下账号密码验证步骤。基于安全考虑,Gitee 建议配置并使用私人令牌替代登录密码进行克隆、推送等操作

Username for 'https://gitee.com': userName

Password for 'https://userName@gitee.com': # 私人令牌

新建文件新建 Diagram 文件

新建子模块

上传文件

分支 1

标签 4

贡献代码

同步代码

创建 Pull Request

了解更多

对比差异通过 Pull Request 同步

同步更新到分支

通过 Pull Request 同步

将会在向当前分支创建一个 Pull
Request,合入后将完成同步

松鼠Quant release: SSQuant v0.4.4 - backtest stats, ... 429d73c

41 次提交

.claude/skills

ai_agent

examples

ssquant

.gitignore

042.MD

043.MD

AGENTS.md

API参考手册.md

LICENSE

MANIFEST.in

README.md

pyproject.toml

requirements.txt

setup.py

文档导航.md

用户手册.md

README

未知许可证

# SSQuant - 期货量化交易框架

🐿️ **松鼠Quant** | 专业的期货CTP量化交易框架
<img width="728" height="352" alt="image" src="https://github.com/user-attachments/assets/26201b06-0992-44dd-8416-03edcbb8878b" />

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Non--Commercial-red.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux-lightgrey.svg)]()
[![当前版本](https://img.shields.io/badge/当前版本-0.4.4-brightgreen.svg)](更新日志_v0.4.4.md)

[GitHub](https://github.com/songshuquant/ssquant) | [Gitee(国内推荐)](https://gitee.com/ssquant/ssquant)

**一次编写,三处运行** - 回测 / SIMNOW模拟 / 实盘CTP

</div>

---

## 🤖 AI Agent.SKILLS 技能集成

SSQuant 内置了 [SKILL.md](https://github.com/anthropics/skill-md) 开放标准的 AI 智能体技能,支持 Claude Code、Cursor、Codex、Gemini CLI 等 AI 编程助手 **直接理解并操作** SSQuant 框架。

| 技能 | 路径 | 能力 |
|------|------|------|
| **策略编写** | `.claude/skills/ssquant-strategy/` | 编写符合框架规范的期货策略,包含 API 参考和示例 |
| **回测验证** | `.claude/skills/ssquant-backtest/` | 配置回测参数、执行回测、参数优化 |
| **部署上线** | `.claude/skills/ssquant-deploy/` | SIMNOW 仿真 → 实盘部署全流程 |
| **问题诊断** | `.claude/skills/ssquant-debug/` | 排查 CTP 连接、数据、策略、交易异常 |
| **数据查询** | `.claude/skills/ssquant-data/` | 行情、持仓、账户、订单流数据查询 |

在支持 SKILL.md 的 AI 编程助手中打开 SSQuant 项目,即可通过自然语言完成策略编写、回测、部署、调试全流程。项目级 AI 上下文见 [AGENTS.md](AGENTS.md)。

---

## 🎯 核心特性

### ✅ 统一的策略框架

- **一套代码三处运行** - 同一份策略代码可在回测、SIMNOW模拟、实盘CTP三种环境下运行
- **完整的数据支持** - K线数据(任意周期:1m/2m/5m/15m/30m/1h/4h/1d...)+ TICK逐笔数据
- **多品种多周期** - 同时交易多个品种,使用不同周期数据
- **跨平台支持** - 支持 Windows 和 Linux (x86_64) 系统

### ✅ 强大的交易功能

- **自动开平仓管理** - 智能识别开平仓、今昨仓,强平自动处理
- **智能算法交易** - 支持限价单排队、超时撤单、追价重发等高级逻辑
- **自动移仓引擎** - 主力合约换月时自动平旧开新,支持同时/顺序两种模式
- **实时回调系统** - on_trade/on_order/on_cancel 实时通知
- **TICK流双驱动** - K线驱动 + TICK驱动两种模式,data_server 模式实时推送深度数据K线
- **断线自动重连** - CTP连接断开后自动重连,认证失败自动重试,WebSocket 鉴权自动恢复
- **实盘抗压机制** - Tick 有界队列 + 水位控制 + 积压压缩 + 压力等级感知

### ✅ 灵活的数据获取

- **三种数据请求方式**:
 - 日期范围:`start_date` / `end_date`
 - 精确时间:`start_time` / `end_time`
 - K线数量:`limit`(获取最近N根K线)
- **本地K线派生** - 从1M自动派生任意周期(2M/7M/65M/120M等)
- **远程数据推送** - 支持 data_server WebSocket 实时K线推送
- **本地复权计算** - 支持前复权/后复权,基于合约切换点比例因子算法

### ✅ 回测引擎

- **资金约束** - 开仓按可用资金校验,待执行订单资金预占,资金不足自动裁剪手数
- **智能停止** - 资金耗尽且无持仓时提前终止回测,避免空跑
- **拒单可见** - 资金不足等关键信息即使 `debug=False` 也会在控制台显示

### ✅ 丰富的策略示例

- 24个完整策略示例,注释全面重写为用户友好风格
- 涵盖趋势、套利、轮动、期权、机器学习、自动移仓等类型
- 从入门到高级,循序渐进

---

## 📡 数据服务器

### 全新 data_server 架构

远程数据服务独立的 `data_server` 数据服务器:

| 功能 | 说明 |
|------|------|
| **实时K线推送** | WebSocket 实时推送K线,毫秒级延迟 |
| **历史K线补全** | 连接时自动预加载历史最新K线,无缝衔接 |
| **订单流数据** | 新增12个订单流字段,支持量价分析策略 |
| **多周期支持** | 服务端直接推送任意周期K线(1M/5M/15M/1H/1D等) |
| **断线自动重连** | 网络中断后自动重连并重新鉴权,数据不丢失 |
| **开盘假死修复** | data_server + Tick回调模式下智能节流,解决开盘积压 |

### 📊 订单流数据字段

新增完整的订单流数据支持,可用于量价分析、主力资金追踪等策略:

```python
# 订单流字段(K线数据中自动包含)
'开仓' # 总开仓量
'平仓' # 总平仓量
'多开' # 多头开仓
'空开' # 空头开仓
'多平' # 多头平仓
'空平' # 空头平仓
'双开' # 双开(多空同时开仓)
'双平' # 双平(多空同时平仓)
'双换' # 双换(换手)
'B' # 主买量(Buy)
'S' # 主卖量(Sell)
'未知' # 未知方向
```

### 🔄 实时K线推送模式

```python
config = get_config(
 mode=RunMode.SIMNOW,
 symbol='rb2601',
 kline_period='1m',
 kline_source='data_server', # 使用远程实时推送
)
```

**工作流程:**
1. 连接 data_server WebSocket 服务器
2. 自动预加载最近 N 根历史K线(可配置)
3. 实时接收订阅周期的K线推送(支持1M/5M/15M/30M/1H/1D等)
4. 无需本地聚合,服务端直接推送目标周期

---

## 🔄 自动移仓引擎(v0.4.3 新增)

主力合约换月时,框架自动完成移仓(平旧合约 → 开新主力),无需在策略里手写换月逻辑。

### 两种模式

| 模式 | 说明 |
|------|------|
| `simultaneous`(默认) | 同一次回调内平旧 + 开新,不等成交,速度更快 |
| `sequential` | 先平旧,旧腿平仓确认后再开新,更稳妥 |

### 使用方式

```python
config = get_config(
 mode=RunMode.SIMNOW,
 symbol='rb888', # 888 = 自动映射当前主力
 kline_period='15m',
 auto_roll_enabled=True, # 开启自动移仓
 auto_roll_reopen=True, # 平旧后自动在新主力开仓
 auto_roll_mode='simultaneous', # 移仓模式
)
```

### 策略内查询

```python
def strategy(api):
 if api.is_rollover_busy():
 return # 移仓进行中,暂停交易信号
 status = api.get_rollover_status()
```

> 仅 SIMNOW / 实盘生效,回测模式下不执行自动移仓。默认开启复盘日志(`./live_data/rollover_logs/`)。

---

## 📐 本地复权算法(v0.4.3 新增)

data_server 只存储不复权(raw)数据,复权计算在框架本地完成。

通过 `real_symbol` 列检测合约切换点,在切换点计算比例因子自动调整 OHLC 价格。

```python
from ssquant.data import get_futures_data

df = get_futures_data('au888', '1D', adjust_type='1', limit=300) # 后复权
df = get_futures_data('au888', '1D', adjust_type='2', limit=300) # 前复权
```

| 类型 | 参数 | 说明 |
|------|------|------|
| 不复权 | `adjust_type='0'` | 原始价格,默认 |
| 后复权 | `adjust_type='1'` | 最早数据保持原价,后续累积因子调整 |
| 前复权 | `adjust_type='2'` | 最新数据保持原价,历史数据反向调整 |

---

## 🖥️ 系统要求

| 项目 | 要求 |
|------|------|
| **操作系统** | Windows 10+ / Linux (x86_64) |
| **Python** | 3.9 ~ 3.14 |
| **CTP版本** | >=6.7.7 版本 |
| **内存** | 4GB+ |

---

## ⚡ 快速开始

### 1. 安装及更新

> ⚠️ **重要提示**:从 v0.4.3 起,**不再支持 `pip install ssquant` 安装和更新**。由于包含 CTP 二进制文件(.pyd/.dll/.so),包体积超过 PyPI 限制,必须通过 **Git 仓库** 或 **下载源码压缩包** 的方式安装。已通过 pip 安装的旧版本请先卸载:`pip uninstall ssquant`,然后按以下方式重新安装。

**方式一:Git 克隆 + 更新(推荐)**

如果你是通过 `git clone` 安装的,可以用以下命令更新到最新版本:

```bash
# 1. 进入项目目录
cd ssquant

# 2. 拉取最新代码
git pull origin main

# 3. 重新安装(更新依赖)
pip install -e .
```

**完整的首次克隆 + 安装流程:**

```bash
# GitHub
git clone https://github.com/songshuquant/ssquant.git
cd ssquant
pip install -e .

# 或 Gitee(国内推荐,速度更快)
git clone https://gitee.com/ssquant/ssquant.git
cd ssquant
pip install -e .
```

> 💡 **提示**:使用 `pip install -e .`(开发模式)安装后,`git pull` 拉取的代码更新会立即生效,无需重复安装。

**方式二:下载压缩包重新安装**

如果你是下载源码压缩包安装的,需要重新下载最新版本:

1. 从 [GitHub Releases](https://github.com/songshuquant/ssquant/releases) 或 [Gitee](https://gitee.com/ssquant/ssquant) 下载最新压缩包
2. 解压到新目录
3. 进入目录执行安装:

```bash
cd ssquant-main
pip install -e .
```

#### ❓ 常见问题:ModuleNotFoundError: No module named 'ssquant'

如果运行策略时遇到这个错误:

```
ModuleNotFoundError: No module named 'ssquant'
```

**原因**:ssquant 未安装或已被卸载。

**解决方法**:

1. 检查是否已安装:
 ```bash
 pip list | findstr ssquant # Windows
 pip list | grep ssquant # Linux
 ```

2. 如果没有找到,从源码安装(在项目目录下执行):
 ```bash
 pip install -e .
 ```

3. 验证安装成功:
 ```bash
 python -c "from ssquant.api.strategy_api import StrategyAPI; print('ssquant 导入成功!')"
 ```

### 2. 配置账户

安装完成后,需要配置相关账户信息。编辑 `ssquant/config/trading_config.py`:

#### 📊 数据API配置(回测必需)

框架使用**松鼠俱乐部会员远程数据库**,会员填入账号密码后,回测和实盘自动预拉取数据到本地:

```python
# ========== 远程数据API认证 quant789.com(松鼠俱乐部会员) ==========
API_USERNAME = "你的会员账号" # 鉴权账号 (您的俱乐部手机号或邮箱)
API_PASSWORD = "你的会员密码" # 鉴权密码
```

> 💡 **非会员用户**:
> - 可自行修改远程服务器地址
> - 或参考 `examples/A_工具_导入数据库DB示例.py` 导入本地数据

#### 🔐 交易账户配置(模拟/实盘)

```python
# SIMNOW账户(模拟交易)
ACCOUNTS = {
 'simnow_default': {
 'investor_id': '你的SIMNOW账号',
 'password': '你的密码',
 'server_name': '电信1', # 电信1/电信2/移动/TEST
 # ...
 },
 
 # 实盘账户
 'real_default': {
 'broker_id': '期货公司代码',
 'investor_id': '资金账号',
 'password': '密码',
 'md_server': 'tcp://xxx:port',
 'td_server': 'tcp://xxx:port',
 'app_id': 'AppID',
 'auth_code': '授权码',
 # ...
 },
}
```

### 3. 编写策略

```python
from ssquant.api.strategy_api import StrategyAPI
from ssquant.backtest.unified_runner import UnifiedStrategyRunner, RunMode
from ssquant.config.trading_config import get_config

def my_strategy(api: StrategyAPI):
 """双均线策略"""
 close = api.get_close()
 
 if len(close) < 20:
 return
 
 ma5 = close.rolling(5).mean()
 ma20 = close.rolling(20).mean()
 pos = api.get_pos()
 
 # 金叉做多
 if ma5.iloc[-2] <= ma20.iloc[-2] and ma5.iloc[-1] > ma20.iloc[-1]:
 if pos <= 0:
 if pos < 0:
 api.buycover(order_type='next_bar_open')
 api.buy(volume=1, order_type='next_bar_open')
 
 # 死叉做空
 elif ma5.iloc[-2] >= ma20.iloc[-2] and ma5.iloc[-1] < ma20.iloc[-1]:
 if pos >= 0:
 if pos > 0:
 api.sell(order_type='next_bar_open')
 api.sellshort(volume=1, order_type='next_bar_open')

if __name__ == "__main__":
 config = get_config(
 mode=RunMode.BACKTEST,
 symbol='rb888',
 start_date='2025-01-01',
 end_date='2025-11-30',
 kline_period='1h',
 )
 
 runner = UnifiedStrategyRunner(mode=RunMode.BACKTEST)
 runner.set_config(config)
 results = runner.run(strategy=my_strategy)
```

### 4. 多种数据请求方式

```python
# ===== 方式1:日期范围 =====
config = get_config(
 mode=RunMode.BACKTEST,
 symbol='rb888',
 start_date='2025-01-01',
 end_date='2025-11-30',
 kline_period='1h',
)

# ===== 方式2:精确时间范围 =====
config = get_config(
 mode=RunMode.BACKTEST,
 symbol='au888',
 kline_period='1m',
 start_time='2026-02-10 09:00:00',
 end_time='2026-02-14 15:00:00',
)

# ===== 方式3:获取最近N根K线 =====
config = get_config(
 mode=RunMode.BACKTEST,
 symbol='au888',
 kline_period='5m',
 limit=1000,
)

# ===== 方式4:从某日期开始取N根 =====
config = get_config(
 mode=RunMode.BACKTEST,
 symbol='au888',
 kline_period='5m',
 start_date='2026-01-01',
 limit=500,
)
```

### 5. 切换运行模式

```python
# ===== 回测模式 =====
config = get_config(
 mode=RunMode.BACKTEST,
 symbol='rb888',
 start_date='2025-01-01',
 end_date='2025-11-30',
 kline_period='1h',
)

# ===== SIMNOW模拟 =====
config = get_config(
 mode=RunMode.SIMNOW,
 account='simnow_default',
 symbol='rb888', # 888 自动映射当前主力合约
 kline_period='1m',
 auto_roll_enabled=False, # 需要自动移仓时设为 True
)

# ===== 实盘交易 =====
config = get_config(
 mode=RunMode.REAL_TRADING,
 account='real_default',
 symbol='rb888',
 kline_period='1m',
 auto_roll_enabled=False,
)
```

**策略代码完全不用改!**

---

## 📚 文档导航

| 文档 | 说明 | 适合 |
|------|------|------|
| [用户手册.md](用户手册.md) | 📖 完整使用教程 | 新手必读 |
| [API参考手册.md](API参考手册.md) | 📚 详细API说明 | 开发查询 |
| [文档导航.md](文档导航.md) | 📑 所有文档索引 | 查找文档 |

---

## 🎓 示例策略

所有示例在 `examples/` 目录(共 **25个**),v0.4.3 全部示例注释重写为面向用户的简洁说明:

### 工具类 (A_开头)

| 文件 | 说明 |
|------|------|
| `A_工具_导入数据库DB示例.py` | 数据导入数据库 |
| `A_工具_数据库管理_查看与删除.py` | 数据库管理 |
| `A_撤单重发示例.py` | 订单撤单重发机制 |
| `A_穿透式测试脚本.py` | CTP穿透式认证测试 |
| `A_CTP连接状态监测测试_真实断网.py` | 🆕 CTP连接状态异常监测(真实断网测试) |

### 策略类 (B_开头)

| 文件 | 说明 |
|------|------|
| `B_双均线策略.py` | ⭐ 经典均线交叉,入门推荐 |
| `B_海龟交易策略.py` | 唐奇安通道突破 |
| `B_十大经典策略之Aberration.py` | 布林带突破 |
| `B_日内交易策略.py` | 日内交易 |
| `B_网格交易策略.py` | 网格交易 |
| `B_强弱截面轮动策略.py` | 多品种强弱轮动 |
| `B_跨周期过滤策略.py` | 多周期信号过滤 |
| `B_跨品种套利策略.py` | 品种间价差套利 |
| `B_跨期套利策略.py` | 同品种跨期套利 |
| `B_多品种多周期交易策略.py` | 多品种多周期 |
| `B_多品种多周期交易策略_参数优化.py` | 参数优化示例 |
| `B_机器学习策略_随机森林.py` | ML机器学习预测 |
| `B_自动参数示例.py` | 合约参数自动获取演示 |
| `B_自动换月示例.py` | 🆕 **自动移仓 + 双均线**,演示主力换月自动平旧开新 |

### 高级类 (C_开头)

| 文件 | 说明 |
|------|------|
| `C_期权交易策略.py` | 期权交易 |
| `C_期货期权组合策略.py` | 期货期权组合 |
| `C_纯Tick高频交易策略.py` | TICK流高频交易 |
| `C_纯Tick限价单交易策略.py` | 限价单 + 智能追单演示 |

### data_server 模式 (D_开头)

| 文件 | 说明 |
|------|------|
| `D_订单流与深度数据_data_server模式.py` | **订单流数据交易策略** |

> **订单流策略说明**:
> - 利用 data_server 提供的 **12个订单流字段** 和 **盘口深度数据**
> - 多因子评分体系:订单流动量 + 主动买卖 + 资金流向 + 盘口压力
> - 仅 data_server 模式可用(本地聚合模式不包含订单流数据)

### 示例注释规范(v0.4.3)

所有示例的文件头 docstring 和配置区注释已统一重写:

```
合约代码 symbol 怎么填:
 回测:品种+888 = 主力连续合约(如 au888、rb888)
 SIMNOW / 实盘:
 au888 → 自动映射为当前主力月份(如 au888→au2508)
 au777 → 自动映射为次主力月份
 au2508 → 指定月份,直接使用

自动移仓:auto_roll_enabled=True 即可自动平旧开新
合约参数:乘数、最小变动价、手续费等自动获取
复权:'0'=不复权 '1'=后复权 '2'=前复权
K线来源:'local'=本地CTP Tick合成 'data_server'=远程推送
```

---

## 🤖 AI-Agent 智能助手

项目内置 **AI 量化策略编写助手**,帮助你快速生成、调试和优化交易策略。

### 功能特性

- 💬 **智能对话** - 用自然语言描述策略需求,AI 自动生成代码
- 📝 **代码生成** - 一键生成符合 ssquant 框架规范的策略代码
- 🔧 **一键回测** - 直接运行策略,实时查看回测输出和报告
- 🔄 **自动迭代** - AUTO模式下 AI 自动分析报告并优化策略

### 使用方法

> ⚠️ **重要提示**:
> - AI-Agent **不包含在 `pip install ssquant` 中**,需要 clone 仓库使用
> - `ai_agent` 目录**必须位于项目根目录下**,依赖 ssquant 框架运行

```bash
# 1. 克隆仓库
git clone https://github.com/songshuquant/ssquant.git
cd ssquant

# 2. 确保目录结构正确
# ssquant/ ← 项目根目录
# ├── ai_agent/ ← AI Agent
# ├── ssquant/ ← 核心框架(必需)
# └── examples/ ← 示例策略

# 3. 进入 ai_agent 目录并安装依赖
cd ai_agent
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 启动服务
python app.py

# 5. 打开浏览器访问 http://localhost:5000
# 6. 点击右上角 ⚙️ 配置 AI 模型 API Key
```

详细使用说明请查看 [ai_agent/README.md](ai_agent/README.md)

---

## 🏗️ 项目结构

```
ssquant-main/ # 📁 项目根目录
├── ssquant/ # 核心框架
│ ├── api/ # 策略API
│ │ ├── strategy_api.py # 核心API类(含运行时压力/移仓状态查询)
│ │ └── debug_utils.py # 调试工具
│ ├── backtest/ # 回测引擎
│ │ ├── unified_runner.py # 统一运行器
│ │ ├── backtest_core.py # 回测核心(资金约束、拒单摘要)
│ │ ├── backtest_logger.py # 回测日志(含 log_important)
│ │ ├── live_trading_adapter.py # 实盘适配器(Tick队列抗压、节流)
│ │ ├── rollover_engine.py # 🆕 自动移仓引擎
│ │ └── rollover_audit.py # 🆕 移仓复盘日志
│ ├── config/ # 配置管理
│ │ ├── trading_config.py # 配置生成(账户配置在此)
│ │ └── _server_config.py # data_server 连接配置
│ ├── data/ # 数据管理
│ │ ├── api_data_fetcher.py # API数据获取
│ │ ├── data_source.py # 数据源(资金校验、预占)
│ │ ├── local_data_loader.py # 本地数据加载
│ │ ├── ws_kline_client.py # WebSocket K线客户端(鉴权恢复)
│ │ ├── multi_period.py # 多周期K线派生器
│ │ ├── auth_manager.py # 鉴权管理器
│ │ ├── local_adjust.py # 🆕 本地复权模块(前复权/后复权)
│ │ ├── contract_info.py # 合约信息服务
│ │ └── contract_mapper.py # 合约映射器
│ ├── ctp/ # CTP二进制文件
│ │ ├── py39/ ~ py314/ # 各Python版本的CTP文件
│ │ │ ├── *.pyd / *.dll # Windows 二进制
│ │ │ └── *.so # Linux 二进制
│ │ └── loader.py # CTP加载器(自动识别平台)
│ ├── pyctp/ # CTP封装
│ │ ├── simnow_client.py # SIMNOW客户端(断线重连)
│ │ └── real_trading_client.py # 实盘客户端(断线重连 + is_ready)
│ └── indicators/ # 技术指标
│ └── tech_indicators.py
│
├── ai_agent/ # 🤖 AI智能助手(独立工具)
│ ├── app.py # Flask Web应用
│ ├── templates/index.html # 前端界面
│ ├── settings.json # 配置文件
│ ├── requirements.txt # 依赖清单
│ └── README.md # 使用说明
│
├── examples/ # 📚 策略示例(25个)
├── backtest_results/ # 📊 回测报告输出
├── backtest_logs/ # 📝 回测日志
└── data_cache/ # 💾 数据缓存
```

---

## 💡 核心API

### 数据获取

```python
api.get_close() # 收盘价序列
api.get_open() # 开盘价序列
api.get_high() # 最高价序列
api.get_low() # 最低价序列
api.get_volume() # 成交量序列
api.get_klines() # 完整K线DataFrame
api.get_tick() # 当前TICK数据(实盘)
```

### 持仓查询

```python
api.get_pos() # 净持仓(正=多,负=空)
api.get_long_pos() # 多头持仓
api.get_short_pos() # 空头持仓
api.get_position_detail() # 详细持仓(今昨仓)
```

### 交易操作

```python
api.buy(volume=1) # 买入开仓
api.sell() # 卖出平仓
api.sellshort(volume=1) # 卖出开仓
api.buycover() # 买入平仓
api.close_all() # 全部平仓
api.reverse_pos() # 反手
```

### 运行时状态(v0.4.3 新增)

```python
api.get_runtime_stats() # 运行时统计(队列长度、处理耗时等)
api.get_runtime_pressure() # 压力等级:normal / busy / critical
api.is_runtime_under_pressure() # 是否处于高压状态
api.is_rollover_busy() # 是否正在移仓
api.get_rollover_status() # 移仓详细状态
```

### 多数据源

```python
# 访问第2个数据源(index=1)
close = api.get_close(index=1)
api.buy(volume=1, index=1)
```

详见 [API参考手册.md](API参考手册.md)

---

## 🔧 系统要求

- **Python**: 3.9 ~ 3.14
- **系统**: Windows 10+ / Linux (x86_64)
- **内存**: 4GB+
- **网络**: 稳定连接(实盘/SIMNOW)

### CTP版本支持

框架支持 CTP 6.7.7 及以上版本,CTP 文件位于 `ssquant/ctp/pyXXX/` 目录:

| Python版本 | 目录 | Windows | Linux |
|-----------|------|---------|-------|
| 3.9 | `py39/` | ✅ .pyd + .dll | ✅ .so |
| 3.10 | `py310/` | ✅ .pyd + .dll | ✅ .so |
| 3.11 | `py311/` | ✅ .pyd + .dll | ✅ .so |
| 3.12 | `py312/` | ✅ .pyd + .dll | ✅ .so |
| 3.13 | `py313/` | ✅ .pyd + .dll | ✅ .so |
| 3.14 | `py314/` | ✅ .pyd + .dll | ✅ .so |

### Linux 使用说明

Linux 系统首次使用时,框架会自动预加载 CTP 运行库。如遇问题,可手动设置:

```bash
export LD_LIBRARY_PATH=/path/to/ssquant/ctp/py3xx:$LD_LIBRARY_PATH
```

---

## ⚠️ 风险提示

本框架仅供学习和研究使用。期货交易有风险,入市需谨慎。

- ⚠️ 请先在SIMNOW充分测试(至少1周)
- ⚠️ 实盘前用小资金验证
- ⚠️ 做好风险管理和止损
- ⚠️ 不要使用高杠杆

---

## 📖 快速链接

- [GitHub 仓库](https://github.com/songshuquant/ssquant) - 源码和问题反馈
- [Gitee 仓库](https://gitee.com/ssquant/ssquant) - 国内推荐,访问更快
- [用户手册](用户手册.md) - 完整使用教程
- [API参考](API参考手册.md) - 所有API详解

---

## 📝 更新日志

### v0.4.4 (2026年04月06日) 📊 回测统计 · 多品种资金 · 数据服务一致性

本版重点让**复杂成交场景下的回测数字更可信**,并理顺**多品种资金展示**与**远程历史 K 线**行为;升级后若策略含加仓、反手或多数据源,建议重新跑一遍回测对照。

| 方向 | 说明 |
|------|------|
| **回测结果** | 加仓、减仓、反手等成交的配对与盈亏、权益曲线、滑点、盈亏比等统计已按实盘逻辑修正 |
| **多品种资金** | 支持 `capital_ratio` 按比例划分总资金;报告里各数据源初始资金与总资金一致,不再「虚高」 |
| **HTML 报告** | 可筛选反手类成交;K 线图上反手标记更清晰(含拆分成交合并显示) |
| **data_server** | 历史 K 线 HTTP 请求与鉴权一致,按 `api_url` + `fallback_servers` 顺序尝试节点 |
| **示例与文档** | 海龟示例逻辑修正;新增加仓/减仓/正反手等验证示例;账户类 API 文档与回测/仿真/实盘行为对齐 |

详细说明见 [更新日志_v0.4.4.md](更新日志_v0.4.4.md)。

### v0.4.3 (2026年04月02日) 🚀 自动移仓 & 实盘抗压 & 回测资金约束

#### 🔄 自动移仓引擎(重点新功能)

| 更新项 | 说明 |
|-------|------|
| **🆕 自动移仓** | 主力换月时自动平旧开新,支持 simultaneous / sequential 两种模式 |
| **🆕 移仓复盘日志** | 每笔移仓操作记录到本地日志,支持 JSON Lines 格式 |
| **🆕 策略查询接口** | `api.is_rollover_busy()` / `api.get_rollover_status()` |
| **🔧 旧合约匹配修复** | 平旧合约时按「新主力或旧合约」统一匹配,撤单使用实际合约代码 |

#### 📐 本地复权算法(新功能)

| 更新项 | 说明 |
|-------|------|
| **🆕 前复权/后复权** | 基于合约切换点比例因子的本地复权算法 |
| **配置开关** | `ENABLE_REMOTE_ADJUST` / `adjust_type` 参数控制 |

#### 💪 实盘抗压增强

| 更新项 | 说明 |
|-------|------|
| **Tick 有界队列** | 新增 `tick_queue_maxsize`,队列满时按品种缓存最新 Tick |
| **水位控制** | 软水位 + 恢复水位,高压时自动压缩积压数据 |
| **压力等级** | `normal` → `busy` → `critical`,策略可感知并主动降级 |
| **运行时统计** | `api.get_runtime_stats()` 获取队列长度、处理耗时等 |

#### 💰 回测资金约束修复

| 更新项 | 说明 |
|-------|------|
| **资金校验** | 所有开仓按账户可用资金校验,资金不足自动裁剪手数 |
| **资金预占** | 待执行开仓单入队时预估资金占用,避免超额开仓 |
| **智能停止** | 资金耗尽且无持仓时提前终止回测 |
| **拒单可见** | 资金不足等关键信息在控制台显示(`log_important`) |

#### 🐛 BUG修复

| 更新项 | 说明 |
|-------|------|
| **CTP 线程阻塞** | tick 队列 + 独立处理线程,CTP 回调只入队立即返回 |
| **持仓查询翻倍** | `_on_position` 按 key 跟踪覆盖,不再累加 |
| **强平未处理** | 交易所强制平仓时本地持仓正确更新 |
| **终态订单残留** | 扩展终态判断,部分成交部分撤单的订单正确清理 |
| **实盘 is_ready** | 补齐 `RealTradingClient` 的 `is_ready()` 方法 |
| **断线认证重试** | 改用 `self.connected` 检查,断线后认证重试正确取消 |
| **WS 鉴权恢复** | data_server 重启后自动重新鉴权,不再无限重连失败 |
| **开盘假死** | data_server + Tick回调模式下智能节流,新K线立即触发 |

#### 📝 示例全面优化

| 更新项 | 说明 |
|-------|------|
| **注释重写** | 全部示例注释面向用户重写,去除内部术语 |
| **新增示例** | `B_自动换月示例.py`(自动移仓演示) |
| **移仓配置** | 所有 B 类策略统一添加自动移仓参数(默认关闭) |

详细更新内容请查看 [043.MD](043.MD)

### v0.4.2 (2026年02月22日) 🚀 Linux支持 & 数据服务器重大升级

#### 📡 数据服务器升级

| 更新项 | 说明 |
|-------|------|
| **全新 data_server** | 独立数据服务器架构,更稳定更快速 |
| **订单流数据** | 新增12个订单流字段 |
| **实时K线推送** | WebSocket 毫秒级推送 |
| **历史K线补全** | 连接时自动预加载 |
| **多周期支持** | 服务端直接推送任意周期 |

#### 🐧 平台与功能

| 更新项 | 说明 |
|-------|------|
| **Linux 平台支持** | 新增 CTP Linux 二进制文件 (.so) |
| **精确时间请求** | start_time/end_time/limit 参数 |
| **断线重连优化** | 认证失败自动重试 |

详细更新内容请查看 [042.MD](042.MD)

### v0.4.1 (2026年02月04日) 🐛 平今平昨Bug修复

| 更新项 | 说明 |
|-------|------|
| **昨仓识别修复** | `YdPosition` 改为 `Position - TodayPosition` |
| **解决问题** | 不再出现"错误50: 平今仓位不足" |

详细更新内容请查看 [更新日志_v0.4.1.md](更新日志_v0.4.1.md)

### v0.4.0 (2026-01) 🎯 合约参数自动获取

| 更新项 | 说明 |
|-------|------|
| **合约信息服务** | 自动获取合约参数,无需手动填写 |
| **账户查询** | 新增 `api.get_balance()` 等 |
| **数据库优化** | 线程安全写入 + 快速追加 |

详细更新内容请查看 [更新日志_v0.4.0.md](更新日志_v0.4.0.md)

### v0.3.9 (2026-01) 🚀 重大升级

| 更新项 | 说明 |
|-------|------|
| **AI-Agent** | 新增 AI 量化策略编写助手 |
| **报告重制** | Plotly 交互式 HTML 报告,生成速度提升 5-10 倍 |
| **性能优化** | 数据窗口控制、内存占用降低 90%+ |

详细更新内容请查看 [更新日志_2026年01月06日.md](更新日志_2026年01月06日.md)

### v0.3.7 及更早

- 🔄 移除构建脚本和冗余文件
- ✅ 修复 CTP 登录报错乱码问题
- ✅ 完整的TICK流双驱动模式
- ✅ 多品种多周期支持
- ✅ 19个策略示例

---

**开始你的量化交易之旅!**

查看 [用户手册.md](https://github.com/songshuquant/ssquant/blob/main/%E7%94%A8%E6%88%B7%E6%89%8B%E5%86%8C.md) 了解详细使用方法。

SSQuant 专有许可证 (非商用许可) SSQuant Proprietary License (Non-Commercial Use Only) 版权所有 (c) 2025 SSQuant Team Copyright (c) 2025 SSQuant Team ======================================== 许可条款 ======================================== 1. 定义 - "软件"指 SSQuant 期货量化交易框架及其所有组件 - "商业使用"指任何以盈利为目的的使用,包括但不限于: * 在商业产品或服务中使用本软件 * 为客户提供基于本软件的服务 * 将本软件集成到商业解决方案中 * 使用本软件进行商业交易或投资管理 2. 授权范围本许可证授予您以下权利(仅限非商业用途): ✓ 下载和安装本软件 ✓ 用于个人学习和研究 ✓ 用于学术研究和教育目的 ✓ 用于个人投资策略开发和回测 ✓ 修改源代码供个人使用 3. 禁止事项未经版权所有者书面授权,您不得: ✗ 将本软件用于任何商业目的 ✗ 出售、出租或以其他方式分发本软件 ✗ 将本软件作为商业产品或服务的一部分 ✗ 移除或修改本软件中的版权声明 4. 商业授权如需商业使用,请联系版权所有者获取商业许可: - 邮箱:339093103@qq.com - 网站:https://github.com/songshuquant/ssquant-ai 5. 免责声明本软件按"原样"提供,不提供任何明示或暗示的保证。在任何情况下,版权所有者均不对因使用本软件而产生的任何损害承担责任。期货交易具有高风险,使用本软件进行交易的风险由用户自行承担。 6. 终止如果您违反本许可证的任何条款,您的使用权将自动终止。 ======================================== License Terms (English) ======================================== 1. Definitions - "Software" refers to the SSQuant futures quantitative trading framework - "Commercial Use" means any use for profit, including but not limited to: * Using in commercial products or services * Providing services based on this software * Integrating into commercial solutions * Using for commercial trading or investment management 2. Granted Rights (Non-Commercial Only) ✓ Download and install the software ✓ Personal learning and research ✓ Academic research and education ✓ Personal investment strategy development ✓ Modify source code for personal use 3. Restrictions Without written authorization, you may NOT: ✗ Use for any commercial purpose ✗ Sell, rent, or distribute the software ✗ Include as part of commercial products ✗ Remove or modify copyright notices 4. Commercial License For commercial use, contact: - Email: 339093103@qq.com - Website: https://github.com/songshuquant/ssquant-ai 5. Disclaimer THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. Futures trading involves high risk. Use at your own risk. 6. Termination Violation of any terms will automatically terminate your rights.