Quant Research Platform

一个 LLM 原生的量化研究平台，提供因子管理、策略回测、研报分析等功能，并通过 MCP 协议让 AI 助手直接访问量化知识库。

Features

因子知识库 - 因子管理、评分、分析
策略回测 - 策略管理、参数搜索
研报知识库 - PDF 上传、RAG 对话
经验知识库 - 结构化研究经验、语义检索、知识提炼
数据服务 - K线数据、因子计算
MCP 协议 - LLM 直接访问量化知识库

Quick Start

1. 安装依赖

按顺序安装以下依赖:

序号	依赖	macOS / Linux	Windows
1	Docker	下载 Docker Desktop	下载 Docker Desktop
2	Node.js 20+	下载或 `brew install node`	下载安装包
3	pnpm	`npm install -g pnpm`	`npm install -g pnpm`
4	uv	`curl -LsSf https://astral.sh/uv/install.sh \| sh`	`irm https://astral.sh/uv/install.ps1 \| iex`

Windows 提示: 安装完成后需要重启终端使环境变量生效

2. 配置环境变量

# 复制环境变量模板
cp .env.example .env

编辑 .env 文件，填入以下必要配置:

配置项	说明	示例
`PRE_DATA_PATH`	预处理K线数据路径	`/Users/xxx/Downloads/coin-binance-spot-swap-preprocess-pkl-1h`
`COIN_CAP_PATH`	市值数据路径 (可选)	`/Users/xxx/Downloads/coin-cap`
`LLM_API_URL`	LLM API 地址	`https://api.openai.com/v1`
`LLM_API_KEY`	LLM API 密钥	`sk-xxx`

3. 启动项目

macOS / Linux:

# 克隆项目
git clone https://github.com/your-username/quant-research-platform.git
cd quant-research-platform

# 启动（自动安装依赖、启动数据库、启动服务）
make start local

# 查看服务状态
make status

# 查看日志
make logs local

# 停止服务
make stop local

Windows (PowerShell):

# 一键启动（自动安装依赖、启动所有服务、打开浏览器）
uv run python scripts/dev.py start

# 停止所有服务
uv run python scripts/dev.py stop

# 查看服务状态
uv run python scripts/dev.py status

# 查看日志
uv run python scripts/dev.py logs              # 全部服务
uv run python scripts/dev.py logs api           # 仅 API
uv run python scripts/dev.py logs -n 100 mcp-factor  # 最近 100 行

scripts/dev.py 是跨平台任务运行器，也可在 macOS/Linux 上使用，等价于 make start local。该脚本会自动启动 PostgreSQL、Redis、API、7 个 MCP 服务和前端，无需手动开多个终端。

4. 访问服务

启动后访问:

前端界面: http://127.0.0.1:5173
API 文档: http://127.0.0.1:8000/docs

MCP Integration

通过 MCP 协议，LLM 可以直接访问平台的所有功能。

Claude 配置

在 .mcp.json 中添加:

{
  "mcpServers": {
    "factor-hub": {
      "url": "http://localhost:6789/mcp"
    },
    "data-hub": {
      "url": "http://localhost:6790/mcp"
    },
    "strategy-hub": {
      "url": "http://localhost:6791/mcp"
    },
    "note-hub": {
      "url": "http://localhost:6792/mcp"
    },
    "research-hub": {
      "url": "http://localhost:6793/mcp"
    },
    "experience-hub": {
      "url": "http://localhost:6794/mcp"
    }
  }
}

Development

目录结构

quant-research-platform/
├── backend/
│   ├── app/routes/          # HTTP 路由层
│   ├── app/schemas/         # Pydantic 模型
│   └── domains/             # 业务域
│       ├── mcp_core/        # MCP 基础设施
│       ├── factor_hub/      # 因子知识库
│       ├── strategy_hub/    # 策略回测
│       ├── research_hub/    # 研报 RAG
│       ├── experience_hub/  # 经验知识库
│       ├── data_hub/        # 数据服务
│       └── note_hub/        # 笔记管理
├── frontend/
│   └── src/
│       ├── features/        # 功能模块
│       ├── components/      # 通用组件
│       └── lib/             # 工具库
├── docker/                  # 容器配置
├── docs/                    # 文档
└── factors/                 # 因子定义库

常用命令

# 开发
make start local          # 本地开发模式
make start dev            # Docker 开发模式
make logs-api             # API 实时日志
make logs-frontend        # 前端实时日志

# 生产
make start                # 生产模式
make healthcheck prod     # 健康检查

运行模式

模式	命令	说明
local	`make start local`	本地运行 Python/Node，仅 Docker 运行数据库
dev	`make start dev`	全容器化，支持热重载
prod	`make start`	全容器化，优化构建

Tech Stack

Backend

FastAPI, SQLAlchemy 2.0, PostgreSQL 16 + pgvector
LangChain, Redis, aiohttp
structlog, ruff, pytest

Frontend

React 18, TypeScript, Vite 6
TanStack Query, Zustand, shadcn/ui
AG Grid, ECharts, Tailwind CSS

Infrastructure

Docker, Docker Compose, Caddy, Supervisor

License

MIT

重要更新

因子和截面因子文件已迁移至 private/ 目录。

# 旧位置（已废弃）
factors/
sections/

# 新位置
private/
  factors/      # 因子代码 (.py)
  sections/     # 截面因子 (.py)
  metadata/     # 因子元数据 (YAML)

private/ 目录已被 gitignore，需通过独立的私有仓库管理。详见 private/.gitkeep。