canslim-screener

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CANSLIM Stock Screener - Phase 2

CANSLIM股票筛选工具 - 第二阶段

Overview

概述

This skill screens US stocks using William O'Neil's proven CANSLIM methodology, a systematic approach for identifying growth stocks with strong fundamentals and price momentum. CANSLIM analyzes 7 key components: Current Earnings, Annual Growth, Newness/New Highs, Supply/Demand, Leadership/RS Rank, Institutional Sponsorship, and Market Direction.

Phase 2 implements 6 of 7 components (C, A, N, S, I, M), representing 80% of the full methodology. This phase adds critical volume analysis (S) and institutional ownership tracking (I) to the Phase 1 foundation.

Two-Stage Approach:

Stage 1 (FMP API + Finviz): Analyze stock universe with 6 CANSLIM components
Stage 2 (Reporting): Rank by composite score and generate actionable reports

Key Features:

Composite scoring (0-100 scale) with weighted components
Finviz fallback for institutional ownership data (automatic when FMP data incomplete)
Progressive filtering to optimize API usage
JSON + Markdown output formats
Interpretation bands: Exceptional+ (90+), Exceptional (80-89), Strong (70-79), Above Average (60-69)
Bear market protection (M component gating)

Phase 2 Component Weights (Renormalized for 6 components):

C (Current Earnings): 19%
A (Annual Growth): 25%
N (Newness): 19%
S (Supply/Demand): 19% ← NEW
I (Institutional): 13% ← NEW
M (Market Direction): 6%

Future Phases:

Phase 3: Add L (Leadership/RS Rank) → 100% coverage (full CANSLIM)
Phase 4: FINVIZ Elite integration → 10x faster execution

本工具采用William O'Neil经过验证的CANSLIM方法论筛选美股，这是一种识别具备强劲基本面和价格动量的成长股的系统化方法。CANSLIM分析7个核心要素：C当前盈利（Current Earnings）、A年度增长（Annual Growth）、N新鲜度/创新高（Newness/New Highs）、S供需关系（Supply/Demand）、L领导力/相对强度排名（Leadership/RS Rank）、I机构支持（Institutional Sponsorship）、M市场趋势（Market Direction）。

第二阶段实现了7个要素中的6个（C、A、N、S、I、M），覆盖了完整方法论的80%。本阶段在第一阶段的基础上新增了关键的成交量分析（S要素）和机构持股追踪（I要素）。

两阶段流程：

第一阶段（FMP API + Finviz）：使用6个CANSLIM要素分析股票池
第二阶段（报告生成）：根据综合得分排名并生成可执行的报告

核心特性：

带权重的综合评分系统（0-100分）
机构持股数据的Finviz fallback机制（当FMP数据不完整时自动触发）
渐进式筛选以优化API使用效率
JSON + Markdown双输出格式
评分区间：卓越+（90分及以上）、卓越（80-89分）、强劲（70-79分）、高于平均（60-69分）
熊市保护机制（M要素门禁）

第二阶段要素权重（针对6个要素重新归一化）：

C（当前盈利）：19%
A（年度增长）：25%
N（新鲜度）：19%
S（供需关系）：19% ← 新增
I（机构支持）：13% ← 新增
M（市场趋势）：6%

未来阶段规划：

第三阶段：新增L要素（领导力/相对强度排名）→ 100%覆盖完整CANSLIM方法论
第四阶段：集成FINVIZ Elite → 执行速度提升10倍

When to Use This Skill

适用场景

Explicit Triggers:

"Find CANSLIM stocks"
"Screen for growth stocks using O'Neil's method"
"Which stocks have strong earnings and momentum?"
"Identify stocks near 52-week highs with accelerating earnings"
"Run a CANSLIM screener on [sector/universe]"

Implicit Triggers:

User wants to identify multi-bagger candidates
User is looking for growth stocks with proven fundamentals
User wants systematic stock selection based on historical winners
User needs a ranked list of stocks meeting O'Neil's criteria

When NOT to Use:

Value investing focus (use value-dividend-screener instead)
Income/dividend focus (use dividend-growth-pullback-screener instead)
Bear market conditions (M component will flag - consider raising cash)

明确触发场景：

"筛选CANSLIM标的"
"用O'Neil的方法分析成长股"
"哪些股票具备强劲盈利和动量？"
"找出接近52周新高且盈利加速的股票"
"对[板块/股票池]运行CANSLIM筛选"

隐含触发场景：

用户希望识别潜在的十倍股候选
用户寻找具备可靠基本面的成长股
用户需要基于历史赢家的系统化选股方案
用户需要符合O'Neil标准的股票排名列表

不适用场景：

专注价值投资（请使用价值-股息筛选工具）
专注收益/股息（请使用股息增长回调筛选工具）
熊市环境（M要素会触发预警 - 考虑持有现金）

Workflow

操作流程

Step 1: Verify API Access and Requirements

步骤1：验证API访问权限及要求

Check if user has FMP API key configured:

bash

undefined

检查用户是否已配置FMP API密钥：

bash

undefined

Check environment variable

检查环境变量

echo $FMP_API_KEY

If not set, prompt user to provide it

如果未设置，提示用户提供


**Requirements:**
- **FMP API key** (free tier: 250 calls/day, sufficient for 40 stocks)
- **Python 3.7+** with required libraries:
  - `requests` (FMP API calls)
  - `beautifulsoup4` (Finviz web scraping)
  - `lxml` (HTML parsing)

**Installation:**
```bash
pip install requests beautifulsoup4 lxml

If API key is missing, guide user to:

Sign up at https://site.financialmodelingprep.com/developer/docs
Get free API key (250 calls/day)
Set environment variable:
```
export FMP_API_KEY=your_key_here
```


**要求：**
- **FMP API密钥**（免费 tier：每日250次调用，足够筛选40只股票）
- **Python 3.7+** 及依赖库：
  - `requests`（用于FMP API调用）
  - `beautifulsoup4`（用于Finviz网页抓取）
  - `lxml`（用于HTML解析）

**安装命令：**
```bash
pip install requests beautifulsoup4 lxml

