laoxong/nofx
1
0
Fork 0
mirror of https://github.com/laoxong/nofx.git synced 2026-06-07 03:07:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add backtest and debate module technical documentation

Browse Source
This commit is contained in:
tinkle-community
2025-12-15 15:55:07 +08:00
parent 7532d09dfb
commit 85cf8c4986
2 changed files with 1529 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/BACKTEST_MODULE.md
+622
View File
@@ -0,0 +1,622 @@
# NOFX 回测模块技术文档
## 概述
本文档详细描述 NOFX 回测模块的完整技术实现，包括配置、历史数据加载、模拟引擎、AI 决策、性能指标计算和结果存储。
---
## 完整回测流程图
```
┌─────────────────────────────────────────────────────────────────┐
│ 回测执行流程 │
└─────────────────────────────────────────────────────────────────┘
1. API 请求: /backtest/start
↓
2. Manager.Start()
├─ 验证配置
├─ 解析 AI 模型
├─ 创建 Runner 实例
└─ 启动 runner.Start() (goroutine)
↓
3. Runner.Start() → Runner.loop()
└─ 遍历每个决策时间点:
├─ DataFeed.BuildMarketData() [构建市场数据]
├─ 检查决策触发条件 [每 N 根 K 线]
├─ buildDecisionContext() [构建决策上下文]
├─ invokeAIWithRetry() [调用 AI + 缓存]
├─ executeDecision() [执行交易]
├─ checkLiquidation() [检查爆仓]
├─ updateState() [更新状态]
├─ appendEquityPoint() [记录权益]
├─ appendTradeEvent() [记录交易]
├─ maybeCheckpoint() [保存检查点]
└─ persistMetrics() [持久化指标]
↓
4. 完成/失败
├─ 计算最终指标
├─ 持久化所有结果
└─ 释放锁
↓
5. API 查询: /backtest/metrics, /backtest/equity, /backtest/trades
└─ 加载并返回结果
```
---
## 1. 回测配置 (Configuration)
**核心文件:** `backtest/config.go`
### 1.1 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `RunID` | string | (必填) | 回测运行唯一标识 |
| `UserID` | string | "default" | 用户 ID |
| `Symbols` | []string | (必填) | 交易币种列表 |
| `Timeframes` | []string | ["3m", "15m", "4h"] | K 线周期 |
| `DecisionTimeframe` | string | Symbols[0] | 主决策周期 |
| `DecisionCadenceNBars` | int | 20 | 每 N 根 K 线触发一次决策 |
| `StartTS`, `EndTS` | int64 | (必填) | 回测时间范围 (Unix 时间戳) |
| `InitialBalance` | float64 | 1000 | 初始资金 (USD) |
| `FeeBps` | float64 | 5 | 手续费 (基点) |
| `SlippageBps` | float64 | 2 | 滑点 (基点) |
| `FillPolicy` | string | "next_open" | 成交策略 |
| `PromptVariant` | string | "baseline" | AI 提示词变体 |
| `CacheAI` | bool | false | 是否缓存 AI 决策 |
| `Leverage` | LeverageConfig | BTC/ETH:5, Altcoin:5 | 杠杆设置 |
### 1.2 成交策略 (Fill Policy)
```go
// backtest/config.go:163-179
switch fillPolicy {
case "next_open": // 下一根 K 线开盘价
case "bar_vwap": // 当前 K 线 VWAP
case "mid": // 当前 K 线 (High+Low)/2
default: // Mark Price
}
```
### 1.3 配置示例
```go
cfg := backtest.BacktestConfig{
RunID: "bt_20231215_150405",
Symbols: []string{"BTCUSDT", "ETHUSDT"},
Timeframes: []string{"3m", "15m", "4h"},
DecisionTimeframe: "3m",
DecisionCadenceNBars: 20,
StartTS: 1702566000,
EndTS: 1702652400,
InitialBalance: 10000,
FeeBps: 5,
SlippageBps: 2,
FillPolicy: "next_open",
}
```
---
## 2. 历史数据加载 (Data Loading)
**核心文件:** `backtest/datafeed.go`
### 2.1 数据加载流程
```
1. NewDataFeed() - 初始化
↓
2. loadAll() - 加载所有历史数据
├─ 计算缓冲区 (StartTS 前 200 根 K 线)
├─ 调用 market.GetKlinesRange() 获取数据
├─ 存储到 symbolSeries map
└─ 从主周期构建决策时间线
↓
3. BuildMarketData() - 构建市场数据快照
├─ 切片 K 线数据到当前时间戳
├─ 计算技术指标 (EMA, MACD, RSI, ATR)
└─ 返回 market.Data 结构
```
### 2.2 数据结构
```go
// DataFeed 核心结构
type DataFeed struct {
decisionTimes []int64 // 决策时间点列表
symbolSeries map[string]*symbolSeries // 按币种存储的数据
}
// 单币种时间序列
type symbolSeries struct {
timeframes map[string]*timeframeSeries // 按周期存储
}
// 单周期数据
type timeframeSeries struct {
klines []market.Kline // K 线数据
closeTimes []int64 // 收盘时间索引
}
```
### 2.3 关键代码引用
- 数据获取: `backtest/datafeed.go:48-93`
- 时间线生成: `backtest/datafeed.go:96-115`
- 市场数据组装: `backtest/datafeed.go:141-171`
---
## 3. 模拟引擎 (Simulation Engine)
**核心文件:** `backtest/runner.go`
### 3.1 主循环
```go
// backtest/runner.go:232-264
func (r *Runner) loop() {
for _, ts := range r.feed.DecisionTimes() {
if r.isPaused() {
break
}
r.stepOnce(ts)
}
}
```
### 3.2 单步执行
```go
// backtest/runner.go:266-471
func (r *Runner) stepOnce(ts int64) {
// 1. 获取当前 K 线时间戳
// 2. 构建市场数据
// 3. 检查决策触发条件 (每 N 根 K 线)
// 4. 执行决策周期 (如果触发)
// 5. 检查爆仓
// 6. 更新状态并记录
}
```
### 3.3 状态管理
```go
// backtest/types.go:31-47
type BacktestState struct {
BarIndex int // 当前 K 线索引
Cash float64 // 可用余额
Equity float64 // 总权益
UnrealizedPnL float64 // 未实现盈亏
RealizedPnL float64 // 已实现盈亏
MaxEquity float64 // 最高权益
MinEquity float64 // 最低权益
MaxDrawdownPct float64 // 最大回撤
Positions map[string]*position // 持仓
}
```
---
## 4. AI 决策 (AI Decision Making)
**核心文件:** `backtest/runner.go`
### 4.1 决策上下文构建
```go
// backtest/runner.go:473-532
func (r *Runner) buildDecisionContext() *decision.Context {
return &decision.Context{
CurrentTime: "2023-12-15 10:30:00 UTC",
RuntimeMinutes: elapsed,
CallCount: cycleNumber,
Account: {
TotalEquity, AvailableBalance, TotalPnL, MarginUsedPct
},
Positions: []PositionInfo{...},
CandidateCoins: []string{symbols...},
MarketDataMap: map[symbol]*market.Data{...},
MultiTFMarket: map[symbol]map[timeframe]*market.Data{...},
}
}
```
### 4.2 AI 调用
```go
// backtest/runner.go:544-563
func (r *Runner) invokeAIWithRetry() (*decision.FullDecision, error) {
// 最多重试 3 次
// 指数退避: 500ms, 1000ms, 1500ms
// 使用 decision.GetFullDecisionWithStrategy() 统一提示词生成
}
```
### 4.3 AI 缓存
```go
// backtest/aicache.go:127-168
// 缓存键: SHA256(context payload)
// 包含: variant, timestamp, account, positions, market data
```
### 4.4 支持的 AI 模型
| 模型 | 客户端文件 |
|------|-----------|
| DeepSeek | `mcp/deepseek_client.go` |
| Qwen | `mcp/qwen_client.go` |
| Claude | `mcp/claude_client.go` |
| Gemini | `mcp/gemini_client.go` |
| Grok | `mcp/grok_client.go` |
| OpenAI | `mcp/openai_client.go` |
| Kimi | `mcp/kimi_client.go` |
---
## 5. 性能指标 (Performance Metrics)
**核心文件:** `backtest/metrics.go`
### 5.1 指标计算
| 指标 | 公式 | 代码位置 |
|------|------|----------|
| **总收益率** | (最终权益 - 初始资金) / 初始资金 × 100 | metrics.go:36-42 |
| **最大回撤** | max((峰值 - 当前) / 峰值 × 100) | metrics.go:64-91 |
| **夏普比率** | 平均收益 / 收益标准差 | metrics.go:94-138 |
| **胜率** | 盈利交易数 / 总交易数 × 100 | metrics.go:180-181 |
| **盈亏比** | 总盈利 / 总亏损 | metrics.go:189-193 |
### 5.2 交易统计
```go
// backtest/metrics.go:141-225
type TradeMetrics struct {
TotalTrades int
WinningTrades int
LosingTrades int
AvgWin float64
AvgLoss float64
BestSymbol string
WorstSymbol string
SymbolStats map[string]*SymbolStat
}
```
---
## 6. 权益曲线 (Equity Curve)
**核心文件:** `backtest/equity.go`
### 6.1 权益点结构
```json
{
"ts": 1702566000000,
"equity": 10500.50,
"available": 8000.00,
"pnl": 500.50,
"pnl_pct": 5.005,
"dd_pct": 2.34,
"cycle": 42
}
```
### 6.2 权益更新
```go
// backtest/runner.go:829-872
func (r *Runner) updateState() {
// 1. 计算总权益: cash + margin + 未实现盈亏
// 2. 追踪峰值 (MaxEquity)
// 3. 追踪谷值 (MinEquity)
// 4. 重新计算回撤: (MaxEquity - Equity) / MaxEquity × 100
}
```
### 6.3 数据重采样
```go
// backtest/equity.go:10-50
func ResampleEquity(points []EquityPoint, timeframe string) []EquityPoint {
// 按时间周期分桶
// 保留每个桶的最后一个点
}
```
---
## 7. 结果存储 (Result Storage)
**核心文件:** `backtest/storage.go`, `store/backtest.go`
### 7.1 文件存储结构
```
backtests/
├── <run_id>/
│ ├── run.json # 运行元数据
│ ├── checkpoint.json # 检查点 (用于恢复)
│ ├── equity.jsonl # 权益曲线 (逐行 JSON)
│ ├── trades.jsonl # 交易记录 (逐行 JSON)
│ ├── metrics.json # 性能指标
│ ├── progress.json # 进度信息
│ ├── ai_cache.json # AI 决策缓存
│ └── decision_logs/ # 决策日志
│ ├── 0.json
│ ├── 1.json
│ └── ...
```
### 7.2 数据库表结构
```sql
-- 回测运行元数据
CREATE TABLE backtest_runs (
run_id TEXT PRIMARY KEY,
user_id TEXT,
config_json TEXT,
state TEXT, -- pending, running, completed, failed
processed_bars INTEGER,
progress_pct REAL,
equity_last REAL,
max_drawdown_pct REAL,
liquidated BOOLEAN,
ai_provider TEXT,
ai_model TEXT,
created_at DATETIME,
updated_at DATETIME
);
-- 权益曲线
CREATE TABLE backtest_equity (
id INTEGER PRIMARY KEY,
run_id TEXT,
ts INTEGER,
equity REAL,
available REAL,
pnl REAL,
pnl_pct REAL,
dd_pct REAL,
cycle INTEGER
);
-- 交易记录
CREATE TABLE backtest_trades (
id INTEGER PRIMARY KEY,
run_id TEXT,
ts INTEGER,
symbol TEXT,
action TEXT,
side TEXT,
qty REAL,
price REAL,
fee REAL,
slippage REAL,
realized_pnl REAL,
leverage INTEGER,
liquidation BOOLEAN
);
-- 性能指标
CREATE TABLE backtest_metrics (
run_id TEXT PRIMARY KEY,
payload BLOB,
updated_at DATETIME
);
-- 检查点 (暂停/恢复)
CREATE TABLE backtest_checkpoints (
run_id TEXT PRIMARY KEY,
payload BLOB,
updated_at DATETIME
);
```
---
## 8. API 接口
**核心文件:** `api/backtest.go`
### 8.1 接口列表
| 接口 | 方法 | 说明 |
|------|------|------|
| `/backtest/start` | POST | 开始回测 |
| `/backtest/pause` | POST | 暂停回测 |
| `/backtest/resume` | POST | 恢复回测 |
| `/backtest/stop` | POST | 停止回测 |
| `/backtest/status` | GET | 获取状态 |
| `/backtest/runs` | GET | 列出所有回测 |
| `/backtest/equity` | GET | 获取权益曲线 |
| `/backtest/trades` | GET | 获取交易记录 |
| `/backtest/metrics` | GET | 获取性能指标 |
| `/backtest/trace` | GET | 获取决策日志 |
| `/backtest/export` | GET | 导出 ZIP |
| `/backtest/delete` | POST | 删除回测 |
### 8.2 请求示例
```bash
# 开始回测
POST /backtest/start
{
"config": {
"run_id": "bt_20231215",
"symbols": ["BTCUSDT", "ETHUSDT"],
"timeframes": ["3m", "15m", "4h"],
"start_ts": 1702566000,
"end_ts": 1702652400,
"initial_balance": 10000,
"ai_model_id": "model_001"
}
}
# 获取权益曲线
GET /backtest/equity?run_id=bt_20231215&tf=1h&limit=1000
# 获取指标
GET /backtest/metrics?run_id=bt_20231215
```
### 8.3 响应示例
```json
// 状态响应
{
"run_id": "bt_20231215",
"state": "running",
"progress_pct": 45.5,
"processed_bars": 1234,
"equity": 10234.50,
"unrealized_pnl": 234.50
}
// 指标响应
{
"total_return_pct": 12.34,
"max_drawdown_pct": 5.67,
"sharpe_ratio": 1.89,
"profit_factor": 2.34,
"win_rate": 65.5,
"trades": 123
}
```
---
## 9. 账户与持仓管理
**核心文件:** `backtest/account.go`
### 9.1 持仓结构
```go
type position struct {
Symbol string
Side string // "long" 或 "short"
Quantity float64
EntryPrice float64
Leverage int
Margin float64 // 保证金
Notional float64 // 名义价值
LiquidationPrice float64 // 爆仓价格
OpenTime int64
}
```
### 9.2 开仓逻辑
```go
// backtest/account.go:61-104
func (a *BacktestAccount) Open(symbol, side string, qty, price float64, leverage int) {
// 1. 应用滑点
// 2. 计算名义价值 (qty × price)
// 3. 计算保证金 (notional / leverage)
// 4. 扣除保证金 + 手续费
// 5. 创建/加仓
// 6. 计算爆仓价格
}
```
### 9.3 平仓逻辑
```go
// backtest/account.go:106-140
func (a *BacktestAccount) Close(symbol, side string, qty, price float64) {
// 1. 验证持仓存在
// 2. 应用滑点 (反向)
// 3. 计算已实现盈亏
// long: (exit - entry) × qty
// short: (entry - exit) × qty
// 4. 返还保证金 + 盈亏 - 手续费
// 5. 更新/删除持仓
}
```
### 9.4 爆仓价格计算
```go
// backtest/account.go:177-186
func computeLiquidation(entry float64, leverage int, side string) float64 {
if side == "long" {
return entry * (1 - 1.0/float64(leverage)) // 做多: 下跌爆仓
}
return entry * (1 + 1.0/float64(leverage)) // 做空: 上涨爆仓
}
```
---
## 10. 检查点与恢复
**核心文件:** `backtest/runner.go`
### 10.1 检查点结构
```json
{
"bar_index": 1234,
"bar_ts": 1702609200000,
"cash": 8000.00,
"equity": 10234.50,
"max_equity": 10500.00,
"max_drawdown_pct": 5.67,
"positions": [...],
"decision_cycle": 62,
"liquidated": false
}
```
### 10.2 检查点触发
```go
// backtest/runner.go:874-898
func (r *Runner) maybeCheckpoint() {
// 每 N 根 K 线保存
// 或每 N 秒保存
}
```
### 10.3 恢复流程
```go
func (r *Runner) RestoreFromCheckpoint() {
// 1. 加载检查点
// 2. 恢复账户状态
// 3. 恢复 K 线索引 (从下一根继续)
// 4. 恢复权益曲线、交易记录
}
```
---
## 核心文件索引
| 模块 | 文件 | 关键方法 |
|------|------|----------|
| **配置** | `backtest/config.go` | `BacktestConfig`, `Validate()` |
| **数据加载** | `backtest/datafeed.go` | `NewDataFeed()`, `loadAll()`, `BuildMarketData()` |
| **模拟引擎** | `backtest/runner.go` | `Start()`, `loop()`, `stepOnce()` |
| **决策** | `backtest/runner.go` | `buildDecisionContext()`, `invokeAIWithRetry()` |
| **执行** | `backtest/runner.go` | `executeDecision()` |
| **账户** | `backtest/account.go` | `Open()`, `Close()`, `TotalEquity()` |
| **指标** | `backtest/metrics.go` | `CalculateMetrics()` |
| **权益** | `backtest/equity.go` | `ResampleEquity()`, `LimitEquityPoints()` |
| **存储** | `backtest/storage.go` | `SaveCheckpoint()`, `appendEquityPoint()` |
| **数据库** | `store/backtest.go` | 表结构和 CRUD 操作 |
| **API** | `api/backtest.go` | HTTP 处理器 |
| **AI 缓存** | `backtest/aicache.go` | `Get()`, `Put()`, `save()` |
---
**文档版本:** 1.0.0
**最后更新:** 2025-01-15
docs/architecture/DEBATE_MODULE.md
+907
View File
@@ -0,0 +1,907 @@
# Debate Arena Module - Technical Documentation
## Overview
The Debate Arena is a collaborative AI decision-making system where multiple AI models with different personalities debate market conditions and reach consensus on trading decisions. The system supports multi-round debates, real-time streaming, voting mechanisms, and automatic trade execution.
## Table of Contents
1. [Architecture Overview](#1-architecture-overview)
2. [Backend Components](#2-backend-components)
3. [Debate Execution Flow](#3-debate-execution-flow)
4. [Personality System](#4-personality-system)
5. [Consensus Algorithm](#5-consensus-algorithm)
6. [Auto-Execution](#6-auto-execution)
7. [API Reference](#7-api-reference)
8. [Real-Time Updates (SSE)](#8-real-time-updates-sse)
9. [Database Schema](#9-database-schema)
10. [Frontend Components](#10-frontend-components)
11. [Integration Points](#11-integration-points)
12. [Error Handling](#12-error-handling)
---
## 1. Architecture Overview
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Debate Arena System │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Bull AI │ │ Bear AI │ │ Analyst AI │ │ Risk Mgr AI │ │
│ │ 🐂 │ │ 🐻 │ │ 📊 │ │ 🛡️ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └──────────────────┴──────────────────┴──────────────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Debate Engine │ │
│ │ (debate/engine) │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌──────────────────────────┼──────────────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌─────────▼─────────┐ ┌────────▼────────┐ │
│ │ Market Data │ │ Voting System │ │ Auto-Executor │ │
│ │ Assembly │ │ & Consensus │ │ (optional) │ │
│ └─────────────┘ └───────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### File Structure
```
├── debate/
│ └── engine.go # Core debate engine logic
├── api/
│ └── debate.go # HTTP handlers and SSE streaming
├── store/
│ └── debate.go # Database operations and schema
└── web/src/pages/
└── DebateArenaPage.tsx # Frontend UI
```
---
## 2. Backend Components
### 2.1 Core Files
| File | Purpose | Key Functions |
|------|---------|---------------|
| `debate/engine.go` | Core debate logic | `StartDebate()`, `runDebate()`, `collectVotes()`, `determineConsensus()` |
| `api/debate.go` | HTTP handlers | `HandleCreateDebate()`, `HandleStartDebate()`, `HandleDebateStream()` |
| `store/debate.go` | Database ops | `CreateSession()`, `AddMessage()`, `AddVote()`, `GetSessionWithDetails()` |
### 2.2 Debate Engine Structure
```go
// debate/engine.go
type DebateEngine struct {
store *store.DebateStore
aiClients map[string]ai.Client
strategyEngine *strategy.Engine
subscribers map[string]map[chan []byte]bool
}
// Event callbacks for real-time updates
var OnRoundStart func(sessionID string, round int)
var OnMessage func(sessionID string, msg *DebateMessage)
var OnVote func(sessionID string, vote *DebateVote)
var OnConsensus func(sessionID string, decision *DebateDecision)
var OnError func(sessionID string, err error)
```
---
## 3. Debate Execution Flow
### 3.1 Session Creation
```
POST /api/debates
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Validate user authentication │
│ 2. Parse CreateDebateRequest: │
│ - name, strategy_id, symbol, max_rounds, participants │
│ - interval_minutes, prompt_variant, auto_execute │
│ 3. Validate strategy ownership │
│ 4. Auto-select symbol if not provided: │
│ - Static coins → Use first coin from strategy │
│ - CoinPool → Fetch from AI500 API │
│ - OI Top → Fetch from OI ranking API │
│ - Mixed → Try pool first, fallback to OI │
│ 5. Set defaults: │
│ - max_rounds: 3 (range 2-5) │
│ - interval_minutes: 5 │
│ - prompt_variant: "balanced" │
│ 6. Create DebateSession in database │
│ 7. Add participants with AI models and personalities │
│ 8. Return full session with participants │
└─────────────────────────────────────────────────────────────┘
```
### 3.2 Debate Start
**Location:** `debate/engine.go:StartDebate()` (Lines 114-154)
```
POST /api/debates/:id/start
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Validate session status (must be pending) │
│ 2. Validate participants (minimum 2) │
│ 3. Initialize AI clients for all participants │
│ 4. Get strategy configuration │
│ 5. Update status to "running" │
│ 6. Launch goroutine: runDebate() │
└─────────────────────────────────────────────────────────────┘
```
### 3.3 Market Context Building
**Location:** `debate/engine.go:buildMarketContext()` (Lines 292-362)
```
┌─────────────────────────────────────────────────────────────┐
│ buildMarketContext() │
├─────────────────────────────────────────────────────────────┤
│ 1. Get candidate coins from strategy engine │
│ 2. Fetch market data for each candidate: │
│ - Multiple timeframes (15m, 1h, 4h) │
│ - K-line count from strategy config │
│ - OHLCV data, indicators │
│ 3. Fetch quantitative data batch: │
│ - Capital flow │
│ - Position changes │
│ 4. Fetch OI ranking data (market-wide) │
│ 5. Build Context object with: │
│ - Account info (simulated: $1000 equity) │
│ - Candidate coins │
│ - Market data map │
│ - Quant data map │
│ - OI ranking data │
└─────────────────────────────────────────────────────────────┘
```
### 3.4 Debate Rounds
**Location:** `debate/engine.go:runDebate()` (Lines 157-289)
```
┌─────────────────────────────────────────────────────────────┐
│ For each round (1 to max_rounds): │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 1. Broadcast "round_start" event │ │
│ │ 2. For each participant (in speak_order): │ │
│ │ ┌─────────────────────────────────────────────────┐ │ │
│ │ │ a. Build personality-enhanced system prompt │ │ │
│ │ │ b. Build user prompt with: │ │ │
│ │ │ - Market data (from strategy engine) │ │ │
│ │ │ - Previous debate messages (if round > 1) │ │ │
│ │ │ c. Call AI model with 60s timeout │ │ │
│ │ │ d. Parse multi-coin decisions from response │ │ │
│ │ │ e. Save message to database │ │ │
│ │ │ f. Broadcast "message" event │ │ │
│ │ └─────────────────────────────────────────────────┘ │ │
│ │ 3. Broadcast "round_end" event │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ After all rounds: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 1. Enter voting phase (status = "voting") │ │
│ │ 2. Collect final votes from all participants │ │
│ │ 3. Determine multi-coin consensus │ │
│ │ 4. Store final decisions │ │
│ │ 5. Update status to "completed" │ │
│ │ 6. Broadcast "consensus" event │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## 4. Personality System
### 4.1 Available Personalities
| Personality | Emoji | Name | Description | Trading Bias |
|------------|-------|------|-------------|--------------|
| Bull | 🐂 | Aggressive Bull | Looks for long opportunities | Optimistic, trend-following |
| Bear | 🐻 | Cautious Bear | Skeptical, focuses on risks | Pessimistic, short bias |
| Analyst | 📊 | Data Analyst | Neutral, purely data-driven | No bias, objective analysis |
| Contrarian | 🔄 | Contrarian | Challenges majority view | Alternative perspectives |
| Risk Manager | 🛡️ | Risk Manager | Focus on risk control | Position sizing, stop loss |
### 4.2 Personality Prompt Enhancement
**Location:** `debate/engine.go:buildDebateSystemPrompt()` (Lines 365-426)
```
## DEBATE MODE - ROUND {round}/{max_rounds}
You are participating as {emoji} {personality}.
### Your Debate Role:
{personality_description}
### Debate Rules:
1. Analyze ALL candidate coins
2. Support arguments with specific data
3. Respond to other participants (round > 1)
4. Be persuasive but data-driven
5. Can recommend multiple coins with different actions
### Output Format (STRICT JSON):
<reasoning>
- Market analysis with data references
- Main trading thesis
- Response to others (if round > 1)
</reasoning>
<decision>
[
{"symbol": "BTCUSDT", "action": "open_long", "confidence": 75, ...},
{"symbol": "ETHUSDT", "action": "open_short", "confidence": 80, ...}
]
</decision>
```
### 4.3 Personality-Specific Prompts
**Bull (🐂):**
```
As a bull, you are optimistic about market trends.
Look for long opportunities, identify bullish patterns,
and support your thesis with technical and fundamental data.
Focus on: breakout patterns, momentum, support levels.
```
**Bear (🐻):**
```
As a bear, you are cautious and skeptical.
Look for short opportunities, identify bearish patterns,
and highlight risks and potential downside.
Focus on: resistance levels, divergences, overbought conditions.
```
**Analyst (📊):**
```
As a data analyst, you are completely neutral.
Provide objective analysis based purely on data.
No emotional bias - let the numbers speak.
Focus on: key metrics, statistical patterns, historical comparisons.
```
**Contrarian (🔄):**
```
As a contrarian, challenge the majority view.
Look for overlooked opportunities and hidden risks.
Play devil's advocate to strengthen the debate.
Focus on: crowd positioning, sentiment extremes, neglected signals.
```
**Risk Manager (🛡️):**
```
As a risk manager, focus on capital preservation.
Evaluate position sizing, stop loss levels, and risk/reward ratios.
Ensure all decisions have appropriate risk controls.
Focus on: max drawdown, position limits, volatility-adjusted sizing.
```
---
## 5. Consensus Algorithm
### 5.1 Vote Collection
**Location:** `debate/engine.go:collectVotes()` (Lines 542-567)
```
For each participant:
┌─────────────────────────────────────────────────────────────┐
│ 1. Build voting system prompt │
│ 2. Build voting user prompt with debate summary │
│ 3. Call AI model for final vote │
│ 4. Parse multi-coin decisions │
│ 5. Validate/fix symbols against session.Symbol │
│ 6. Save vote to database │
│ 7. Broadcast "vote" event │
└─────────────────────────────────────────────────────────────┘
```
### 5.2 Multi-Coin Consensus Determination
**Location:** `debate/engine.go:determineMultiCoinConsensus()` (Lines 752-924)
**Algorithm:**
```
1. Collect all coin decisions from all votes
2. Group by: symbol → action → aggregated data
3. For each vote decision:
weight = confidence / 100.0
Accumulate:
┌─────────────────────────────────────────────────────────┐
│ score += weight │
│ total_confidence += confidence │
│ total_leverage += leverage │
│ total_position_pct += position_pct │
│ total_stop_loss += stop_loss │
│ total_take_profit += take_profit │
│ count++ │
└─────────────────────────────────────────────────────────┘
4. For each symbol:
Find winning action (max score)
Calculate averages:
┌─────────────────────────────────────────────────────────┐
│ avg_confidence = total_confidence / count │
│ avg_leverage = clamp(total_leverage / count, 1, 20) │
│ avg_position_pct = clamp(total_pct / count, 0.1, 1.0) │
│ avg_stop_loss = default 3% if not set │
│ avg_take_profit = default 6% if not set │
└─────────────────────────────────────────────────────────┘
5. Return array of consensus decisions
```
### 5.3 Consensus Example
**Input Votes:**
```
AI1 (Bull): BTC open_long (conf=80, lev=10, pos=0.3)
AI2 (Bear): BTC open_short (conf=60, lev=5, pos=0.2)
AI3 (Analyst): BTC open_long (conf=70, lev=8, pos=0.25)
```
**Calculation:**
```
open_long:
score = 0.80 + 0.70 = 1.50
avg_conf = (80 + 70) / 2 = 75
avg_lev = (10 + 8) / 2 = 9
avg_pos = (0.3 + 0.25) / 2 = 0.275
open_short:
score = 0.60
avg_conf = 60
avg_lev = 5
avg_pos = 0.2
Winner: open_long (score 1.50 > 0.60)
```
**Output:**
```json
{
"symbol": "BTCUSDT",
"action": "open_long",
"confidence": 75,
"leverage": 9,
"position_pct": 0.275,
"stop_loss": 0.03,
"take_profit": 0.06
}
```
---
## 6. Auto-Execution
### 6.1 Execution Flow
**Location:** `debate/engine.go:ExecuteConsensus()` (Lines 932-1052)
```
POST /api/debates/:id/execute
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Validate session status = completed │
│ 2. Validate final_decision exists and not executed │
│ 3. Validate action is open_long or open_short │
│ 4. Get current market price │
│ 5. Get account balance: │
│ - Try available_balance │
│ - Fallback to total_equity or wallet_balance │
│ 6. Calculate position size: │
│ position_size_usd = available_balance × position_pct │
│ (minimum $12 to meet exchange requirements) │
│ 7. Calculate stop loss and take profit prices: │
│ ┌───────────────────────────────────────────────────┐ │
│ │ open_long: │ │
│ │ SL = price × (1 - stop_loss_pct) │ │
│ │ TP = price × (1 + take_profit_pct) │ │
│ │ open_short: │ │
│ │ SL = price × (1 + stop_loss_pct) │ │
│ │ TP = price × (1 - take_profit_pct) │ │
│ └───────────────────────────────────────────────────┘ │
│ 8. Create Decision object │
│ 9. Call executor.ExecuteDecision() │
│ 10. Update final_decision: │
│ - executed = true/false │
│ - executed_at = timestamp │
│ - error message if failed │
└─────────────────────────────────────────────────────────────┘
```
### 6.2 Position Size Calculation
```go
// Calculate position value
position_size_usd := available_balance * position_pct
// Ensure minimum size for exchange
if position_size_usd < 12 {
position_size_usd = 12
}
// Calculate quantity
quantity := position_size_usd / market_price
```
---
## 7. API Reference
### 7.1 Endpoints
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/debates` | List all debates for user |
| GET | `/api/debates/personalities` | Get AI personality configs |
| GET | `/api/debates/:id` | Get debate with full details |
| POST | `/api/debates` | Create new debate |
| POST | `/api/debates/:id/start` | Start debate execution |
| POST | `/api/debates/:id/cancel` | Cancel running debate |
| POST | `/api/debates/:id/execute` | Execute consensus trade |
| DELETE | `/api/debates/:id` | Delete debate |
| GET | `/api/debates/:id/messages` | Get all messages |
| GET | `/api/debates/:id/votes` | Get all votes |
| GET | `/api/debates/:id/stream` | SSE live stream |
### 7.2 Create Debate Request
```json
POST /api/debates
{
"name": "BTC Market Debate",
"strategy_id": "strategy-uuid",
"symbol": "BTCUSDT",
"max_rounds": 3,
"interval_minutes": 5,
"prompt_variant": "balanced",
"auto_execute": false,
"trader_id": "trader-uuid",
"enable_oi_ranking": true,
"oi_ranking_limit": 10,
"oi_duration": "1h",
"participants": [
{"ai_model_id": "deepseek-v3", "personality": "bull"},
{"ai_model_id": "qwen-max", "personality": "bear"},
{"ai_model_id": "gpt-5.2", "personality": "analyst"}
]
}
```
### 7.3 Create Debate Response
```json
{
"id": "debate-uuid",
"user_id": "user-uuid",
"name": "BTC Market Debate",
"strategy_id": "strategy-uuid",
"status": "pending",
"symbol": "BTCUSDT",
"max_rounds": 3,
"current_round": 0,
"participants": [
{
"id": "participant-uuid",
"ai_model_id": "deepseek-v3",
"ai_model_name": "DeepSeek V3",
"provider": "deepseek",
"personality": "bull",
"color": "#22C55E",
"speak_order": 0
}
],
"messages": [],
"votes": [],
"created_at": "2025-12-15T12:00:00Z"
}
```
### 7.4 Execute Consensus Request
```json
POST /api/debates/:id/execute
{
"trader_id": "trader-uuid"
}
```
---
## 8. Real-Time Updates (SSE)
### 8.1 SSE Endpoint
**Location:** `api/debate.go:HandleDebateStream()` (Lines 407-453)
```
GET /api/debates/:id/stream
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Validate user ownership │
│ 2. Set SSE headers: │
│ Content-Type: text/event-stream │
│ Cache-Control: no-cache │
│ Connection: keep-alive │
│ 3. Send initial state │
│ 4. Subscribe to events │
│ 5. Stream updates until client disconnects │
└─────────────────────────────────────────────────────────────┘
```
### 8.2 Event Types
| Event | Trigger | Data |
|-------|---------|------|
| `initial` | Connection start | Full session state |
| `round_start` | Round begins | `{round, status}` |
| `message` | AI speaks | DebateMessage object |
| `round_end` | Round complete | `{round, status}` |
| `vote` | AI votes | DebateVote object |
| `consensus` | Debate complete | DebateDecision object |
| `error` | Error occurs | `{error: string}` |
### 8.3 SSE Message Format
```
event: message
data: {"id":"msg-uuid","session_id":"session-uuid","round":1,"ai_model_name":"DeepSeek V3","personality":"bull","content":"...","decision":{"action":"open_long","symbol":"BTCUSDT","confidence":75}}
event: vote
data: {"id":"vote-uuid","session_id":"session-uuid","ai_model_name":"DeepSeek V3","action":"open_long","symbol":"BTCUSDT","confidence":80,"reasoning":"..."}
event: consensus
data: {"action":"open_long","symbol":"BTCUSDT","confidence":75,"leverage":8,"position_pct":0.25,"stop_loss":0.03,"take_profit":0.06}
```
---
## 9. Database Schema
### 9.1 Tables
**debate_sessions:**
```sql
CREATE TABLE debate_sessions (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
name TEXT NOT NULL,
strategy_id TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
symbol TEXT NOT NULL,
max_rounds INTEGER DEFAULT 3,
current_round INTEGER DEFAULT 0,
interval_minutes INTEGER DEFAULT 5,
prompt_variant TEXT DEFAULT 'balanced',
final_decision TEXT,
final_decisions TEXT,
auto_execute BOOLEAN DEFAULT 0,
trader_id TEXT,
enable_oi_ranking BOOLEAN DEFAULT 0,
oi_ranking_limit INTEGER DEFAULT 10,
oi_duration TEXT DEFAULT '1h',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```
**debate_participants:**
```sql
CREATE TABLE debate_participants (
id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
ai_model_id TEXT NOT NULL,
ai_model_name TEXT NOT NULL,
provider TEXT NOT NULL,
personality TEXT NOT NULL,
color TEXT NOT NULL,
speak_order INTEGER DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (session_id) REFERENCES debate_sessions(id) ON DELETE CASCADE
);
```
**debate_messages:**
```sql
CREATE TABLE debate_messages (
id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
round INTEGER NOT NULL,
ai_model_id TEXT NOT NULL,
ai_model_name TEXT NOT NULL,
provider TEXT NOT NULL,
personality TEXT NOT NULL,
message_type TEXT NOT NULL,
content TEXT NOT NULL,
decision TEXT,
decisions TEXT,
confidence INTEGER DEFAULT 0,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (session_id) REFERENCES debate_sessions(id) ON DELETE CASCADE
);
```
**debate_votes:**
```sql
CREATE TABLE debate_votes (
id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
ai_model_id TEXT NOT NULL,
ai_model_name TEXT NOT NULL,
action TEXT NOT NULL,
symbol TEXT NOT NULL,
confidence INTEGER DEFAULT 0,
leverage INTEGER DEFAULT 5,
position_pct REAL DEFAULT 0.2,
stop_loss_pct REAL DEFAULT 0.03,
take_profit_pct REAL DEFAULT 0.06,
reasoning TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (session_id) REFERENCES debate_sessions(id) ON DELETE CASCADE
);
```
### 9.2 Key Store Methods
| Method | Description |
|--------|-------------|
| `CreateSession()` | Create new debate session |
| `GetSession()` | Get session by ID |
| `GetSessionWithDetails()` | Get session with participants, messages, votes |
| `UpdateSessionStatus()` | Update session status |
| `UpdateSessionRound()` | Update current round |
| `UpdateSessionFinalDecisions()` | Store consensus decisions |
| `AddParticipant()` | Add AI participant |
| `AddMessage()` | Store debate message |
| `AddVote()` | Store final vote |
---
## 10. Frontend Components
### 10.1 Page Structure
**Location:** `web/src/pages/DebateArenaPage.tsx`
```
DebateArenaPage
├── Left Sidebar (w-56)
│ ├── New Debate Button
│ ├── Debate Sessions List
│ │ └── SessionItem (status, name, timestamp)
│ └── Online Traders List
│ └── TraderItem (name, status, AI model)
│
├── Main Content
│ ├── Header Bar
│ │ ├── Session Info (name, status, symbol)
│ │ ├── Participants Avatars
│ │ └── Vote Summary
│ │
│ ├── Content Area (two-column)
│ │ ├── Left: Discussion Records
│ │ │ ├── Round Headers
│ │ │ └── MessageCards (expandable)
│ │ │
│ │ └── Right: Final Votes
│ │ └── VoteCards (action, confidence, reasoning)
│ │
│ └── Consensus Bar
│ ├── Final Decision Display
│ └── Execute Button (if auto_execute disabled)
│
└── Modals
├── CreateModal
│ ├── Name Input
│ ├── Strategy Selector
│ ├── Symbol Input (auto-filled)
│ ├── Max Rounds Selector
│ └── Participant Picker (AI model + personality)
│
└── ExecuteModal
└── Trader Selector
```
### 10.2 UI Components
**MessageCard:**
- Expandable message display
- Shows AI avatar, personality emoji, decision
- Parses reasoning/analysis sections from content
- Displays decision details (leverage, position, SL/TP)
- Supports multi-coin decisions
**VoteCard:**
- Confidence bar visualization
- Action indicator (long/short/hold/wait)
- Leverage and position size display
- Stop loss and take profit display
- Reasoning preview
### 10.3 Status Colors
```typescript
const STATUS_COLOR = {
pending: 'bg-gray-500',
running: 'bg-blue-500 animate-pulse',
voting: 'bg-yellow-500 animate-pulse',
completed: 'bg-green-500',
cancelled: 'bg-red-500',
}
```
### 10.4 Action Styling
```typescript
const ACT = {
open_long: {
color: 'text-green-400',
bg: 'bg-green-500/20',
icon: <TrendingUp />,
label: 'LONG'
},
open_short: {
color: 'text-red-400',
bg: 'bg-red-500/20',
icon: <TrendingDown />,
label: 'SHORT'
},
hold: {
color: 'text-blue-400',
bg: 'bg-blue-500/20',
icon: <Minus />,
label: 'HOLD'
},
wait: {
color: 'text-gray-400',
bg: 'bg-gray-500/20',
icon: <Clock />,
label: 'WAIT'
},
}
```
### 10.5 Personality Colors
```typescript
const PERS = {
bull: { emoji: '🐂', color: '#22C55E', name: '多头', nameEn: 'Bull' },
bear: { emoji: '🐻', color: '#EF4444', name: '空头', nameEn: 'Bear' },
analyst: { emoji: '📊', color: '#3B82F6', name: '分析', nameEn: 'Analyst' },
contrarian: { emoji: '🔄', color: '#F59E0B', name: '逆势', nameEn: 'Contrarian' },
risk_manager: { emoji: '🛡️', color: '#8B5CF6', name: '风控', nameEn: 'Risk Mgr' },
}
```
---
## 11. Integration Points
### 11.1 Strategy System
Debate sessions depend on saved strategies for:
- **Coin source configuration:** static/pool/OI top
- **Market data indicators:** K-lines, timeframes, technical indicators
- **Risk control parameters:** leverage limits, position sizing
- **Custom prompts:** role definition, trading rules
### 11.2 AI Model System
Each participant requires:
- AI model configuration (provider, API key, custom URL)
- Supported providers: deepseek, qwen, openai, claude, gemini, grok, kimi
- Client initialization with timeout handling (60s per call)
### 11.3 Trader System
For auto-execution:
- Requires active trader with running status
- Trader must have valid exchange connection
- Executor interface: `ExecuteDecision()`, `GetBalance()`
### 11.4 Market Data
Market context building uses:
- Market data service (K-lines, OHLCV)
- Quantitative data (capital flow, position changes)
- OI ranking data (market-wide position changes)
---
## 12. Error Handling
### 12.1 Cleanup on Startup
**Location:** `debate/engine.go:cleanupStaleDebates()` (Lines 58-71)
```go
// On server restart, cancel all running/voting debates
func cleanupStaleDebates() {
sessions := debateStore.ListAllSessions()
for _, session := range sessions {
if session.Status == running || session.Status == voting {
debateStore.UpdateSessionStatus(session.ID, cancelled)
}
}
}
```
### 12.2 AI Call Timeout
```go
// 60 seconds per participant response
select {
case res := <-resultCh:
response = res.response
case <-time.After(60 * time.Second):
return nil, fmt.Errorf("AI call timeout")
}
```
### 12.3 Symbol Validation
```go
// Force all decisions to use session symbol if specified
if session.Symbol != "" {
for _, d := range decisions {
if d.Symbol == "" || d.Symbol != session.Symbol {
logger.Warnf("Fixing invalid symbol '%s' -> '%s'", d.Symbol, session.Symbol)
d.Symbol = session.Symbol
}
}
}
```
### 12.4 Panic Recovery
```go
defer func() {
if r := recover(); r != nil {
logger.Errorf("Debate panic: %v", r)
debateStore.UpdateSessionStatus(sessionID, cancelled)
if OnError != nil {
OnError(sessionID, fmt.Errorf("panic: %v", r))
}
}
}()
```
---
## Summary
The Debate Arena module provides a sophisticated multi-AI collaborative decision system with:
- **Multi-Personality Debate:** 5 distinct AI personalities (Bull, Bear, Analyst, Contrarian, Risk Manager) with unique trading biases
- **Consensus Mechanism:** Weighted voting based on confidence levels to determine final decisions
- **Real-Time Updates:** SSE streaming for live debate progress
- **Auto-Execution:** Optional automatic trade execution based on consensus
- **Strategy Integration:** Deep integration with strategy configuration for market data and risk parameters
- **Multi-Coin Support:** Ability to analyze and decide on multiple coins simultaneously
The system enables users to leverage multiple AI perspectives for more robust trading decisions while maintaining full control over execution.