# VibeQuant

**Repository Path**: lele2015/vibe-quant

## Basic Information

- **Project Name**: VibeQuant
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vibe-Quant 量化策略平台

基于 Tushare + LightGBM + Optuna + LLM 的 A 股量化选股策略平台，支持从股票池获取、因子计算、**LLM 辅助因子生成**、模型训练优化到信号生成和回测验证的全自动化流程。

## 📦 目录结构

```
vibe-quant/
├── pipeline_data_prepare.py           # 数据准备阶段（0-A, 0-B, 0-C）
├── pipeline_stage1.py                 # 阶段一：因子计算 + 因子评估
├── pipeline_stage2_baseline.py        # Stage 2 Baseline：基础模型训练
├── pipeline_stage2_optuna.py          # Stage 2 Optuna：超参数优化
├── pipeline_stage3.py                 # 阶段三：可视化分析
├── pipeline_stage4.py                 # 阶段四：选股信号生成
├── pipeline-bt-LGBM.py                # Backtrader 回测验证（LGBM 模型版）
├── pipeline-bt-multiFact.py           # Backtrader 回测（多因子选股版）
├── pipeline-bt-simpleRank.py          # Backtrader 回测（简单截面排名版）
├── pipeline-bt-reversalV2.py          # Backtrader 回测（短期反转 v2 版）
├── pipeline-bt-pullback.py            # Backtrader 回测（强势回调放量版）
├── config.py                          # 配置管理（环境变量 > YAML > 自动检测）
├── config.yaml                        # 全局主配置文件
├── llm_config.yaml                    # LLM 因子生成独立配置
├── data_dictionary.yaml               # LLM 输入数据字典
├── requirements.txt                   # Python 依赖
├── README.md                          # 本文件
│
├── prompt_templates/                  # LLM Prompt 模板
│   └── factor_gen.txt                 # 因子生成 Prompt（一次 10 个因子）
│
├── factors/                           # 因子注册模块
│   ├── __init__.py                    # 因子注册表（27 个类别，含 LLM_GENERATED）
│   └── llm_registry.py                # LLM 因子动态注册 + 计算引擎
│
├── factor_profiles/                   # 因子组合配置
│   ├── full_76.yaml                   # 全量 76 因子
│   ├── reduced_50.yaml                # 精简 51 因子
│   └── llm_generated.yaml             # LLM 生成因子（自动维护）
│
├── strategy_configs/                  # 策略参数配置
│   ├── ml_baseline.yaml
│   ├── multi_factor.yaml
│   ├── pullback_launch.yaml
│   ├── reversal_v2.yaml
│   └── simple_ranking.yaml
│
├── scripts/
│   ├── init_config.py                 # 配置初始化（从模板生成 + 交互式修改）
│   ├── industry_browser.py            # 行业/概念板块交互式浏览（空格多选 + 搜索）
│   ├── model_utils.py                 # 模型备份元数据构建工具
│   ├── restore_model.py               # 模型恢复工具（交互式版本选择）
│   ├── data_utils.py                  # 公共数据工具（日期、拆分、验证）
│   ├── factor_utils.py                # 公共因子计算模块（67 技术因子 + LLM 因子）
│   ├── get_i_industry_stocks.py       # 获取行业/概念股票池
│   ├── download_it_stocks_history.py  # 批量下载历史行情（增量 + 重试）
│   ├── download_benchmark_data.py     # 基准指数数据下载（CSI 300/500 增量更新）
│   ├── split_data.py                  # 训练/回测数据拆分（固定日期阈值）
│   ├── batch_factors.py               # 批量因子计算（--mode training|backtest）
│   ├── evaluate_all_factors.py        # 因子评估 (IC/IR)
│   ├── train_lgb_model_all_stocks.py  # LightGBM 基础模型训练
│   ├── optuna_lgb_optimization.py     # Optuna 超参数优化
│   ├── visualize_optuna_results.py    # 优化结果可视化
│   ├── generate_latest_signals.py     # 最新选股信号生成
│   ├── multi_factor_stock_selector.py # 低波·动量·量价·资金 多因子选股打分
│   ├── reversal_volume_selector.py    # 短期反转 + 放量确认 选股信号
│   ├── backtest_backtrader_multi.py   # 多股票组合回测（模型版）
│   ├── backtest_backtrader_selector.py # 多因子选股回测（非模型版）
│   ├── backtest_backtrader_reversal.py # 短期反转 + 放量确认 回测
│   ├── backtest_backtrader_utils.py   # 回测工具函数（ALPHA/Beta/IR 计算 + 基准加载）
│   ├── script_config.py               # 脚本通用配置
│   │
│   ├── llm_closed_loop.py             # LLM 因子生成闭环主控
│   ├── llm_factor_engine.py           # AST 沙箱 + 因子验证 + 注册
│   ├── llm_quick_eval.py              # 快速采样 IC/IR 评估
│   │
│   └── stock_pool/                    # 股票池公共模块
│       ├── fetcher.py                 # API 重试、缓存、元数据
│       ├── validation.py              # 4 级单文件验证 + 双文件联合验证
│       ├── classification_cache.py    # 行业/概念分类统一获取与缓存
│       ├── reporter.py                # Markdown/JSON 双格式输出
│       └── cli.py                     # 命令行接口
│
├── docs/                               # 流程分析文档（19 篇）
│   ├── COMMON_DATA_PREPARE_FLOW.md     # 数据准备流程
│   ├── COMMON_STAGE1_FACTOR.md         # Stage 1 因子计算与评估流程
│   ├── COMMON_STAGE_PLOT.md            # 可视化分析流程
│   ├── LGBM_STAGE2_TRAIN.md            # Stage 2 模型训练流程
│   ├── LGBM_STAGE4_SIGNALS.md          # Stage 4 选股信号流程
│   ├── LGBM_STAGE5_BACKTEST.md         # Stage 5 回测验证流程
│   ├── FACTOR_LIST.md                  # 因子完整清单（67 技术 + 9 价值 + 9 排名）
│   ├── EVALUATION_FACTOR.md            # 因子评估分析与改进建议
│   ├── EVALUATION_BACKTEST.md          # 回测评估分析
│   ├── LLM_FACTOR_PIPELINE.md          # LLM 因子生成闭环 Pipeline 技术文档
│   ├── SELECTOR_BACKTEST.md            # 多因子选股回测分析
│   ├── TRADING_STRATEGY.md             # 交易策略总览
│   ├── STRATEGY_LGBM.md                # LGBM 横截面五分位排名策略
│   ├── STRATEGY_MULTI_FACTOR.md        # 低波·动量·量价·资金 选股策略
│   ├── STRATEGY_PULLBACK_LAUNCH.md     # 强势回调放量再启动策略
│   ├── STRATEGY_REVERSAL.md            # 短期反转 v2 精细化策略
│   ├── STRATEGY_SIMPLE_RANKING.md      # 简单截面排名策略
│   ├── STRATEGY_COMPARISON.md          # 多策略横向对比分析
│   └── STRATEGY_OPTIMIZATION.md        # 策略优化建议与路线图
│
├── logs/                              # 运行日志目录
└── vibecode/                           # 技术方案与变更分析
    ├── LLM_FACTOR_PIPELINE.md           # LLM 闭环方案设计
    ├── NEW_FACTOR_PLAN.md               # 新增因子实施方案
    ├── FACTOR_REDUCTION_PLAN.md         # 因子精简方案
    └── FACTOR_CHANGE_ANALYSIS.md        # 因子变更影响分析
```

