# FUTURES-AI

**Repository Path**: erroot/futures-ai

## Basic Information

- **Project Name**: FUTURES-AI
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FuturesAI — 中国商品期货ai自动交易系统

> 将大语言模型（LLM）接入中国商品期货市场，实现从行情订阅、AI 分析到自动下单的全链路自主交易；同时回测系统支持 AI 策略的历史验证。

---

## 项目简介

本项目是一套**可替换策略架构**的量化交易系统，核心创新点在于用 LLM 替代传统规则引擎，让 AI 直接阅读 K 线特征并输出结构化交易信号。默认内置基于价格行为学的策略实现。

系统支持同时分析多个商品期货合约，AI 每根 K 线收盘后自动触发分析，输出开仓/持仓/平仓/反手决策，并通过追踪止损守卫管理风险。配套回测系统支持逐根 K 线重建市场上下文、调用真实 LLM 决策并模拟追踪止损出场，实现 AI 策略的历史验证。

---
<img width="2909" height="1698" alt="屏幕截图 2026-04-21 004525" src="https://github.com/user-attachments/assets/7591ab06-3d2c-4bb8-90e5-dbff78232a5d" />

<img width="2904" height="1679" alt="屏幕截图 2026-04-21 004746" src="https://github.com/user-attachments/assets/a04f69e3-9795-4730-92b4-1039f7272520" />

<img width="2906" height="1687" alt="屏幕截图 2026-04-21 004948" src="https://github.com/user-attachments/assets/95beafd0-4970-4215-959b-f2e08a9e65cb" />

---

## 系统架构

**实时交易路径**

```
tqsdk 线程                         asyncio 事件循环
──────────────────────────────     ──────────────────────────────
行情订阅（250根K线）
K线收盘检测 ─────────────────────→ 多合约 x 多模型并发分析
tick守卫轮询（SL / TP / EOD）                  │
       ↑                              结构化 JSON 信号
       │                                      │
insert_order ←──── 下单队列 ←─────────────────┘
       │
       ↓
FastAPI + SSE ──→ 浏览器前端（实时面板 / 权益曲线）
```

**回测路径（独立）**

```
Parquet历史K线
     │
     ↓
逐根重建 market_data ──→ 策略层特征计算 ──→ 真实LLM分析 ──→ 追踪止损模拟
                                                                   │
/backtest/* API ──→ backtest.html（K线图可视化）        统计汇总（胜率/盈亏R）
```

### 核心模块

| 模块 | 文件 | 职责 |
|------|------|------|
| 后端服务 | `main.py` | FastAPI 应用，状态管理，SSE 实时推送 |
| 配置管理 | `config.py` | 环境变量读取，交易时间判断 |
| 行情订阅 | `data_feed.py` | TqSdk 行情线程，K线订阅，守卫轮询 |
| AI 分析 | `analyzers.py` | 多模型调用，Prompt 构建，JSON 解析 |
| 下单执行 | `trader.py` | 开平仓，线程安全队列，守卫持久化 |
| 策略层 | `strategies/` | 价格行为特征计算，System Prompt 管理 |
| 回测引擎 | `backtest/` | 历史 K 线加载，追踪止损模拟，统计计算 |

---

## 技术栈

**后端**
- Python 3.14
- FastAPI + uvicorn（异步 Web 框架）
- TqSdk（天勤量化，期货行情与交易接口）
- asyncio + 多线程（tqsdk 线程与 asyncio 事件循环隔离）

**AI 层**
- Anthropic SDK（Claude 系列）
- OpenAI SDK（兼容接口，接入 DeepSeek / Gemini / Grok / Qwen3 等）
- 流式输出 + 信号量并发控制（默认 3 并发）
- 动态 System Prompt（有仓/无仓自动切换，token 节省约 62%）

**前端**
- 纯 HTML + Vanilla JS（无构建步骤）
- SSE 实时推送（分析结果、持仓变化、权益曲线）
- Lightweight Charts（回测 K 线图表）

**数据**
- Parquet（历史 K 线存储）
- JSONL（交易记录按日分区）
- JSON（守卫持久化，支持重启恢复）

---

## 主要功能

