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
README.md
+79 -181
View File
@@ -7,225 +7,123 @@
```
cc-cursor/
├── finance/ # 核心量化引擎
│ ├── config/ # 全局配置（MariaDB / AkShare）
│ ├── database/ # ORM 模型 + DAO（mac_ 前缀表）
│ ├── config/ # 全局配置
│ ├── database/ # ORM 模型 + DAO
│ ├── data/ # DataManager 统一数据层
│ ├── factors/ # 因子引擎（34 因子 / 12 分类，含情绪因子）
│ ├── backtest/ # 回测引擎（VectorBT + 5 策略 + 截面回测）
│ ├── optimizer/ # Optuna 参数优化 + Walk-Forward
│ ├── factors/ # 因子引擎（34 因子 / 12 分类）
│ ├── backtest/ # 回测引擎（VectorBT + 5 策略）
│ ├── optimizer/ # Optuna 参数优化
│ ├── models/ # LightGBM / CatBoost ML 模型
│ ├── agents/ # Agent 系统（4 Agent + 编排器 + CLI）
│ ├── agents/ # Agent 系统（4 Agent + 编排器）
│ ├── cli/ # 命令行 & 验证脚本
│ ├── reports/ # 自动日报输出目录
│ └── .env # 环境变量配置（API Key / 分析范围）
├── djapi/ # Django API 后端（A 股数据 + 新闻联播 + 日报查询）
├── mcp-servers/ # MCP Server（Serena，本机工具，git 忽略）
├── shared/ # 共享工具（SSH 隧道脚本）
├── docs/ # 文档 & 使用指南
└── .claude/ # Claude Code 配置
│ └── reports/ # 日报输出目录
├── djapi/ # Django API 后端
├── shared/script/ # SSH 隧道脚本
└── docs/ # 项目文档
```
## 数据流
```
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
```
全部通过 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 隧道
# 环境 & SSH 隧道
conda activate quant
bash shared/script/autossh.sh
# Python 环境
conda activate quant # Python 3.11.13
# 每日 Agent 运行
python finance/cli/agent_cli.py daily
```
### 验证脚本
## CLI 命令
```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 — 情绪因子（单股详情）
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 | 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 | — | 本机工具（不随仓库分发） |
| 组件 | 技术 |
|------|------|
| 数据获取 | 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） | ✅ |
- **模块隔离**：各引擎通过统一接口交互，可替换实现（VectorBT → Backtrader）
- **接口标准化**：因子 `calculate(df)→Series` / 策略 `generate_signals(df)→Series` / 模型 `fit/predict/save/load` / 优化 `optimize()→Result`
- **数据层统一**：策略/模型不直连数据源，全部通过 DataManager
- **Agent 不重建轮子**：Agent 通过依赖注入复用已有引擎，编排而非重建
- **防前视偏差**：时间序列交叉验证、expanding window 统计量
- **渐进演进**：全链路 8 个 Sprint 平滑推进，无推倒重写
**全部 8 个 Sprint 已完成。**
## 文档
- [使用指南](./docs/usage.md) — 详细使用说明（12 章节，含代码示例）
- [使用指南 (HTML)](./docs/usage.html) — 网页版使用指南
- [新闻日报 API](./docs/news_report_api.md) — djapi 日报查询接口使用手册
| 文档 | 内容 |
|------|------|
| [使用指南](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 端点）+ 新闻联播处理 + 日报查询（news/reports、news/events）
- [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_
```
```