如果缺少API密钥，引导用户完成以下步骤：

访问 https://site.financialmodelingprep.com/developer/docs 注册账号
获取免费API密钥（每日250次调用）
设置环境变量：
```
export FMP_API_KEY=your_key_here
```

Step 2: Determine Stock Universe

步骤2：确定股票池

Option A: Default Universe (Recommended) Use top 40 S&P 500 stocks by market cap (predefined in script):

bash

python3 skills/canslim-screener/scripts/screen_canslim.py

Option B: Custom Universe User provides specific symbols or sector:

bash

python3 skills/canslim-screener/scripts/screen_canslim.py \
  --universe AAPL MSFT GOOGL AMZN NVDA META TSLA

Option C: Sector-Specific User can provide sector-focused list (Technology, Healthcare, etc.)

API Budget Considerations (Phase 2):

40 stocks × ~5.1 calls/stock = ~203 API calls (within free tier)
- FMP: ~3.3 calls/stock (income statements, quotes, prices, institutional holders)
- Finviz: ~1.8 calls/stock (institutional ownership fallback, 2s rate limit)
Market data (S&P 500, VIX): 3 calls
Total: ~206 calls per screening run

选项A：默认股票池（推荐） 使用按市值排名的前40只标普500股票（脚本中预定义）：

bash

python3 skills/canslim-screener/scripts/screen_canslim.py

选项B：自定义股票池 用户提供特定股票代码或板块：

bash

python3 skills/canslim-screener/scripts/screen_canslim.py \
  --universe AAPL MSFT GOOGL AMZN NVDA META TSLA

选项C：板块专属股票池 用户可提供板块聚焦列表（科技、医疗等）

API预算考量（第二阶段）：

40只股票 × 约5.1次调用/股票 = 约203次API调用（在免费 tier范围内）
- FMP：约3.3次调用/股票（利润表、报价、价格、机构持有者）
- Finviz：约1.8次调用/股票（机构持股 fallback，2秒速率限制）
市场数据（标普500、VIX）：3次调用
总计：每次筛选约206次调用

Step 3: Execute CANSLIM Screening Script

步骤3：执行CANSLIM筛选脚本

Run the main screening script with appropriate parameters:

bash

cd /Users/takueisaotome/PycharmProjects/claude-trading-skills/skills/canslim-screener/scripts

运行主筛选脚本并传入合适参数：

bash

cd /Users/takueisaotome/PycharmProjects/claude-trading-skills/skills/canslim-screener/scripts

Basic run (40 stocks, top 20 in report)

基础运行（40只股票，报告显示前20只）

python3 screen_canslim.py --api-key $FMP_API_KEY

Custom parameters

自定义参数

python3 screen_canslim.py
--api-key $FMP_API_KEY
--max-candidates 40
--top 20
--output-dir ../../../


**Script Workflow (Phase 2):**
1. **Market Direction (M)**: Analyze S&P 500 trend vs 50-day EMA
   - If bear market detected (M=0), warn user to raise cash
2. **Stock Analysis**: For each stock, calculate:
   - **C Component**: Quarterly EPS/revenue growth (YoY)
   - **A Component**: 3-year EPS CAGR and stability
   - **N Component**: Distance from 52-week high, breakout detection
   - **S Component**: Volume-based accumulation/distribution (up-day vs down-day volume) ← **NEW**
   - **I Component**: Institutional holder count + ownership % (with Finviz fallback) ← **NEW**
3. **Composite Scoring**: Weighted average with component breakdown
4. **Ranking**: Sort by composite score (highest first)
5. **Reporting**: Generate JSON + Markdown outputs

**Expected Execution Time (Phase 2):**
- 40 stocks: **~1 minute 40 seconds** (tested: 101.42 seconds)
- Finviz fallback adds ~2 seconds per stock (rate limiting)
- Much faster than Phase 1 due to optimized API calls

**Finviz Fallback Behavior:**
- Triggers automatically when FMP `sharesOutstanding` unavailable
- Scrapes institutional ownership % from Finviz.com (free, no API key)
- Increases I component accuracy from 35/100 (partial data) to 60-100/100 (full data)
- User sees: `✅ Using Finviz institutional ownership for NVDA: 68.3%`

python3 screen_canslim.py
--api-key $FMP_API_KEY
--max-candidates 40
--top 20
--output-dir ../../../


**脚本流程（第二阶段）：**
1. **市场趋势（M）**：分析标普500走势与50日指数移动平均线（EMA）的关系
   - 如果检测到熊市（M=0），警告用户持有现金
2. **股票分析**：对每只股票计算：
   - **C要素**：季度EPS/营收同比增长
   - **A要素**：3年EPS复合年增长率（CAGR）及稳定性
   - **N要素**：与52周新高的距离、突破检测
   - **S要素**：基于成交量的积累/派发分析（上涨日vs下跌日成交量）← **新增**
   - **I要素**：机构持有者数量 + 持股比例（Finviz fallback）← **新增**
3. **综合评分**：加权平均计算各要素得分
4. **排名**：按综合得分从高到低排序
5. **报告生成**：生成JSON + Markdown格式输出

**预期执行时间（第二阶段）：**
- 40只股票：**约1分40秒**（测试值：101.42秒）
- Finviz fallback每只股票增加约2秒（速率限制）
- 由于API调用优化，比第一阶段快得多

**Finviz fallback行为：**
- 当FMP的`sharesOutstanding`数据不可用时自动触发
- 从Finviz.com抓取机构持股比例（免费，无需API密钥）
- 将I要素的准确率从35/100（部分数据）提升至60-100/100（完整数据）
- 用户会看到：`✅ Using Finviz institutional ownership for NVDA: 68.3%`

