value-dividend-screener

价值股息筛选器

概述

此技能采用两阶段筛选方法，识别兼具价值特征、诱人收益和稳定增长的优质股息股票：

1. FINVIZ Elite API（可选，但推荐）：使用基本条件预筛选股票（快速且经济高效）
2. Financial Modeling Prep（FMP）API：对候选股票进行详细的基本面分析

根据估值比率、股息指标、财务健康状况和盈利能力等量化标准筛选美国股票。生成综合报告，依据综合质量评分对股票进行排名，并提供详细的基本面分析。

效率优势：使用 FINVIZ 预筛选可减少 90% 的 FMP API 调用次数，因此此方法非常适合使用免费版 API 的用户。

适用情形

用户提出以下请求时调用此技能：

• “寻找优质股息股票”
• “筛选价值型股息机会”
• “给我看看股息增长强劲的股票”
• “寻找估值合理的收益型股票”
• “筛选高收益且可持续的股票”
• 任何结合股息收益率、估值指标和基本面分析的请求

工作流

步骤 1：确认 API 密钥是否可用

两阶段筛选（推荐）：

检查是否同时提供了两个 API 密钥：

import os
fmp_api_key = os.environ.get('FMP_API_KEY')
finviz_api_key = os.environ.get('FINVIZ_API_KEY')

如果未提供，请用户提供 API 密钥或设置环境变量：

export FMP_API_KEY=your_fmp_key_here
export FINVIZ_API_KEY=your_finviz_key_here

仅使用 FMP 筛选：

检查是否提供了 FMP API 密钥：

import os
api_key = os.environ.get('FMP_API_KEY')

如果未提供，请用户提供 API 密钥或设置环境变量：

export FMP_API_KEY=your_key_here

FINVIZ Elite API 密钥：

• 需要订阅 FINVIZ Elite（约 40 美元/月或约 330 美元/年）
• 可导出预筛选结果的 CSV 文件
• 强烈推荐使用，以减少 FMP API 的用量

如有需要，请提供 references/fmp_api_guide.md 中的说明。

步骤 2：运行筛选脚本

使用适当的参数运行筛选脚本：

两阶段筛选（推荐）

使用 FINVIZ 进行预筛选，然后使用 FMP 进行详细分析：

默认执行（前 20 只股票）：

python3 scripts/screen_dividend_stocks.py --use-finviz

显式指定 API 密钥：

python3 scripts/screen_dividend_stocks.py --use-finviz \
  --fmp-api-key $FMP_API_KEY \
  --finviz-api-key $FINVIZ_API_KEY

自定义前 N 只：

python3 scripts/screen_dividend_stocks.py --use-finviz --top 50

自定义输出位置：

python3 scripts/screen_dividend_stocks.py --use-finviz --output /path/to/results.json

脚本行为（两阶段）：

1. 使用 FINVIZ Elite 预筛选：
   • 市值：中盘股或更高
   • 股息收益率：3% 以上
   • 股息增长率（3 年）：5% 以上
   • EPS 增长率（3 年）：正值
   • P/B：低于 2
   • P/E：低于 20
   • 销售额增长率（3 年）：正值
   • 地区：美国
2. 使用 FMP 对 FINVIZ 结果进行详细分析（通常为 20–50 只股票）：
   • 计算股息增长率（3 年 CAGR）
   • 分析营收和 EPS 趋势
   • 评估股息可持续性（派息率、FCF 覆盖率）
   • 财务健康指标（债务权益比、流动比率）
   • 质量评分（ROE、利润率）
3. 综合评分并排名
4. 将前 N 只股票输出到 JSON 文件

**预计运行时间（两阶段）：**筛选 30–50 只 FINVIZ 候选股票需 2–3 分钟（远快于仅使用 FMP 的方式）

仅使用 FMP 筛选（原始方法）

仅使用 FMP Stock Screener API（API 用量更高）：

默认执行：

python3 scripts/screen_dividend_stocks.py

显式指定 API 密钥：

python3 scripts/screen_dividend_stocks.py --fmp-api-key $FMP_API_KEY

脚本行为（仅使用 FMP）：

1. 使用 FMP Stock Screener API 进行初步筛选（股息收益率 >=3.0%、P/E <=20、P/B <=2）
2. 对候选股票进行详细分析（通常为 100–300 只股票）：
   • 详细分析内容与两阶段方法相同
3. 综合评分并排名
4. 将前 N 只股票输出到 JSON 文件

**预计运行时间（仅使用 FMP）：**分析 100–300 只候选股票需 5–15 分钟（受速率限制影响）

API 用量对比：

