# 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 端点参考 |