Step 4: Read and Parse Screening Results

步骤4：读取并解析筛选结果

The script generates two output files:

```
canslim_screener_YYYY-MM-DD_HHMMSS.json
```
- Structured data
```
canslim_screener_YYYY-MM-DD_HHMMSS.md
```
- Human-readable report

Read the Markdown report to identify top candidates:

bash

undefined

脚本会生成两个输出文件：

```
canslim_screener_YYYY-MM-DD_HHMMSS.json
```
- 结构化数据
```
canslim_screener_YYYY-MM-DD_HHMMSS.md
```
- 人类可读报告

读取Markdown报告以识别顶级候选：

bash

undefined

Find the latest report

查找最新报告

ls -lt canslim_screener_*.md | head -1

Read the report

读取报告

cat canslim_screener_YYYY-MM-DD_HHMMSS.md


**Report Structure (Phase 2):**
- Market Condition Summary (trend, M score, warnings)
- Top 20 CANSLIM Candidates (ranked)
- For each stock:
  - Composite Score and Rating (Exceptional+/Exceptional/Strong/etc.)
  - Component Breakdown (C, A, N, **S**, **I**, M scores with details) ← **S and I added**
  - Interpretation (rating description, guidance, weakest component)
  - Warnings (quality issues, market conditions, data source notes)
- Summary Statistics (rating distribution)
- Methodology note (Phase 2: 6 components)

**New Component Details in Report:**
- **S Component**: "Up/Down Volume Ratio: 1.06 ✓ Accumulation"
- **I Component**: "6199 holders, 68.3% ownership ⭐ Superinvestor"

cat canslim_screener_YYYY-MM-DD_HHMMSS.md


**报告结构（第二阶段）：**
- 市场状况摘要（趋势、M得分、警告）
- 前20只CANSLIM候选股票（排名）
- 每只股票详情：
  - 综合得分及评级（卓越+/卓越/强劲等）
  - 要素细分得分（C、A、N、**S**、**I**、M得分及详情）← **新增S和I**
  - 解读（评级描述、指导建议、最弱要素）
  - 警告（质量问题、市场状况、数据源说明）
- 汇总统计（评级分布）
- 方法论说明（第二阶段：6个要素）

**报告中新增的要素详情：**
- **S要素**："涨跌成交量比：1.06 ✓ 积累状态"
- **I要素**："6199位持有者，68.3%持股比例 ⭐ 超级投资者"

Step 5: Analyze Top Candidates and Provide Recommendations

步骤5：分析顶级候选并提供建议

Review the top-ranked stocks and cross-reference with knowledge bases:

Reference Documents to Consult:

```
references/interpretation_guide.md
```
- Understand rating bands and portfolio sizing
```
references/canslim_methodology.md
```
- Deep dive into component meanings (now includes S and I)
```
references/scoring_system.md
```
- Understand scoring formulas (Phase 2 weights)

Analysis Framework:

For Exceptional+ stocks (90-100 points):

All components near-perfect (C≥85, A≥85, N≥85, S≥80, I≥80, M≥80)
Guidance: Immediate buy, aggressive position sizing (15-20% of portfolio)
Example: "NVDA scores 97.2 - explosive quarterly earnings (100), strong 3-year growth (95), at new highs (98), volume accumulation (85), strong institutional support (90), uptrend market (100)"

For Exceptional stocks (80-89 points):

Outstanding fundamentals + strong momentum
Guidance: Strong buy, standard sizing (10-15% of portfolio)

For Strong stocks (70-79 points):

Solid across all components, minor weaknesses
Guidance: Buy, standard sizing (8-12% of portfolio)
Phase 2 Example: "NVDA scores 77.5 - explosive earnings (100), strong growth (90), near high (60), accumulation (60), good institutions (60), uptrend (90)"

For Above Average stocks (60-69 points):

Meets thresholds, one component weak
Guidance: Buy on pullback, conservative sizing (5-8% of portfolio)

Bear Market Override:

If M component = 0 (bear market detected), do NOT buy regardless of other scores
Guidance: Raise 80-100% cash, wait for market recovery
CANSLIM does not work in bear markets (3 out of 4 stocks follow market trend)

回顾排名靠前的股票，并与知识库交叉验证：

参考文档：

```
references/interpretation_guide.md
```
- 理解评级区间和仓位配置
```
references/canslim_methodology.md
```
- 深入了解各要素含义（现已包含S和I）
```
references/scoring_system.md
```
- 理解评分公式（第二阶段权重）

分析框架：

卓越+股票（90-100分）：

所有要素接近完美（C≥85，A≥85，N≥85，S≥80，I≥80，M≥80）
指导建议：立即买入，激进仓位配置（组合的15-20%）
示例："NVDA得分97.2 - 季度盈利爆发（100分），强劲3年增长（95分），处于历史新高（98分），成交量积累（85分），强大机构支持（90分），市场上涨趋势（100分）"

卓越股票（80-89分）：

基本面优秀 + 强劲动量
指导建议：强力买入，标准仓位配置（组合的10-15%）

强劲股票（70-79分）：

各要素表现稳健，存在微小弱点
指导建议：买入，标准仓位配置（组合的8-12%）
第二阶段示例："NVDA得分77.5 - 盈利爆发（100分），强劲增长（90分），接近新高（60分），积累状态（60分），良好机构支持（60分），上涨趋势（90分）"

高于平均股票（60-69分）：

符合阈值，存在一个薄弱要素
指导建议：回调时买入，保守仓位配置（组合的5-8%）

熊市覆盖规则：

如果M要素=0（检测到熊市），无论其他得分如何，请勿买入
指导建议：持有80-100%现金，等待市场复苏
CANSLIM在熊市中无效（4只股票中有3只跟随市场趋势）

Step 6: Generate User-Facing Report

步骤6：生成面向用户的报告

