# 收敛三角形检测系统 - 使用指南

> 最后更新：2026-01-22  
> 版本：v1.0

## 目录

1. [系统概述](#系统概述)
2. [快速开始](#快速开始)
3. [参数配置](#参数配置)
4. [脚本说明](#脚本说明)
5. [输出文件](#输出文件)
6. [算法原理](#算法原理)
7. [常见问题](#常见问题)

---

## 系统概述

收敛三角形检测系统用于自动识别股票K线中的收敛三角形形态，并计算突破强度分数进行选股。

### 功能特点

- **批量检测**：支持多股票、多日期的滚动窗口检测
- **突破强度评分**：0~1 连续分数，量化突破有效性
- **可视化图表**：自动生成个股三角形图表
- **选股报告**：每日 Markdown 格式选股简报

### 系统架构

```
technical-patterns-lab/
├── src/
│   └── converging_triangle.py    # 核心算法
├── scripts/
│   ├── triangle_config.py        # 参数配置（统一管理）
│   ├── run_converging_triangle.py    # 批量检测
│   ├── report_converging_triangles.py # 报告生成
│   ├── plot_converging_triangles.py   # 图表绘制
│   └── pipeline_converging_triangle.py # 一键流水线
├── outputs/converging_triangles/
│   ├── all_results.csv           # 全部检测结果
│   ├── report.md                 # 选股报告
│   └── charts/                   # 个股图表
└── data/
    └── pkl/                      # OHLCV 数据文件
```

---

## 快速开始

### 1. 一键运行（推荐）

```bash
cd technical-patterns-lab
python scripts/pipeline_converging_triangle.py
```

这会依次执行：
1. 批量检测 → 生成 `all_results.csv`
2. 报告生成 → 生成 `report.md`
3. 图表绘制 → 生成 `charts/*.png`

### 2. 指定日期运行

```bash
python scripts/pipeline_converging_triangle.py --date 20260120
```

### 3. 跳过部分步骤

```bash
# 跳过检测（使用已有结果），只生成报告和图表
python scripts/pipeline_converging_triangle.py --skip-detection

# 只运行检测
python scripts/pipeline_converging_triangle.py --skip-report --skip-plot
```

### 4. 单独运行各步骤

```bash
# 批量检测
python scripts/run_converging_triangle.py

# 生成报告
python scripts/report_converging_triangles.py

# 绘制图表
python scripts/plot_converging_triangles.py
```

---

## 参数配置

所有参数统一在 `scripts/triangle_config.py` 中管理：

### 检测参数（当前使用严格模式）

| 参数 | 严格模式 | 默认模式 | 宽松模式 | 说明 |
|------|----------|----------|----------|------|
| `window` | 120 | 120 | 120 | 检测窗口（交易日） |
| `pivot_k` | 15 | 15 | 15 | 枢轴点检测周期 |
| `shrink_ratio` | **0.6** | 0.8 | 0.85 | 收敛比例阈值 |
| `break_tol` | **0.005** | 0.001 | 0.001 | 突破判定容差 |
| `vol_k` | **1.5** | 1.3 | 1.2 | 放量确认倍数 |

### 数据范围配置

| 参数 | 值 | 说明 |
|------|-----|------|
| `RECENT_DAYS` | 500 | 计算最近 N 个交易日 |
| `DISPLAY_WINDOW` | 500 | 图表显示范围 |
| `ONLY_VALID` | True | 只输出有效三角形 |

### 切换参数模式

编辑 `scripts/triangle_config.py`，修改 `DETECTION_PARAMS` 的定义：

```python
# 当前使用严格模式（推荐）
DETECTION_PARAMS = ConvergingTriangleParams(
    shrink_ratio=0.6,    # 更严格的收敛要求
    break_tol=0.005,     # 更明显的突破
    vol_k=1.5,           # 更强的放量要求
    ...
)
```

---

## 脚本说明

### run_converging_triangle.py

**功能**：批量检测收敛三角形

**输出**：
- `outputs/converging_triangles/all_results.csv`
- `outputs/converging_triangles/strong_breakout_up.csv`
- `outputs/converging_triangles/strong_breakout_down.csv`

**耗时**：约 15-20 秒（108只股票 × 500天）

---

### report_converging_triangles.py

**功能**：生成 Markdown 选股报告

**参数**：

```bash
# 指定报告日期
python scripts/report_converging_triangles.py --report-date 20260120

# 指定输入输出路径
python scripts/report_converging_triangles.py \
    --input outputs/converging_triangles/all_results.csv \
    --output outputs/converging_triangles/report.md
```

**输出**：`outputs/converging_triangles/report.md`

---

### plot_converging_triangles.py

**功能**：绘制个股收敛三角形图表

**参数**：

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

# 指定输出目录
python scripts/plot_converging_triangles.py --output-dir outputs/converging_triangles/charts
```

**输出**：`outputs/converging_triangles/charts/*.png`

**特点**：
- 每次运行自动清空旧图片
- 显示 500 天历史走势
- 检测窗口 120 天高亮显示
- 支持中文字体（SimHei/Microsoft YaHei）

---

### pipeline_converging_triangle.py

**功能**：一键执行完整流水线

**参数**：

| 参数 | 说明 |
|------|------|
| `--date YYYYMMDD` | 指定目标日期 |
| `--skip-detection` | 跳过批量检测 |
| `--skip-report` | 跳过报告生成 |
| `--skip-plot` | 跳过图表绘制 |

**输出**：流水线执行摘要，包含各步骤耗时

---

## 输出文件

### all_results.csv

所有有效收敛三角形检测结果。

| 字段 | 类型 | 说明 |
|------|------|------|
| `stock_idx` | int | 股票索引 |
| `stock_code` | str | 股票代码 |
| `stock_name` | str | 股票名称 |
| `date` | int | 日期（YYYYMMDD） |
| `is_valid` | bool | 是否有效三角形 |
| `breakout_strength_up` | float | 向上突破强度（0~1） |
| `breakout_strength_down` | float | 向下突破强度（0~1） |
| `breakout_dir` | str | 突破方向：up/down/none |
| `width_ratio` | float | 收敛比例（末端/起始宽度） |
| `volume_confirmed` | bool | 是否放量确认 |
| `touches_upper` | int | 触碰上沿次数 |
| `touches_lower` | int | 触碰下沿次数 |

### report.md

每日选股简报，包含：
- 数据说明（股票池、检测窗口、算法）
- 当日统计（总数、向上/向下/无突破）
- 向上突破排名表
- 向下突破排名表
- 无突破形态列表

### charts/*.png

个股图表，文件名格式：`{date}_{stock_code}_{stock_name}.png`

图表内容：
- 上半部分：K线走势 + 趋势线
- 下半部分：成交量柱状图
- 标题：股票信息 + 检测/显示范围

---

## 算法原理

### 收敛三角形定义

收敛三角形是一种技术形态，特征为：
1. **上沿下倾**：高点连线斜率 ≤ 0（或轻微上倾）
2. **下沿上翘**：低点连线斜率 ≥ 0（或轻微下倾）
3. **逐渐收敛**：末端宽度 < 起始宽度
4. **多次触碰**：价格至少 2 次触碰上下沿

### 检测流程

```
1. 枢轴点检测
   └── 使用分形方法找出局部高点/低点

2. 边界线拟合
   └── 分段取极值 + 线性回归

3. 形态验证
   ├── 斜率约束检查
   ├── 收敛度检查（width_ratio < shrink_ratio）
   └── 触碰程度检查（loss < touch_loss_max）

4. 突破判定
   ├── 向上突破：close > upper_line × (1 + break_tol)
   └── 向下突破：close < lower_line × (1 - break_tol)

5. 强度计算
   └── 加权求和：价格分(60%) + 收敛分(25%) + 成交量分(15%)
```

### 突破强度公式

```python
strength = 0.60 × tanh(突破幅度% × 15) +  # 价格分
           0.25 × (1 - width_ratio) +        # 收敛分
           0.15 × vol_bonus                   # 成交量分
```

详见 [突破强度计算方法.md](./突破强度计算方法.md)

---

## 常见问题

### Q1: 图表中文乱码？

确保系统安装了中文字体（SimHei 或 Microsoft YaHei）。脚本已配置：

```python
plt.rcParams['font.sans-serif'] = ['SimHei', 'Microsoft YaHei', 'Arial Unicode MS']
plt.rcParams['axes.unicode_minus'] = False
```

### Q2: 检测结果太少/太多？

调整 `scripts/triangle_config.py` 中的参数：
- 结果太少 → 使用宽松模式（`shrink_ratio=0.85`）
- 结果太多 → 使用严格模式（`shrink_ratio=0.6`）

### Q3: 突破强度都很高？

旧版本公式有此问题，已在 v2.0 修复。确保使用最新的 `src/converging_triangle.py`。

### Q4: 如何添加新股票？

将 OHLCV 数据以 `.pkl` 格式放入 `data/pkl/` 目录，格式要求：
- 二维 numpy 数组，shape=(n_stocks, n_days)
- 文件名：`open.pkl`, `high.pkl`, `low.pkl`, `close.pkl`, `volume.pkl`

### Q5: 如何调整检测窗口？

修改 `scripts/triangle_config.py`：

```python
DETECTION_PARAMS = ConvergingTriangleParams(
    window=120,  # 修改此值（如 60, 90, 180）
    ...
)
```

---

## 版本历史

| 版本 | 日期 | 更新内容 |
|------|------|----------|
| v1.0 | 2026-01-22 | 初始版本，加权求和公式，严格模式 |

---

## 相关文档

- [突破强度计算方法.md](./突破强度计算方法.md) - 突破强度公式详解
- [converging_triangles_outputs.md](./converging_triangles_outputs.md) - 输出文件字段说明
- [2026-01-16_converging_triangle_algorithm.md](./2026-01-16_converging_triangle_algorithm.md) - 算法设计文档