### 实时交易
- **自定义 K 线周期**：支持任意分钟级周期（默认 5 分钟）
- **多合约并发分析**：同时监控 10 个合约，每根 K 线收盘触发 AI 分析
- **结构化信号输出**：AI 输出 JSON 格式信号（操作建议 / 入场价 / 止损价 / 止盈价）
- **追踪止损守卫**：tick 级别轮询，分段追踪策略（0.6R / 1R / 2R 三档）
- **止盈感知收紧**：接近止盈时自动压缩追踪距离
- **尾盘强制平仓**：收盘前 2 分钟独立检测，tick 级别执行
- **企业微信推送**：开仓/平仓实时通知（可选；无法使用天勤自动下单时，可通过推送人工跟单）
- **飞书推送**：支持飞书机器人 webhook，默认推送渠道，可通过 `PUSH_CHANNEL=wechat` 切回企业微信

### 回测系统

> 传统回测用固定规则跑历史数据；本系统的回测是 **AI 决策的历史重演**——逐根 K 线重建完整市场上下文，调用真实 LLM 分析，追踪止损模拟与实盘代码路径完全共享，确保回测与实盘行为一致。

- **逐根重建上下文**：每根 K 线调用 `build_market_data_at()`，完整还原 EMA、趋势结构、H2/L2 标签等预计算特征
- **真实 AI 调用**：回测直接调用线上 LLM，结果反映模型的真实决策能力，而非规则近似
- **追踪止损模拟**：K 线级分段追踪（0.6R / 1R / 2R 三档）+ 止盈感知收紧，分段逻辑与实盘一致；但实盘为 tick 级执行，回测存在 K 线内滑点误差
- **可视化交互**：Lightweight Charts K 线图点击任意 Bar → 查看预计算面板 → 触发 AI 分析 → 模拟出场
- **统计汇总**：胜率 / 平均盈亏 R / 盈亏比 / 期望值
- **内置历史数据**：仓库已附带部分商品期货 K 线数据（`data/klines/`），克隆后可直接运行回测；回测页面支持在线下载更多品种的历史数据，无需手动执行脚本

### 交易统计分析（`analyze_trades.py`）

离线分析脚本，读取实盘/模拟账户的历史交易与 AI 分析记录，无需启动服务。

**运行方式**

```bash
python analyze_trades.py                        # 自动读取当前账户模式数据
python analyze_trades.py --days 30             # 只看最近 30 天
python analyze_trades.py --model gemini        # 只看某个模型
python analyze_trades.py --chart               # 额外生成多维度图表 PNG
python analyze_trades.py --chart --show        # 生成图表并弹出预览
```

**多模型自动分流**：不加 `--model` 时，脚本自动检测所有有交易数据的模型，逐一输出各自的完整报告并保存为 `trade_report_{model}.txt`，同时生成合并对比报告 `trade_report.txt`。

**文字报告内容**

| 分析维度 | 说明 |
|----------|------|
| 整体盈亏 | 胜率、盈亏比、期望值、R 倍数分布 |
| 多空拆分 | 做多 vs 做空方向独立统计 |
| 按品种 / 模型 | 各品种、各模型盈亏汇总 |
| 按设置类型 | Al Brooks 入场设置胜率排名（≥3笔） |
| 按市场状态 | 五分类趋势强度下的胜率对比 |
| 时段 × 市场状态 | 交叉矩阵，找出最佳交易时窗 |
| 归因分析 | 盈利 vs 亏损交易入场特征分布差（↑有利 / ↓不利） |
| 各模型独立分析 | 每个模型的完整品种/趋势/设置类型/归因明细 |

**图表报告（`--chart`）**

生成 2×3 共 6 张子图的 PNG，多模型时每个模型单独出一张（标题注明模型名）：

| 图 | 内容 |
|----|------|
| 胜率 × 品种 | 柱状图，绿=胜率≥50%，红=胜率<50%，标注数值 |
| 胜率 × 市场状态 | 五分类趋势强度对比 |
| 盈亏分布直方图 | 绿=盈利/红=亏损，标注笔数与均值 |
| 权益曲线 | 累计盈亏折线 + 填色 + 终点标注 |
| 胜率热力图 | 市场状态 × 设置类型，灰=样本不足 |
| 归因差值图 | 各入场特征在盈利/亏损中的占比差，±15% 参考线 |