Create a concise, actionable summary for the user:

Report Format:

markdown

undefined

创建简洁、可执行的用户摘要：

markdown

undefined

CANSLIM Stock Screening Results (Phase 2)

CANSLIM股票筛选结果（第二阶段）

Date: YYYY-MM-DD Market Condition: [Trend] - M Score: [X]/100 Stocks Analyzed: [N] Components: C, A, N, S, I, M (6 of 7)

日期： YYYY-MM-DD 市场状况： [趋势] - M得分：[X]/100 分析股票数量： [N] 覆盖要素： C、A、N、S、I、M（7个中的6个）

Market Summary

市场摘要

[2-3 sentences on current market environment based on M component] [If bear market: WARNING - Consider raising cash allocation]

[基于M要素的2-3句当前市场环境描述] [如果是熊市：警告 - 考虑增加现金配置]

Top 5 CANSLIM Candidates

前5只CANSLIM候选股票

1. [SYMBOL] - [Company Name] ⭐⭐⭐

1. [股票代码] - [公司名称] ⭐⭐⭐

Score: [X.X]/100 ([Rating]) Price: $[XXX.XX] | Sector: [Sector]

Component Breakdown:

C (Earnings): [X]/100 - [EPS growth]% QoQ, [Revenue growth]% revenue
A (Growth): [X]/100 - [CAGR]% 3yr EPS CAGR
N (Newness): [X]/100 - [Distance]% from 52wk high
S (Supply/Demand): [X]/100 - Up/Down Volume Ratio: [X.XX]
I (Institutional): [X]/100 - [N] holders, [X.X]% ownership [⭐ Superinvestor if present]
M (Market): [X]/100 - [Trend]

Interpretation: [Rating description and guidance] Weakest Component: [X] ([score]) Data Source Note: [If Finviz used: "Institutional data from Finviz"]

[Repeat for top 5 stocks]

得分： [X.X]/100（[评级]） 价格： $[XXX.XX] | 板块： [板块]

要素细分：

C（盈利）：[X]/100 - [EPS增长]% 季度环比，[营收增长]% 营收
A（增长）：[X]/100 - [CAGR]% 3年EPS复合增长率
N（新鲜度）：[X]/100 - 距52周新高[距离]%
S（供需）：[X]/100 - 涨跌成交量比：[X.XX]
I（机构）：[X]/100 - [N]位持有者，[X.X]%持股比例 [⭐ 超级投资者（如有）]
M（市场）：[X]/100 - [趋势]

解读： [评级描述和指导建议] 最弱要素： [X]（得分[score]） 数据源说明： [如果使用Finviz："机构数据来自Finviz"]

[重复前5只股票]

Investment Recommendations

投资建议

Immediate Buy List (90+ score):

[List stocks with exceptional+ ratings]
Position sizing: 15-20% each

Strong Buy List (80-89 score):

[List stocks with exceptional ratings]
Position sizing: 10-15% each

Watchlist (70-79 score):

[List stocks with strong ratings]
Buy on pullback

立即买入列表（90分以上）：

[列出卓越+评级的股票]
仓位配置：每只15-20%

强力买入列表（80-89分）：

[列出卓越评级的股票]
仓位配置：每只10-15%

观察列表（70-79分）：

[列出强劲评级的股票]
回调时买入

Risk Factors

风险因素

[Identify any quality warnings from components]
[Market condition warnings]
[Sector concentration risks if applicable]
[Data source reliability notes if Finviz heavily used]

[识别各要素中的质量警告]
[市场状况警告]
[如适用，板块集中度风险]
[如大量使用Finviz，数据源可靠性说明]

Next Steps

后续步骤

Conduct detailed fundamental analysis on top 3 candidates
Check earnings calendars for upcoming reports
Review technical charts for entry timing
[If bear market: Wait for market recovery before deploying capital]

Note: This is Phase 2 (C, A, N, S, I, M components - 80% coverage). Phase 3 will add L component for full 7-component CANSLIM.

---

对前3只候选股票进行详细基本面分析
查看盈利日历，关注即将发布的财报
查看技术图表，确定入场时机
[如果是熊市：等待市场复苏后再部署资金]

说明： 这是第二阶段（覆盖C、A、N、S、I、M要素 - 80%覆盖率）。第三阶段将新增L要素，实现完整的7要素CANSLIM。

---

Resources

资源

Scripts Directory (

scripts/

)

脚本目录（

scripts/

）

Main Scripts:

```
screen_canslim.py
```
- Main orchestrator script
- Entry point for screening workflow
- Handles argument parsing, API coordination, ranking, reporting
- Usage:
```
python3 screen_canslim.py --api-key KEY [options]
```
```
fmp_client.py
```
- FMP API client wrapper
- Rate limiting (0.3s between calls)
- 429 error handling with 60s retry
- Session-based caching
- Methods:
```
get_income_statement()
```
  ,
```
get_quote()
```
  ,
```
get_historical_prices()
```
  ,
```
get_institutional_holders()
```
```
finviz_stock_client.py
```
- Finviz web scraping client ← NEW
- BeautifulSoup-based HTML parsing
- Fetches institutional ownership % from Finviz.com
- Rate limiting (2.0s between calls)
- No API key required (free web scraping)
- Methods:
```
get_institutional_ownership()
```
  ,
```
get_stock_data()
```

Calculators (
scripts/calculators/
):

