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投资体系