# 使用说明

## 快速启动

```powershell
.\.venv\Scripts\Activate.ps1
python scripts/pipeline_converging_triangle.py
```

## 1. 创建与激活虚拟环境

```powershell
# 创建环境（首次）
python -m venv .venv

# 激活环境
.\.venv\Scripts\Activate.ps1
```

## 2. 安装依赖

```powershell
pip install numpy pandas matplotlib
```

## 3. 运行脚本

### 一键流水线（推荐）

```powershell
python scripts/pipeline_converging_triangle.py
```

常用参数：

```powershell
# 指定日期
python scripts/pipeline_converging_triangle.py --date 20260120

# 生成详情模式图片（显示所有枢轴点和拟合点）
python scripts/pipeline_converging_triangle.py --show-details

# 组合使用
python scripts/pipeline_converging_triangle.py --date 20260120 --show-details

# 跳过检测（仅生成报告与图表）
python scripts/pipeline_converging_triangle.py --skip-detection
```

### 仅批量检测

```powershell
python scripts/run_converging_triangle.py
```

### 仅生成报告

```powershell
python scripts/report_converging_triangles.py
```

### 仅绘制图表

```powershell
# 简洁模式（默认）- 仅显示收盘价、上沿、下沿
# 文件名格式: YYYYMMDD_股票代码_股票名称.png
python scripts/plot_converging_triangles.py

# 详细模式 - 显示所有枢轴点、拟合点、分段线等
# 文件名格式: YYYYMMDD_股票代码_股票名称_detail.png
python scripts/plot_converging_triangles.py --show-details

# 指定日期
python scripts/plot_converging_triangles.py --date 20260120

# 同时生成两种模式进行对比（先后运行两次）
python scripts/plot_converging_triangles.py              # 生成简洁版
python scripts/plot_converging_triangles.py --show-details # 生成详细版
```

**提示**: 简洁模式和详细模式的文件名不同（详细模式带 `_detail` 后缀），两种模式的图表会同时保留，方便对比查看。

输出（已被 `.gitignore` 忽略，默认不推送远程）：
- `outputs/converging_triangles/all_results.csv`
- `outputs/converging_triangles/strong_breakout_up.csv`
- `outputs/converging_triangles/strong_breakout_down.csv`
- `outputs/converging_triangles/report.md`
- `outputs/converging_triangles/charts/*.png`

## 4. 参数调整

编辑 `scripts/triangle_config.py`（统一配置）：

```python
DETECTION_PARAMS = ConvergingTriangleParams(
    window=120,        # 检测窗口大小
    pivot_k=15,        # 枢轴点检测窗口
    shrink_ratio=0.6,  # 收敛比阈值（严格模式）
    # ...
)

# 实时模式配置
REALTIME_MODE = True      # True=实时模式（默认），False=标准模式
FLEXIBLE_ZONE = 5         # 灵活区域大小（最近5天）

# 显示配置
RECENT_DAYS = 500         # 计算最近 N 天（None=全部历史）
DISPLAY_WINDOW = 500      # 图表显示范围
ONLY_VALID = True         # 只输出有效三角形
SHOW_CHART_DETAILS = False  # 图表详细模式（False=简洁，True=详细）
```

### 实时模式 vs 标准模式

- **实时模式**（推荐，默认）：
  - ✅ 能捕获最近的枢轴点（无15天滞后）
  - ✅ 适合实时选股
  - ⚠️ 候选枢轴点置信度较低

- **标准模式**：
  - ✅ 枢轴点质量高（完整窗口确认）
  - ✅ 适合历史回测
  - ⚠️ 有15天确认滞后

### 图表详细模式

- **简洁模式**（默认，`SHOW_CHART_DETAILS = False`）：
  - 仅显示收盘价、上沿线、下沿线
  - 图表清爽，适合日常使用

- **详细模式**（`SHOW_CHART_DETAILS = True` 或命令行 `--show-details`）：
  - 额外显示所有枢轴点、拟合点、分段线
  - 便于理解算法逻辑和调试

## 5. 数据格式

数据文件位于 `data/` 目录，格式为 pkl：

```python
{
    'mtx': ndarray (n_stocks, n_days),  # 数据矩阵
    'dtes': ndarray (n_days,),          # 日期 (20050104)
    'tkrs': ndarray (n_stocks,),        # 股票代码 (SH600000)
    'tkrs_name': ndarray (n_stocks,),   # 股票名称
}
```

## 6. 备注

- 关闭环境：`deactivate`
- 权限问题（PowerShell）：
  ```powershell
  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  ```