> `--chart` 模式需要 `matplotlib`（`pip install matplotlib`）

<img width="2683" height="1636" alt="analyze_report_20260422_025829_claude2api" src="https://github.com/user-attachments/assets/33226ca7-7e21-4950-8945-e2a89d8971fd" />

<img width="2681" height="1636" alt="analyze_report_20260422_025829_deepseek2" src="https://github.com/user-attachments/assets/20c6a2ba-5a7a-40a5-a0b0-3540c2081f90" />

---

## 价格行为学交易策略

### 核心框架（价格行为学）

策略实现基于价格行为学体系，以裸 K 线为唯一信息来源，不使用 MACD / RSI / 布林带等衍生指标。EMA20 仅作动态价格区域参考；趋势以 EMA 斜率 + 高高/低低结构联合判断分五级；回调腿是主要入场信号；信号棒强度以实体比率衡量。

**入场原则**
- 最少需要 **2 个独立理由**（趋势 + 回调腿标签 + EMA 支撑/压力 + 信号棒等）
- H1/L1（极端趋势下）可单理由入场

### 5 分钟周期的选择

系统默认运行在 **5 分钟 K 线周期**，这一选择经过模拟权衡：

- **信号频率**：5 分钟在日内交易中提供足够的信号频率（每个交易时段约 50~60 根），兼顾噪音过滤与响应速度
- **AI 调用节奏**：每 5 分钟一次 AI 分析，在多合约（10 个）并发下总调用频率可控
- **追踪止损粒度**：tick 级守卫轮询 + K 线级跟进不足检测（默认 2 根），5 分钟周期下跟进窗口约 10 分钟，既不过早退出又不让亏损头寸久挂
- **历史数据可用性**：天勤 5 分钟历史数据充足，可下载多年数据回测

周期通过 `ANALYSIS_INTERVAL_MINUTES` 配置变量控制，所有相关逻辑（K 线订阅、交易时段边界判断、尾盘平仓窗口）统一派生自该值，修改一处全局生效。

### 震荡区间检测与跳过

**为什么跳过震荡区间**

在震荡（窄幅区间）行情中，AI 也会遵循"不追突破"的策略规则返回"观望"，但仍消耗一次完整的 LLM 调用（~1~2 秒延迟 + token 成本）。窄幅行情可能持续数十根 K 线，批量跳过可显著降低无效成本。

**跳过机制**

检测在策略层 `build_price_structure()` 中完成，结果写入 `market_data`。`main.py` 触发分析前读取此标志：
- 无持仓 → 直接跳过 AI 调用，记录"跳过（震荡区间）"
- 有持仓 → 照常调用（需要持仓管理决策）

回测模块同样遵循此逻辑，`/api/analyze` 端点返回 `skipped: true` 时前端直接标记，不发起 AI 调用，保证回测行为与实盘一致。

- **代码层参数调校**：止损距离、追踪止损各阶段的触发阈值（0.6R/1R/2R）、跟进不足退出的 K 线计数（`bar_exit_limit`）等参数均经历了多轮基于模拟结果的调整。调整原则是"先观察再改"，每次只动一个参数，用 `analyze_trades.py` 对比前后胜率和盈亏比，避免多变量干扰。

---

## 策略插件化

系统采用插件化策略架构，通过抽象基类定义统一接口，新策略只需继承并实现对应方法，在 `.env` 中切换 `STRATEGY_ID` 即可生效，无需改动核心代码。

策略接口 [`strategies/base.py`](strategies/base.py) 完全公开，继承 `BaseStrategy` 实现自定义策略后，在 `.env` 中设置 `STRATEGY_ID=my_strategy` 即可切换。内置的 `price_action` 策略实现以编译形式（`.pyd`）发布，源码不公开。

---

## 提示词工程

### 设计哲学：让 AI 做判断，不做计算

Prompt 的核心原则是**把计算留给代码，把判断留给 AI**。策略层预先计算所有数值型特征（EMA 缺口数、趋势强度分类、H2/L2 回调腿标签、区间边界位置），以结构化 JSON 块传给 AI，AI 读到的是"当前处于弱上升趋势、存在 H2 回调腿、EMA 缺口 8 根"这样的语义结论，而非原始数列——既节省 token，又让模型直接聚焦交易决策。

