---
name: dividend-yield-rate-sort
description: "分红扫描按股息率% 倒序(用户偏好 2026-07-13),不按派息金额"
version: 1.0.0
type: reference
---

# 分红扫描: 按股息率% 排序(用户明确偏好)

## 用户原话
> "这种任务推送的结果, 按股息率排个序, 倒序" (2026-07-13)

## 错误做法 ❌

`dividend_alert.py` 原版按 **`div` 字段排序**(派息金额绝对值 USD):
```python
us_h = sorted(us_r, key=lambda x: -x['div'])  # 错!
```

**问题**: 派息 USD 0.54(NEWTH)排第一,但股息率 8.49%;派息 USD 0.14(CPZ)股息率 **12.74%** 被挤后面。**用户买的是收益率,不是绝对金额**。

## 正确做法 ✅

按 **年化股息率 % = (年化派息 / 当前价) × 100** 倒序排序:
- 美股: `yield = annual_div / price × 100`
- A 股: `yield = (每 10 股派 / 10) / price × 100`
- 港股: 同 A 股(每 10 股派多少 HKD)

### 代码模板(2026-07-13 已部署 dividend_alert.py)

```python
# 4.5. 重排序 - 按股息率% 倒序
def _yr_a(r):
    price = (a_p.get(r['code'] + '.SH') or a_p.get(r['code'] + '.SZ') or a_p.get(r['code'] + '.BJ') or 0)
    if price <= 0: return 0
    return (r.get('div', 0) / 10) / price * 100

def _yr_hk(r):
    price = (hk_p.get(r['code'] + '.HK') or 0)
    if price <= 0: return 0
    return (r.get('div', 0) / 10) / price * 100

def _yr_us(r):
    price = (us_p.get(r['code'] + '.US') or 0)
    if price <= 0: return 0
    # 关键: fetch_us() 字段名是 'ann' (不是 'ann_div')
    # 原代码用 'ann_div' 拿不到 → fallback 到 'div' 单次派息
    # → 算出的 yield 是当次收益率,不是年化 (SATA 年化 12.54% 被算成 0.05%)
    ann = r.get('ann', 0) or r.get('div', 0)
    return ann / price * 100

if a_p: a_h = sorted(a_h, key=lambda x: -_yr_a(x))
if hk_p: hk_h = sorted(hk_h, key=lambda x: -_yr_hk(x))
if us_p: us_h = sorted(us_h, key=lambda x: -_yr_us(x))
```

## 排序 vs 价格的依赖

**重要**:**必须先 `batch_quote()` 拿价格**,再排序。如果先按 div 排序再去重价格,排行榜就是错的(代码顺序:`先 div 排序 → 批量拿价 → 按 yield 重排序`)。

## 实际效果对比(2026-07-13 美股清单)

| 排名 | 按派息金额 (旧) | 按股息率% (新) |
|------|-----------------|----------------|
| 1 | NEWTH $0.54 (8.49%) | **NEWTH 8.49%** |
| 2 | APOG $0.27 (2.78%) | **CPZ 12.74%** ⭐ |
| 3 | CCD $0.20 (9.03%) | CCD 9.03% |
| 4 | CPZ $0.14 (12.74%) | CHY 8.73% |
| 5 | CSQ $0.14 (7.07%) | CHI 8.49% |
| 6 | CHY $0.10 (8.73%) | CHW 6.80% ⭐(新发现) |
| 7 | CHI $0.10 (8.49%) | CGO 7.09% |

**CPZ 12.74% 从第 4 → 第 2**(用户买到的高息标的从筛子漏出)。

## 关联文件

- `~/.hermes/scripts/dividend_alert.py` — 已部署 `dividend_alert.py --market {cn_hk|us|all}` 两种模式
- `~/.hermes/scripts/dividend_alert_cn_hk.sh` — wrapper (cron `789a7710b1cf`)
- `~/.hermes/scripts/dividend_alert_us.sh` — wrapper (cron `366934c1474c`)
- SKILL.md `dividend-investing` (若存在) 或 `cron-job-management` — cron 调度

## 其他可应用的场景

任何"收益率 / 性价比"扫描(类似 dividend alert)都该用相同排序:
- 财报收益率
- 套息年化收益率
- bond yield
- staking APY

永远 **先拿价格 → 再按收益率排序**(不是按绝对金额)。