Hermes-Skills/dividend-scanner/references/us-dividend-frequency-tier.md

dividend_alert.py 美股频率反推 + 周派票数据缺口 (2026-08-26)

📋 背景

dividend_alert.py 推送"明天除权的美股"列表时,只显示「每股派/annual/连续估年」, 没法区分:

• 季度派息的稳定票 (EXPE/SOLS) vs
• BDC/REIT 的高频派息陷阱 (PSEC月派, SATA周派)

用户原话 "PSEC 显示连续 12 年, SATA 显示连续 249 年, 显然公式 bug"。

✅ 加的修复 (2026-08-26)

dividend_alert.py 加了「频率(估)」列, 用 round(ann/rate) 反推年度派息次数 → 档位标签:

freq_n = round(ann / d)  # d = 单次每股派, ann = 年化
if   freq_n >= 50: freq_str = '🔄周W'
elif freq_n >= 25: freq_str = '🔄双周BW'
elif freq_n >= 11: freq_str = '🔄月M'
elif freq_n >=  5: freq_str = '🔄双月BM'
elif freq_n >=  3: freq_str = '📅季度Q'
elif freq_n ==  2: freq_str = '📅半年S'
elif freq_n ==  1: freq_str = '📅年A'
else:              freq_str = '❓'

档位	年度次数	真实场景
🔄周W	≈52	BDC 周派 (SATA, EPRF) — 高息陷阱常见
🔄双周BW	≈26	BDC 双周派
🔄月M	≈12	BDC/REIT 月派 (PSEC, AGNC) — 高息陷阱
🔄双月BM	≈6	不常见
📅季度Q	3-4	标准季度派 (EXPE/SOLS/JNJ)
📅半年S	2	半年派
📅年A	1	年度派

⚠️ 周派票数据缺口 (已部分解决 — 2026-08-26)

Nasdaq 除权日历 API (api.nasdaq.com/api/calendar/dividends?date=...) 不收录周派 ETF/BDC:

实测 (2026-08-25):

• QQQY / RDTE 每周四都派息 (yfinance 历史可查)
• 但 Nasdaq API 未来 7 天所有除权日都查不到 QQQY/RDTE
• 周派 ETF 普遍被漏: QQQY/RDTE/EPRF/EFC/STWD 等

根因: Nasdaq API 的 indicated_Annual_Dividend 对周派 ETF 返回 0, 脚本过滤掉 ann=0 的票, 但根本拉不到除权日信息。

✅ 解决方案 (2026-08-26 上线): LongPort MCP dividend 工具

关键发现: 长桥 MCP 的 mcp_longport_dividend 工具有 QQQY/RDTE/EPRF 的完整历史派息。本会话验证:

resp = mcp_call('tools/call', {
    'name':'dividend','arguments':{'symbol':'QQQY.US'}
}, ...)
# → list 含 100 条记录, 每条 record_date 是周四 (2026.08.20, 2026.08.13, 2026.08.06...)
# desc 字段: "每股派发 0.1309 USD" (编码乱但能 parse 数字)

新工具: ~/.hermes/scripts/dividend_highfreq.py

设计: 全 US 市场动态扫描, 找出高频派息票 (W/BW/M/BM 档)。

数据流:

1. security_list 翻页 (US market, page=1..N, 每页 50 条) → 候选池
2. quote 批量 (一次最多 500) → 当前价格
3. dividend 逐只 (1-4 秒/只) → 历史派息日期 + 金额
4. 算频率档位 (period_days_avg: ≤5=W, ≤11=BW, ≤18=M, ≤35=BM, ≤70=Q)
5. 筛 yield ≥ 4% 入 SQLite highfreq_pool
6. 按 freq + yield + 稳定度 (std/mean cv) 排序推送

cron 频率: 每日一次 (建议 21:00 北京, 比长桥主推送早 30 分钟), Top 200 票 ~8 分钟跑完。

推送格式 (横表):

🔄 美股高频派息雷达 (YYYY-MM-DD 北京) 数据源: 长桥 MCP
| 票 | 频率 | 连续(期) | 稳定度 | 平均派$ | 现价 | 年化股息率 |
|:---|:---|:---|:---|:---|:---|:---|
| LEND.US | 🔄双月BM | 8 | ⭐⭐⭐ cv=0.05 | $0.193 | $20.50 | **9.41%** |
| VAIE.US | 🔄双周BW | 12 | ⭐⭐⭐ cv=0.04 | $0.077 | $4.74 | **16.27%** |

⚠️ 高频派息 (W/BW/M/BM) 多为 BDC/REIT, 高息常不可持续, 文化娱乐参考。

⚠️ 长桥 screener_search 工具的隐性坑

实测 (2026-08-26): screener_search 的 dividend 和 dpseps indicator 字段返 None (即使请求了), 只返 prevclose/marketcap/pettm/pbmrq/salesgrowthyoy 这些。

所以:

• ❌ 不要试图用 screener_search filter=[dividend≥X] 筛高息股 — 返的 dividend 字段全 None
• ✅ 改用 security_list 拿全市场 → quote 拿现价 → dividend 拿历史 → 算 yield
• ✅ security_list 支持 page=N 翻页 (每页 50 条), total=16008 (US)

🧠 数据源优先级 (v2 决策)

方案	数据源	优/缺	状态
A	yfinance 单只拉	准 / 慢	❌ 太慢
B	yfinance bulk download	一次 / 数据大,漏票	❌
C	ETF.com API	准 / 付费	❌
D	stockanalysis.com HTML scrape	免费 / 反爬	❌
E	LongPort MCP dividend 工具	准 / 已知完整覆盖 QQQY/RDTE 等	✅ v2 实装
F	Nasdaq 除权日历 (旧)	不收周派	❌ 已被覆盖

用户决策 (2026-08-26): 走 E。dividend_highfreq.py v1.0 已实装, cron 接入待办。

🛠️ 加列后推送对比

前:

| PSEC | 💰$0.04 | $0.42 | 🔥12 | 📊$2.35 | **17.87%** | 8/27/2026 |
| SATA | 💰$0.05 | $12.85 | 🔥249 | 📊$100.00 | **12.85%** | 8/27/2026 |

后 (frequency column added):

| PSEC | 💰$0.04 | $0.42 | 🔄月M | 🔥12 | 📊$2.35 | **17.87%** | 8/27/2026 |
| SATA | 💰$0.05 | $12.85 | 🔄周W | 🔥249 | 📊$100.00 | **12.85%** | 8/27/2026 |

新增列一目了然看出 BDC/REIT 高频派息陷阱。

📌 实现位置

~/.hermes/scripts/dividend_alert.py line ~226 (us_h 表格渲染分支), 改动注释 2026-08-26 加频率(估)列, 在 SKILL.md 末尾加一行 disclaimer。

验证

python3 ~/.hermes/scripts/dividend_alert.py --market us
# 验证: 输出表格有"频率(估)"列, 数字标的是 W/M/Q 等档位