myquant/docs/development.md

cc-cursor 开发指南

环境搭建

1. 克隆项目

git clone https://github.com/Simon2046/myquant.git
cd cc-cursor

2. Python 环境

conda activate quant          # Python 3.11.13

3. 数据库 SSH 隧道

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

4. 环境变量配置

复制并编辑 finance/.env（参考 finance/.env.example）：

TUSHARE_TOKEN=your_token_here
QWEN_API_KEY=sk-your-key-here
MAC_DB_PASSWORD=your_password_here

5. 验证环境

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)

接口规范

因子接口

class BaseFactor:
    def calculate(self, df: pd.DataFrame) -> pd.Series:
        """接收 OHLCV 数据，返回因子值序列"""

策略接口

class BaseStrategy:
    def generate_signals(self, factor_df: pd.DataFrame) -> pd.Series:
        """接收因子数据，返回交易信号: 1=buy, 0=sell, -1=hold"""

模型接口

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 缓存优先。

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、均线、波动率、换手率、振幅、基本面、情绪。

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 个内置策略 + 自定义策略接口。

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 滚动验证。

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，统一接口，特征工程防前视偏差。

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 双后端。

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。

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 — 仅含占位符的示例配置

提交前检查

grep -r "sk-\|token\|password" --include="*.py" --include="*.md" --include="*.yaml" | grep -v ".example\|your_token\|your_password"

已知 Bug 速查

详见 data-layer.md 和 agents.md 中的 Bug 列表。

文档索引

文档	内容
使用指南	各模块使用方法和代码示例
架构说明	项目架构、数据流、设计原则
因子与表结构速查	34 因子注册表、DB 表结构、数据源接口
数据层详解	DataManager、数据库、缓存策略、已知 Bug
因子引擎详解	因子计算、情绪引擎、新闻源
回测引擎详解	VectorBT、策略、信号工具、Optuna
ML 模型详解	特征工程、LightGBM/CatBoost、ML 策略
Agent 系统详解	Agent 架构、CLI、日报
部署说明	本地环境、服务器、uWSGI、rsync 部署
DJAPI 接口	Django API 端点参考