Cup and Handle Pattern Detector

检测股票日线是否符合"杯柄形态（Cup and Handle）"技术分析形态，并生成含轮廓线的识别示意图。触发场景：(1) 询问某只股票是否形成杯柄形态 (2) 查询杯柄形态股票 (3) 技术形态识别需求。触发词：杯柄形态、cup and handle、欧奈尔形态、技术形态识别。

Cup Handle Detector

检测股票日线数据是否符合经典的"杯柄形态"技术分析形态，并生成可视化识别示意图（含杯柄轮廓线）。

功能特性

• 形态检测：自动检测杯身（U型底部）和把手（下跌回调）
• 轮廓绘制：在K线图上绘制杯柄轮廓线（蓝色杯身+橙色把手）
• 关键标注：标记左杯口、杯底、右杯口、把手等关键点
• 自适应日期：日期标签自动调整间隔，避免重叠
• 双语支持：自动检测中文字体，无字体时使用英文标签

依赖要求

必需依赖

依赖	版本要求	说明
Python	≥3.10	运行环境
pandas	≥1.5	数据处理
numpy	≥1.20	数值计算
matplotlib	≥3.6	图表生成

可选依赖

依赖	用途	说明
tushare	实时数据获取	需配置 TUSHARE_TOKEN 环境变量

中文字体支持

图表标签自动适配：

• 检测系统中文字体（SimHei、WenQuanYi等）
• 无中文字体时自动使用英文标签（避免乱码）

快速使用

bash

# 单股票检测（需要 TUSHARE_TOKEN）
python3 scripts/cup_handle_detector.py <股票代码>

# 批量扫描（从SQLite数据库）
python3 scripts/batch_scan_cup_handle.py --db <数据库路径>

示例

bash

python3 scripts/cup_handle_detector.py 600519.SH
python3 scripts/batch_scan_cup_handle.py --db data/stocks.sqlite

输出结果

符合杯柄形态时：

• 输出形态评分和各项参数
• 生成含轮廓线的识别示意图（仅显示最近一年数据）
• 图表保存至临时目录

不符合杯柄形态时：

• 输出 "不匹配杯柄形态"
• 不生成图形文件

图表特性

生成的示意图包含：

• K线蜡烛图（红涨绿跌，最近一年数据）
• 杯身轮廓线（蓝色U型曲线）
• 把手轮廓线（橙色回调曲线）
• 颈线标注（红色虚线，突破位）
• 关键点标记（左杯口、杯底、右杯口、把手）
• 形态特征信息框

杯柄形态技术特征

杯柄形态是威廉·欧奈尔提出的经典看涨持续形态。

【重要】最新时间点约束

本检测器只关注最新一段时间内出现的杯柄形态，历史过往形态不属于符合范畴。

具体约束条件：

• 右杯口距离最新交易日 ≤ 30 天
• 把手终点距离最新交易日 ≤ 5 天

这意味着形态的最后一个时间点必须是或接近最新的交易日，确保检测到的是当前正在形成或刚完成的形态，而非历史已完成的形态。

杯身（Cup）

• 形状：U型底部（非V型）
• 深度：前期涨幅的1/3到1/2（15-33%）
• 时间跨度：1-6个月（30-180天）

把手（Handle）

• 位置：位于杯子右侧
• 形态：向下倾斜或横向整理
• 深度：不超过杯深的1/3
• 时间跨度：1-4周（5-30天）

前置趋势

• 形成前应有明显上升趋势（≥30%涨幅）

算法说明

详见 references/algorithm.md。

注意事项

1. 数据要求：至少需要180天日线数据
2. 形态主观性：算法评分仅作参考
3. 风险提示：技术形态仅为参考工具，不构成投资建议

---

基于威廉·欧奈尔《笑傲股市》CANSLIM投资体系