基于 Bitget 实时行情与全球财经快讯的开源加密货币行情研究与交易终端 —— K 线终端、市场总览、筛币器、热力图、社区观点与快讯中心一体化。
中文 · English
免责声明：本项目仅用于学习与研究，不构成任何投资建议。当前版本聚焦行情数据与终端展示，不提供交易执行能力。
Trade-Agent 是一个全栈的加密货币行情研究与交易终端：
- 后端（Python / FastAPI）：通过 Bitget 官方 MCP 服务抓取 K 线历史并写入 PostgreSQL，通过公共 WebSocket 实时推送行情；提供指标 / 结构 / 支撑阻力分析，以及基于 AKShare / BlockBeats 的财经快讯管线。
- 前端（React 19 / Vite / TypeScript）：类 TradingView 的专业终端界面，包含行情仪表盘、市场总览、筛币器、热力图、社区观点、新闻中心等，全中文界面、支持暗/亮主题。
关于 AI Agent：本项目曾内置自研的 AI 交易智能体与 QUANT LAB 量化研究，二者已整体移除。现以 LangChain / LangGraph / Deep Agents 重建，遵循一条硬边界：LLM 只做前置的"深度市场研报与策略生成"，下单执行与硬风控由零 LLM 的确定性 LangGraph 状态图接管。
当前为 Phase 1（纸面闭环）：研究与执行均在独立 worker 进程内定时自治运行；执行走纸面 broker，不接实盘；checkpointer、JSON 存储（告警 / 图表配置 / BlockBeats 缓存 / 事件）与 K 线 / 智能体投影均已迁移到 PostgreSQL（独立的 compose
postgres服务，唯一持久层），作为跨进程恢复与查询的基础；人工审批（HITL）与跨进程恢复留待 Phase 2。启用研究层需提供模型凭据（MD_AGENT_MODEL+ 对应 provider API Key）；缺失时 worker 空转、不下单、不报错。
整个项目以 OpenSpec 规格驱动开发，历史功能均有对应规格与设计文档沉淀在 openspec/。
- 专业 K 线终端：
klinecharts-pro渲染，多周期 / 多图表联动、技术指标、SMC 结构分析、支撑阻力、绘图工具、价格预警线。 - 实时行情：Bitget 公共 WebSocket 推送 K 线 / 盘口 / Ticker，前端 WS 订阅协议（candle / books / ticker）。
- 市场总览与分析：市场总览、筛币器、热力图、社区观点；指标 / 结构 / 支撑阻力 REST 分析接口。
- 全球财经快讯：AKShare 聚合东财 / 新浪 / 同花顺 / 财联社 7×24 快讯，SSE 实时推送，主题自动分类，瀑布流 UI，支持历史分页。
- BlockBeats 快讯/数据：加密货币新闻流与数据缓存。
- 价格提醒：本地 + 服务端持久化告警。
- K 线历史：MCP / REST v2 / v3 深度历史回填，PostgreSQL 存储，增量调度，数据完整性校验。
- 全中文界面，暗/亮主题，响应式多市场（SPOT / USDT-FUTURES）。
| 层 | 技术 |
|---|---|
| 后端 | Python ≥ 3.11 · FastAPI · uvicorn · APScheduler · pandas / pyarrow · numpy · pydantic-settings · akshare · PostgreSQL（唯一持久层：K 线 / 告警 / 图表配置 / 事件 / 快讯缓存 / 智能体投影 / LangGraph checkpointer） |
| 数据接入 | Bitget Agent MCP（stdio）· Bitget 公共 WebSocket · REST v2/v3 |
| 前端 | React 19 · Vite 6 · TypeScript 5 · Tailwind CSS v4 · klinecharts + klinecharts-pro · Radix UI · motion · lucide-react · 自托管 Google Sans Flex / Noto Sans SC |
| 测试 | pytest（三层测试）· Vitest + Testing Library · Playwright（E2E） |
| 工程 | uv / pip · npm · OpenSpec 规格驱动开发 · GPL-3.0 |
┌────────────────────── 浏览器 · React 19 + Vite ──────────────────────┐
│ SuperCharts │ Markets │ Screener │ Heatmaps │ Community │ News │
│ klinecharts-pro · i18n(中文) · Tailwind v4 · dark/light │
└───────────────────────┬─────────────────────────┬──────────────────┘
│ /api (vite proxy) │ /ws
┌───────────────────────▼─────────────────────────▼──────────────────┐
│ FastAPI · uvicorn (:8000) │
│ REST：/candles /analyze /structure /levels /tickers /news ... │
│ WS：candle / ticker / books / trade / mark-price / funding-time │
│ SSE：/news/stream（全球快讯实时流） │
├────────────────────────────────────────────────────────────────────┤
│ Bitget MCP (stdio) │ Bitget 公共 WS │ AKShare │ BlockBeats API │
│ K线抓取/回填 │ 实时bar/盘口 │ 快讯4源 │ 加密快讯/数据 │
│ ▼ 单一持久层（PostgreSQL） │
│ candles · alerts · chart_config · blockbeats_cache · events · │
│ proposals · runs · stream_events · LangGraph 检查点表 │
└────────────────────────────────────────────────────────────────────┘
持久层只有 PostgreSQL：
candles/alerts/chart_config/blockbeats_cache/events/proposals/runs/stream_events（外加 LangGraph checkpointer 建的表）。 旧文件 ——backend/data/parquet的日分区与backend/data/agent下的 JSON / JSONL （runs.jsonl、stream.jsonl等）—— 是迁移前的存储，留在磁盘上仅供审计与重跑， 运行时不再读写。
- Python ≥ 3.11
- Node.js ≥ 20（含 npm）
- Windows / macOS / Linux 均可
cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -e .
cp .env.example .env # 按需修改（默认无 Key 也可启动）启动 API 服务（默认 http://127.0.0.1:8000）：
# 方式一：uvicorn（开发）
uvicorn market_data.webapi:create_app --factory --port 8000
# 方式二：CLI 入口
market-data serve公开行情（K 线、实时 WebSocket）无需任何 API Key。仅 BlockBeats 快讯需要
BB_API_KEY，缺失时相关接口自动降级。
cd frontend
npm install
npm run dev打开 http://127.0.0.1:5173 即可（/api 与 /ws 自动代理到后端 8000 端口）。
# 查看可用 MCP 工具
market-data discover
# 抓取一段 K 线并导出 Excel
market-data pull --symbol BTCUSDT --timeframe 5m --start 2024-01-01 --end 2024-01-02 --export
# 增量拉取
market-data incremental --symbol BTCUSDT --timeframe 5m --start 2024-01-01 --end 2024-01-03
# 数据缺口检查
market-data gaps --symbol BTCUSDT --timeframe 5m
# 指标 + 支撑阻力分析
market-data analyze --symbol BTCUSDT --timeframe 1h仓库附带一套基于 Docker Compose 的 Debian 开发环境（compose.yaml / Dockerfile /
docker/entrypoint.sh / scripts/dev-sync.sh），采用原生工作副本（native working
copy）模型：仓库不再 bind-mount 进容器，容器在 ext4 命名卷里维护自己的工作副本，
Windows 侧仓库只读挂载为 /src-ro 作为单向 rsync 源；git / pytest / vitest / pnpm 全部在
容器内运行。旧设计把仓库 bind-mount 进 9p 挂载，容器内 git 会 SIGBUS / Bus error、pytest
慢到 462–547 s，新设计下 git 正常、pytest 实测 69.5 s（pytest 自报；端到端 74.4 s）。
# 构建 + 启动（唯一容器，自动常驻 backend/frontend）+ 首次同步
wsl.exe -d Ubuntu-26.04 -- bash -lc 'cd /mnt/d/work/project/trade && scripts/dev-sync.sh up'
# 进入容器（可选）
wsl.exe -d Ubuntu-26.04 -- bash -lc 'cd /mnt/d/work/project/trade && scripts/dev-sync.sh shell'始终在线 · 两服务（dev + postgres）：整栈现在由 dev 容器（trade-dev-1）与 postgres
服务（trade-postgres-1）组成，使用镜像 trade_agent_img 与 postgres:16 及命名卷。
入口脚本 docker/entrypoint.sh 在同一 dev 容器内常驻拉起 backend（8181 →
http://127.0.0.1:8181）与 frontend（5173 → http://127.0.0.1:5173），**这两个端口都发布在
dev 容器上**；postgres 提供 LangGraph checkpointer 后端，宿主端口 5433（数据卷
trade-pgdata），凭据来自仓库根 gitignored .env，dev 经 depends_on: service_healthy
等待其健康后就绪。
日常：宿主编辑 →
scripts/dev-sync.sh sync → 浏览器直接看（单向：宿主 → 容器）；只想起工具箱（不起服务器）用
SERVICES=0 docker compose up -d。
自动恢复：WSL 发行版由用户自行启动；/etc/wsl.conf 的 systemd=true 会让 dockerd
随发行版启动（docker.service 已 enabled），因此带 restart: unless-stopped 的容器会在
dockerd / 发行版重启后自动恢复——本环境不注册任何 Windows 计划任务 / 自启项。
scripts/dev-sync.sh 另提供 sync / up / shell / down / logs / backend / frontend / test-backend / test-frontend / test-e2e / hub-e2e / doctor 子命令（backend / frontend
现在只跟随常驻服务日志，不会另起进程抢端口；test-e2e 在容器内跑 Playwright E2E，
用空闲端口另起 vite + 后端，不与常驻服务冲突）。完整说明（单容器始终在线栈、入口脚本等待/自愈行为、
SERVICES=0 工具箱模式、自启链、同步语义、.git 双工作副本注意事项、backend/data 与
backend/.env、命名卷、镜像来源）见 docs/docker-dev.md。
PostgreSQL checkpointer（Phase 2 基础）：两张 LangGraph 图共用 postgres 服务的同步
PostgresSaver（按 thread_id 隔离，worker 唯一写者）。旧 backend/data/agent/checkpoints.sqlite
为 legacy（不再写入、保留可审计），用一次性脚本迁移（幂等、支持 --dry-run）：
docker compose exec dev bash -lc \
'cd /workspace/backend && .venv/bin/python scripts/migrate_checkpoints_sqlite_to_pg.py'
⚠️ docker compose down -v会删除trade-workspace卷，等于销毁整个工作副本——请只用docker compose down。环境限制（详见文档）：本环境
docker.io不可达，基础镜像经镜像源 （docker.m.daocloud.io）拉取并 retag 为python:3.12-slim-bookworm；容器内的 git 与宿主 git 是两份独立工作副本，git 写操作请在 Windows 宿主完成。
后端配置前缀为 MD_（backend/.env 加载），全部可选：
| 变量 | 默认值 | 说明 |
|---|---|---|
BB_API_KEY |
空 | BlockBeats 新闻/数据 API Key（缺失时快讯接口降级） |
BITGET_API_KEY / SECRET / PASSPHRASE |
空 | 预留，公开行情无需 |
MD_DATA_DIR |
./data |
数据根目录；live 数据在 PostgreSQL，此目录只放 legacy 文件（Parquet / Excel / 旧 JSON 缓存） |
MD_POSTGRES_DSN |
postgresql://trade@postgres:5432/trade |
唯一持久层的 PostgreSQL 连接串（K 线 / 告警 / 图表配置 / 事件 / BlockBeats 缓存 / 智能体投影 / LangGraph checkpointer）；compose 从仓库根 .env 注入（宿主进程改用 localhost:5433） |
MD_SYMBOLS |
BTCUSDT,ETHUSDT,SOLUSDT |
默认抓取标的 |
MD_TIMEFRAMES |
1m,5m,…,1d |
默认周期 |
MD_CATEGORY |
USDT-FUTURES |
默认产品线 |
MD_CATEGORIES |
SPOT,USDT-FUTURES |
交易所行情中枢覆盖的产品线列表 |
MD_SCHEDULE_INTERVAL_SECONDS |
300 |
定时增量拉取周期 |
MD_MCP_COMMAND / MD_MCP_ARGS |
npx / @bitget-ai/bitget-agent-mcp |
Bitget MCP 启动命令 |
MD_CANDLE_PAGE_LIMIT |
100 |
单请求 K 线页大小 |
MD_REST_CANDLE_PAGE_LIMIT |
500 |
REST v2 深回填页大小 |
MD_V3_CANDLE_PAGE_LIMIT |
100 |
REST v3 深回填页大小 |
MD_BACKFILL_PAGE_DELAY |
0.05 |
深回填页间节流延时（秒） |
MD_NEWS_POLL_SECONDS |
60 |
全球快讯轮询周期 |
MD_NEWS_BUFFER_SIZE |
500 |
快讯环形缓冲条数 |
MD_WS_PUBLIC_URL |
Bitget 官方 | 公共 WebSocket 地址 |
MD_WS_HEARTBEAT_SECONDS |
30 |
WS 心跳间隔 |
MD_WS_RECONNECT_SECONDS |
5 |
WS 断线重连间隔 |
MD_BLOCKBEATS_REFRESH_HOUR / MD_BLOCKBEATS_REFRESH_MINUTE |
12 / 0 |
BlockBeats 数据缓存每日刷新时刻 |
MD_LOG_LEVEL |
INFO |
日志级别 |
项目采用三层测试金字塔（全部可本地运行，online 子集需外网）：
| 层 | 命令 | 覆盖 |
|---|---|---|
| L1 数据完整性 | cd backend && python -m pytest -m integrity |
PostgreSQL candles 全序列质量（单调性 / OHLC / 缺口白名单；需已导入的测试库，无 Postgres 时跳过） |
| L2 实时 API/WS | cd backend && python -m pytest -m live --run-live |
真实 uvicorn 进程的 REST + WS 全通道 |
| L3 浏览器旅程 | cd frontend && npm run test:e2e |
Playwright 用户旅程（自动起 vite + 后端） |
单元回归：
cd backend && python -m pytest -q
cd frontend && npm run test && npm run typecheck标记说明：
--run-online启用需外网的online用例（缺省跳过）；--run-live启动真实 uvicorn 进程运行 L2 子集（缺省不选中，pytest -q保持快速全绿）； 服务启动超时可用环境变量MD_TEST_SERVER_START_TIMEOUT（默认 180s）调整。
CI（.github/workflows/ci.yml）在 push / PR 时执行：后端 ruff + 单元回归 + L1
（+ L2 独立 job）、前端 Biome + typecheck + 单测 + 覆盖率。online 外网用例
保持 skip，不在 CI 中启用；Playwright E2E 需安装浏览器，暂不纳入 CI。
本地等价命令：
# 后端：静态检查 + 格式化检查 + 覆盖率
cd backend && ruff check . && ruff format --check .
ruff check --fix . && ruff format . # 自动修复 / 格式化
python -m pytest -q --cov=market_data --cov-report=term-missing
# 前端：静态检查 + 格式化检查 + 覆盖率
cd frontend && npm run lint && npm run format:check && npm run typecheck
npm run format # 自动格式化
npm run test:coverage覆盖率采取只升不降的棘轮策略：初次启用时的实测基线，阈值取不超过基线的值， 后续变更只允许上调。
| 端 | 工具 | 初始基线 | 门禁阈值 |
|---|---|---|---|
| 后端 | pytest-cov（--cov=market_data） |
81% | fail_under = 80 |
| 前端 | @vitest/coverage-v8（src/**） |
55.69% lines / statements | lines = 55、statements = 55 |
提交前可用 pre-commit 在本地复现同一套检查：
pip install pre-commit && pre-commit install && pre-commit run --all-files├── backend/
│ └── src/market_data/
│ ├── webapi.py # FastAPI 路由（REST / WS / SSE）
│ ├── realtime.py # Bitget 公共 WebSocket 实时行情
│ ├── streamhub.py # WS 订阅路由与推送
│ ├── ingestion.py # MCP / REST 历史抓取与回填
│ ├── mcp_client.py # Bitget Agent MCP 客户端
│ ├── store.py / scheduler.py # PostgreSQL K 线存储 / 增量持久化调度
│ ├── indicators.py / levels.py # 技术指标 / 支撑阻力
│ ├── smc.py / structure.py # 市场结构与流动性位
│ ├── newsfeed.py / news_broker.py # 全球快讯（AKShare → SSE）
│ ├── blockbeats.py / blockbeats_cache.py # BlockBeats 快讯/数据 + 每日本地缓存
│ ├── chartstore.py / alertstore.py # 图表配置 / 告警存储
│ └── cli.py # market-data 命令行
├── frontend/
│ └── src/
│ ├── components/views/ # 页面视图（SuperCharts/Markets/Screener/Heatmaps/Community/News…）
│ ├── components/bottom/ # 底部停靠栏（筛选器 / 文本备注）
│ ├── lib/ # 数据层与工具（globalNews/useMasonry…）
│ ├── api/client.ts # REST 客户端
│ ├── hooks/ types/ utils/ data/
│ └── vendor/klinecharts-pro
├── openspec/ # OpenSpec 规格驱动的开发文档（specs + 归档）
├── agent_hub-main/ # 参考项目（MIT，非本仓库主体）
├── LICENSE # GNU GPL v3
└── README.md
GET /health、GET /candles、GET /candles/recent、POST /candles/backfillGET /analyze、GET /levels、GET /structureGET /tickers、GET /books/{symbol}、GET /books/{category}/{symbol}、GET /trades/{symbol}、GET /trades/{category}/{symbol}、GET /funding、GET /mark-price、GET /instrumentsWS /ws：candle/ticker/books/trade/mark-price/funding-time订阅推送
GET /news/categories、GET /news/history?offset=&limit=&category=GET /news/stream（SSE：快照 → 实时条目 → 心跳）GET /news/context?hours=&category=、GET /news/healthGET /blockbeats/newsflash/{type}、GET /blockbeats/data/{endpoint}、POST /blockbeats/data/refresh
GET/PUT /chart-config、GET/POST/PUT/DELETE /alerts
| 数据 | 来源 | 说明 |
|---|---|---|
| K 线历史 | Bitget（MCP / REST v2 / v3） | 深度历史回填，PostgreSQL 存储 |
| 实时行情 | Bitget 公共 WebSocket | K 线 / 盘口 / Ticker，无需鉴权 |
| 全球财经快讯 | AKShare（东财 / 新浪 / 同花顺 / 财联社） | 7×24 快讯，SSE 推送，主题分类，免费无 Key |
| 加密新闻 | BlockBeats API | 快讯 / 数据，需 BB_API_KEY |
- 本仓库使用 OpenSpec 规格驱动开发：功能先写
openspec/changes/<change>/（proposal → design → specs → tasks），实现后归档合并到openspec/specs/。 - 提交前请通过三层测试回归（见测试）。
- 欢迎 Issue 与 PR。建议先讨论设计再提交代码。
本项目以 GNU General Public License v3.0（GPL-3.0）开源，完整文本见 LICENSE。
- 你可以自由使用、修改与再分发本软件（含商用），但任何基于本项目的衍生作品必须同样以 GPL-3.0 授权并开放源代码。
- 本软件按“现状”提供，不附带任何担保（详见 LICENSE 第 15–17 条）。
- 仓库内的
agent_hub-main/为引入的参考项目，采用 MIT License（Copyright (c) 2025 Bitget），不受本仓库 GPL-3.0 约束。
仅供学习研究使用。加密货币市场风险极高，本项目不构成投资建议。