前言¶
做 A 股技術形態篩選時，常見做法是手寫腳本掃全市場，或在回測裏用「看見未來」的極值點。杯柄（Cup and Handle）規則多、參數雜，還要區分「形態剛走完」和「已經放量突破」兩個階段，單靠通用對話很難穩定復現同一套約束。
下面介紹 SkillHub 社區 Skill「杯柄形態預警v1」（@user_91e44d7e/cup-handle-alert-v1）。它把 CANSLIM 杯柄的識別與預警流程寫進 SKILL.md 和 Python 腳本，強調無未來函數、按收盤數據運行，適合交給 Agent 在固定話術下觸發掃描或單股分析。
這是什麼¶
「杯柄形態預警v1」是面向專業投研場景的 Agent Skill（分類 professional，版本 1.0.0，來源 community），由發佈者 user_91e44d7e 維護。SkillHub 頁面標註 requires_api_key=false，安裝後不需要額外 API Key。
定位：基於 William O’Neil CANSLIM 框架的每日杯柄形態預警系統。系統輸出兩類信號——D 點確認預警（形態完成，進入觀察池）與放量突破預警（觀察池內標的放量突破杯沿）。官方說明中明確採用「數據只到當日、關鍵點延遲確認」的設計，避免平滑與極值識別中的前視偏差。
- 官方 API 入口：https://api.skillhub.cn/user_91e44d7e/cup-handle-alert-v1
- SkillHub 展示頁：https://www.skillhub.cn/skills/user_91e44d7e/cup-handle-alert-v1
核心功能¶
以下內容均來自 Skill 包內 SKILL.md 與腳本說明，可與安裝後的目錄對照。
兩類預警¶
- D 點確認預警：杯柄形態在規則約束下走完，標的進入觀察池，等待突破。
- 放量突破預警：觀察池中的形態滿足放量且收盤突破杯沿條件時，觸發買入信號類預警。
每日處理流程（無未來函數）¶
收盤後按下列順序執行（摘自 SKILL.md）：
- 對截至當日的前復權日線做 Savitzky–Golay 平滑（數據截止當天）。
- ABCD 關鍵點只取「5 天前已確認」的極值，避開平滑尾部不穩定區間。
- 形態約束包括：前置上漲 ≥10%、杯深 10%–40%、右杯沿恢復度 ≥70%、柄部 5–25 天且回調 1%–12%、杯底不跌破 K（起漲點）等。
- D 點確認後進入觀察池。
- 在 D 點之後檢索是否放量突破（收盤 > 杯沿 × 1.01 且量比 ≥ 1.3）。
Agent 觸發場景¶
當用戶提出以下需求時，Agent 應加載該 Skill（SKILL.md 原文）：
- 運行杯柄形態每日預警掃描
- 查看最新的杯柄突破信號
- 分析某隻股票是否形成杯柄形態
- 生成杯柄預警可視化圖表
預警結果字段¶
掃描結果 CSV 中包含 alert_type、alert_date、ts_code、name、breakout_price、breakout_vol_ratio、cup_depth_pct、handle_depth_pct、recovery_pct、breakout_level 以及 K–D 各點價格等字段，便於下游篩選或對接自有看板。
安裝與啓用¶
通過 SkillHub CLI 安裝¶
先確認本機已安裝 skillhub（安裝方式見 https://skillhub.cn/install/skillhub.md）。安裝 Skill 時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 且可能不被識別。
Cursor 常用路徑爲 ~/.cursor/skills/；Claude Code 爲 ~/.claude/skills/；Codex 爲 ~/.codex/skills/ 或項目下的 .agents/skills/。以下以 Cursor 爲例：
skillhub install cup-handle-alert-v1 --namespace user_91e44d7e --dir ~/.cursor/skills/
SkillHub 頁面也支持把下面提示交給 AI，讓其按安裝文檔拉取同一座標：
請根據 https://skillhub.cn/install/skillhub.md，安裝 @user_91e44d7e/cup-handle-alert-v1。
安裝完成後，在對話中使用上文「觸發場景」中的表述即可讓 Agent 讀取 Skill 內指引並調用腳本。
數據與運行環境¶
腳本依賴本地 Parquet 數據（SKILL.md 約定路徑）：
- L1 前復權日線：
data/L1_price/daily_qfq.parquet - 股票信息：
data/L0_raw/stock_info.parquet
scripts/daily_alert.py 支持 --data 指定數據根目錄，或通過環境變量 CUP_HANDLE_DATA 覆蓋默認路徑。運行需要 Python 3 及 pandas、numpy、scipy；單股 HTML 可視化腳本還依賴 plotly。
典型用法¶
進入已安裝 Skill 所在項目根目錄（或你存放數據與腳本的工程目錄），按 SKILL.md 示例執行。
全市場每日預警¶
對全市場（或數據文件中全部標的）做掃描，結果打印到控制台並寫入 CSV。
cd /path/to/project
python3 scripts/daily_alert.py
默認會生成 cup_handle_daily_alerts.csv。
單隻股票分析¶
只掃描指定代碼，例如深交所標的：
python3 scripts/daily_alert.py --stock 000426.SZ
可通過 --days 限制「D 點之後」的最大天數（腳本默認 30）。
預警 HTML 圖¶
SKILL.md 給出的命令爲：
python3 scripts/daily_alert.py --html
說明輸出交互式 HTML 到 alerts_html/ 目錄。包內另有 scripts/analyze_stock.py，文檔寫明用於「單隻股票杯柄形態分析 + HTML 可視化」，可按需在裝好數據後單獨調用並覈對是否與你的工程佈局一致。
適用場景與注意¶
適合誰
- 已自建或能生成
daily_qfq.parquet、stock_info.parquet的量化/投研環境，希望在收盤後做規則固定的杯柄掃描。 - 希望 Agent 在「杯柄」「突破」「每日預警」等話術下，走同一套 CANSLIM 參數（如
SMOOTH_BW=11、CONFIRM_BUFFER=5、BREAKOUT_VOL_THRESH=1.3等，見SKILL.md參數表），而不是每次重新口述規則。
限制與注意
- 本 Skill 不提供行情數據源，須自行維護 L0/L1 Parquet；數據缺失或字段不符會導致腳本無法運行。
- 形態識別與突破條件均爲程序化規則，不構成投資建議；實盤前應結合流動性、停牌、復權口徑與自身風控驗證。
- SkillHub 統計（截至頁面抓取）：評分 100000，下載約 798 次；具體數字以 SkillHub 實時展示爲準。
- 方法說明中引用了 O’Neil《笑傲股市》、Lo et al. (2000) 平滑與極值思路等文獻與開源參考，詳見
SKILL.md「方法來源」一節。
結尾¶
「杯柄形態預警v1」把 CANSLIM 杯柄的兩段式預警（D 點確認 + 放量突破）和延遲確認、無未來函數流程固化成 Agent Skill 與可執行腳本，適合在已有日線數據管線上做收盤後掃描。需要安裝或查看元數據時，請訪問 SkillHub 展示頁：https://www.skillhub.cn/skills/user_91e44d7e/cup-handle-alert-v1 。
