simon/myquant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 文档重构 — 清理 AI agent 残留，整合 docs/ 目录结构

Browse Source 
- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md
- 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀
- 新增 4 个文档: architecture.md, development.md, api.md, deployment.md
- 重写 usage.md, README.md
- 修复所有过时引用和交叉链接
This commit is contained in:
Simon
2026-08-22 11:56:40 +08:00
parent 6e1ac0c46b
commit 6acf938caf
34 changed files with 1191 additions and 3909 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+196
View File
@@ -0,0 +1,196 @@
# cc-cursor 项目架构
## 概述
cc-cursor 是一个 Mac Mini 单机量化研究平台，覆盖从数据获取到策略报告的全链路量化研究流程。
## 项目布局
```
cc-cursor/ # 项目根目录
│
├── finance/ # 🔥 核心量化引擎（代码实际位置）
│ ├── config/ # 全局配置：.env 加载、数据库/API 路径
│ ├── database/ # 数据库层：ORM 模型、SQLAlchemy 连接、DAO
│ ├── data/ # 数据层：DataManager 统一入口
│ │ └── sources/ # Tushare + AkShare 双数据源实现
│ ├── factors/ # 因子引擎：34 个注册因子
│ │ ├── technical/ # 技术因子（动量、RSI、MACD、布林等 10 类）
│ │ ├── fundamental/ # 基本面因子（ROE、PE、PB、EP）
│ │ └── sentiment/ # 情绪因子（Qwen NLP + 三源新闻聚合）
│ ├── backtest/ # 回测引擎：VectorBT 封装
│ │ ├── vectorbt/ # VectorBT 引擎适配
│ │ └── strategies/ # 5 个内置策略（均线、RSI、动量等）
│ ├── optimizer/ # 参数优化：Optuna 引擎 + Walk-Forward
│ ├── models/ # ML 模型：LightGBM + CatBoost + 特征工程
│ │ ├── lightgbm/ # LightGBM 模型封装
│ │ └── catboost/ # CatBoost 模型封装
│ ├── agents/ # Agent 系统：4 个 Agent + 编排器
│ ├── cli/ # 命令行入口：agent_cli + 7 个 demo 验证脚本
│ ├── reports/ # 日报输出：daily_YYYYMMDD.md + 存储层
│ ├── strategy/ # 策略层（空壳占位，仅 __init__.py）
│ ├── portfolio/ # 组合管理（空壳占位，仅 __init__.py）
│ ├── execution/ # 执行层（空壳占位，仅 __init__.py）
│ └── scheduler/ # 调度层（空壳占位，仅 __init__.py）
│
├── djapi/ # 🌐 Django API 后端
│ ├── djapi/ # 项目配置：settings、urls、env_loader
│ └── api/ # 唯一 Django app
│ ├── stock/ # A 股数据 API（16 端点）
│ ├── video/ # 新闻联播视频处理（独立模块）
│ └── report/ # 日报查询 API（news/reports + news/events）
│
├── shared/ # 🔧 共享工具
│ └── script/ # autossh.sh（MariaDB SSH 隧道）
│
├── docs/ # 📚 项目文档（13 个 md 文件）
│
├── .claude/ # Claude 配置（空目录，仅保留框架）
│
├── .git/ # Git 仓库
│
├── README.md # 项目入口文档
└── .gitignore # Git 忽略规则
```
### 各目录职责
| 目录 | 职责 | 状态 |
|------|------|------|
| `finance/` | **核心量化引擎**，全链路代码所在地 | ✅ 已实现 |
| `finance/config/` | 全局配置，`.env` 加载和路径管理 | ✅ |
| `finance/database/` | MariaDB 连接、ORM 模型、DAO 数据访问 | ✅ |
| `finance/data/` | 统一数据层，双源（Tushare→AkShare）fallback | ✅ |
| `finance/factors/` | 因子引擎，34 因子/12 分类（技术+基本面+情绪） | ✅ |
| `finance/backtest/` | VectorBT 回测，5 策略 + 截面回测 | ✅ |
| `finance/optimizer/` | Optuna 参数寻优 + Walk-Forward 验证 | ✅ |
| `finance/models/` | LightGBM/CatBoost ML 模型 + 特征工程 | ✅ |
| `finance/agents/` | 4 Agent（Research/Selection/Risk/Report）+ 编排器 | ✅ |
| `finance/cli/` | 命令行入口 + 7 个 demo 验证脚本 | ✅ |
| `finance/reports/` | 日报输出（daily_YYYYMMDD.md）+ 持久化存储 | ✅ |
| `finance/strategy/` | 策略层，预留扩展 | 🚧 空壳 |
| `finance/portfolio/` | 组合管理，预留扩展 | 🚧 空壳 |
| `finance/execution/` | 执行层，预留扩展 | 🚧 空壳 |
| `finance/scheduler/` | 调度层，预留扩展 | 🚧 空壳 |
| `djapi/` | Django API 后端，A 股数据 + 新闻联播 + 日报查询 | ✅ 已部署 |
| `shared/` | 跨项目共享工具（SSH 隧道脚本） | ✅ |
| `docs/` | 项目文档，13 个 md 文件 | ✅ |
## 数据流
```
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
```
### 核心数据流
```
Data → Factor → Model → Strategy → Backtest → Report
```
## 设计原则
### 模块隔离
各引擎通过统一接口交互，可替换实现（VectorBT → Backtrader）。
### 接口标准化
- 因子：`calculate(df) → pd.Series`
- 策略：`generate_signals(df) → pd.Series`
- 模型：`fit/predict/save/load`
- 优化：`optimize() → OptimizationResult`
### 数据层统一
策略/模型不直连数据源，全部通过 `DataManager`。禁止：
- 策略直接访问 AkShare/Tushare
- 模型直接访问数据库
### Agent 不重建轮子
Agent 通过依赖注入复用已有引擎，编排而非重建。
### 防前视偏差
- 时间序列交叉验证（TimeSeriesSplit）
- expanding window 统计量
- 特征工程 fit 在训练集，transform 在测试集
## 技术栈
| 组件 | 技术 | 说明 |
|------|------|------|
| 数据获取 | AkShare + Tushare (双源) | Tushare 优先，AkShare fallback |
| 数据库 | MariaDB (SSH 隧道) | 本地 13306 → 远程 3306 |
| 因子/特征 | pandas / numpy / sklearn | — |
| 回测引擎 | VectorBT 1.0 | 只做多，10 万/万三 |
| 参数优化 | Optuna 4.9 | Walk-Forward 验证 |
| ML 模型 | LightGBM 4.6 + CatBoost 1.2 | 统一接口 |
| NLP 情绪 | Qwen (DashScope / Ollama) | 双后端 |
| Agent 编排 | 自研编排器 | finance/agents/ |
| API 后端 | Django 5.2 + uWSGI | djapi/ |
## 开发进度
| Sprint | 模块 | 状态 |
|--------|------|------|
| Sprint 0 | 基础设施（DataManager + MariaDB 3 表） | ✅ |
| Sprint 1 | 因子引擎（34 因子 / 12 分类） | ✅ |
| Sprint 2 | VectorBT 回测（5 策略 + 截面 + BacktestReport） | ✅ |
| Sprint 3 | Optuna 优化（+ Walk-Forward） | ✅ |
| Sprint 4 | ML 模型（LightGBM + CatBoost + MLStrategy） | ✅ |
| Sprint 5 | Qwen 情绪因子（三源新闻 + 日期对齐） | ✅ |
| Sprint 6 | Agent 系统（4 Agent + CLI + 日报 .md/.html） | ✅ |
| Sprint 7 | djapi API（日报查询 ×2） | ✅ |
**全部 8 个 Sprint 已完成。**
## 数据源架构
### finance/ 引擎层
```
DataManager
├── TushareSource（优先，需 TUSHARE_TOKEN）
├── AkShareSource（fallback，无需 token）
└── Database Cache（SQLAlchemy + MariaDB）
```
### djapi/ API 层
```
api/stock/data_source.py（统一入口）
├── get_tushare_pro() — 全局单例
├── get_daily() — 双源 fallback
└── get_mysql_db() — MySQL 全局单例
```
## 指数代码规则
- `.SH` 结尾且不以 `399` 开头 → 指数（如 `000001.SH`）
- `.SZ` 开头非 `399` → 个股（如 `000001.SZ`）
- `399*.SZ` → 指数（如 `399001.SZ`）
## 文档索引
| 文档 | 内容 |
|------|------|
| [使用指南](usage.md) | 各模块使用方法和代码示例 |
| [开发指南](development.md) | 环境搭建、开发约定、模块说明 |
| [因子与表结构速查](reference.md) | 34 因子注册表、DB 表结构、数据源接口 |
| [数据层详解](data-layer.md) | DataManager、数据库、缓存策略、已知 Bug |
| [因子引擎详解](factors.md) | 因子计算、情绪引擎、新闻源 |
| [回测引擎详解](backtest.md) | VectorBT、策略、信号工具、Optuna |
| [ML 模型详解](ml-models.md) | 特征工程、LightGBM/CatBoost、ML 策略 |
| [Agent 系统详解](agents.md) | Agent 架构、CLI、日报 |
| [部署说明](deployment.md) | 本地环境、服务器、uWSGI、rsync 部署 |
| [DJAPI 接口](api.md) | Django API 端点参考 |
| [日报查询 API](news_report_api.md) | news/reports + news/events 接口 |