docs: 文档重构 — 清理 AI agent 残留，整合 docs/ 目录结构
- 删除 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
@@ -0,0 +1,271 @@
|
||||
# cc-cursor 开发指南
|
||||
|
||||
## 环境搭建
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Simon2046/myquant.git
|
||||
cd cc-cursor
|
||||
```
|
||||
|
||||
### 2. Python 环境
|
||||
|
||||
```bash
|
||||
conda activate quant # Python 3.11.13
|
||||
```
|
||||
|
||||
### 3. 数据库 SSH 隧道
|
||||
|
||||
```bash
|
||||
bash shared/script/autossh.sh
|
||||
# host: 127.0.0.1:13306 user: myquant database: myquant
|
||||
```
|
||||
|
||||
### 4. 环境变量配置
|
||||
|
||||
复制并编辑 `finance/.env`（参考 `finance/.env.example`）：
|
||||
|
||||
```bash
|
||||
TUSHARE_TOKEN=your_token_here
|
||||
QWEN_API_KEY=sk-your-key-here
|
||||
MAC_DB_PASSWORD=your_password_here
|
||||
```
|
||||
|
||||
### 5. 验证环境
|
||||
|
||||
```bash
|
||||
python finance/cli/demo_data_manager.py
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
finance/ # 核心量化引擎（代码实际位置）
|
||||
├── config/ # 全局配置
|
||||
│ └── settings.py # .env 加载 + 路径配置
|
||||
├── database/ # 数据库层
|
||||
│ ├── connection.py # SQLAlchemy 引擎 + SSH 自动恢复
|
||||
│ ├── models.py # ORM 模型（mac_ 前缀表）
|
||||
│ └── dao.py # 数据访问对象
|
||||
├── data/ # 数据层
|
||||
│ ├── data_manager.py # 统一数据入口
|
||||
│ └── sources/ # 数据源实现
|
||||
│ ├── tushare_source.py
|
||||
│ └── akshare_source.py
|
||||
├── factors/ # 因子引擎
|
||||
│ ├── base.py # 因子基类
|
||||
│ ├── engine.py # 因子计算引擎
|
||||
│ ├── registry.py # 因子注册表
|
||||
│ ├── technical/ # 技术因子（10 类）
|
||||
│ ├── fundamental/ # 基本面因子
|
||||
│ └── sentiment/ # 情绪因子
|
||||
│ ├── sentiment_engine.py
|
||||
│ ├── sentiment_factor.py
|
||||
│ ├── news_source.py # 三源新闻聚合
|
||||
│ └── qwen_client.py # Qwen API 客户端
|
||||
├── backtest/ # 回测引擎
|
||||
│ ├── base.py # 策略基类
|
||||
│ ├── report.py # 回测报告
|
||||
│ ├── signal.py # 信号工具
|
||||
│ ├── vectorbt/ # VectorBT 引擎
|
||||
│ └── strategies/ # 内置策略
|
||||
├── optimizer/ # 参数优化
|
||||
│ ├── engine.py # Optuna 引擎
|
||||
│ ├── space.py # 搜索空间
|
||||
│ ├── objectives.py # 优化目标
|
||||
│ └── result.py # 优化结果
|
||||
├── models/ # ML 模型
|
||||
│ ├── base.py # 模型基类
|
||||
│ ├── features.py # 特征工程
|
||||
│ ├── backtest_integration.py # ML 策略
|
||||
│ ├── lightgbm/
|
||||
│ └── catboost/
|
||||
├── agents/ # Agent 系统
|
||||
│ ├── base.py # Agent 基类
|
||||
│ ├── orchestrator.py # 编排器
|
||||
│ ├── research_agent.py # 因子研究
|
||||
│ ├── selection_agent.py # 股票打分
|
||||
│ ├── risk_agent.py # 风险评估
|
||||
│ └── report_agent.py # 日报生成
|
||||
├── cli/ # 命令行
|
||||
│ ├── agent_cli.py # Agent CLI 入口
|
||||
│ └── demo_*.py # 验证脚本
|
||||
└── reports/ # 日报输出
|
||||
└── storage.py # 报告持久化
|
||||
```
|
||||
|
||||
## 开发约定
|
||||
|
||||
### 代码组织
|
||||
|
||||
- 代码内 import 用顶层名 `data.*`/`factors.*` 等 — CLI 自动把 `finance/` 加入 sys.path
|
||||
- 文件路径为 `finance/data/xxx.py` 等
|
||||
|
||||
### 数据流约束
|
||||
|
||||
```
|
||||
Data → Factor → Model → Strategy → Backtest → Report
|
||||
```
|
||||
|
||||
**必须遵守**：
|
||||
- 策略层禁止直接访问 AkShare/Tushare → 全部通过 `DataManager`
|
||||
- 模型层禁止直接访问数据库 → 全部通过 `DataManager`
|
||||
- 指数代码规则：`.SH`=指数, `.SZ` 开头非 399=个股
|
||||
- 数据源优先级：Tushare → AkShare (fallback)
|
||||
|
||||
### 接口规范
|
||||
|
||||
#### 因子接口
|
||||
```python
|
||||
class BaseFactor:
|
||||
def calculate(self, df: pd.DataFrame) -> pd.Series:
|
||||
"""接收 OHLCV 数据，返回因子值序列"""
|
||||
```
|
||||
|
||||
#### 策略接口
|
||||
```python
|
||||
class BaseStrategy:
|
||||
def generate_signals(self, factor_df: pd.DataFrame) -> pd.Series:
|
||||
"""接收因子数据，返回交易信号: 1=buy, 0=sell, -1=hold"""
|
||||
```
|
||||
|
||||
#### 模型接口
|
||||
```python
|
||||
class BaseModel:
|
||||
def fit(self, X, y): ...
|
||||
def predict(self, X) -> np.ndarray: ...
|
||||
def save(self, path): ...
|
||||
@classmethod
|
||||
def load(cls, path): ...
|
||||
```
|
||||
|
||||
### 多步任务规则
|
||||
|
||||
复杂任务（涉及 3+ 文件或 2+ 模块）执行前：
|
||||
1. 输出执行计划清单（步骤 + 每步验证方法）
|
||||
2. 每步完成后验证通过才继续
|
||||
3. 遇到失败先定位根因，不跳过
|
||||
|
||||
### 修改多文件前
|
||||
|
||||
先说明：文件清单、原因、影响；优先小范围修改。
|
||||
|
||||
## 模块说明
|
||||
|
||||
### 数据层 (`finance/data/`)
|
||||
|
||||
双数据源架构：Tushare（优先）→ AkShare（fallback），DB 缓存优先。
|
||||
|
||||
```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") # → 财务
|
||||
n = dm.sync_daily("000001.SZ") # → 增量同步
|
||||
```
|
||||
|
||||
### 因子引擎 (`finance/factors/`)
|
||||
|
||||
34 个注册因子，12 个分类：动量、RSI、MACD、量价、布林、ATR、均线、波动率、换手率、振幅、基本面、情绪。
|
||||
|
||||
```python
|
||||
from factors.registry import get_factor, list_factors
|
||||
from factors.engine import FactorEngine
|
||||
|
||||
fe = FactorEngine(dm)
|
||||
factor_df = fe.compute("000001.SZ", [get_factor("momentum_20"), get_factor("rsi_14")])
|
||||
```
|
||||
|
||||
### 回测引擎 (`finance/backtest/`)
|
||||
|
||||
VectorBT 1.0，只做多，10 万/万三。5 个内置策略 + 自定义策略接口。
|
||||
|
||||
```python
|
||||
from backtest.vectorbt.engine import VectorBTEngine
|
||||
engine_bt = VectorBTEngine(initial_capital=100_000, commission=0.0003)
|
||||
report = engine_bt.run(strategy, price_df, factor_df)
|
||||
```
|
||||
|
||||
### 参数优化 (`finance/optimizer/`)
|
||||
|
||||
Optuna 4.9 + Walk-Forward 滚动验证。
|
||||
|
||||
```python
|
||||
from optimizer.engine import OptunaEngine
|
||||
opt = OptunaEngine(engine_bt)
|
||||
result = opt.optimize(StrategyClass, space, price_df, factor_df, metric="sharpe", n_trials=200)
|
||||
```
|
||||
|
||||
### ML 模型 (`finance/models/`)
|
||||
|
||||
LightGBM 4.6 + CatBoost 1.2，统一接口，特征工程防前视偏差。
|
||||
|
||||
```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)
|
||||
```
|
||||
|
||||
### 情绪因子 (`finance/factors/sentiment/`)
|
||||
|
||||
三数据源聚合（AkShare 个股新闻 + 新闻联播 DB + MCP trendradar-news），Qwen DashScope + Ollama 双后端。
|
||||
|
||||
```python
|
||||
from factors.sentiment.sentiment_engine import SentimentEngine
|
||||
sent = SentimentEngine(dm)
|
||||
sent_df = sent.compute("000001.SZ", max_news=20)
|
||||
```
|
||||
|
||||
### Agent 系统 (`finance/agents/`)
|
||||
|
||||
4 个 Agent（Research/Selection/Risk/Report）+ 编排器 + CLI。
|
||||
|
||||
```bash
|
||||
python finance/cli/agent_cli.py daily # 完整流程
|
||||
python finance/cli/agent_cli.py picks 15 # 选股
|
||||
python finance/cli/agent_cli.py risk # 风险评估
|
||||
```
|
||||
|
||||
## 安全规范
|
||||
|
||||
### 禁止提交
|
||||
|
||||
- `.env`（含真实 key）
|
||||
- API Key（`sk-*`、`TUSHARE_TOKEN` 等）
|
||||
- Cookie / Session / Token / 密钥
|
||||
- 个人隐私数据（手机号、身份证、密码）
|
||||
|
||||
### 必须提供
|
||||
|
||||
- `.env.example` — 仅含占位符的示例配置
|
||||
|
||||
### 提交前检查
|
||||
|
||||
```bash
|
||||
grep -r "sk-\|token\|password" --include="*.py" --include="*.md" --include="*.yaml" | grep -v ".example\|your_token\|your_password"
|
||||
```
|
||||
|
||||
## 已知 Bug 速查
|
||||
|
||||
详见 [data-layer.md](data-layer.md) 和 [agents.md](agents.md) 中的 Bug 列表。
|
||||
|
||||
## 文档索引
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| [使用指南](usage.md) | 各模块使用方法和代码示例 |
|
||||
| [架构说明](architecture.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 端点参考 |
|
||||
Reference in New Issue
Block a user