• 两阶段：约 50–100 次 FMP API 调用（FINVIZ 将候选范围预筛至约 30 只股票）
• 仅使用 FMP：约 500–1500 次 FMP API 调用（分析筛选器返回的所有结果）

步骤 3：解析和分析结果

读取生成的 JSON 文件：

import json

with open('dividend_screener_results.json', 'r') as f:
    data = json.load(f)

metadata = data['metadata']
stocks = data['stocks']

每只股票的关键数据点：

• 基本信息：symbol、company_name、sector、market_cap、price
• 估值：dividend_yield、pe_ratio、pb_ratio
• 增长指标：dividend_cagr_3y、revenue_cagr_3y、eps_cagr_3y
• 可持续性：payout_ratio、fcf_payout_ratio、fcf_amount、fcf_status、fcf_coverage_status、sustainability_basis、dividend_sustainable、sustainability_bonus、sustainability_note
• 财务健康状况：debt_to_equity、current_ratio、financially_healthy
• 质量：roe、profit_margin、quality_score
• 综合排名：composite_score

步骤 4：生成 Markdown 报告

为用户创建包含以下部分的结构化 Markdown 报告：

报告结构

# Value Dividend Stock Screening Report

**Generated:** [Timestamp]
**Screening Criteria:**
- Dividend Yield: >= 3.5%
- P/E Ratio: <= 20
- P/B Ratio: <= 2
- Dividend Growth (3Y CAGR): >= 5%
- Revenue Trend: Positive over 3 years
- EPS Trend: Positive over 3 years

**Total Results:** [N] stocks

---

## Top 20 Stocks Ranked by Composite Score

| Rank | Symbol | Company | Yield | P/E | Div Growth | Score |
|------|--------|---------|-------|-----|------------|-------|
| 1 | [TICKER] | [Name] | [%] | [X.X] | [%] | [XX.X] |
| ... |

---

## Detailed Analysis

### 1. [SYMBOL] - [Company Name] (Score: XX.X)

**Sector:** [Sector Name]
**Market Cap:** $[X.XX]B
**Current Price:** $[XX.XX]

**Valuation Metrics:**
- Dividend Yield: [X.X]%
- P/E Ratio: [XX.X]
- P/B Ratio: [X.X]

**Growth Profile (3-Year):**
- Dividend CAGR: [X.X]% [✓ Consistent / ⚠ One cut]
- Revenue CAGR: [X.X]%
- EPS CAGR: [X.X]%

**Dividend Sustainability:**
- Payout Ratio: [XX]%
- FCF Payout Ratio: [XX]%
- FCF Observed: [amount or unavailable] ([POSITIVE / ZERO / NEGATIVE / MISSING_DATA])
- FCF Coverage: [COVERED / AT_LIMIT / INSUFFICIENT_FCF / ZERO_FCF / NEGATIVE_FCF / MISSING_DATA / NO_DIVIDEND]
- Decision Basis: [EARNINGS_AND_FCF / FFO]
- Status: [✓ Sustainable / ⚠ Not confirmed]; Bonus: [0 / 10] points
- Explanation: [sustainability_note]

**Financial Health:**
- Debt-to-Equity: [X.XX]
- Current Ratio: [X.XX]
- Status: [✓ Healthy / ⚠ Caution]

**Quality Metrics:**
- ROE: [XX]%
- Net Profit Margin: [XX]%
- Quality Score: [XX]/100

**Investment Considerations:**
- [Key strength 1]
- [Key strength 2]
- [Risk factor or consideration]

---

[Repeat for other top stocks]

---

## Portfolio Construction Guidance

**Diversification Recommendations:**
- Sector breakdown of top 20 results
- Suggested allocation strategy
- Concentration risk warnings

**Monitoring Recommendations:**
- Key metrics to track quarterly
- Warning signs for each position
- Rebalancing triggers

**Risk Considerations:**
- Market cap concentration
- Sector biases in results
- Economic sensitivity warnings

在面向读者的报告中，应将观察到的 FCF 与股息覆盖情况分开说明。负 FCF 表示观察到的资金缺口；FCF 为零表示没有现金覆盖；MISSING_DATA 表示源字段不可用。这些情况都不能证明未来会削减股息。AT_LIMIT 表示 FCF 与股息相等、没有缓冲，因此不获得加分。对于已确认的 REIT，应以 FFO 作为判断依据，同时将 FCF 状态作为背景信息展示，即使 FCF 为负也应如此；不能仅因为某公司的板块为 Real Estate 就对其采用 FFO 处理。将 sustainability_note 原样纳入说明，不要用可持续性断言替代未知状态。

步骤 5：提供背景和方法论

解释结果时，请参考筛选方法：

需要解释的关键概念：

