- name
- cup-handle-detector
- description
- 检测股票日线是否符合"杯柄形态（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等）
- 无中文字体时自动使用英文标签（避免乱码）
快速使用
# 单股票检测（需要 TUSHARE_TOKEN）
python3 scripts/cup_handle_detector.py <股票代码>
# 批量扫描（从SQLite数据库）
python3 scripts/batch_scan_cup_handle.py --db <数据库路径>示例
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%涨幅）
算法说明
注意事项
- 数据要求：至少需要180天日线数据
- 形态主观性：算法评分仅作参考
- 风险提示：技术形态仅为参考工具，不构成投资建议
*基于威廉·欧奈尔《笑傲股市》CANSLIM投资体系*