VCP 篩選器 - Minervini 波動收縮型態
篩選 S&P 500 股票中 Mark Minervini 的波動收縮型態（VCP），找出處於 Stage 2 上升趨勢、在突破樞紐點附近波動收縮的股票。
使用時機
- 使用者要求進行 VCP 篩選或 Minervini 風格型態
- 使用者想尋找緊密基底 / 波動收縮型態
- 使用者要求進行 Stage 2 動能股掃描
- 使用者尋找有明確風險定義的突破候選股
- 使用者問「尋找 <股票代碼> 的所有歷史 VCP」或想研究單一股票的過去 VCP 型態及其未來結果（
--history --ticker SYM）
前置條件
- FMP API 金鑰（設定
FMP_API_KEY環境變數或透過--api-key傳入） - 免費方案（每日 250 次呼叫）足以進行預設篩選（前 100 名候選股）
- 付費方案建議用於完整 S&P 500 篩選（
--full-sp500）
工作流程
步驟 1：準備並執行篩選
執行 VCP 篩選腳本：
# 預設：S&P 500，前 100 名候選股
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts
# 自訂股票池
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts
# 完整 S&P 500（付費 API 方案）
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts
嚴格模式（Minervini 純正型態）
僅回傳 valid_vcp=True 且 execution_state 為 Pre-breakout 或 Breakout 的股票：
python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/
歷史單一股票模式
遍歷單一股票多年的價格歷史，偵測所有曾出現過的 VCP，並為每個偵測結果附加未來結果統計（突破 / 停損 / 超時、達到結果所需天數、最大漲幅、最大跌幅）。適用於型態研究與回測情境 — 非即時篩選器。
# 預設：掃描約 5 年（1260 個交易日），5 天步長，60 天結果視窗
python3 skills/vcp-screener/scripts/screen_vcp.py \
--history --ticker FIX --output-dir reports/
# 自訂掃描長度：750 個交易日（約 3 年），90 天結果視窗
python3 skills/vcp-screener/scripts/screen_vcp.py \
--history 750 --ticker TSLA \
--stride-days 5 --outcome-days 90 \
--output-dir reports/
# 長期掃描：10 年（2520 個交易日）
python3 skills/vcp-screener/scripts/screen_vcp.py \
--history 2520 --ticker NVDA --output-dir reports/
輸出（附時間戳）：
vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json— 偵測時間線，包含完整分析器資料 + 每個偵測的forward_outcome+ 摘要統計。vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md— 可讀性高的時間線報告。
模式專用參數：
| 參數 | 預設值 | 範圍 | 效果 |
|---|---|---|---|
--history [DAYS] | （關閉）/ 若無參數則為 1260 | 100-5040 | 啟用歷史模式；可指定交易日掃描視窗（需配合 --ticker） |
--ticker SYM | — | — | 要掃描的股票代碼 |
--stride-days | 5 | 1-60 | 以交易日為單位的資料點間隔步長 |
--outcome-days | 60 | 5-252 | 每個偵測結果的未來評估視窗 |
備註：
- 每次掃描僅需 2 次 FMP API 呼叫（股票 + SPY 歷史），而非橫斷面流程的 100 次以上。
marketCap和絕對 RS 百分位僅反映單一股票本身，而非相對於即時篩選股票池 — 請將此報告用於型態研究，而非投資組合配置。- 偵測結果會根據
(T1_high_date, last_low_date, pivot)進行去重，避免同一個 VCP 隨著時間重複報告。
進階調整（用於回測）
為研究和回測調整 VCP 偵測參數：
python3 skills/vcp-screener/scripts/screen_vcp.py \
--min-contractions 3 \
--t1-depth-min 12.0 \
--breakout-volume-ratio 2.0 \
--trend-min-score 90 \
--atr-multiplier 1.5 \
--output-dir reports/
| 參數 | 預設值 | 範圍 | 效果 |
|---|---|---|---|
--min-contractions | 2 | 2-4 | 越高 = 數量越少但品質更高 |
--t1-depth-min | 10.0% | 1-50 | 越高 = 排除太淺的第一次修正 |
--breakout-volume-ratio | 1.5x | 0.5-10 | 越高 = 成交量確認越嚴格 |
--trend-min-score | 85 | 0-100 | 越高 = Stage 2 過濾越嚴格 |
--atr-multiplier | 1.5 | 0.5-5 | 越低 = 擺動偵測越敏感 |
--contraction-ratio | 0.70 | 0.1-1 | 越低 = 要求更緊密的收縮 |
--min-contraction-days | 5 | 1-30 | 越高 = 最低收縮期間越長 |
--lookback-days | 120 | 30-365 | 越長 = 能找到更舊的型態 |
--max-sma200-extension | 50.0% | — | 用於判斷過度延伸狀態與懲罰的 SMA200 距離門檻 |
--wide-and-loose-threshold | 15.0% | — | 最終收縮深度超過此值將觸發寬鬆型態標記 |
--strict | 關閉 | — | Minervini 嚴格模式：僅回傳 Pre-breakout 或 Breakout 且 valid VCP 為 True 的股票 |
步驟 2：審閱結果
- 讀取產生的 JSON 和 Markdown 報告
- 載入
references/vcp_methodology.md以了解型態解讀背景 - 載入
references/scoring_system.md以了解分數門檻指引
步驟 3：呈現分析
針對每位頂級候選股，呈現：
- 品質（
composite_score/ 評級）— VCP 型態形成情況 - 執行狀態（
execution_state）— 目前是否可買入？（Pre-breakout / Breakout = 可操作） - 型態類型（
pattern_type）— 教科書型 VCP / 近似 VCP / 突破後 / 延伸領頭股 / 受損 - 若應用狀態限制（原始分數被降級），則標記
★ - 收縮細節（T1/T2/T3 深度與比率）
- 交易設定：樞紐價格、停損點、風險百分比
- 成交量枯竭比率與突破成交量分數
- 相對強弱排名
步驟 4：提供可操作指引
依執行狀態（主要過濾條件）：
- Pre-breakout / Breakout： 型態處於可進場視窗 — 根據評級進行部位配置
- Early-post-breakout： 突破正在進行但已高於理想進場點 — 減少部位或等待拉回
- Extended / Overextended： 錯過交易 — 加入觀察清單等待下一個基底
- Damaged / Invalid： 型態失效 — 不要進場
依評級（確定狀態可操作後的次要條件）：
- Textbook VCP（90+）： 在樞紐點買入，積極配置部位（1.5-2x）
- Strong VCP（80-89）： 在樞紐點買入，標準配置（1x）
- Good VCP（70-79）： 在成交量確認突破樞紐點後買入（0.75x）
- Developing（60-69）： 加入觀察清單，等待更緊密的收縮
- Weak/No VCP（<60）： 僅觀察或跳過
三階段流程
- 預篩選 - 基於報價的篩選（價格、成交量、52 週位置）約 101 次 API 呼叫
- 趨勢模板 - 7 點 Stage 2 過濾器，搭配 260 天歷史約 100 次 API 呼叫
- VCP 偵測 - 型態分析、評分、報告生成（無額外 API 呼叫）
輸出
vcp_screener_YYYY-MM-DD_HHMMSS.json- 結構化結果vcp_screener_YYYY-MM-DD_HHMMSS.md- 可讀性高的報告
參考資源
references/vcp_methodology.md- VCP 理論與趨勢模板說明references/scoring_system.md- 評分門檻與組成權重references/fmp_api_endpoints.md- API 端點與速率限制