### Prompt 演进与输出稳定性

Prompt 的演进经历了数十次模拟驱动的迭代，主要方向如下：

**第一代（单段 Prompt）**：一个超长中文 Prompt 包含全部规则，有仓/无仓复用同一份。模拟中发现持仓管理和入场规则互相干扰，且超长上下文推理质量不稳定。

**第二代（有仓/无仓分离）**：拆分为"无持仓版"（含完整入场规则）和"有持仓版"（仅含持仓管理，去掉第二步~第五步入场规则）。有持仓时 Prompt 体积缩减约 **62%**，推理更聚焦，误操作（不该开新仓时开仓）显著减少。

**第三代（中英文双语）**：对接外国模型时发现，英文 Prompt 比中文每 token 约携带 **18%** 更多语义（英文 ~4 字符/token vs 中文 ~1.5 字符/token）。为此实现了完全平行的中英文 Prompt 体系，模型注册时声明 `lang: "zh/en"` 自动路由，同等规则下英文版 token 成本更低。

**代码层前置过滤**：模拟中发现部分情形（首尾盘、震荡区间）即使进入 AI 分析也会浪费 token，因为答案是确定的。迭代后将这些"无需看图即可判断"的二元否决逻辑完全移出 Prompt，改在代码层强制执行：震荡区间直接跳过 AI 调用；无持仓时首尾盘跳过；有持仓时尾盘调用 AI 后强制覆盖为平仓。Prompt 不再描述这些规则，既减少无效请求，也让 Prompt 专注于真正需要模型判断的形态分析。

**输出稳定性迭代**：稳定输出是比节省 token 更长期的工程课题。主要方向有以下：

- **持续收紧交易规则**：模拟中发现 AI 在某些模糊地带（如弱趋势中的小回调、区间中部的反弹）倾向于随机输出做多/做空，而这类形态本应观望。每遇一类误判，就将对应规则在 Prompt 中明确化（从"不建议"改为"禁止"），同时在预计算特征块中增加对应的判别字段，让规则有数值依据而非依赖模型推断。经历数十次这样的"发现误判→收紧规则→补充特征"循环，当前交易规则已从早期的宽松指导方针演变为有较强约束力的决策树。

- **去除空字段传输**：早期特征块中存在大量值为 `None`/`[]`/空字符串的字段（当前无信号时的测量目标），这些空字段会占用 token，也会干扰 AI 对有效字段的注意力。迭代后在 `build_features()` 中统一过滤空值，只传非空字段；预计算 `_DEFAULTS` 中将列表默认值明确为 `[]`，方便判断是否有有效内容再决定是否传入。

### 预计算特征块

每次 AI 调用前，策略层生成一个 JSON 特征块作为 User Message 开头：

```json
{
  "EMA缺口K线数": 12,
  "EMA方向": "多头",
  "趋势强度分类": "弱上升趋势",
  "H2计数": 1,
  "回调腿标签": "H2回调进行中",
  "测量目标向上": [4850, 4920],
  "区间边界": {"上沿": 4810, "下沿": 4760, "当前位置": 0.73}
}
```

AI 第一步直接采用这些预判值，仅在形态明显矛盾时才覆盖。这样既减少了 AI 的计算负担，也让 System Prompt 中的规则描述更精准。

### 历史记录折叠

AI 调用时会附带当日历史决策记录，但连续多根"持有"或"观望"会大量重复消耗 token。为此实现了折叠逻辑：连续相同操作折叠为 `持有×7`，并过滤 **3 小时**以前的旧记录（覆盖最长午休，跨交易时段旧记录无参考价值），保留开仓/平仓/反手的完整逻辑。实测可减少高频交易时段 40%~60% 的历史记录 token。

### 数据层 Token 优化

- **K 线只传最近 40 根**：`klines` 字段截断，减少原始行情 token
- **字段双重过滤**：`_SKIP_FIELDS` 过滤无需传 AI 的元字段；`_SKIP_STRUCT` 过滤已在特征块中的价格结构字段，消除双重传输
- **早退信号流式捕获**：流式输出中实时检测 `操作建议+入场价` 字段，提前触发下单后继续接收止损/止盈，不额外增加 API 调用

---