```
earnings_calculator.py
```
- C component (Current Earnings)
- Quarterly EPS/revenue growth (YoY)
- Scoring: 50%+ = 100pts, 30-49% = 80pts, 18-29% = 60pts
```
growth_calculator.py
```
- A component (Annual Growth)
- 3-year EPS CAGR calculation
- Stability check (no negative growth years)
- Scoring: 40%+ = 90pts, 30-39% = 70pts, 25-29% = 50pts
```
new_highs_calculator.py
```
- N component (Newness)
- Distance from 52-week high
- Volume-confirmed breakout detection
- Scoring: 5% of high + breakout = 100pts, 10% + breakout = 80pts
```
supply_demand_calculator.py
```
- S component (Supply/Demand) ← NEW
- Volume-based accumulation/distribution analysis
- Up-day volume vs down-day volume ratio (60-day lookback)
- Scoring: ratio ≥2.0 = 100pts, 1.5-2.0 = 80pts, 1.0-1.5 = 60pts
```
institutional_calculator.py
```
- I component (Institutional) ← NEW
- Institutional holder count (from FMP)
- Ownership % (from FMP or Finviz fallback)
- Superinvestor detection (Berkshire Hathaway, Baupost, etc.)
- Scoring: 50-100 holders + 30-60% ownership = 100pts
```
market_calculator.py
```
- M component (Market Direction)
- S&P 500 vs 50-day EMA
- VIX-adjusted scoring
- Scoring: Strong uptrend = 100pts, Uptrend = 80pts, Bear market = 0pts

Supporting Modules:

```
scorer.py
```
- Composite score calculation
- Phase 2 weighted average: C×19% + A×25% + N×19% + S×19% + I×13% + M×6%
- Rating interpretation (Exceptional+/Exceptional/Strong/etc.)
- Minimum threshold validation (all 6 components must meet baseline)
```
report_generator.py
```
- Output generation
- JSON export (programmatic use)
- Markdown export (human-readable)
- Phase 2 component breakdown tables
- Summary statistics calculation

主脚本：

```
screen_canslim.py
```
- 主协调脚本
- 筛选流程入口
- 处理参数解析、API协调、排名、报告生成
- 使用方式：
```
python3 screen_canslim.py --api-key KEY [选项]
```
```
fmp_client.py
```
- FMP API客户端封装
- 速率限制（调用间隔0.3秒）
- 429错误处理（60秒后重试）
- 基于会话的缓存
- 方法：
```
get_income_statement()
```
  、
```
get_quote()
```
  、
```
get_historical_prices()
```
  、
```
get_institutional_holders()
```
```
finviz_stock_client.py
```
- Finviz网页抓取客户端 ← 新增
- 基于BeautifulSoup的HTML解析
- 从Finviz.com获取机构持股比例
- 速率限制（调用间隔2.0秒）
- 无需API密钥（免费网页抓取）
- 方法：
```
get_institutional_ownership()
```
  、
```
get_stock_data()
```

计算器（
scripts/calculators/
）：

```
earnings_calculator.py
```
- C要素（当前盈利）
- 季度EPS/营收同比增长
- 评分规则：50%+ = 100分，30-49% = 80分，18-29% = 60分
```
growth_calculator.py
```
- A要素（年度增长）
- 3年EPS复合增长率计算
- 稳定性检查（无负增长年份）
- 评分规则：40%+ = 90分，30-39% = 70分，25-29% = 50分
```
new_highs_calculator.py
```
- N要素（新鲜度）
- 距52周新高的距离
- 成交量确认的突破检测
- 评分规则：距新高5%以内+突破 = 100分，距新高10%以内+突破 = 80分
```
supply_demand_calculator.py
```
- S要素（供需关系）← 新增
- 基于成交量的积累/派发分析
- 涨跌日成交量比（回溯60天）
- 评分规则：比率≥2.0 = 100分，1.5-2.0 = 80分，1.0-1.5 = 60分
```
institutional_calculator.py
```
- I要素（机构支持）← 新增
- 机构持有者数量（来自FMP）
- 持股比例（来自FMP或Finviz fallback）
- 超级投资者检测（伯克希尔哈撒韦、Baupost等）
- 评分规则：50-100位持有者+30-60%持股比例 = 100分
```
market_calculator.py
```
- M要素（市场趋势）
- 标普500与50日EMA对比
- 经VIX调整的评分
- 评分规则：强劲上涨趋势 = 100分，上涨趋势 = 80分，熊市 = 0分

支持模块：

```
scorer.py
```
- 综合得分计算
- 第二阶段加权平均：C×19% + A×25% + N×19% + S×19% + I×13% + M×6%
- 评级解读（卓越+/卓越/强劲等）
- 最低阈值验证（6个要素均需满足基线要求）
```
report_generator.py
```
- 输出生成
- JSON导出（程序化使用）
- Markdown导出（人类可读）
- 第二阶段要素细分表格
- 汇总统计计算

References Directory (

references/

)

参考文档目录（

references/

）

Knowledge Bases:

```
canslim_methodology.md
```
(27KB) - Complete CANSLIM explanation ← Updated for Phase 2
- All 7 components with O'Neil's original thresholds
- NEW: S component (Volume accumulation/distribution) detailed explanation
- NEW: I component (Institutional sponsorship) detailed explanation
- Historical examples (AAPL 2009, NFLX 2013, TSLA 2019, NVDA 2023)
- Phase 2 implementation notes
```
scoring_system.md
```
(21KB) - Technical scoring specification ← Updated for Phase 2
- Phase 2 component weights and formulas
- Interpretation bands (90-100, 80-89, etc.)
- Minimum thresholds for 6 components
- Composite score calculation examples
```
fmp_api_endpoints.md
```
(18KB) - API integration guide ← Updated for Phase 2
- Required endpoints for each component
- NEW: Institutional holder endpoint documentation
- NEW: Finviz fallback strategy explanation
- Rate limiting strategy
- Cost analysis (Phase 2: ~203 calls for 40 stocks, within free tier)
```
interpretation_guide.md
```
(18KB) - User guidance
- Portfolio construction rules
- Position sizing by rating
- Entry/exit strategies
- Bear market protection rules

How to Use References:

Read
```
canslim_methodology.md
```
first to understand O'Neil's system (now includes S and I)
Consult
```
interpretation_guide.md
```
when analyzing results
Reference
```
scoring_system.md
```
if scores seem unexpected
Check
```
fmp_api_endpoints.md
```
for API troubleshooting or Finviz fallback issues

