# a-stock

**Repository Path**: mingwuda/a-stock

## Basic Information

- **Project Name**: a-stock
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📈 A 股全栈量化交易系统

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115%2B-009688)](https://fastapi.tiangolo.com)
[![LangGraph](https://img.shields.io/badge/LangGraph-ReAct-purple)](https://langchain-ai.github.io/langgraph/)
[![Qlib](https://img.shields.io/badge/Qlib-Alpha158-orange)](https://github.com/microsoft/qlib)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

> 一个可本地运行的全栈 A 股量化交易系统。从数据拉取到 AI 选股、ML 模型训练、自动复盘、AI Agent 对话分析，全链路闭环。**docker compose up** 一键启动。

---

## ✨ 核心特性

### 🧠 AI 智能选股
- **6大因子融合评分**：趋势因子、动量因子、量能因子、估值因子、风险因子、主力资金因子
- **3种风格切换**：稳健型、进取型、短线型，不同因子权重自动适配
- **7层强制风控**：ST过滤、亏损过滤、低流动性过滤、高位过热过滤、高波动过滤、公告风险过滤、次新过滤
- **主力资金估算**：基于大单成交估算 5 日主力资金净流入，短线风格权重 15%
- **暴跌压力测试**：历史暴跌回测 + 跌停风险评分 + 极端回撤快照

### 🤖 ML 日决策闭环
- **Qlib 集成**：数据同步 → Alpha158 因子计算 → LightGBM/XGBoost 模型训练 → 预测
- **自动训练调度**：每晚 20:00 自动执行，支持断点续训、Optuna 超参优化
- **日决策流水线**：`T日 收盘选股 → T+1 开盘买入 → T+2 收盘卖出`
- **自动复盘**：交易窗口关闭后自动复盘推荐结果，生成原因分析与改进建议
- **Kronos 预测**：集成 Transformer 时序预测引擎，预测未来 K 线趋势（支持 GPU）

### 💬 AI Agent 对话分析
- **14 个投资分析工具**：行情查询、技术指标、AI 评分、ML 预测、新闻搜索、板块信息、大盘情绪、资金流向、风险检查、仓位计算、横向对比等
- **LangGraph ReAct 推理**：LLM 自主决策调用工具链，输出结构化投资建议
- **SSE 流式输出**：实时展示 Agent 思考过程和工具调用结果
- **工具卡片渲染**：每个工具结果格式化展示，避免原始 JSON
- **会话管理**：多会话切换、历史记录持久化

### 📊 回测系统
- **4 种策略**：双均线、MACD、KDJ、网格策略，支持自定义参数
- **A 股规则完整**：T+1 锁仓、涨跌停限价（主板10%/创业板20%/科创板20%/北交所30%）、100股整手、佣金/印花税/过户费
- **批量回测**：对 AI 股票池一键批量回测，单票仓位限制 10%
- **可视化报告**：K 线买卖点、资金曲线、回撤曲线、技术指标、交易明细表

### 🔄 定时任务自动化
| 时间 | 任务 |
|------|------|
| 每晚 19:30 | 复盘上一轮 ML 推荐结果 |
| 每晚 20:00 | Qlib 模型自动训练 |
| 每晚 20:30 | 生成次日 Top3 决策 |
| 每周六 20:00 | Top100 股票池全市场刷新 |

---

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                       前端 (HTML+CSS+JS)                      │
│  ┌──────────┐  ┌───────────┐  ┌────────┐  ┌─────────────┐  │
│  │ AI 选股  │  │ ML 决策   │  │ 回测   │  │ Agent 对话  │  │
│  │ 工作台   │  │ 面板      │  │ 页面   │  │ 界面        │  │
│  └────┬─────┘  └─────┬─────┘  └───┬────┘  └──────┬──────┘  │
│       └──────────────┴────────────┴───────────────┘         │
│                       Nginx 反向代理                          │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP / SSE
┌──────────────────────────▼──────────────────────────────────┐
│                    FastAPI 后端 (8000)                        │
│                                                              │
│  ┌──────────────── API 路由层 ──────────────────────────┐    │
│  │ routes.py   │  agent_routes.py  │  auth.py           │    │
│  │ (60+端点)   │  (Agent SSE/会话) │  (JWT登录)         │    │
│  └─────────────┴───────────────────┴────────────────────┘    │
│                                                              │
│  ┌──────────────── 服务层 (22个服务) ────────────────────┐   │
│  │                                                       │   │
│  │  📡 数据层                                             │   │
│  │  ├── MooTdxProvider     ← 通达信协议行情               │   │
│  │  └── MarketUniverseService  ← 全市场股票池              │   │
│  │                                                       │   │
│  │  🧮 因子与选股                                         │   │
│  │  ├── AIStockSelector        ← 多因子评分              │   │
│  │  ├── HybridStockSelector    ← 多因子+ML融合选股        │   │
│  │  ├── Top100PoolService      ← Top100周频股票池        │   │
│  │  └── MomentumRotationService ← 动量轮动策略            │   │
│  │                                                       │   │
│  │  🤖 ML 模型                                            │   │
│  │  ├── QlibEngine             ← Alpha158 + LightGBM     │   │
│  │  ├── QlibAutoTrainer        ← 自动训练调度             │   │
│  │  ├── KronosPredictor        ← Transformer 时序预测     │   │
│  │  └── MLDecisionEngine       ← 每日 Top3 决策引擎       │   │
│  │                                                       │   │
│  │  🔄 回测与策略                                         │   │
│  │  ├── BacktestEngine         ← 回测引擎                │   │
│  │  ├── MLBacktestRunner       ← 模型试跑器              │   │
│  │  ├── Strategies             ← 策略定义库              │   │
│  │  └── StrategyProfiles       ← 顶层策略配置             │   │
│  │                                                       │   │
│  │  💬 AI Agent                                           │   │
│  │  ├── StockAgent             ← LangGraph ReAct Agent   │   │
│  │  │   ├── query_market_data     行情查询               │   │
│  │  │   ├── get_ai_score          多因子评分              │   │
│  │  │   ├── get_ml_prediction     ML预测                 │   │
│  │  │   ├── run_backtest          执行回测               │   │
│  │  │   ├── fetch_news            搜索新闻               │   │
│  │  │   ├── check_risk            风险检查               │   │
│  │  │   ├── calculate_position    仓位计算               │   │
│  │  │   ├── get_technical_indicators  技术指标            │   │
│  │  │   ├── get_stock_pool        查询股票池              │   │
│  │  │   ├── get_fund_flow_estimate 资金流向估算           │   │
│  │  │   ├── get_market_snapshot   市场概况               │   │
│  │  │   ├── get_sector_info       板块信息               │   │
│  │  │   ├── get_market_sentiment  大盘情绪               │   │
│  │  │   └── compare_stocks        横向对比               │   │
│  │  └── AgentConfigService      配置管理                  │   │
│  │                                                       │   │
│  │  ⏰ 调度与持久化                                       │   │
│  │  ├── TaskScheduler           定时调度器                │   │
│  │  ├── BacktestJobManager      回测任务管理              │   │
│  │  ├── MLDecisionJobManager    决策任务管理              │   │
│  │  └── Repository              数据库持久化              │   │
│  └───────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌──────────── 数据层 ────────────┐                          │
│  │ MooTdx(通达信)  腾讯行情(fallback)  AnySearch(新闻)      │   │
│  │ SQLite(app.db)  Qlib数据(parquet)  CSV缓存              │   │
│  └────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
```

---

## 🚀 快速开始

### Docker Compose 一键部署（推荐）

```bash
git clone https://gitee.com/mingwuda/a-stock.git
cd a-stock

# 可选：配置 LLM API Key（用于 AI Agent 对话功能）
echo "LLM_API_KEY=sk-your-key" > .env

# 启动
docker compose up -d --build
```

启动后访问：

| 服务 | 地址 |
|------|------|
| 前端页面 | http://localhost:5173 |
| API 文档 | http://localhost:8000/docs |
| 健康检查 | http://localhost:8000/api/health |

### 本地开发

```bash
# 创建虚拟环境
make venv

# 安装依赖
make install

# 启动后端
make backend

# 新开终端，启动前端
make frontend
```

> 也可以使用一键脚本：`./start.sh`

---

## 📖 使用流程

```
1. 打开浏览器 → 登录系统
2. AI 智能选股 → 选择风格、参数 → 生成股票池
3. 查看评分详情、风险等级、入选理由
4. ML 日决策 → 生成今日 Top3 推荐
5. 查看预测 → Kronos 时序预测未来K线
6. 批量回测 → 验证股票池历史表现
7. 单股回测 → 详细分析单只股票
8. AI Agent → 自然语言对话深度分析
9. 自动复盘 → 次日查看推荐结果反馈
```

---

## 🔧 可用命令（Makefile）

| 命令 | 说明 |
|------|------|
| `make venv` | 创建 `.venv` 虚拟环境 |
| `make install` | 安装后端依赖 |
| `make backend` | 启动后端 (uvicorn + hot-reload, 8000端口) |
| `make frontend` | 启动前端 (python http.server, 5173端口) |
| `make dev` | 一键启动前后端 |
| `make clean` | 清理缓存文件 |

---

## 📦 项目结构

```
a-stock/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   ├── routes.py          # 60+ 核心 API 端点
│   │   │   ├── agent_routes.py    # AI Agent 路由
│   │   │   └── auth.py            # 登录认证
│   │   ├── services/
│   │   │   ├── stock_agent.py     # LangGraph AI Agent
│   │   │   ├── qlib_engine.py     # Qlib 量化引擎
│   │   │   ├── ai_selector.py     # 多因子选股
│   │   │   ├── backtest.py        # 回测引擎
│   │   │   ├── top100_pool.py     # Top100 股票池
│   │   │   ├── ml_decision_engine.py  # ML 日决策
│   │   │   ├── scheduler.py       # 定时调度器
│   │   │   └── ... (共22个服务)
│   │   ├── core/                  # 核心配置
│   │   ├── main.py                # 应用入口
│   │   └── schemas.py             # Pydantic 模型
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── assets/
│   │   ├── app.js                 # 前端主逻辑 (152KB)
│   │   └── styles.css             # 样式表
│   ├── index.html                 # 主页面 (SPA)
│   ├── login.html                 # 登录页面
│   ├── Dockerfile
│   └── nginx.conf
├── docker-compose.yml
├── Makefile
├── start.sh
└── README.md
```

---

## 🤖 AI Agent 工具清单

在 Agent 对话界面，你可以用自然语言问股票，AI 自动调用以下 14 个工具链进行分析：

| 工具 | 功能 | 分类 |
|------|------|------|
| `query_market_data` | 获取股票行情（K线+最新价） | 📊 行情 |
| `get_technical_indicators` | 获取技术指标（MA/MACD/KDJ） | 📊 行情 |
| `get_market_sentiment` | 获取实时大盘情绪（指数涨跌/涨跌比） | 📊 行情 |
| `get_market_snapshot` | 获取市场概况（板块分布/市值分布） | 📊 行情 |
| `get_ai_score` | 获取多因子融合评分 | 🎯 选股 |
| `get_ml_prediction` | 获取 ML 模型预测收益 | 🎯 选股 |
| `get_stock_pool` | 查询 Top100 候选池/动量池 | 🎯 选股 |
| `get_sector_info` | 查询股票所属板块及同板块龙头股 | 🏭 行业 |
| `get_fund_flow_estimate` | 估算主力资金流向 | 💰 资金 |
| `fetch_news` | 搜索个股最新新闻和公告 | 📰 资讯 |
| `check_risk` | 检查个股风险指标 | ⚠️ 风控 |
| `calculate_position` | 根据资金/风险/置信度计算仓位 | 📐 仓位 |
| `compare_stocks` | 横向对比多只股票 | 🔄 对比 |
| `run_backtest` | 对指定股票运行回测 | 🧪 回测 |

---

## 📊 API 概览

### 核心接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/strategies` | 策略列表 |
| GET | `/api/data/history?symbol=&start=&end=&interval=` | K 线历史数据 |
| GET | `/api/data/quote?symbol=` | 实时行情 |
| POST | `/api/ai/select` | AI 多因子选股 |
| POST | `/api/ai/hybrid-select` | 融合选股（多因子+ML） |
| POST | `/api/backtest` | 提交回测 |
| GET | `/api/backtest/{job_id}` | 查询回测结果 |

### Qlib 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/qlib/status` | 引擎状态 |
| POST | `/api/qlib/trigger` | 手动触发训练 |
| POST | `/api/qlib/stop` | 停止训练 |
| POST | `/api/qlib/predict` | 预测排名 |
| GET | `/api/qlib/factor-effectiveness` | 因子有效性分析 |

### ML 决策接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/ml/daily-decision` | 生成日决策（异步） |
| GET | `/api/ml/daily-decision/{job_id}` | 查询决策状态 |
| POST | `/api/ml/review` | 复盘 |
| GET | `/api/ml/latest` | 最新决策 |
| GET | `/api/ml/history` | 决策历史 |
| POST | `/api/ml/backtest/run` | 模型试跑 |

### Agent 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/agent/chat` | Agent 对话（SSE 流式） |
| GET | `/api/agent/config` | 获取 Agent 配置 |
| POST | `/api/agent/config` | 保存 Agent 配置 |
| GET | `/api/agent/sessions` | 会话列表 |
| GET | `/api/agent/sessions/{id}` | 会话详情 |
| DELETE | `/api/agent/sessions/{id}` | 删除会话 |

---

## 🔌 外部依赖

| 依赖 | 用途 | 是否需要 API Key |
|------|------|:---------------:|
| MooTdx | 通达信行情协议（主数据源） | ❌ 免费 |
| 腾讯行情 API | 实时行情/大盘情绪（fallback） | ❌ 免费 |
| DeepSeek/OpenAI API | AI Agent LLM 推理 | ✅ 需配置 |
| AnySearch API | 新闻搜索 | ❌ 免费 |
| Kronos | Transformer 时序预测模型 | ❌ 本地模型 |

---

## 🔒 免责声明

本项目**仅用于研究和教学演示**：

- ❌ 不接入任何实盘交易接口
- ❌ 不下单、不交易、不管理资产
- ⚠️ AI 选股结果仅供参考，不构成投资建议
- ⚠️ 回测历史表现不代表未来收益
- 💡 投资有风险，入市需谨慎

---

## 🛠️ 技术栈

| 类别 | 技术 |
|------|------|
| 后端框架 | FastAPI + Uvicorn |
| AI Agent | LangGraph ReAct + LangChain |
| ML 引擎 | Qlib (LightGBM/XGBoost) + Optuna |
| 时序预测 | Kronos Transformer |
| 数据源 | MooTdx / 腾讯行情 |
| 数据库 | SQLite (Tortoise ORM) |
| 前端 | 原生 HTML / CSS / JavaScript |
| 图表 | ECharts |
| 部署 | Docker Compose |
| 认证 | JWT |

---

> **相关项目对比**：与港大 Vibe-Trading 相比，本项目的优势在于 **A 股深度适配**（完整交易规则、7层风控、主力资金估算）和 **ML 全自动决策闭环**（T→T+1→T+2 日决策 + 自动复盘），适合聚焦 A 股的投资者和研究者和。