VCP筛选器 - 米内尔维尼波动收缩模式
筛选标普500股票中符合马克·米内尔维尼波动收缩模式（VCP）的股票，识别处于第二阶段上涨趋势、波动性在突破枢轴点附近收缩的股票。
何时使用
- 用户要求进行VCP筛选或米内尔维尼式设置
- 用户希望寻找紧密基底/波动收缩模式
- 用户要求扫描第二阶段动量股
- 用户要求寻找具有明确风险的突破候选
- 用户询问“在中查找所有历史VCP”或希望研究单个股票过去
的VCP设置及前瞻性结果 (
--history --ticker SYM)
前提条件
- FMP API密钥（设置
FMP_API_KEY环境变量或传递--api-key） - 免费层（每天250次调用）足以用于默认筛选（前100只候选）
- 推荐付费层用于完整标普500筛选 (
--full-sp500)
工作流
第1步：准备并执行筛选
运行VCP筛选脚本：
# 默认：标普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
# 完整标普500（付费API层）
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts
严格模式（米内尔维尼纯正设置）
仅返回 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 | 越高 = 第二阶段筛选更严格 |
--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 | 关闭 | — | 米内尔维尼严格模式：仅显示 Pre-breakout 或 Breakout 且具有有效VCP的股票 |
第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： 设置失效——不要入场
按评级（次要条件，在状态确认可操作性后）：
- 教科书式VCP（90+）： 在枢轴点买入，激进仓位（1.5-2x）
- 强劲VCP（80-89）： 在枢轴点买入，标准仓位（1x）
- 良好VCP（70-79）： 在成交量确认突破枢轴点后买入（0.75x）
- 发展中（60-69）： 加入观察列表，等待更紧密的收缩
- 弱/无VCP（<60）： 仅监测或跳过
三阶段流水线
- 预筛选 - 基于报价的筛选（价格、成交量、52周位置）约101次API调用
- 趋势模板 - 7点第二阶段筛选器，使用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端点和速率限制