232 lines
8.6 KiB
Markdown
232 lines
8.6 KiB
Markdown
# cc-cursor — Mac Mini 单机量化研究平台
|
||
|
||
从数据获取 → 因子计算 → 回测 → 参数优化 → ML 模型 → 情绪因子 → Agent 系统，全链路量化研究平台。
|
||
|
||
## 架构
|
||
|
||
```
|
||
cc-cursor/
|
||
├── finance/ # 核心量化引擎
|
||
│ ├── config/ # 全局配置（MariaDB / AkShare）
|
||
│ ├── database/ # ORM 模型 + DAO（mac_ 前缀表）
|
||
│ ├── data/ # DataManager 统一数据层
|
||
│ ├── factors/ # 因子引擎（34 因子 / 12 分类，含情绪因子）
|
||
│ ├── backtest/ # 回测引擎（VectorBT + 5 策略 + 截面回测）
|
||
│ ├── optimizer/ # Optuna 参数优化 + Walk-Forward
|
||
│ ├── models/ # LightGBM / CatBoost ML 模型
|
||
│ ├── agents/ # Agent 系统（4 Agent + 编排器 + CLI）
|
||
│ ├── cli/ # 命令行 & 验证脚本
|
||
│ ├── reports/ # 自动日报输出目录
|
||
│ └── .env # 环境变量配置（API Key / 分析范围）
|
||
├── djapi/ # Django API 后端（A 股数据 + 新闻联播 + 日报查询）
|
||
├── mcp-servers/ # MCP Server（Serena，本机工具，git 忽略）
|
||
├── shared/ # 共享工具（SSH 隧道脚本）
|
||
├── docs/ # 文档 & 使用指南
|
||
└── .claude/ # Claude Code 配置
|
||
```
|
||
|
||
## 数据流
|
||
|
||
```
|
||
Agent 编排层
|
||
├── ResearchAgent ── 因子发现（IC/IC_IR 评估）
|
||
├── SelectionAgent ─ 多因子打分 + ML 预测
|
||
├── RiskAgent ────── 仓位控制 + 风险预警
|
||
└── ReportAgent ──── 自动日报生成
|
||
|
||
基础引擎层
|
||
DataManager ──→ FactorEngine ──→ BaseStrategy ──→ VectorBTEngine ──→ BacktestReport
|
||
│ │ │
|
||
│ FeatureEngine OptunaEngine
|
||
│ │ │
|
||
└──────→ LightGBM/CatBoost ←────────┘
|
||
|
||
情绪增强层
|
||
NewsSource(AkShare/DB/MCP) ──→ QwenClient ──→ SentimentFactor ──→ FactorEngine
|
||
```
|
||
|
||
全部通过 Service 层中转：策略不直连 AkShare，模型不直连数据库，Agent 不重建引擎。
|
||
|
||
---
|
||
|
||
## 开发进度
|
||
|
||
| Sprint | 模块 | 关键成果 | 状态 |
|
||
|--------|------|----------|------|
|
||
| Sprint 0 | 基础设施 | DataManager + MariaDB 3 表 | ✅ |
|
||
| Sprint 1 | 因子引擎 | 34 因子 / 12 分类 | ✅ |
|
||
| Sprint 2 | 回测引擎 | VectorBT + 5 策略 + 截面回测 | ✅ |
|
||
| Sprint 3 | 参数优化 | Optuna + Walk-Forward | ✅ |
|
||
| Sprint 4 | ML 模型 | LightGBM + CatBoost + 特征工程 | ✅ |
|
||
| Sprint 5 | 情绪因子 | Qwen + 三源新闻聚合 + 日期对齐 | ✅ |
|
||
| Sprint 6 | Agent 系统 | 4 Agent + 编排器 + CLI + 自动日报 | ✅ |
|
||
| Sprint 7 | djapi API | 日报查询 ×2（news/reports + news/events） | ✅ |
|
||
|
||
**全部 8 个 Sprint 已完成。**
|
||
|
||
---
|
||
|
||
## 功能模块
|
||
|
||
### 数据层 `finance/data/`
|
||
|
||
```python
|
||
from data.data_manager import DataManager
|
||
dm = DataManager(); dm.init_db()
|
||
stocks = dm.get_stock_list() # → 5,524 只
|
||
daily = dm.get_daily("000001.SZ") # → 日线
|
||
fina = dm.get_financial("000001.SZ") # → 财务数据
|
||
dm.sync_daily("000001.SZ") # → 增量同步
|
||
```
|
||
|
||
### 因子引擎 `finance/factors/`
|
||
|
||
```python
|
||
from factors.registry import get_factor, list_factors
|
||
from factors.engine import FactorEngine
|
||
|
||
engine = FactorEngine(dm)
|
||
factors = [get_factor("momentum_20"), get_factor("rsi_14")]
|
||
factor_df = engine.compute("000001.SZ", factors)
|
||
# → 34 个注册因子，12 个分类（动量/RSI/MACD/量价/布林/ATR/均线/波动率/换手率/振幅/基本面/情绪）
|
||
```
|
||
|
||
### 回测引擎 `finance/backtest/`
|
||
|
||
```python
|
||
from backtest.vectorbt.engine import VectorBTEngine
|
||
from backtest.strategies.rsi_mean_revert import RSIMeanRevertStrategy
|
||
|
||
engine_bt = VectorBTEngine(initial_capital=100_000, commission=0.0003)
|
||
report = engine_bt.run(RSIMeanRevertStrategy(oversold=30, overbought=70), price_df, factor_df)
|
||
# → 收益=29.4% 年化=4.3% 回撤=-19.1% 夏普=0.37 胜率=77.1%
|
||
```
|
||
|
||
5 个内置策略 + 自定义策略接口 + 截面回测 + BacktestReport 标准化报告。
|
||
|
||
### 参数优化 `finance/optimizer/`
|
||
|
||
```python
|
||
from optimizer.engine import OptunaEngine
|
||
from optimizer.space import rsi_revert_space
|
||
|
||
result = OptunaEngine(engine_bt).optimize(
|
||
RSIMeanRevertStrategy, rsi_revert_space, price_df, factor_df,
|
||
metric="sharpe", n_trials=200,
|
||
)
|
||
# → 最优参数: oversold=13, overbought=66
|
||
# → 夏普: 0.37→0.60 (+62%), 回撤: -19.1%→-1.8% (10倍改善)
|
||
```
|
||
|
||
7 种优化目标 + 4 个预置搜索空间 + Walk-Forward 滚动验证 + 快捷函数。
|
||
|
||
### ML 模型 `finance/models/`
|
||
|
||
```python
|
||
from models.features import FeatureEngine
|
||
from models.lightgbm.model import LightGBMModel
|
||
|
||
fe = FeatureEngine(lookahead=5)
|
||
X, y = fe.build(factor_df, price_df, fit=True)
|
||
model = LightGBMModel(params={"n_estimators": 200}).fit(X_train, y_train)
|
||
pred = model.predict(X_test) # → IC 评估 + 特征重要性 + 交叉验证 + ML 策略回测
|
||
```
|
||
|
||
Winsorize → 缺失填充 → RobustScaler → LightGBM/CatBoost 训练 → MLBenchmark 对比。
|
||
|
||
### 情绪因子 `finance/factors/sentiment/`
|
||
|
||
```python
|
||
from factors.sentiment.sentiment_engine import SentimentEngine
|
||
|
||
sent = SentimentEngine(dm)
|
||
sent_df = sent.compute("000001.SZ", max_news=20)
|
||
# → news_sent_5, news_conf_5, sent_delta_5
|
||
```
|
||
|
||
三数据源聚合（AkShare 个股新闻 + 新闻联播 DB + MCP trendradar-news）、日期对齐（非交易日→最近交易日）、xwlb 偏移（昨日新闻→今日使用）、DashScope + Ollama 双后端。
|
||
|
||
### Agent 系统 `finance/agents/`
|
||
|
||
```bash
|
||
python finance/cli/agent_cli.py daily # 完整每日流程
|
||
python finance/cli/agent_cli.py picks 15 # 选股 Top 15
|
||
python finance/cli/agent_cli.py risk # 风险评估
|
||
python finance/cli/agent_cli.py research # 因子研究
|
||
python finance/cli/agent_cli.py report # 生成日报
|
||
```
|
||
|
||
4 个 Agent（Research/Selection/Risk/Report）+ 编排器 + 自动日报（reports/daily_YYYYMMDD.md）。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# SSH 隧道
|
||
bash shared/script/autossh.sh
|
||
|
||
# Python 环境
|
||
conda activate quant # Python 3.11.13
|
||
|
||
# 每日 Agent 运行
|
||
python finance/cli/agent_cli.py daily
|
||
```
|
||
|
||
### 验证脚本
|
||
|
||
```bash
|
||
python finance/cli/demo_data_manager.py # Sprint 0 — DataManager
|
||
python finance/cli/demo_factor_engine.py # Sprint 1 — 因子引擎
|
||
python finance/cli/demo_backtest.py # Sprint 2 — 回测引擎
|
||
python finance/cli/demo_optimizer.py # Sprint 3 — 参数优化
|
||
python finance/cli/demo_ml.py # Sprint 4 — ML 模型
|
||
python finance/cli/demo_sentiment.py # Sprint 5 — 情绪因子
|
||
python finance/cli/demo_sentiment_detail.py # Sprint 5 — 情绪因子（单股详情）
|
||
```
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 | 版本 | 状态 |
|
||
|------|------|------|------|
|
||
| 数据获取 | AkShare | 1.18.64 | ✅ |
|
||
| 数据库 | MariaDB (SSH 隧道) | — | ✅ |
|
||
| 因子/特征 | pandas / numpy / sklearn | 2.3 / 2.0 / 1.9 | ✅ |
|
||
| 回测引擎 | VectorBT | 1.0 | ✅ |
|
||
| 参数优化 | Optuna | 4.9 | ✅ |
|
||
| ML 模型 | LightGBM / CatBoost | 4.6 / 1.2 | ✅ |
|
||
| NLP 情绪 | Qwen (DashScope / Ollama) | turbo / 2.5 | ✅ |
|
||
| Agent 框架 | 自研编排器 | — | ✅ |
|
||
| API 后端 | Django + uWSGI | 5.2 | 已有 |
|
||
| 代码分析 | Serena MCP | — | 本机工具（不随仓库分发） |
|
||
|
||
---
|
||
|
||
## 设计原则
|
||
|
||
- **模块隔离**：各引擎通过统一接口交互，可替换实现（VectorBT → Backtrader）
|
||
- **接口标准化**：因子 `calculate(df)→Series` / 策略 `generate_signals(df)→Series` / 模型 `fit/predict/save/load` / 优化 `optimize()→Result`
|
||
- **数据层统一**：策略/模型不直连数据源，全部通过 DataManager
|
||
- **Agent 不重建轮子**：Agent 通过依赖注入复用已有引擎，编排而非重建
|
||
- **防前视偏差**：时间序列交叉验证、expanding window 统计量
|
||
- **渐进演进**：全链路 8 个 Sprint 平滑推进，无推倒重写
|
||
|
||
## 文档
|
||
|
||
- [使用指南](./docs/usage.md) — 详细使用说明（12 章节，含代码示例）
|
||
- [使用指南 (HTML)](./docs/usage.html) — 网页版使用指南
|
||
- [新闻日报 API](./docs/news_report_api.md) — djapi 日报查询接口使用手册
|
||
|
||
## 子项目
|
||
|
||
- [djapi](./djapi/README.md) — Django API 后端：A 股数据 API（16 端点）+ 新闻联播处理 + 日报查询（news/reports、news/events）
|
||
|
||
## 数据库连接
|
||
|
||
```bash
|
||
bash shared/script/autossh.sh
|
||
# host: 127.0.0.1:13306 user: myquant database: myquant table_prefix: mac_
|
||
```
|