CryptoTrader AI

简体中文 · English

基于 LangGraph 多智能体辩论的 AI 加密货币交易系统。

概述

4 个专业 AI 智能体（技术面、链上数据、新闻情绪、宏观经济）独立分析市场数据，然后通过交叉挑战辩论轮次达成共识。硬编码的风控门（11 项规则检查，不依赖 LLM）强制执行仓位限制、损失限制和熔断机制。每个决策都记录在类 Git 的决策日志中，便于审计和基于经验的学习。

每个智能体在输出信号前都会运行领域专属的预信号检查清单（受 Devin 的先思后行模式启发），以减少过度自信和幻觉。

核心特性

• 多智能体辩论 — 4 个智能体独立分析后，经辩论门控渐进过滤：共识或迷茫时跳过辩论，否则进入 2-3 轮并行交叉质疑
• 三种图模式 — 完整辩论流程（含辩论门控）、轻量回测、多空对抗+评委
• 11 项风控检查 — 纯规则，零 LLM：仓位限制、CVaR、相关性、熔断器
• 决策日志链 — 类 Git 不可变提交链，支持相似搜索和校准分析
• 语言强化 — 将历史决策经验注入智能体 prompt，实现经验学习
• 结构化经验记忆 — GSSC 流水线（汇集→选择→结构化）将历史经验注入智能体 prompt，含 regime 感知搜索和防过拟合五层防线
• 回测引擎 — 历史模拟，含真实成本建模和防前视偏差
• 实盘就绪 — 基于 ccxt 的交易所适配器，带重试、精度处理和超时控制
• APScheduler 自动化 — 周期性交易循环 + 每日组合摘要
• 61+ 数据源 — 统一 SQLite 存储，覆盖 7 个类别，按源独立限速

系统架构

数据采集 → 语言强化注入 → 4 智能体（并行）
  → 辩论门控 → [跳过] → 上下文丰富 → 裁决
             → [辩论] → 2 轮辩论（轮内并行）
  → 裁决 → 风控门（11 项检查）→ 执行 / 拒绝 → 日志记录
                                  ↓
                        持仓回写 → 快照保存

三种图模式：

• build_trading_graph() — 完整流程，含辩论门控（共识/迷茫时跳过辩论）、2 轮辩论、AI 裁决可降级
• build_lite_graph() — 跳过辩论，用于回测
• build_debate_graph() — 多空对抗辩论 + 评委（TradingAgents 风格）

智能体分工

• BaseAgent：单次 LLM 调用，结构化 JSON 输出
• ToolAgent：LangChain 代理，带工具调用循环，可实时查询数据（回测模式下降级为单次调用，避免前视偏差）

每个智能体的系统提示都包含 5 点预信号检查清单：矛盾检查、证据落地、信心合理性、基准概率意识、近因偏差防范。data_sufficiency="low" 时信心值上限为 0.3。

辩论流程

1. 第 1 轮：4 个智能体独立分析
2. 辩论门控：评估智能体共识程度；达成共识或极度迷茫时跳过辩论直接进入裁决，否则进入辩论轮次
3. 第 2-3 轮（轮内并行）：每个智能体看到其他人的分析结果，必须用具体数据点支持自己保持或修改立场
4. 收敛检查：每轮计算分歧度（confidence × direction 的总体标准差），相对变化 < 10% 或达到最大轮数时停止
5. 裁决：单个 LLM（temperature=0.1）综合所有智能体输出、持仓上下文（空仓/多头/空头、入场价、浮动盈亏）、价格趋势和风控约束 → 输出 {action, confidence, position_scale, reasoning, thesis, invalidation}

学习系统

• GSSC 流水线：verbal.py（regime 感知搜索）+ reflect.py（结构化规则生成）→ context.py（汇集 → 选择 → 结构化）→ 注入智能体 prompt
• Regime 感知搜索：tag_regime() 将当前快照分类为离散标签（high_funding、high_vol、trending_up、extreme_fear 等），通过 Jaccard 重叠度检索最相关的历史案例
• 结构化经验记忆：LLM 将历史案例提炼为 ExperienceMemory（成功模式、禁止区域、战略洞见），支持增量演化和 maturity 分级（observation → hypothesis → rule）
• 防过拟合五层防线：最小样本阈值、maturity 分级、regime 感知验证、LLM 约束 prompt、代码核验胜率
• 校准分析：逐智能体准确率追踪 + 偏差检测（过度自信、方向偏好、中性默认）。校正信息注入裁决 prompt