## 支持的 AI 模型

| 模型 | 接口 | 语言 |
|------|------|------|
| Claude (Anthropic) | 原生 SDK | 英文 |
| GPT-4o (OpenAI) | OpenAI SDK | 英文 |
| DeepSeek | OpenAI 兼容 | 中文 |
| Gemini | OpenAI 兼容 | 英文 |
| Grok | OpenAI 兼容 | 英文 |
| Qwen3 | OpenAI 兼容 | 中文 |
| OpenRouter | OpenAI 兼容 | 英文 |

新增模型只需在 `config.py` 的 `MODEL_DEFINITIONS` 中添加一条配置，无需修改其他代码。

---

## 快速开始

### 环境要求
- Python 3.14（Windows 64位）
- 天勤量化账号（[tqsdk.com](https://www.shinnytech.com/products/tqsdk)，[支持的期货公司列表](https://www.shinnytech.com/articles/reference/tqsdk-brokers)）
- 至少一个 AI 模型的 API Key

### 安装

```bash
git clone https://github.com/tauadjm/FUTURES-AI.git
cd FUTURES-AI

py -3.14 -m venv .venv
.venv\Scripts\activate

pip install -r requirements.txt
```

### 配置

```bash
copy .env.example .env
# 编辑 .env，填入天勤账号和 AI API Key
```

### 启动

```bash
python main.py
# 访问 http://localhost:8888
```

---

## 目录结构

```
├── main.py               # FastAPI 后端
├── config.py             # 配置管理
├── data_feed.py          # 行情订阅 & 守卫轮询
├── analyzers.py          # AI 模型调用
├── trader.py             # 下单执行
├── strategies/
│   ├── __init__.py           # 策略注册表
│   ├── prompts.py            # System Prompt 字符串（中英文双语，开源）
│   └── *.cp314-win_amd64.pyd # 策略模块（编译发布，不开源）
├── backtest/
│   ├── engine.py         # 回测引擎
│   └── router.py         # 回测 API 路由
├── index.html            # 主界面（SSE 实时更新）
├── equity.html           # 权益分析页
├── backtest.html         # 回测界面
├── analyze_trades.py     # 交易统计分析（多模型分流 / 归因分析 / 可视化图表）
├── calc_fee.py           # 手续费计算
├── calc_trail.py         # 追踪止损推算器
├── download_klines.py    # 历史 K 线下载
├── data/klines/          # 历史 K 线数据（Parquet，供回测用）
└── requirements.txt
```

---

## 风险提示

> 本项目仅供技术学习和研究使用。期货交易有较大风险，AI 决策存在不确定性，请勿将本系统直接用于实盘交易。作者不承担任何因使用本系统产生的经济损失。

> 本项目完全通过 Vibe Coding 构建，作者本人没有任何编程基础。所有代码由 AI 生成，作者以交易者视角驱动需求与迭代。

---

## License

MIT License — 详见 [LICENSE](LICENSE)

---

## News Module / 新闻舆情模块

- Page: `/news`
- Raw collector output stays in `thrd_party/TrendRadar/output`
- FUTURES-AI query/index data stays in `data/news`

Environment flags:

```bash
NEWS_ENABLED=true
NEWS_INTERVAL_MINUTES=10
NEWS_AI_ENABLED=false
NEWS_AI_ENABLED_LIVE=false
NEWS_AI_ENABLED_BACKTEST=false
NEWS_DATA_DIR=data/news
NEWS_TRENDRADAR_DIR=thrd_party/TrendRadar
```

交易通知渠道配置：

```dotenv
PUSH_CHANNEL=feishu
FEISHU_WEBHOOK_URL=
ENABLE_FEISHU_PUSH=true
```

真实 webhook 只应写入本地 `.env` 或外部密钥管理系统，不要提交到版本库。

Notes:

- News context is optional and defaults to off.
- Live analysis only includes news when both `NEWS_AI_ENABLED=true` and `NEWS_AI_ENABLED_LIVE=true`.
- Backtest analysis only includes historical news when both `NEWS_AI_ENABLED=true` and `NEWS_AI_ENABLED_BACKTEST=true`.
- Adding a contract now auto-generates default news keywords for that symbol.
- Removing a contract archives its news keyword config instead of deleting it.