• 为什么选择这些具体阈值（3.5% 股息率、P/E 20、P/B 2）
• 股息增长为何比静态高股息率更重要
• 综合评分如何权衡价值、增长和质量
• 股息可持续性与股息陷阱的区别
• 财务健康指标的重要性

加载 references/screening_methodology.md，以提供以下内容的详细说明：

• 阶段 1：初始定量筛选
• 阶段 2：增长质量筛选
• 阶段 3：可持续性和质量分析
• 综合评分系统
• 投资理念和局限性

步骤 6：回答后续问题

预判用户常见的问题：

“为什么 [stock] 没有上榜？”

• 检查其未通过哪些标准（股息率、估值、增长、可持续性）
• 说明将其排除的具体筛选条件

“可以按特定板块筛选吗？”

• 脚本支持筛选功能（修改第 383-388 行）
• 建议添加板块参数后重新运行

“如果我想提高/降低股息率阈值怎么办？”

• 可以调整脚本参数
• 权衡股息率与增长之间的取舍
• 建议使用新参数重新筛选

“应该多久重新运行一次筛选？”

• 建议每季度运行一次（与财报周期保持一致）
• 对长期持有者而言，每半年一次也足够
• 市场状况可能要求更频繁地检查

“应该买入多少只股票？”

• 分散投资建议：股息投资组合至少包含 10-15 只股票
• 考虑板块平衡
• 根据风险承受能力确定持仓规模

资源

scripts/screen_dividend_stocks.py

功能全面的筛选脚本，能够：

• 调用 FMP API 获取数据
• 实现多阶段筛选逻辑
• 计算 3 年期增长率（CAGR）
• 通过派息率和 FCF 覆盖率评估股息可持续性
• 评估财务健康状况（债务权益比、流动比率）
• 计算质量评分（ROE、利润率）
• 按综合评分系统为股票排名
• 输出结构化 JSON 结果

依赖项： requests 库（通过 pip install requests 安装）

速率限制： 内置延迟，以遵守 FMP API 限制（免费层每天 250 次请求）

错误处理： 针对缺失数据进行平稳降级、速率限制重试以及 API 错误处理

references/screening_methodology.md

筛选方法的完整文档：

阶段 1：初始定量筛选

• 股息收益率 >= 3.5% 的理由和计算方法
• P/E 比率 <= 20 的阈值依据
• P/B 比率 <= 2 的估值逻辑

阶段 2：增长质量筛选

• 股息增长（3 年 CAGR >= 5%）
• 营收正向趋势分析
• EPS 正向趋势分析

阶段 3：质量与可持续性分析

• 股息可持续性指标（派息率、FCF 覆盖率）
• 财务健康指标（D/E、流动比率）
• 质量评分方法（ROE、利润率）

综合评分系统（0-100 分）

• 评分组成部分及权重明细
• 解读指南

投资理念

• 这种方法为何有效
• 这种策略会规避什么（股息陷阱、价值陷阱）
• 理想候选对象的特征

使用说明与局限性

• 投资组合构建的最佳实践
• 卖出标准
• 阈值选择的历史背景

references/fmp_api_guide.md

Financial Modeling Prep API 完整指南：

API 密钥设置

• 获取免费 API 密钥
• 设置环境变量
• 免费套餐限制（每天 250 次请求）

使用的主要端点

• 股票筛选器 API
• 利润表 API
• 资产负债表 API
• 现金流量表 API
• 关键指标 API
• 历史股息 API

速率限制策略

• 脚本内置保护
• 请求额度管理
• 免费套餐最佳实践

错误处理

• 常见错误及解决方案
• 调试技巧

数据质量注意事项

• 数据时效性与缺漏
• 数据准确性注意事项
• 何时通过 SEC 文件核实

高级用法

自定义筛选标准

修改 scripts/screen_dividend_stocks.py 中的阈值：

第 383-388 行 - 初始筛选参数：

candidates = client.screen_stocks(
    dividend_yield_min=3.5,  # Adjust yield threshold
    pe_max=20,               # Adjust P/E threshold
    pb_max=2,                # Adjust P/B threshold
    market_cap_min=2_000_000_000  # Minimum $2B market cap
)

第 423 行 - 股息 CAGR 阈值：

if not div_cagr or div_cagr < 5.0:  # Adjust growth threshold

按行业筛选

在初始筛选后添加行业筛选：

# Filter for specific sectors
target_sectors = ['Consumer Defensive', 'Utilities', 'Healthcare']
candidates = [s for s in candidates if s.get('sector') in target_sectors]

排除 REIT 和金融股

REIT 和金融股的股息特征不同（派息率较高、指标不同）：

