# 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 后端（已有）
├── mcp-servers/          # MCP Server（Serena）
├── 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 + 自动日报 | ✅ |

**全部 7 个 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倍改善)
```

6 种优化目标 + 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 — 情绪因子
```

---

## 技术栈

| 组件 | 技术 | 版本 | 状态 |
|------|------|------|------|
| 数据获取 | AkShare | 1.18 | ✅ |
| 数据库 | MariaDB (SSH 隧道) | — | ✅ |
| 因子/特征 | pandas / numpy / sklearn | 3.0 / 2.4 / 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 统计量
- **渐进演进**：全链路 7 个 Sprint 平滑推进，无推倒重写

## 文档

- [使用指南](./docs/usage.md) — 详细使用说明（12 章节，含代码示例）
- [使用指南 (HTML)](./docs/usage.html) — 网页版使用指南

## 子项目

- [djapi](./djapi/README.md) — Django API 后端，A 股数据 API + 新闻联播视频处理

## 数据库连接

```bash
bash shared/script/autossh.sh
# host: 127.0.0.1:13306  user: myquant  database: myquant  table_prefix: mac_
```
