# 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)` 反推年度派息次数 → 档位标签:

```python
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 的完整历史派息**。本会话验证:

```python
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。

## 验证

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