知识库：

```
canslim_methodology.md
```
（27KB）- 完整CANSLIM解读 ← 针对第二阶段更新
- O'Neil原始阈值的所有7个要素
- 新增：S要素（成交量积累/派发）详细说明
- 新增：I要素（机构支持）详细说明
- 历史案例（AAPL 2009、NFLX 2013、TSLA 2019、NVDA 2023）
- 第二阶段实现说明
```
scoring_system.md
```
（21KB）- 技术评分规范 ← 针对第二阶段更新
- 第二阶段要素权重和公式
- 解读区间（90-100、80-89等）
- 6个要素的最低阈值
- 综合得分计算示例
```
fmp_api_endpoints.md
```
（18KB）- API集成指南 ← 针对第二阶段更新
- 每个要素所需的端点
- 新增：机构持有者端点文档
- 新增：Finviz fallback策略说明
- 速率限制策略
- 成本分析（第二阶段：40只股票约203次调用，在免费 tier范围内）
```
interpretation_guide.md
```
（18KB）- 用户指导
- 组合构建规则
- 按评级配置仓位
- 入场/离场策略
- 熊市保护规则

参考文档使用方式：

首先阅读
```
canslim_methodology.md
```
以理解O'Neil的体系（现已包含S和I）
分析结果时参考
```
interpretation_guide.md
```
如果得分异常，查阅
```
scoring_system.md
```
API故障排查或Finviz fallback问题时查看
```
fmp_api_endpoints.md
```

Troubleshooting

故障排除

Issue 1: FMP API Rate Limit Exceeded

问题1：FMP API速率限制超限

Symptoms:

ERROR: 429 Too Many Requests - Rate limit exceeded
Retrying in 60 seconds...

Causes:

Running multiple screenings within short time window
Exceeding 250 calls/day (free tier limit)
Other applications using same API key

Solutions:

Wait and Retry: Script auto-retries after 60s
Reduce Universe: Use
```
--max-candidates 30
```
to lower API usage
Check Daily Usage: Free tier resets at midnight UTC
Upgrade Plan: FMP Starter ($29.99/month) provides 750 calls/day

症状：

ERROR: 429 Too Many Requests - Rate limit exceeded
Retrying in 60 seconds...

原因：

短时间内多次运行筛选
超过每日250次调用限制（免费 tier）
其他应用使用同一API密钥

解决方案：

等待重试：脚本会在60秒后自动重试
缩小股票池：使用
```
--max-candidates 30
```
减少API使用
查看每日使用情况：免费 tier在UTC时间午夜重置
升级套餐：FMP Starter套餐（每月29.99美元）提供每日750次调用

Issue 2: Missing Required Libraries

问题2：缺少依赖库

Symptoms:

ERROR: required libraries not found. Install with: pip install beautifulsoup4 requests lxml

Solutions:

bash

undefined

症状：

ERROR: required libraries not found. Install with: pip install beautifulsoup4 requests lxml

解决方案：

bash

undefined

Install all required libraries

安装所有依赖库

pip install requests beautifulsoup4 lxml

Or install individually

或单独安装

pip install beautifulsoup4 pip install requests pip install lxml

undefined

pip install beautifulsoup4 pip install requests pip install lxml

undefined

Issue 3: Finviz Fallback Slow Execution

问题3：Finviz fallback执行缓慢

Symptoms:

Execution time: 2 minutes 30 seconds for 40 stocks (slower than expected)

Causes:

Finviz rate limiting (2.0s per request)
All stocks triggering fallback due to FMP data gaps

Solutions:

Accept Delay: 1-2 minutes for 40 stocks is normal with Finviz fallback
Monitor Fallback Usage: Check logs for "Using Finviz institutional ownership" messages
Reduce Rate Limit (advanced): Edit
```
finviz_stock_client.py
```
, change
```
rate_limit_seconds=2.0
```
to
```
1.5
```
(risk: IP ban)

Note: Finviz fallback adds ~2 seconds per stock but significantly improves I component accuracy (35 → 60-100 points).

症状：

执行时间：40只股票耗时2分30秒（比预期慢）

原因：

Finviz速率限制（每次请求间隔2.0秒）
所有股票因FMP数据缺失触发fallback

解决方案：

接受延迟：40只股票耗时1-2分钟在Finviz fallback下属于正常情况
监控fallback使用：查看日志中的"Using Finviz institutional ownership"消息
调整速率限制（高级）：编辑
```
finviz_stock_client.py
```
，将
```
rate_limit_seconds=2.0
```
改为
```
1.5
```
（风险：IP被封禁）

注意： Finviz fallback每只股票增加约2秒，但显著提升I要素的准确率（从35分提升至60-100分）。

Issue 4: Finviz Web Scraping Failure

问题4：Finviz网页抓取失败

Symptoms:

WARNING: Finviz request failed with status 403 for NVDA
⚠️ Using Finviz institutional ownership data - FMP shares outstanding unavailable. Finviz fallback also unavailable. Score reduced by 50%.

Causes:

Finviz blocking scraping requests (User-Agent detection)
Rate limit exceeded (too many requests)
Network issues or Finviz downtime

Solutions:

Wait and Retry: Rate limit resets after a few minutes
Check Internet Connection: Verify network access to finviz.com
Fallback Accepted: Script continues with FMP holder count only (I score capped at 70/100)
Manual Verification: Check Finviz website manually for blocked IP

Graceful Degradation:

Script never fails due to Finviz issues
Falls back to FMP holder count only
User sees quality warning in report

症状：

WARNING: Finviz request failed with status 403 for NVDA
⚠️ 使用Finviz机构持股数据 - FMP流通股数据不可用。Finviz fallback也不可用。得分扣减50%。

原因：