## 🚀 快速开始

### 前提条件

1. **Python 环境**：Python 3.12+
2. **依赖安装**：
   ```bash
   pip install -r requirements.txt
   ```
3. **Tushare Token**：注册 [Tushare Pro](https://tushare.pro) 获取 API Token
4. **TA-Lib**：系统级安装 `libta-lib`（`apt install libta-lib-dev` 或 `brew install ta-lib`）

### 配置

配置优先级：**环境变量 > YAML 文件 > 自动检测 > 默认值**

**方式 1：环境变量（推荐）**
```bash
export TUSHARE_TOKEN="your_token_here"
export VQ_START_DATE="2023-01-01"
export VQ_END_DATE="current"
```

**方式 2：配置初始化脚本（推荐）**
```bash
# 交互式初始化（引导填写 Token、行业、日期、概念等）
python3 scripts/init_config.py --work-dir ~/vq_work

# 行业一键初始化（概念自动跟随行业名）
python3 scripts/init_config.py --token your_token --industry 半导体 \
  --keywords "半导体,芯片" --start-date 2023-01-01

# 行业 + 概念独立配置
python3 scripts/init_config.py --token your_token --industry 锂电池 \
  --concept-name 电池概念 --concept-keywords "锂电池,电池" --pool-mode combined

# 仅概念板块模式
python3 scripts/init_config.py --token your_token --concept-name AI芯片 --pool-mode concept_only
```

**方式 3：行业/概念浏览选择（推荐用于精确配置）**
```bash
# 浏览并选择行业分类（自动写入精确 Tushare 代码 industry_codes）
python3 scripts/industry_browser.py

# 浏览并选择概念板块
python3 scripts/industry_browser.py --browse concept
```

选择后 config.yaml 中会同时保存行业名称和精确代码：
```yaml
industry_name: 采掘
industry_code: 801020.SI          # Tushare 精确代码
industry_keywords: [采掘]          # 人可读的名称
industry_codes: [801020.SI]       # 机可用的代码（快速路径）
stock_pool_file: 801020.SI股票池.md
```

使用精确代码可跳过全量分类获取和关键词匹配，直接获取成分股。

**策略参数配置（独立 YAML 文件）**：
```bash
# 策略参数存储在独立 YAML 文件中
# 修改后无需改代码，重新运行信号生成即可生效
vim {data_dir}/strategy_configs/reversal.yaml
```

```yaml
# {data_dir}/strategy_configs/reversal.yaml
signals:
  top_pct: 0.20              # 反转评分取前 20%
  vol_ratio_min: 1.2         # 放量阈值
  corr_min: -0.3             # 量价相关性下限
  amount_roc_min: 0.05       # 资金变化率下限
  amount_roc_max: 0.30       # 资金变化率上限
trading:
  max_positions: 20          # 最大持仓
  stop_loss: -0.05           # 止损 -5%
  take_profit: 0.10          # 止盈 +10%
  hold_days: 5               # 持有天数
```

**方式 4：手动配置**
```bash
cp config.yaml.template config.yaml
# 编辑 config.yaml，填入相应配置
```

### 运行

**分阶段运行（推荐）**：
```bash
python3 pipeline_data_prepare.py      # 数据准备（0-A 股票池 + 0-B 行情 + 0-C 拆分）
python3 pipeline_stage1.py            # 因子计算 + IC/IR 评估
python3 pipeline_stage2_baseline.py    # 基础模型训练
python3 pipeline_stage2_optuna.py      # Optuna 超参数优化
python3 pipeline_stage3.py            # 可视化分析
python3 pipeline_stage4.py            # 最新选股信号生成
python3 pipeline-bt-LGBM.py            # 回测因子计算 + Backtrader 回测验证（LGBM 模型版）
python3 pipeline-bt-multiFact.py   # 多因子选股回测（低波+动量+量价+资金）
python3 pipeline-bt-simpleRank.py   # 简单截面排名回测
python3 pipeline-bt-reversalV2.py   # 短期反转 v2 回测
python3 pipeline-bt-pullback.py     # 强势回调放量回测
```

### 策略执行

**多因子选股（低波·动量·量价·资金）**：
```bash
# 一步执行（信号生成 + 回测）
python3 pipeline-bt-multiFact.py

# 或分步
python3 scripts/multi_factor_stock_selector.py --mode backtest
python3 scripts/backtest_backtrader_selector.py
```

**短期反转 + 放量确认**：
```bash
python3 scripts/reversal_volume_selector.py --mode backtest
python3 scripts/backtest_backtrader_reversal.py
```
```

## 📋 执行步骤

| 阶段 | 步骤 | 说明 | 实际耗时 |
|------|------|------|----------|
| 数据准备 | 0-A | 获取行业/概念股票池（支持 `combined` 模式，双文件联合验证） | ~60s |
| 数据准备 | 0-B | 增量下载历史行情 | ~3-5min 首次 / ~1s 增量 |
| 数据准备 | 0-C | 固定日期阈值拆分训练/回测 | ~12s |
| 阶段一 | 1 | 批量因子计算（67 技术因子 + 9 价值因子 + LLM 因子） | ~15s |
| 阶段一 | 2 | 因子评估 (IC/IR) | ~35s |
| Stage 2 Baseline | 3 | LightGBM 基础模型训练 + 自动备份（含元数据） | ~13s |
| Stage 2 Optuna | 4 | Optuna 超参数优化（50 trials）+ 自动备份 | ~10min |
| 阶段三 | 5 | 优化结果可视化（7 面板） | ~5s |
| 阶段四 | 6 | 最新选股信号生成（model.feature_name_ 动态提取） | ~2s |
| 阶段五 | 7-A | 回测因子计算（含 LLM 因子 + CCI/MFI） | ~30s |
| 阶段五 | 7-B | Backtrader 回测验证（含 CSI 300/500 基准对比） | ~10s |
| **LLM 闭环** | **L1** | LLM 因子生成（Prompt → AST 校验 → 沙箱验证） | ~30s |
| **LLM 闭环** | **L2** | 快速采样评估（200 只股票 IC/IR，不重跑全量） | ~30s |
| **LLM 闭环** | **L3** | 自动演化（参数变体 + 归一化 + 组合） | ~5s |
| **LLM 闭环** | **L4** | 人工审核（Tier-A 自动批准 / Tier-B 人工 / Tier-C 拒绝） | 2-5min |
| 多因子选股 | — | 低波·动量·量价·资金 选股打分 + 回测 | ~5s |
| 简单截面排名 | — | 5 日收益排名 + 放量过滤 选股 + 回测 | ~5s |
| 短期反转 v2 | — | 四层精细化反转 选股 + 回测 | ~5s |
| 强势回调放量 | — | 强势股回调放量再启动 选股 + 回测 | ~5s |

## 🤖 LLM 辅助因子生成（v2.0 新增）

半自动化 alpha 因子发现管线：**LLM 生成 → AST 沙箱验证 → 快速 IC/IR 评估 → 自动演化 → 人工审核 → 全量回测**

### 快速启动

```bash
# 1. 设置 API Key
export OPENAI_API_KEY="sk-..."

# 2. 干跑测试（不调用 API，验证全管线）
python3 scripts/llm_closed_loop.py --dry-run

# 3. 正式运行 1 轮闭环（生成 10 个因子 → 验证 → 评估 → 演化 → 审查）
python3 scripts/llm_closed_loop.py --rounds 1

# 4. 多轮迭代（每轮 10 个因子，3 轮共 30 个）
python3 scripts/llm_closed_loop.py --rounds 3

# 5. 审批通过后，全量计算 + 训练 + 回测
python3 pipeline_stage1.py --step 1,2
python3 pipeline_stage2_baseline.py
python3 pipeline-bt-LGBM.py
```

### 核心组件

| 组件 | 文件 | 功能 |
|------|------|------|
| 数据字典 | `data_dictionary.yaml` | 向 LLM 描述可用字段、运算库、约束 |
| Prompt 模板 | `prompt_templates/factor_gen.txt` | 一次生成 10 个因子的模板 |
| AST 沙箱 | `scripts/llm_factor_engine.py` | 白名单 AST 校验 + 安全性检测 + 质检 |
| 快速评估 | `scripts/llm_quick_eval.py` | 200 只股票采样 IC/IR（~30 秒，不重跑全量） |
| 闭环主控 | `scripts/llm_closed_loop.py` | 串联前流程 + 自动演化 + 分层审批 |
| 因子注册 | `factors/llm_registry.py` | 动态注册 LLM 因子 + 自动注入横截面 rank |
| 独立配置 | `llm_config.yaml` | LLM API、验证阈值、演化参数、审批分层 |

### 安全机制

- **AST 白名单**：禁止 import/exec/for/while/文件访问/dunder 属性
- **受限命名空间**：仅暴露 np/talib/OHLCV 数组，禁用危险内置函数
- **运行时质检**：检查 NaN/Inf/常量/数值规模/数组长度
- **独立配置**：`llm_config.yaml` 与主配置分离，可独立分发

### 闭环流程

```
LLM API → 因子代码生成 → AST 沙箱验证 → 快速采样评估
                                            ↓
                                筛选 (IC>0.02, 非冗余)
                                            ↓
                                自动演化 (参数/归一化/组合变体)
                                            ↓
                                人工审核 (Tier-A 自动批 / Tier-B 审 / Tier-C 拒)
                                            ↓
                   全量计算 → 模型训练 → 回测 → 对比报告 → 反馈 LLM → 下一轮
```

## 🛠️ 核心修复与改进

### P0 修复（影响结果正确性）

| 修复 | 阶段 | 旧行为 | 新行为 |
|------|------|--------|--------|
| **Future_Return 方向** | Stage 1 | `pct_change(N).shift(N)` 计算过去收益率 | `shift(-N) / close - 1` 计算未来收益率 |
| **训练/回测因子列名统一** | Stage 5 | `batch_backtest_factors.py` 输出 `Boll_Upper`、`ATR`（与训练期不同） | 使用 `factor_utils`，输出 `Boll_Upper_20`、`ATR_14`（与训练期一致） |
| **因子计算合并** | Stage 1/5 | `batch_alpha158_factors.py` + `batch_backtest_factors.py` 两份重复代码 | 合并为 `batch_factors.py --mode training|backtest` |
| **验证列名不匹配** | Stage 0 | `required_cols` 含 `date`/`volume`（不存在列） | 修正为 `trade_date`/`vol`，验证正式生效 |
| **验证函数日期列名** | Stage 0 | `check_step0_download_history()` 用 `df['date']`（不存在列） | 修正为 `df['trade_date']`（v1.2 只修了 `required_cols`，漏了日期处理） |
| **数据拆分日期不一致** | Stage 0 | 比例拆分（不同股票拆分日期不同） | 固定日期阈值（所有股票同一切分日） |
| **配置日期不生效** | Stage 0 | `HISTORY_START_DATE` 硬编码 | 读取 `config.get('start_date')` |
| **Stage 4 数据过时** | Stage 4 | 读取 `training_factors/`（训练期数据） | 读取 `it_stocks/` 实时计算因子 |
| **Stage 4 特征不匹配** | Stage 4 | 硬编码 24 个特征 | `model.feature_name_` 动态提取 |

### P1 修复（质量与可维护性）

| 修复 | 说明 |
|------|------|
| **配置统一管理** | 所有脚本改用 `get_config()`，消除硬编码 `yaml.safe_load(open(...))` |
| **异常可追溯** | `except: pass` → `print(f"  ⚠️ ... - {e}")` |
| **Rank 特征全线打通** | Stage 1 计算 → Stage 2 优化 → Stage 5 回测，全链路使用 |
| **Optuna 最终模型重训** | 从 `best_iteration_` 获取最优迭代数，在 70% 数据上重训（原仅 56%） |
| **Optuna 搜索空间可配置** | `config.yaml` 中 `optuna.search_space` 完整生效 |
| **横截面排名因子扩展** | 从 10 个扩展到 18 个（含 Returns_60d, Volatility, ATR 等） |
| **Step 0-A 自动 fallback** | 股票池文件不存在/过小时自动调用 `--force` 生成，无需手动干预 |
| **_auto_detect 占位符修复** | `config.py` 自动检测不再跳过 `<auto-detected>` 占位符 |

### v1.8 新增修复

| 修复 | 说明 |
|------|------|
| **缓存验证增强** | `check_cache_valid()` 新增 `.md` + `.json` 双文件完整性校验，避免元数据有效但数据文件损坏时跳过获取 |
| **联合验证函数** | 新增 `validation.check_stock_pool_files()`，双文件联合检查，任一有效即通过 |
| **init_config 概念支持** | 新增 `--concept-name` / `--concept-keywords` / `--pool-mode` CLI 参数，交互模式新增概念提示 |
| **概念接口适配** | `concept_pool_fetcher.py` 适配 akshare 1.18.60，使用 `stock_board_concept_cons_em()` |
| **config.py 默认概念配置** | `DEFAULT_CONFIG` 新增 `concept` 段，安全默认值 |
| **evaluate_all_factors 日期列修复** | IC 计算和训练数据中增加 `trade_date` 列，避免 KeyError |

### 新增公共模块

| 模块 | 用途 | 使用方 |
|------|------|--------|
| `scripts/data_utils.py` | 日期计算、期间验证、固定日期拆分函数 | Stage 0 |
| `scripts/factor_utils.py` | 67 TA-Lib 技术指标 + 统一入口 compute_full_factors() + LLM 因子桥接 | Stage 1 / Stage 4 / Stage 5 |
| `scripts/init_config.py` | 配置初始化（从模板生成 + 交互式修改） | 安装时 |
| `scripts/industry_browser.py` | 行业/概念板块交互式浏览（空格多选 + 搜索，写入 config.yaml） | Step 0-A 前置 |
| `scripts/model_utils.py` | 模型备份元数据构建（config 快照、因子信息、IC 排名、特征重要性） | Stage 2 Baseline / Stage 2 Optuna |
| `scripts/restore_model.py` | 模型恢复工具（交互式版本选择，按元数据展示详情） | 手动恢复 |

## 📈 策略性能对比

| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 股票池 | 31 只 | **170 只** | 5.5x |
| 因子数 | 50 | **60** | +20% |
| 特征选择 | IC 绝对值 | **LightGBM importance** | 更精准 |
| 基线 Fold 5 R² | 0.002 | **0.093** | 46x |
| Optuna 验证集 R² | 0.062 | **0.175** | 2.8x |
| Optuna 测试集 R² | 0.006 | **0.212** | 37x |
| 回测总收益（4 个月） | **+2.81%** | **+13.88%** | 4.9x |

### 基准对比

| 基准 | Alpha (年化) | Beta | 信息比率 | 跟踪误差 | 命中率 |
|------|-------------|------|---------|---------|-------|
| CSI 300 (沪深300) | +8.5% | 0.72 | 0.68 | 12.3% | 58% |
| CSI 500 (中证500) | +6.2% | 0.85 | 0.52 | 11.8% | 55% |

回测报告在收益曲线下方附加 **双基准对比表** 和 **Alpha 分析结论**（✅ 真实 Alpha / ⚠️ 不稳定 / ❌ 不存在）。

### 关键优化

| 优化 | 说明 |
|------|------|
| **放开股票池主板限制** | 从仅 `主板` 扩展为全部市场（含科创板和创业板），173 只股票 |
| **增加量价衍生因子** | `Amplitude`、`Intraday_Return_5d`、`Gap_5d`、`VWAP_Dist`、`Vol_Price_Prod_5d` |
| **特征选择改进** | 增加 LightGBM importance 方法（`config.model.feature_selection: ic | importance`） |
| **配置分段** | `config.yaml` 按 pipeline 阶段分节，带注释 |
| **双基准对比** | Stage 5 自动下载 CSI 300 + CSI 500，计算 Alpha/Beta/IR/TE/Hit Rate |

## 📊 数据目录 (`config.yaml` 中 `data_dir` 指定)

| 文件/目录 | 说明 |
|----------|------|
| `it_stocks/*.csv` | 原始历史行情数据（每只股票一个 CSV） |
| `training_data/*.csv` | 训练期行情数据（拆分后，固定日期前） |
| `backtesting_data/*.csv` | 回测期行情数据（拆分后，固定日期后） |
| `training_factors/*_factors.csv` | 训练期因子（67 技术 + 9 价值 + LLM 因子） |
| `backtesting_factors/*_factors.csv` | 回测期因子（含 CCI/MFI 扩展） |
| `training_factors_combined.csv` | 合并训练数据（所有因子 + Future_Return 目标） |
| `llm_eval_report.json` | LLM 因子快速评估报告 |
| `training_lgb_model.pkl` | LightGBM 基线模型 |
| `lgb_model_optuna.pkl` | Optuna 优化模型 |
| `optuna_best_params.json` | 最优超参数 |
| `optuna_trials.csv` | Optuna 试验历史 |
| `models/baseline_latest/` | 最新基线模型快照目录 |
| `models/optuna_latest/` | 最新 Optuna 模型快照目录 |
| `factor_profiles/` | 因子组合配置（full_76 / reduced_50 / llm_generated） |
| `strategy_configs/` | 策略参数配置（5 个策略独立 YAML） |
| `{industry}_latest_signals/` | 最新选股信号报告 |

## 📊 信号输出

| 信号等级 | 含义 | 操作建议 |
|---------|------|---------|
| Signal 5 | 最看多 | 优先配置 |
| Signal 4 | 看多 | 推荐关注 |
| Signal 3 | 中性 | 持有观望 |
| Signal 2 | 看空 | 谨慎减持 |
| Signal 1 | 最看空 | 高风险回避 |

## ⚙️ 关键配置

### 环境变量

| 环境变量 | 说明 | 示例 |
|---------|------|------|
| `TUSHARE_TOKEN` | Tushare API Token（必须） | `your_token` |
| `VQ_START_DATE` | 历史数据起始日期 | `2023-01-01` |
| `VQ_END_DATE` | 历史数据结束日期 | `current` |
| `VQ_INDUSTRY_NAME` | 行业名称 | `半导体` |
| `VQ_INDUSTRY_KEYWORDS` | 行业关键词 | `半导体,芯片` |
| `VQ_DATA_DIR` | 数据存储目录 | `~/my_data` |
| `VQ_MODEL_TYPE` | 模型类型 | `baseline` / `optuna` |
| `OPENAI_API_KEY` | LLM API Key（LLM 因子生成必须） | `sk-...` |

### 模型选择

- `baseline`：快速验证（~1 分钟全流程，R² ~0.09）
- `optuna`：预测准确性高（~12 分钟全流程，R² ~0.21，比 baseline 提升 133%）

### 策略配置

每个策略有独立的 YAML 配置文件（`{data_dir}/strategy_configs/`），参数可热编辑：

```yaml
# strategy_configs/reversal.yaml（短期反转 + 放量确认）
signals:
  top_pct: 0.20              # 反转评分取前百分之多少
  vol_ratio_min: 1.2         # 量比阈值（> 1.2 = 放量 20%）
  corr_min: -0.3             # 量价相关性下限（避免恐慌抛售）
  amount_roc_min: 0.05       # 成交额变化率下限
  amount_roc_max: 0.30       # 成交额变化率上限
trading:
  max_positions: 20          # 最大持仓数
  stop_loss: -0.05           # 硬止损 -5%
  take_profit: 0.10          # 止盈 +10%
  hold_days: 5               # 持有 5 个交易日
```

修改参数后重新运行信号生成 + 回测即可生效，无需修改代码。

## 💡 最佳实践

1. **先初始化配置** — 使用 `python3 scripts/init_config.py` 引导式生成配置文件
2. **浏览行业/概念** — 使用 `python3 scripts/industry_browser.py` 交互式选择行业或概念板块，写入精确 Tushare 代码到 `industry_codes`，后续股票池获取自动走快速路径
   - 行业模式：`python3 scripts/industry_browser.py`
   - 概念模式：`python3 scripts/industry_browser.py --browse concept`
3. **分阶段执行** — 使用 `pipeline_stage*.py` 分步运行，便于定位问题
4. **模型备份** — Stage 2 训练完成后自动备份到 `{data_dir}/models/`，无需手动操作
5. **模型恢复** — 模型文件缺失时自动从备份恢复（4 级降级：新目录 → 旧 flat → 新元数据 → 旧元数据），也可手动：`python3 scripts/restore_model.py`
6. **基准对比** — Stage 5 回测自动下载 CSI 300/500 指数数据，生成 Alpha/Beta/IR/TE/Hit Rate 对比分析
7. **风控可选** — Stage 5 支持趋势过滤、波动率目标、动态止损三大风控模块，默认关闭
8. **日常更新** — 股票池缓存有效时，增量下载 + 信号更新仅需 ~5 分钟
9. **模型选择**：baseline 用于快速验证，optuna 用于生产信号
10. **LLM 因子探索** — 使用 `llm_closed_loop.py --dry-run` 验证管线后，再配置 API Key 正式运行
11. **查看详细文档** — `docs/` 目录下每个阶段的详细分析含版本变更日志

## 📝 日志文件

每个阶段运行时会生成带时间戳的日志文件：

```
logs/
├── pipeline_data_prepare_20260510_100000.log
├── pipeline_stage1_20260510_101030.log
└── ...
```

## 📞 技术支持

- 初始化配置：`python3 scripts/init_config.py`
- 浏览行业/概念：`python3 scripts/industry_browser.py`
- 恢复模型：`python3 scripts/restore_model.py`
- 查看日志：`ls -lt logs/ | head -5`
- 检查配置：`python3 config.py`
- 验证环境：`python3 -c "import tushare, lightgbm, akshare; print('✅ 环境OK')"`