快速开始

前置条件

• Python 3.12+
• uv 包管理器
• 一个兼容 OpenAI 的 LLM API Key（OpenAI、Anthropic、DeepSeek 等）

安装

# 克隆并安装
git clone https://github.com/your-org/cryptotrader-ai.git
cd cryptotrader-ai
uv sync

# 配置 LLM 端点
cp config/default.toml config/local.toml
# 编辑 config/local.toml：设置 [llm] api_key 和 base_url

# 或使用环境变量
export OPENAI_API_KEY=your_key

首次运行

# 运行单次分析（模拟交易）
arena run --pair BTC/USDT --mode paper

# 多交易对分析（完整辩论）
arena run --pair BTC/USDT --pair ETH/USDT --graph full

# 查看决策日志
arena journal log --limit 10
arena journal show <hash>

回测

# AI 智能体回测
arena backtest --pair BTC/USDT --start 2024-01-01 --end 2024-06-01 --interval 4h

# 快速 SMA 交叉回测（无 LLM 调用）
arena backtest --pair BTC/USDT --start 2024-01-01 --end 2024-06-01 --no-llm

# 先同步历史数据，回测数据更丰富
arena sync

回测引擎特性：

• 防前视偏差：bar[i] 生成信号，bar[i+1] 开盘执行
• 真实成本：可配置滑点（5 bps）+ 手续费（10 bps）
• 动态仓位：高信心 35%、中等 12%、低 6%
• 丰富数据：ETF 流量、OI、多空比、DeFi TVL、VIX、S&P500、稳定币供应、哈希率
• 指标输出：总收益、夏普比率（365 天年化）、最大回撤、胜率、权益曲线

调度器

# 启动周期性交易循环（需 config 中 scheduler.enabled=true）
arena scheduler start

# 查看组合状态
arena scheduler status

基于 APScheduler，IntervalTrigger（默认 4 小时）执行交易循环，CronTrigger 发送每日组合摘要。

仪表盘 & API

# Web 前端（React + Vite）
arena web --port 5173

# FastAPI 服务
arena serve --port 8003

CLI 命令参考

数据源

行情与链上

5 个数据源，支持优雅降级（无 API Key 也能运行）：

新闻与情绪

宏观

统一数据存储

所有数据缓存在 ~/.cryptotrader/market_data.db（SQLite，WAL 模式）：

• 61+ 数据源，覆盖 7 个类别（宏观、链上、衍生品、DeFi、情绪、ETF、稳定币）
• 按源独立限速（5 分钟到 1 小时 TTL）
• 交易日数据前向填充（FRED、ETF），处理周末和假期
• arena sync 批量拉取全部历史数据用于回测

配置

配置文件

config/
├── default.toml          # 主配置（模式、模型、风控、调度器、数据源）
├── local.toml            # 本地覆盖（API Key，已 gitignore）
└── exchanges.toml.example  # 交易所凭证模板

先加载 default.toml，再深度合并 local.toml。首次加载后全局缓存。

关键配置段

[llm]
api_key = ""           # 统一 LLM API Key
base_url = ""          # API 端点（如 "http://localhost:3000/v1"）

[models]               # 按角色选择模型 — 模型名必须存在于 LLM 网关
analysis = "deepseek-v4-flash"
debate = "deepseek-v4-flash"
verdict = "gpt-5.5"
tech_agent = "deepseek-v4-flash"
chain_agent = "deepseek-v4-flash"
news_agent = "deepseek-v4-flash"
macro_agent = "deepseek-v4-flash"
fallback = "deepseek-v4-flash"
# 任何留空字段会回退到 models.analysis → models.fallback

[debate]
max_rounds = 3
convergence_threshold = 0.1
gate_consensus_threshold = 0.8   # 分歧度低于此值时跳过辩论（共识）
gate_confusion_threshold = 0.05  # 分歧度高于此值时跳过辩论（迷茫）

[risk]
max_stop_loss_pct = 0.05
[risk.position]
max_single_pct = 0.10
max_total_exposure_pct = 0.50
[risk.loss]
max_daily_loss_pct = 0.03
max_drawdown_pct = 0.10

[scheduler]
enabled = false
pairs = ["BTC/USDT", "ETH/USDT"]
interval_minutes = 240
exchange_id = "binance"
daily_summary_hour = 0    # UTC 小时（0-23）

[experience]
enabled = true
every_n_cycles = 20
token_budget = 2000              # 注入 prompt 的 token 上限
win_rate_tolerance = 0.10        # 规则胜率容差（防过拟合验证）

