# cc-cursor — Mac Mini 单机量化研究平台

从数据获取 → 因子计算 → 回测 → 参数优化 → ML 模型 → 情绪因子 → Agent 系统，全链路量化研究平台。

## 架构

```
cc-cursor/
├── finance/              # 核心量化引擎
│   ├── config/           # 全局配置
│   ├── database/         # ORM 模型 + DAO
│   ├── data/             # DataManager 统一数据层
│   ├── factors/          # 因子引擎（34 因子 / 12 分类）
│   ├── backtest/         # 回测引擎（VectorBT + 5 策略）
│   ├── optimizer/        # Optuna 参数优化
│   ├── models/           # LightGBM / CatBoost ML 模型
│   ├── agents/           # Agent 系统（4 Agent + 编排器）
│   ├── cli/              # 命令行 & 验证脚本
│   └── reports/          # 日报输出目录
├── djapi/                # Django API 后端
├── shared/script/        # SSH 隧道脚本
└── docs/                 # 项目文档
```

## 数据流

```
Data → Factor → Model → Strategy → Backtest → Report
```

## 快速开始

```bash
# 环境 & SSH 隧道
conda activate quant
bash shared/script/autossh.sh

# 每日 Agent 运行
python finance/cli/agent_cli.py daily
```

## CLI 命令

```bash
python finance/cli/agent_cli.py daily              # 5 步完整流程
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 20260603    # 生成日报
python finance/cli/agent_cli.py warmup 50          # 首次预热缓存
```

## 验证脚本

```bash
python finance/cli/demo_data_manager.py --ts_code 600519.SH
python finance/cli/demo_factor_engine.py --ts_code 300750.SZ
python finance/cli/demo_backtest.py --ts_code 000001.SZ
python finance/cli/demo_optimizer.py --ts_code 000001.SZ --trials 100
python finance/cli/demo_ml.py --ts_code 000001.SZ --lookahead 5
python finance/cli/demo_sentiment.py --ts_code 600519.SH
python finance/cli/demo_sentiment_detail.py --ts_code 600519.SH --date 20260603
```

## 技术栈

| 组件 | 技术 |
|------|------|
| 数据获取 | AkShare + Tushare (双源) |
| 数据库 | MariaDB (SSH 隧道) |
| 因子/特征 | pandas / numpy / sklearn |
| 回测引擎 | VectorBT 1.0 |
| 参数优化 | Optuna 4.9 |
| ML 模型 | LightGBM 4.6 + CatBoost 1.2 |
| NLP 情绪 | Qwen (DashScope / Ollama) |
| Agent 编排 | 自研编排器 |
| API 后端 | Django 5.2 + uWSGI |

## 开发进度

| Sprint | 模块 | 状态 |
|--------|------|------|
| Sprint 0 | 基础设施（DataManager + MariaDB） | ✅ |
| 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） | ✅ |

**全部 8 个 Sprint 已完成。**

## 文档

| 文档 | 内容 |
|------|------|
| [使用指南](docs/usage.md) | 各模块使用方法和代码示例 |
| [架构说明](docs/architecture.md) | 项目架构、数据流、设计原则 |
| [开发指南](docs/development.md) | 环境搭建、开发约定、模块说明 |
| [部署说明](docs/deployment.md) | 本地环境、服务器、uWSGI、rsync 部署 |
| [因子与表结构速查](docs/reference.md) | 34 因子注册表、DB 表结构 |
| [数据层详解](docs/data-layer.md) | DataManager、数据库、缓存策略 |
| [因子引擎详解](docs/factors.md) | 因子计算、情绪引擎、新闻源 |
| [回测引擎详解](docs/backtest.md) | VectorBT、策略、信号工具、Optuna |
| [ML 模型详解](docs/ml-models.md) | 特征工程、LightGBM/CatBoost |
| [Agent 系统详解](docs/agents.md) | Agent 架构、CLI、日报 |
| [DJAPI 接口](docs/api.md) | Django API 端点参考 |
| [日报查询 API](docs/news_report_api.md) | news/reports + news/events 接口 |
| [日报数据库](docs/db_schema_v1.1.md) | news_report / news_event 表结构 |

## 子项目

- [djapi](djapi/README.md) — Django API 后端：A 股数据 API（16 端点）+ 新闻联播处理 + 日报查询

## 设计原则

- **模块隔离**：各引擎通过统一接口交互，可替换实现
- **接口标准化**：因子 `calculate(df)→Series` / 策略 `generate_signals(df)→Series` / 模型 `fit/predict/save/load`
- **数据层统一**：策略/模型不直连数据源，全部通过 DataManager
- **Agent 不重建轮子**：Agent 通过依赖注入复用已有引擎
- **防前视偏差**：时间序列交叉验证、expanding window 统计量

## 数据库连接

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