wolfjkd/tradex-hub

---

项目介绍

tradex-hub 是一个本地运行的金融数据中台，把分散在多个数据源（通达信、腾讯财经、东方财富、同花顺、新浪、巨潮、财联社、AKShare 等）的 A 股数据，统一封装成 168 个 MCP 工具 + 58 个 REST 端点（2026-10-13 tq 本地源接入后基线），供 AI Agent（WorkBuddy / Claude Code / Cursor / Dify / LangChain）和前端看板（TradeX）一站式调用。

核心定位：让 AI Agent 不用关心数据从哪儿来、怎么反爬、怎么降级 —— 只管调一个统一接口，tradex-hub 自动选最优数据源、自动健康检查、自动故障隔离。

核心能力

三层能力模型

┌────────────────────────────────────────────────────────────────┐
│  外部调用方                                                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐    │
│  │ MCP 客户端     │  │ REST 客户端    │  │ 浏览器看板     │    │
│  │ (AI Agent)     │  │ (前端/外部)    │  │ (/dashboard)   │    │
│  └────────┬───────┘  └────────┬───────┘  └────────┬───────┘    │
│           │                   │                   │             │
└───────────┼───────────────────┼───────────────────┼─────────────┘
            │                   │                   │
            ▼                   ▼                   ▼