Finviz阻止抓取请求（User-Agent检测）
速率限制超限（请求过多）
网络问题或Finviz宕机

解决方案：

等待重试：速率限制会在几分钟后重置
检查网络连接：验证能否访问finviz.com
接受部分数据：脚本会继续仅使用FMP持有者数量（I得分上限70/100）
手动验证：手动访问Finviz网站检查IP是否被封禁

优雅降级：

脚本不会因Finviz问题失败
回退到仅使用FMP持有者数量
用户会在报告中看到质量警告

Issue 5: No Stocks Meet Minimum Thresholds

问题5：无股票满足最低阈值

Symptoms:

✓ Successfully analyzed 40 stocks
Top 5 Stocks:
  1. AAPL  -  58.3 (Average)
  2. MSFT  -  55.1 (Average)
  ...

Causes:

Bear market conditions (M component low)
Selected universe lacks growth stocks
Market rotation away from growth

Solutions:

Check M Component: If M=0 (bear market), raise cash per CANSLIM rules
Expand Universe: Try different sectors or market cap ranges
Lower Expectations: Average scores (55-65) may still be actionable in weak markets
Wait for Better Setup: CANSLIM works best in bull markets

症状：

✓ 成功分析40只股票
前5只股票：
  1. AAPL  -  58.3（平均）
  2. MSFT  -  55.1（平均）
  ...

原因：

熊市环境（M要素得分低）
所选股票池缺乏成长股
市场风格从成长股转向其他

解决方案：

检查M要素：如果M=0（熊市），按照CANSLIM规则持有现金
扩大股票池：尝试不同板块或市值范围
降低预期：在弱势市场中，平均得分（55-65）仍可能具备操作价值
等待更好的时机：CANSLIM在牛市中效果最佳

Issue 6: Data Quality Warnings

问题6：数据质量警告

Symptoms:

⚠️ Revenue declining despite EPS growth (possible buyback distortion)
⚠️ Using Finviz institutional ownership data (68.3%) - FMP shares outstanding unavailable.

Interpretation:

These are not errors - they are quality flags from calculators
Revenue warning: EPS growth may be from share buybacks, not organic growth
Finviz warning: Data source switched from FMP to Finviz (still accurate)

Actions:

Review component details in full report
Cross-check with fundamental analysis
Adjust position sizing based on risk level
Finviz data is reliable - no action needed for data source warnings

症状：

⚠️ 营收下降但EPS增长（可能是股票回购导致的失真）
⚠️ 使用Finviz机构持股数据（68.3%）- FMP流通股数据不可用。

解读：

这些不是错误 - 是计算器发出的质量标记
营收警告：EPS增长可能来自股票回购，而非有机增长
Finviz警告：数据源从FMP切换到Finviz（数据仍准确）

操作建议：

查看完整报告中的要素详情
结合基本面分析交叉验证
根据风险水平调整仓位配置
Finviz数据可靠 - 数据源警告无需额外操作

Important Notes

重要说明

Phase 2 Implementation Status

第二阶段实现状态

This is Phase 2 implementing 6 of 7 CANSLIM components:

✅ C (Current Earnings) - Implemented
✅ A (Annual Growth) - Implemented
✅ N (Newness) - Implemented
✅ S (Supply/Demand) - Implemented (Phase 2) ← NEW
❌ L (Leadership/RS Rank) - Not implemented (Phase 3)
✅ I (Institutional) - Implemented (Phase 2) ← NEW
✅ M (Market Direction) - Implemented

Implications:

Composite scores represent 80% of full CANSLIM methodology
Top scores typically max out at ~95 (full CANSLIM can reach 200+)
Missing component: Relative strength rank (L component)
Phase 2 provides highly accurate screening with volume and institutional analysis

Score Conversion:

Phase 2 score 85+ ≈ Full CANSLIM 145-165 (Strong to Exceptional)
Phase 2 score 70-84 ≈ Full CANSLIM 125-144 (Above Average to Strong)
Phase 2 score 60-69 ≈ Full CANSLIM 110-124 (Average to Above Average)

这是第二阶段，实现了7个CANSLIM要素中的6个：

✅ C（当前盈利）- 已实现
✅ A（年度增长）- 已实现
✅ N（新鲜度）- 已实现
✅ S（供需关系）- 已实现（第二阶段）← 新增
❌ L（领导力/相对强度排名）- 未实现（第三阶段）
✅ I（机构支持）- 已实现（第二阶段）← 新增
✅ M（市场趋势）- 已实现

影响：

综合得分代表完整CANSLIM方法论的80%
最高得分通常约为95分（完整CANSLIM可达到200+）
缺失要素：相对强度排名（L要素）
第二阶段通过成交量和机构分析提供高度准确的筛选

得分转换：

第二阶段85分+ ≈ 完整CANSLIM 145-165分（强劲到卓越）
第二阶段70-84分 ≈ 完整CANSLIM 125-144分（高于平均到强劲）
第二阶段60-69分 ≈ 完整CANSLIM 110-124分（平均到高于平均）

Finviz Integration Benefits

Finviz集成优势

Automatic Fallback System:

When FMP API doesn't provide
```
sharesOutstanding
```
, Finviz automatically activates
Scrapes institutional ownership % from Finviz.com (free, no API key)
Improves I component accuracy from 35/100 (partial) to 60-100/100 (full)

Data Source Priority:

FMP API (primary): Institutional holder count + shares outstanding calculation
Finviz (fallback): Direct institutional ownership % from web page
Partial Data (last resort): Holder count only, 50% penalty applied

Tested Reliability:

39/39 stocks successfully retrieved ownership % via Finviz (100% success rate)
Average execution time: 2.54 seconds per stock
No errors or IP blocks during testing

自动回退系统：

当FMP API不提供
```
sharesOutstanding
```
时，Finviz自动激活
从Finviz.com抓取机构持股比例（免费，无需API密钥）
将I要素的准确率从35/100（部分数据）提升至60-100/100（完整数据）

