technical-patterns-lab/docs/2026-01-26_流水线详情模式支持.md

# 流水线脚本详情模式支持

**日期**: 2026-01-26  
**功能**: 为 `pipeline_converging_triangle.py` 添加 `--show-details` 参数

---

## 📋 需求背景

用户希望在使用流水线脚本 `pipeline_converging_triangle.py` 时，能够通过参数控制是否生成详情模式的图片，而不是默认生成。

**之前**：流水线脚本没有详情模式参数，只能生成简洁模式图片。

**现在**：流水线脚本支持 `--show-details` 参数，可以按需生成详情模式图片。

---

## ✅ 实现内容

### 1. 添加命令行参数

在 `pipeline_converging_triangle.py` 中添加：

```python
parser.add_argument(
    "--show-details",
    action="store_true",
    help="生成详情模式图片（显示所有枢轴点和拟合点）",
)
```

### 2. 参数传递逻辑

将参数传递给绘图脚本：

```python
# 步骤 3: 绘制图表
cmd_args = [sys.argv[0]]
if args.date:
    cmd_args.extend(["--date", str(args.date)])
if args.show_details:
    cmd_args.append("--show-details")

sys.argv = cmd_args
run_plot()
```

### 3. 控制台提示信息

在流水线开始时显示当前模式：

```python
if args.show_details:
    print(f"图表模式: 详情模式（显示所有枢轴点）")
else:
    print(f"图表模式: 简洁模式（仅显示价格和趋势线）")
```

---

## 🛠️ 使用方法

### 基本用法

```bash
# 简洁模式（默认）- 不生成详情图片
python scripts/pipeline_converging_triangle.py

# 详情模式 - 生成详情图片
python scripts/pipeline_converging_triangle.py --show-details
```

### 组合参数

```bash
# 指定日期 + 详情模式
python scripts/pipeline_converging_triangle.py --date 20260120 --show-details

# 跳过检测 + 详情模式
python scripts/pipeline_converging_triangle.py --skip-detection --show-details

# 跳过检测和报告，只生成详情图表
python scripts/pipeline_converging_triangle.py --skip-detection --skip-report --show-details
```

---

## 📊 输出对比

### 简洁模式（默认）

```
输出文件: outputs/converging_triangles/charts/20260120_SZ300278_华昌达.png
文件内容: 收盘价 + 上沿线 + 下沿线
```

### 详情模式（--show-details）

```
输出文件: outputs/converging_triangles/charts/20260120_SZ300278_华昌达_detail.png
文件内容: 收盘价 + 上沿线 + 下沿线 + 所有枢轴点 + 拟合点
```

**注意**：两种模式的文件可以共存，互不覆盖。

---

## 🎯 参数优先级

流水线脚本的参数传递链：

```
用户命令行
  └─ pipeline_converging_triangle.py
      ├─ --show-details (可选)
      └─ 传递给 plot_converging_triangles.py
          ├─ --show-details (如果用户指定)
          └─ 调用 plot_triangle(show_details=True/False)
```

**优先级规则**：
1. 流水线脚本的 `--show-details` 参数
2. 传递到绘图脚本
3. 绘图脚本的配置文件 `SHOW_CHART_DETAILS`（命令行参数优先）

---

## 🔍 测试验证

### 测试1：帮助信息

```bash
python scripts/pipeline_converging_triangle.py --help
```

**预期**：显示 `--show-details` 参数说明

### 测试2：简洁模式（默认）

```bash
python scripts/pipeline_converging_triangle.py --skip-detection --skip-report
```

**预期**：
- ✅ 控制台显示："图表模式: 简洁模式（仅显示价格和趋势线）"
- ✅ 生成不带 `_detail` 后缀的图片

### 测试3：详情模式

```bash
python scripts/pipeline_converging_triangle.py --skip-detection --skip-report --show-details
```

**预期**：
- ✅ 控制台显示："图表模式: 详情模式（显示所有枢轴点）"
- ✅ 控制台显示："详细模式: 开启 (--show-details)"
- ✅ 生成带 `_detail` 后缀的图片

---

## 📝 修改文件列表

1. **scripts/pipeline_converging_triangle.py**
   - 添加 `--show-details` 参数
   - 添加模式提示信息
   - 参数传递逻辑

2. **USAGE.md**
   - 更新流水线脚本的使用说明
   - 添加 `--show-details` 参数示例

3. **docs/2026-01-26_图表详细模式功能.md**
   - 更新文档，添加流水线使用方法
   - 标注为 v2.0 版本

---

## 🎉 效果总结

### 用户体验改进

**之前**：
```bash
# 想要详情图片
python scripts/pipeline_converging_triangle.py  # ❌ 只能生成简洁模式
# 需要单独运行绘图脚本
python scripts/plot_converging_triangles.py --show-details
```

**现在**：
```bash
# 一键生成详情图片
python scripts/pipeline_converging_triangle.py --show-details  # ✅ 直接搞定
```

### 优势

1. **一致性**：流水线和绘图脚本参数统一
2. **便捷性**：无需分步操作
3. **灵活性**：默认简洁，按需详细
4. **清晰性**：控制台明确提示当前模式

---

## 📚 相关文档

- [USAGE.md](../USAGE.md) - 使用指南
- [2026-01-26_图表详细模式功能.md](./2026-01-26_图表详细模式功能.md) - 详情模式完整说明
- [枢轴点拟合算法详解.md](./枢轴点分段选择算法详解.md) - 拟合算法原理

---

**总结**：通过添加 `--show-details` 参数，流水线脚本现在完全支持详情模式，用户可以更方便地按需生成详细的调试图表。✅