# Exclude REITs and Financials
exclude_sectors = ['Real Estate', 'Financial Services']
candidates = [s for s in candidates if s.get('sector') not in exclude_sectors]

导出为 CSV

将 JSON 结果转换为 CSV，以便在 Excel 中分析：

import json
import csv

with open('dividend_screener_results.json', 'r') as f:
    data = json.load(f)

stocks = data['stocks']

with open('screening_results.csv', 'w', newline='') as csvfile:
    if stocks:
        fieldnames = stocks[0].keys()
        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(stocks)

故障排除

“ERROR: requests library not found”

**解决方案：**安装 requests 库

pip install requests

“ERROR: FMP API key required”

**解决方案：**设置环境变量或通过命令行提供

export FMP_API_KEY=your_key_here
# OR
python3 scripts/screen_dividend_stocks.py --fmp-api-key your_key_here

“ERROR: FINVIZ API key required when using --use-finviz”

**解决方案：**设置环境变量或通过命令行提供

export FINVIZ_API_KEY=your_key_here
# OR
python3 scripts/screen_dividend_stocks.py --use-finviz --finviz-api-key your_key_here

**注意：**需要 FINVIZ Elite 订阅（约 $40/月或约 $330/年）

“ERROR: FINVIZ API authentication failed”

可能原因：

1. FINVIZ API 密钥无效
2. FINVIZ Elite 订阅已过期
3. API 密钥格式不正确

解决方案：

• 确认 FINVIZ Elite 订阅处于有效状态
• 检查 API 密钥是否有拼写错误（应为字母数字字符串）
• 登录 FINVIZ Elite 账户，并在设置中确认 API 密钥
• 尝试手动访问 FINVIZ Elite 筛选器，以确认订阅状态

“ERROR: FINVIZ pre-screening failed or returned no results”

可能原因：

1. FINVIZ API 连接问题
2. 筛选标准过于严格（没有符合条件的股票）
3. 市场状况（熊市可能筛选出较少结果）

解决方案：

• 检查互联网连接
• 确认可以访问 FINVIZ Elite 网站
• 尝试使用仅 FMP 的方法作为备用方案：

  python3 scripts/screen_dividend_stocks.py
  

“WARNING: Rate limit exceeded”

**解决方案：**脚本会在 60 秒后自动重试。如果问题持续：

• 等到次日（免费套餐每天重置）
• 减少分析的股票数量（修改第 394 行的限制）
• 考虑升级至付费 FMP 套餐

“No stocks found matching all criteria”

**解决方案：**筛选标准可能过于严格

• 放宽 P/E 阈值（从 20 上调）
• 降低股息收益率要求（从 3.5% 下调）
• 降低股息增长要求（从 5% 下调）
• 检查市场状况（熊市可能筛选出较少符合条件的股票）

脚本运行缓慢

预期行为： 脚本在 API 调用之间延迟 0.3 秒，以遵守速率限制

• 分析 100 只股票 ≈ 8-10 分钟
• 通常在分析前 50-70 只股票时，就能找到最先符合条件的 20-30 只

性能与成本优化

API 调用对比

两阶段筛选（FINVIZ + FMP）：

• FINVIZ：1 次 API 调用
• FMP Quote API：约 30-50 次调用（每个预筛选后的标的代码调用一次）
• FMP Financial Data：约 150-250 次调用（5 个端点 × 30-50 个标的代码）
• FMP 调用总数：约 180-300 次

仅使用 FMP 筛选：

• FMP Stock Screener：1 次调用（返回 100-1000 只股票）
• FMP Financial Data：约 500-5000 次调用（5 个端点 × 100-1000 个标的代码）
• FMP 调用总数：约 500-5000 次

节省：FMP API 使用量减少 60-94%

成本分析

FINVIZ Elite：

• 每月：$39.50
• 每年：$299.50（约 $24.96/月）

FMP API：

• 免费套餐：每天 250 次调用（足以满足两阶段筛选需求）
• Starter 套餐：$29.99/月，每天 750 次调用
• Professional 套餐：$79.99/月，每天 2000 次调用

建议：

• 对于 FMP 免费套餐用户：使用两阶段筛选（FINVIZ + FMP 免费套餐）
• 对于 FMP 付费套餐用户：两种方式都适用；两阶段筛选速度更快
• 预算方案：仅使用 FMP 免费套餐进行筛选（每隔几天运行一次筛选）
• 最佳方案：FINVIZ Elite（$330/年）+ FMP 免费套餐 = 完整解决方案

版本历史

• v1.1（2025 年 11 月）：新增 FINVIZ Elite 集成，支持两阶段筛选
• v1.0（2025 年 11 月）：首次发布，包含全面的多阶段筛选