数据源优先级：

FMP API（首选）：机构持有者数量 + 流通股计算
Finviz（回退）：从网页直接获取机构持股比例
部分数据（最后手段）：仅持有者数量，扣减50%得分

测试可靠性：

39/39只股票成功通过Finviz获取持股比例（100%成功率）
平均执行时间：每只股票2.54秒
测试期间无错误或IP封禁

Future Enhancements

未来增强

Phase 3 (Planned):

Add L component: RS Rank estimation (52-week high proxy, 80% accuracy)
Full 7-component CANSLIM: C 15%, A 20%, N 15%, S 15%, L 20%, I 10%, M 5%
Coverage: 100% of full CANSLIM

Phase 4 (Planned):

FINVIZ Elite integration for pre-screening
Execution time: 2 minutes → 10-15 seconds
FMP API usage reduction: 90%
Larger universe possible (100+ stocks)

第三阶段（规划中）：

新增L要素：相对强度排名估算（52周新高代理，准确率80%）
完整7要素CANSLIM：C 15%，A 20%，N 15%，S 15%，L 20%，I 10%，M 5%
覆盖率：完整CANSLIM的100%

第四阶段（规划中）：

集成FINVIZ Elite进行预筛选
执行时间：2分钟 → 10-15秒
FMP API使用减少90%
支持更大股票池（100+只股票）

Data Source Attribution

数据源归属

FMP API: Income statements, quotes, historical prices, key metrics, institutional holders
Finviz: Institutional ownership % (fallback), market data
Methodology: William O'Neil's "How to Make Money in Stocks" (4th edition)
Scoring System: Adapted from IBD MarketSmith proprietary system

FMP API：利润表、报价、历史价格、关键指标、机构持有者
Finviz：机构持股比例（回退）、市场数据
方法论：William O'Neil的《How to Make Money in Stocks》（第4版）
评分系统：改编自IBD MarketSmith专有系统

Disclaimer

免责声明

This screener is for educational and informational purposes only.

Not investment advice
Past performance does not guarantee future results
CANSLIM methodology works best in bull markets (M component confirms)
Conduct your own research and consult a financial advisor before making investment decisions
O'Neil's historical winners include AAPL (2009: +1,200%), NFLX (2013: +800%), but many stocks fail to perform

Version: Phase 2 Last Updated: 2026-01-12 API Requirements: FMP API (free tier sufficient) + BeautifulSoup/requests/lxml for Finviz Execution Time: ~1 minute 40 seconds for 40 stocks Output Formats: JSON + Markdown Components Implemented: C, A, N, S, I, M (6 of 7, 80% coverage)

本筛选工具仅用于教育和信息目的。

不构成投资建议
过往业绩不代表未来结果
CANSLIM方法论在牛市中效果最佳（M要素确认）
做出投资决策前请自行研究并咨询财务顾问
O'Neil的历史赢家包括AAPL（2009年：+1200%）、NFLX（2013年：+800%），但许多股票表现不佳

版本： 第二阶段 最后更新： 2026-01-12 API要求： FMP API（免费 tier足够）+ BeautifulSoup/requests/lxml（用于Finviz） 执行时间： 40只股票约1分40秒 输出格式： JSON + Markdown 已实现要素： C、A、N、S、I、M（7个中的6个，80%覆盖率）

canslim-screener

Original

Translation

CANSLIM Stock Screener - Phase 2

CANSLIM股票筛选工具 - 第二阶段

Overview

概述

When to Use This Skill

适用场景

Workflow

操作流程

Step 1: Verify API Access and Requirements

步骤1：验证API访问权限及要求

Check environment variable

检查环境变量

If not set, prompt user to provide it

如果未设置，提示用户提供

Step 2: Determine Stock Universe

步骤2：确定股票池

Step 3: Execute CANSLIM Screening Script

步骤3：执行CANSLIM筛选脚本

Basic run (40 stocks, top 20 in report)

基础运行（40只股票，报告显示前20只）

Custom parameters

自定义参数

Step 4: Read and Parse Screening Results

步骤4：读取并解析筛选结果

Find the latest report

查找最新报告

Read the report

读取报告

Step 5: Analyze Top Candidates and Provide Recommendations

步骤5：分析顶级候选并提供建议

Step 6: Generate User-Facing Report

步骤6：生成面向用户的报告

CANSLIM Stock Screening Results (Phase 2)

CANSLIM股票筛选结果（第二阶段）

Market Summary

市场摘要

Top 5 CANSLIM Candidates

前5只CANSLIM候选股票

1. [SYMBOL] - [Company Name] ⭐⭐⭐

1. [股票代码] - [公司名称] ⭐⭐⭐

Investment Recommendations

投资建议

Risk Factors

风险因素

Next Steps

后续步骤

Resources

资源

Scripts Directory (scripts/)

脚本目录（scripts/）

References Directory (references/)

参考文档目录（references/）

Troubleshooting

故障排除

Issue 1: FMP API Rate Limit Exceeded

问题1：FMP API速率限制超限

Issue 2: Missing Required Libraries

问题2：缺少依赖库

Install all required libraries

安装所有依赖库

Or install individually

或单独安装

Issue 3: Finviz Fallback Slow Execution

问题3：Finviz fallback执行缓慢

Issue 4: Finviz Web Scraping Failure

问题4：Finviz网页抓取失败

Issue 5: No Stocks Meet Minimum Thresholds

问题5：无股票满足最低阈值

Issue 6: Data Quality Warnings

问题6：数据质量警告

Important Notes

重要说明

Phase 2 Implementation Status

第二阶段实现状态

Finviz Integration Benefits

Finviz集成优势

Future Enhancements

Scripts Directory (
`scripts/`
)

脚本目录（
`scripts/`
）

References Directory (
`references/`
)

参考文档目录（
`references/`
）