trading skills: 文档同步 (单币上限规则/平仓盈亏字段/静默规则/推送模板)

tonghuashun/SKILL.md

@@ -36,6 +36,7 @@ AKShare 是一个免费开源的 Python 金融数据接口库，底层数据源
 - 用户问板块："今天什么板块涨得好"、"AI概念股有哪些"
 - 用户要排名："连续下跌的股票"、"创新高的股票"
 - 用户要 A 股数据补充长桥 LongBridge 的覆盖
+- **用户给 fuyao.aicubes.cn API key**（同花顺官方 REST API，2026-09-19 发现）→ **优先用官方 API**，akshare 仅作 fallback
 
 ## 核心函数速查
 
@@ -207,7 +208,12 @@ print(f"营收: {latest['营业总收入']} | 净利润: {latest['净利润']} |
 
 ## Common Pitfalls
 
-1. **代码格式**：A股代码直接传字符串（如 '600519'），不要加后缀
+1. **🔴 脑补股票代码 → 先查证再答 (2026-09-17 实战)**:
+    - **场景**: 用户问"北京银行是多少", agent **脑补**"北京银行 = 601988", 实查 601988 = 中国银行, 真实北京银行 = 601169, 用户从没说过 601988 是北京银行
+    - **正解**: 用户问"X 是多少/是哪个" → **先查证** (grep / akshare / 长桥), **不联想**; **不确定 → 列 3-4 个候选项** 让用户选, **不要脑补一个当答案**; 验证后答, **带源**: "601169 (akshare 验证), 当前价 X, 股息率 Y"
+    - **触发词**: "X 是哪个" / "X 是多少" / "那 X 呢" / "X 是 Y 吗" / "你找错了" / "你说的不对" / "我说过吗" → 触发脑补陷阱
+
+2. **代码格式**：A股代码直接传字符串（如 '600519'），不要加后缀
 2. **实时行情慢**：full_spot = `stock_zh_a_spot_em()` 第一次跑很慢，但Hermes会话中变量保持，可以复用
 3. **同花顺 vs 东方财富**：同花顺的财务/板块数据更全，东方财富的K线/行情更稳定，按需选择
 4. **无法交易**：同花顺没有Linux API，本skill只做数据查询
@@ -233,10 +239,53 @@ print(f"营收: {latest['营业总收入']} | 净利润: {latest['净利润']} |
    ```
    如需宽格式，用旧版 `stock_financial_abstract_ths()`。
 
+10. **分红/股息率接口（2026-09-17 实测）**：
+    - **批量（推荐）**：`ak.stock_fhps_em(date='20241231')` 一次返回 ~3700 只股票的分红数据。字段含 `现金分红-股息率`（**同花顺 APP 算法**直接给出，不用算）。
+      ```python
+      df = ak.stock_fhps_em(date='20241231')  # 该报告期所有实施/预案
+      # 字段：'代码','名称','送转股份-送转总比例','现金分红-现金分红比例',
+      #       '现金分红-股息率','每股收益','方案进度','股权登记日','除权除息日'...
+      ```
+    - **单只（带历史）**：`ak.stock_fhps_detail_ths(symbol='601169')` 返回该股**所有历史派息**。关键字段 `税前分红率`（**直接是 %**，同花顺 APP 算法）。
+      ```python
+      df = ak.stock_fhps_detail_ths(symbol='601169')
+      # 字段：'报告期','董事会日期','股东大会预案公告日期','实施公告日',
+      #       '分红方案说明'(如"10派1.2元"),'分红总额','股利支付率','税前分红率'
+      # 进度过滤：df[df['方案进度']=='实施方案']
+      ```
+    - **🔴 单位陷阱（必踩）**：`ak.stock_history_dividend` 的 `年均股息` 字段单位是 **"每 10 股"**（不是每股！）。`ak.stock_history_dividend_detail` 的 `派息` 字段也是 **"每 10 股"**。计算股息率必须 `/10`：
+      ```python
+      avg_div = float(row['年均股息'])  # 例如 4.10
+      px = prices[code]                  # 当前价
+      div_per_share = avg_div / 10       # /10 → 每股派息
+      yield_pct = div_per_share / px * 100
+      ```
+    - **🔴 "派息" / % 字符串**：同花顺/东方财富股息率带 `%` 符号，转 float 必须 `str.replace('%','')`：
+      ```python
+      df = ak.stock_fhps_detail_ths(symbol='601169')
+      yld = df['税前分红率'].astype(str).str.replace('%','',regex=False)
+      yld = pd.to_numeric(yld[yld != '--'], errors='coerce').dropna()
+      ```
+    - **🔴 不要自己算 TTM 用"报告期"过滤**：按"实施公告日"过滤才是同花顺算法。北京银行 2024 中报 2025-01-14 实施，按"报告期 2024-06-30"会算漏，要按"实施公告日"找最近 365 天。
+      ```python
+      from datetime import datetime, timedelta
+      now = datetime.now()
+      ttm_start = now - timedelta(days=365)
+      df['imp_dt'] = pd.to_datetime(df['实施公告日'], errors='coerce')
+      recent = df[df['imp_dt'] >= ttm_start]
+      ttm_yield = float(pd.to_numeric(recent['税前分红率'].astype(str)
+                                       .str.replace('%','',regex=False), errors='coerce').sum())
+      ```
+    - **🔴 AI 算不过同花顺专家**：user 原话 2026-09-17 "你一个AI写算法，还能比得过人家真正的专家吗"。**能用 `现金分红-股息率` 字段就别用派息金额反推**；多只股票优先用 `stock_fhps_em(date=)` 批量接口，不要循环 `stock_fhps_detail_ths`。
+
 ## Reference Documents
 
 See `references/buy-point-analysis.md` for a complete A-share buy-point analysis framework (technical + valuation + financials + profit forecast + entry/stop/target strategy templates).
 
+See `references/cn-broker-account-api-2026-09-14.md` for A股券商账户 API 接入路线 (同花顺无账户API; 中泰 XTP / easytrader / QMT 对比, 2026-09-14 中泰证券实战调研)。
+
+See `references/fuyao-aicubes-ths-official-api-2026-09-19.md` for 同花顺官方 REST API (fuyao.aicubes.cn) — key 存 `~/.bashrc` FUYAO_API_KEY; `corporate-actions/adjustment-factors` 返 dividend_per_share 每股派息流; **官方无股息率 TTM 字段**, valuations 只有 PE/PB/PS/PCF TTM。
+
 ## Verification Checklist
 
 - [ ] `pip show akshare` 确认已安装