┌────────────────────────────────────────────────────────────────┐
│  协议层（双协议并存）                                            │
│  ┌─────────────────────┐    ┌─────────────────────────────┐    │
│  │  MCP Server         │    │  FastAPI REST               │    │
│  │  168 个工具         │    │  58 个端点（/api/v1/*）      │    │
│  └──────────┬──────────┘    └──────────────┬──────────────┘    │
│             │                              │                    │
│             └──────────┬───────────────────┘                    │
│                        ▼                                        │
└────────────────────────┼────────────────────────────────────────┘
                         │
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  Service 层（共享业务逻辑）                                      │
│  ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐     │
│  │market│price │fund  │compny│financ│news  │indstr│write │     │
│  └──┬───└──┬───└──┬───└──┬───└──┬───└──┬───└──┬───└──┬───┘     │
│     └──────┴──────┴──────┴──────┴──────┴──────┴──────┘         │
│                        │                                        │
└────────────────────────┼────────────────────────────────────────┘
                         ▼
┌────────────────────────────────────────────────────────────────┐
│  SmartRouter 全量路由层                                          │
│  ┌────────────────────────────────────────────────────────┐    │
│  │  对每个数据类型按梯队选最优源、健康评分、自动降级        │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                 │
│  数据源梯队                                                     │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐       │
│  │ 第一梯队      │  │ 第二梯队      │  │ 第三梯队      │       │
│  │ (不封 IP)     │  │ (低风险)      │  │ (限流防封)    │       │
│  │ eltdx / 腾讯  │  │ 同花顺 / 新浪 │  │ 东财 push2    │       │
│  │ 本地 vipdoc   │  │ 巨潮 / 财联社 │  │ push2ex       │       │
│  └───────────────┘  └───────────────┘  └───────────────┘       │
└────────────────────────────────────────────────────────────────┘

---

双协议并存架构

tradex-hub 同时暴露两个协议接口，共享同一套业务逻辑，调用方按需选择：

flowchart LR
    subgraph Caller["调用方"]
        A1["AI Agent(WorkBuddy / Claude)"]
        A2["前端看板(TradeX)"]
        A3["外部系统(Dify / LangChain)"]
    end

    subgraph Gateway["tradex-hub 网关 (端口 8000)"]
        B1["MCP Server168 个工具JSON-RPC over HTTP"]
        B2["FastAPI REST58 个端点统一包裹响应"]
        B3["监控看板/dashboardPrometheus /metrics"]
        B1 -.共享.- B2
        B2 -.共享.- B3
    end

    subgraph Service["Service 层（业务逻辑）"]
        C1["11 个领域模块market / price / fund /company / financial / news /industry / indicator /diagnostic / write / metrics"]
    end

    subgraph Router["SmartRouter"]
        D1["全量路由78 类型 / 102 源三梯队降级"]
    end

    A1 -->|tools/call| B1
    A2 -->|HTTP GET/POST| B2
    A3 -->|HTTP GET/POST| B2
    B1 --> C1
    B2 --> C1
    B3 --> C1
    C1 --> D1

两个协议返回的数据完全一致（仅序列化差异：MCP 返 JSON 字符串、REST 返包裹 dict），契约严格对齐。

---

SmartRouter 全量路由原理

SmartRouter 是 tradex-hub 的核心 —— 它让上层无需关心数据从哪个源来：

flowchart TD
    Q["业务层发起数据请求(如 get_realtime_quote)"] --> SR{"SmartRouter.route()"}
    SR --> Sel["按数据类型查路由表取出该类型的候选源列表（按梯队排序）"]
    Sel --> Try["尝试第一梯队源"]
    Try --> Health{"健康检查(近期成功率)"}
    Health -->|健康| Call["调用数据源"]
    Health -->|不健康| Next1["跳过，尝试下一候选"]
    Next1 --> Try2["尝试第二梯队"]
    Call --> Resp{"返回数据是否合法?"}
    Resp -->|合法| OK["✅ 返回数据上报健康 + 延迟"]
    Resp -->|异常/空| Fail["❌ 标记本次失败降级下一源"]
    Fail --> Try2
    Try2 --> Try3["尝试第三梯队(限流防封)"]
    Try3 --> Resp2{"成功?"}
    Resp2 -->|成功| OK
    Resp2 -->|失败| Err["抛出最后错误"]

    style OK fill:#90ee90
    style Err fill:#ffcccc

梯队划分（按封禁风险从低到高）：

---

安装

环境要求

• Python 3.13+
• 网络可访问国内 A 股数据源（eltdx 协议、HTTP 接口；代理仅给 GitHub 用，国内数据源必须直连）

快速开始

git clone https://github.com/wolfjkd/tradex-hub.git
cd tradex-hub

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate    # Windows
# source .venv/bin/activate  # Linux/macOS

# 安装依赖（可编辑安装，含 http 网关 extras）
pip install -e "tradex[http]"

# 启动网关（HTTP 模式，默认 8000 端口）
python -m tradex --http

启动后访问：

• 监控看板：http://127.0.0.1:8000/dashboard
• REST 接口文档：http://127.0.0.1:8000/docs
• Prometheus 指标：http://127.0.0.1:8000/metrics
• 健康检查：http://127.0.0.1:8000/health

可选：通达信官方 MCP（tdx_mcp）

tdx_mcp 与 eltdx 同属第一梯队、互为备份、互为兜底，提供 eltdx 没有的纯增量能力： 自然语言条件选股（natural_lang_screener）、券商研报（research_report）、 宏观数据增强（query_macro_indicator）。

它可选：不配置 TDX_MCP_TOKEN 也能正常运行——缺 token 时该源自动标记不可用， realtime_quote / historical_kline 无缝回落到 eltdx（健康分互备，用户无感）。

配置（复制 tradex/.env.example 为 .env）：

# 在通达信官方 MCP 控制台获取访问 token，填入
TDX_MCP_TOKEN=你的token
# 端点与限流（通常无需改动）
TDX_MCP_ENDPOINT=https://txmcp.tdx.com.cn:3001/txmcp
TDX_MCP_MIN_INTERVAL=0.8

⚠️ 开源分发时请勿提交真实 token。token 冲突、泄漏或失效都只会让该源降级到 eltdx，不会导致服务不可用——这正是"平级互备"的设计意图。

可选：通达信 TQ 本地源（tq）

tq 是通达信客户端本地暴露的 JSON-RPC 通道（http://127.0.0.1:17709/）， 与 eltdx / tdx_mcp 同属第一梯队，realtime_quote 互为备份（本地直连 ~11ms，不封 IP）， 并提供两个独占增量工具：

• get_l2_stats(code)：当日 L2 统计（逐笔委托数 / 逐笔成交数 / 买撤单额 / 卖撤单额）
• run_tdx_formula(formula, codes)：通达信内置公式批量计算（公式生态桥）

零配置：无需任何 env。通达信客户端（含 Python 插件支持的版本）运行中即自动可用； 未运行时该源自动降级（DEBUG 日志，不影响其他源）。可用 env TQ_ENDPOINT / TQ_TIMEOUT 覆盖默认端点与超时。

---

MCP 工具清单（168 个）

完整工具清单详见 docs/MCP_TOOLS.md（由 scripts/generate_tool_docs.py 从源码 AST 生成，含每个工具的说明）。按业务领域分组：

---

REST API

58 个 REST 端点统一挂在 /api/v1/* 路径下，与 MCP 工具共享同一 service 层。

快速上手

# 行情
curl http://127.0.0.1:8000/api/v1/market/overview
curl "http://127.0.0.1:8000/api/v1/price/quote?symbol=600519"

# 技术指标（自动取 K 线）
curl "http://127.0.0.1:8000/api/v1/indicator/macd?symbol=600519"

# 综合诊断
curl "http://127.0.0.1:8000/api/v1/diagnostic/stock?symbol=600519"

# 写操作（策略持久化）
curl -X POST http://127.0.0.1:8000/api/v1/write/strategy \
  -H "Content-Type: application/json" \
  -d '{"name":"双均线策略","content":"MA5 上穿 MA20 买入","tags":["momentum"]}'

# 访问日志查询
curl "http://127.0.0.1:8000/api/v1/access-log?limit=10&path=/api/v1/price"

Python SDK 调用：

from tradex_client import TradexClient

client = TradexClient("http://127.0.0.1:8000")
resp = client.quote(query={"symbol": "600519"})
if resp["code"] == 0:
    print(resp["data"]["name"], resp["data"]["price"])

统一响应包裹

所有 /api/v1/* 端点返回标准包裹格式：

{"code": 0, "data": , "msg": "ok"}

错误码定义：

端点清单

完整的 OpenAPI 交互式文档启动网关后访问 http://127.0.0.1:8000/docs。

---

监控与可观测性

Prometheus 指标

GET /metrics 输出标准 Prometheus 文本格式，含 10+ 个指标：

Dashboard 监控看板

GET /dashboard 是商务风格暗色看板，30 秒自动刷新，包含五个区域：

访问日志（双写）

每个 REST 请求被中间件同时写到两处：

GET /api/v1/access-log?limit=50&path=/api/v1/price 查询最近访问记录，支持按路径前缀过滤。

限流（令牌桶三层）

超阈值返回 HTTP 429 + envelope code=42901 + Retry-After header。本机回环白名单（127.0.0.1 / ::1）不受限流，保证本地 AI Agent 与监控探针不被误伤。

---

写操作持久化

策略和自选股支持本地持久化 CRUD，底层用 SQLite（WAL 模式）：

首次启动自动迁移：发现旧 JSON 文件（data/written/strategies/*.json、data/written/watchlist.json）时自动导入 SQLite，原文件改名 .migrated 留底，迁移过程写 data/written/migration.log。迁移幂等。

并发安全：写入用 BEGIN IMMEDIATE 立即获取写锁，主键格式 {毫秒时间戳}-{线程ID}-{随机4位} 杜绝并发冲突，WAL 模式保证读写不互斥。

---

客户端 SDK

为方便第三方快速接入，提供 TypeScript 与 Python 双语言 SDK，由 scripts/generate_sdk.py 从 /openapi.json 自动生成：

sdk/
├── typescript/index.ts        # TypeScript 客户端（基于 fetch）
├── python/tradex_client/      # Python 客户端（基于 requests）
└── README.md                  # 双语言对照、安装、示例

快速示例：

# Python
from tradex_client import TradexClient
client = TradexClient("http://127.0.0.1:8000")
quote = client.quote(query={"symbol": "600519"})

// TypeScript
import { TradexClient } from "./typescript";
const client = new TradexClient("http://127.0.0.1:8000");
const quote = await client.quote({ query: { symbol: "600519" } });

修改端点后重新生成：python scripts/generate_sdk.py

---

配置到 AI Agent

WorkBuddy / Claude Code / Cursor

编辑 MCP 配置文件（如 ~/.workbuddy/mcp.json）：

{
  "mcpServers": {
    "tradex": {
      "command": "python",
      "args": ["-m", "tradex", "--http"],
      "env": {
        "TRADER_HUB_MODE": "http"
      }
    }
  }
}

外部 HTTP 客户端

直接用 HTTP 调用 REST 端点，无需 MCP 客户端：

curl http://your-host:8000/api/v1/market/overview

---

验证

启动后快速验证：

# 健康检查
curl http://127.0.0.1:8000/health
# 期望: {"status":"ok","service":"tradex-mcp","tools":168}

# REST 端点
curl http://127.0.0.1:8000/api/v1/ping
# 期望: {"code":0,"data":{"pong":true},"msg":"ok"}

# MCP 工具（通过网关 HTTP 模式）
curl http://127.0.0.1:8000/mcp -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

已知限制

---

如何确认当前版本（纯本地，不联网）

只看本地文件夹即可判断版本，无需访问 GitHub：

python scripts/version.py      # 一次输出全部信号并做一致性比对
git describe --tags --dirty    # 最精确：当前代码在哪个 tag 之后第几个提交
cat VERSION                    # 最简：发布版本号单一真源

两个易错点：

• 版本号相同不代表代码相同 —— VERSION 只在发版时变更，tag 之后的提交仍属该版本号。要看代码新旧，看 git describe 的提交数。
• origin/master 是上次 git fetch 的快照，不是实时远端状态。完全不联网时，脚本只能告诉你"相对上次拉取有无差异"，远端是否又更新需 git fetch 后才能判断。

---

版本历史

完整变更记录详见 CHANGELOG.md。

---

许可

Apache License 2.0

---

作者

郭良勇 · A 股日内交易员 / 量化转型中

• GitHub: @wolfjkd

本项目的初衷是为 A 股交易员提供可信赖的本地化金融数据中台。所有数据接口均指向公开数据源，不涉及任何违规数据获取。