[experience.regime_thresholds]
high_funding = 0.01
high_vol = 0.05
trending_up = 0.03
trending_down = -0.03
extreme_fear = 25
extreme_greed = 75

环境变量

# ── API 鉴权（生产必须）──
# 默认 AUTH_MODE=enabled — API_KEY 必须设置，否则进程启动失败。
# AUTH_MODE=disabled 仅作 dev opt-out（每请求打 WARNING 日志）。
AUTH_MODE=enabled
API_KEY=$(openssl rand -hex 32)

# ── 链上数据源（可选但推荐）──
# 缺 key 时 provider 返 None；chain_agent prompt 会被告知哪些数据源
# 不可用，自动降低 data_sufficiency。
COINGLASS_API_KEY=your_key
CRYPTOQUANT_API_KEY=your_key
WHALE_ALERT_API_KEY=your_key
FRED_API_KEY=your_key

# ── 基础设施（用 CRYPTOTRADER_INFRASTRUCTURE__* 前缀注入 config）──
CRYPTOTRADER_INFRASTRUCTURE__DATABASE_URL=postgresql+asyncpg://...
CRYPTOTRADER_INFRASTRUCTURE__REDIS_URL=redis://localhost:6379

# ── 前端（生产构建拒绝 VITE_API_KEY）──
# 仅 dev .env.local 用一次性 hydrate 进 useSettingsStore
VITE_API_BASE_URL=http://localhost:8003
# VITE_API_KEY= （仅 dev；生产用户在 Settings UI 输入）

风控门

11 项规则检查（不依赖 LLM），全部可在 config/default.toml 的 [risk] 段配置：

close 动作（平仓）豁免全部风控检查 — 减仓是降低风险，不应被阻断。

通知

6 种事件类型的 Webhook 通知（在 config/default.toml 配置）：

API 端点

认证：默认 AUTH_MODE=enabled，API_KEY env 必须设置；缺失则进程启动失败。AUTH_MODE=disabled 仅作 dev opt-out（每请求 WARNING 日志）。所有比较使用 secrets.compare_digest（防时序攻击）。限流：60 次/分钟/IP，配置 Redis 时为多进程安全 fixed window；单进程 dev 降级内存。CORS：显式 allow_methods / allow_headers allowlist（与 allow_credentials=true 配合）。

执行层

模拟交易

• 默认模式，不涉及真实资金
• 可配置初始余额（默认 $10,000）
• 滑点模型：base + amount × price × 1e-8
• 通过 asyncio.Lock 保证线程安全

实盘交易

生产级加固的 LiveExchange，封装 ccxt：

• 重试机制：指数退避（3 次），致命错误不重试（认证、权限、余额不足）
• 余额预检：每次下单前验证可用余额
• 精度处理：应用交易所特定的 amount_to_precision() / price_to_precision()
• 最小下单量：检查交易所市场限制
• 超时控制：每 2 秒轮询，30 秒后自动撤单
• 飞行前检查：arena live-check 验证凭证、API 延迟、Redis 和数据库

# 验证实盘就绪状态
arena live-check --exchange binance

Docker 部署

# 启动全套服务（PostgreSQL 16 + Redis 7 + 应用 + 仪表盘 + 调度器）
docker compose up -d

# 服务清单：
#   app        — FastAPI :8003
#   web        — React 前端 :5173
#   scheduler  — 周期性交易循环
#   postgres   — 决策日志 + 组合持久化
#   redis      — 风控状态 + 冷却 + 熔断器

Dockerfile 使用多阶段构建 + 非 root 用户。健康检查每 30 秒轮询 /health。

项目结构

src/cryptotrader/
├── models.py          # 所有数据模型（DataSnapshot, AgentAnalysis, TradeVerdict, Order 等）
├── config.py          # TOML 配置加载 + 数据类验证
├── graph.py           # LangGraph 编排（3 种图模式）
├── state.py           # ArenaState TypedDict + build_initial_state() 工厂
├── scheduler.py       # APScheduler 周期性交易循环 + 每日摘要
├── notifications.py   # Webhook 通知（6 种事件）
├── db.py              # 共享 async DB session 工厂
├── data/
│   ├── store.py       # 统一 SQLite 存储（61+ 源，按源限速）
│   ├── snapshot.py    # SnapshotAggregator（数据聚合入口）
│   ├── market.py      # ccxt OHLCV + ticker + 资金费率 + 波动率
│   ├── onchain.py     # 聚合 5 个数据源（并行获取）
│   ├── news.py        # RSS + 关键词情绪 + CoinGecko 社交热度
│   ├── macro.py       # FRED + CoinGecko + 恐惧贪婪 + SoSoValue ETF
│   ├── sync.py        # 批量历史同步（arena sync）
│   └── providers/     # Binance, DefiLlama, CoinGlass, CryptoQuant, WhaleAlert, SoSoValue
├── agents/
│   ├── base.py        # BaseAgent + ToolAgent + create_llm() 工厂
│   ├── tech.py        # TechAgent（pandas-ta 指标）
│   ├── chain.py       # ChainAgent（ToolAgent + 链上工具）
│   ├── news.py        # NewsAgent（ToolAgent + 新闻工具）
│   ├── macro.py       # MacroAgent（宏观环境分析）
│   └── data_tools.py  # LangChain @tool 定义（6 链上 + 3 新闻）
├── debate/
│   ├── challenge.py   # 交叉挑战 prompt 构建
│   ├── convergence.py # 分歧度计算 + 收敛检测
│   ├── verdict.py     # AI 裁决（LLM）+ 规则裁决（回测）
│   └── researchers.py # 多空对抗辩论 + 评委
├── nodes/             # LangGraph 节点函数
│   ├── agents.py      # 4 智能体并行
│   ├── data.py        # 数据采集 + PnL 更新 + 趋势上下文
│   ├── debate.py      # 辩论轮次 + 收敛路由
│   ├── verdict.py     # 裁决 + 风控检查
│   ├── execution.py   # 下单 + 止损 + 仓位更新
│   └── journal.py     # 日志记录
├── risk/
│   ├── gate.py        # RiskGate（11 项顺序检查）
│   └── state.py       # RedisStateManager（含内存降级）
├── execution/
│   ├── simulator.py   # PaperExchange（模拟交易）
│   ├── exchange.py    # LiveExchange（ccxt，生产级加固）
│   ├── order.py       # OrderManager（状态机）
│   └── reconcile.py   # 仓位对账
├── portfolio/
│   └── manager.py     # PortfolioManager（DB + 内存）
├── journal/
│   ├── store.py       # JournalStore（PostgreSQL + 内存降级）
│   ├── search.py      # 相似搜索（资金费率、波动率、趋势）
│   └── calibrate.py   # 逐智能体准确率追踪 + 偏差检测
├── learning/
│   ├── verbal.py      # 语言强化（regime 感知历史案例检索）
│   ├── reflect.py     # 结构化经验记忆生成（ExperienceMemory JSON）
│   ├── context.py     # GSSC 引擎（汇集→选择→结构化，CJK 感知 token 估算）
│   └── regime.py      # regime 标签（tag_regime）+ Jaccard 重叠度匹配
└── backtest/
    ├── engine.py      # BacktestEngine（LLM + SMA 模式）
    ├── session.py     # 回测会话存储（commits.jsonl + result.json + experience.json）
    ├── cache.py       # OHLCV SQLite 缓存
    ├── historical_data.py  # FnG、资金费率、FRED、期货成交量
    └── result.py      # BacktestResult 指标
src/cli/main.py        # Typer CLI（arena 命令）
src/api/               # FastAPI 服务（认证、限流、中间件）
web/                   # React 19 + Vite 7 前端（仪表盘、决策、回测、风控、指标）

技术栈

开发

make install          # uv pip install -e ".[dev]"
make test             # pytest tests/ -v（347 个测试）
make lint             # ruff check src/ tests/
make format           # ruff format src/ tests/
make scheduler        # arena scheduler start
make pre-commit-run   # 运行所有 pre-commit 钩子

# 运行单个测试
uv run pytest tests/test_risk_gate.py -v
uv run pytest tests/test_risk_gate.py::test_max_position -v

# Docker 基础设施
docker compose up -d   # PostgreSQL 16 + Redis 7
arena migrate          # 创建数据库表
arena sync             # 同步历史数据

代码质量

• 零 lint 错误：ruff check src/ tests/ 必须零错误通过
• 禁止 noqa 注释：遇到 C901 必须重构（阈值 = 10）
• 347 个测试，1 个跳过，70% 覆盖率
• 异步测试：asyncio_mode = "auto" — 无需 @pytest.mark.asyncio
• 必须用 uv run pytest（Python 3.12 venv），不要用裸 pytest

许可证

MIT