@openfinclaw/findoo-datahub-plugin 2026.3.2 → 2026.3.10

package/skills/macro/skill.md

@@ -1,60 +1,251 @@
 ---
 name: fin-macro
-description: "Macro economics and interest rates — China GDP/CPI/PPI/PMI/M2, global rates (Shibor/LPR/Libor/Treasury), World Bank data, FX rates. All via DataHub."
+description: "Macroeconomic analysis — China GDP/CPI/PPI/PMI/M2/social financing, interest rates (Shibor/LPR/Libor/Hibor), CN/US treasury yields, FX rates, WorldBank data, economic calendar. DataHub endpoints via fin_macro. Use when: user asks about economic indicators, monetary policy, rate differentials, yield curve, FX trends, or macro cycle positioning. NOT for: individual stocks (use fin-a-share/fin-us-equity/fin-hk-stock), market signals (use fin-a-share-radar), crypto (use fin-crypto)."
 metadata: { "openclaw": { "emoji": "🏛️", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
 ---
 
 # Macro & Rates
 
-Use the **fin_macro** tool for macroeconomic indicators and interest rate data via DataHub (works out of the box).
-
-## When to Use
-
-- "中国最新GDP" / "China GDP growth"
-- "CPI数据" / "latest CPI"
-- "Shibor利率" / "interbank rate"
-- "LPR是多少" / "loan prime rate"
-- "美国国债收益率" / "US Treasury yield"
-- "世界银行GDP对比" / "World Bank comparison"
-
-## Available Endpoints
-
-### China Macro
-
-| endpoint           | Description           | Example                                  |
-| ------------------ | --------------------- | ---------------------------------------- |
-| `gdp/real`         | China GDP             | `fin_macro(endpoint="gdp/real")`         |
-| `cpi`              | Consumer Price Index  | `fin_macro(endpoint="cpi")`              |
-| `ppi`              | Producer Price Index  | `fin_macro(endpoint="ppi")`              |
-| `pmi`              | Purchasing Managers   | `fin_macro(endpoint="pmi")`              |
-| `money_supply`     | Money supply M0/M1/M2 | `fin_macro(endpoint="money_supply")`     |
-| `social_financing` | Social financing      | `fin_macro(endpoint="social_financing")` |
-
-### Interest Rates
-
-| endpoint      | Description              | Example                             |
-| ------------- | ------------------------ | ----------------------------------- |
-| `shibor`      | Shanghai Interbank Rate  | `fin_macro(endpoint="shibor")`      |
-| `shibor_lpr`  | Loan Prime Rate          | `fin_macro(endpoint="shibor_lpr")`  |
-| `libor`       | London Interbank Rate    | `fin_macro(endpoint="libor")`       |
-| `hibor`       | Hong Kong Interbank Rate | `fin_macro(endpoint="hibor")`       |
-| `treasury_cn` | China treasury yields    | `fin_macro(endpoint="treasury_cn")` |
-| `treasury_us` | US treasury yields       | `fin_macro(endpoint="treasury_us")` |
-
-### Global (World Bank)
-
-| endpoint               | Description           | Example                                                    |
-| ---------------------- | --------------------- | ---------------------------------------------------------- |
-| `worldbank/gdp`        | World Bank GDP        | `fin_macro(endpoint="worldbank/gdp", country="CN")`        |
-| `worldbank/population` | World Bank population | `fin_macro(endpoint="worldbank/population", country="US")` |
-| `worldbank/inflation`  | World Bank inflation  | `fin_macro(endpoint="worldbank/inflation", country="CN")`  |
-| `worldbank/indicator`  | Custom WB indicator   | `fin_macro(endpoint="worldbank/indicator", country="CN")`  |
-
-## Macro Cycle Analysis Pattern
-
-1. `fin_macro(gdp/real)` — growth trend
-2. `fin_macro(cpi)` — inflation
-3. `fin_macro(pmi)` — manufacturing activity
-4. `fin_macro(shibor)` — liquidity conditions
-5. `fin_macro(shibor_lpr)` — policy rate direction
-6. `fin_macro(treasury_cn)` — bond market signal
+Use **fin_macro** for macroeconomic indicators and interest rate data via DataHub.
+
+> 美林时钟四象限: Recovery (GDP↑CPI↓) / Overheat (GDP↑CPI↑) / Stagflation (GDP↓CPI↑) / Recession (GDP↓CPI↓)。判定信号详见下方 Macro Cycle Locator。
+
+## fin_macro Parameters
+
+| Parameter  | Type   | Required | Format                                  | Default | Example        |
+| ---------- | ------ | -------- | --------------------------------------- | ------- | -------------- |
+| endpoint   | string | Yes      | see endpoint tables                     | —       | cpi            |
+| symbol     | string | No       | currency pair or indicator              | —       | USDCNH         |
+| country    | string | No       | ISO 3166 alpha-2 (CN/US/JP/DE/GB/IN/BR) | —       | CN             |
+| indicator  | string | No       | World Bank indicator code               | —       | NY.GDP.MKTP.CD |
+| start_date | string | No       | YYYY-MM-DD                              | —       | 2024-01-01     |
+| end_date   | string | No       | YYYY-MM-DD                              | —       | 2025-12-31     |
+| limit      | number | No       | 1-5000                                  | 200     | 30             |
+
+## Endpoint Map
+
+### China Macro (7)
+
+| endpoint           | Data                 | Freq      |
+| ------------------ | -------------------- | --------- |
+| `gdp/real`         | China GDP            | Quarterly |
+| `cpi`              | Consumer Price Index | Monthly   |
+| `ppi`              | Producer Price Index | Monthly   |
+| `pmi`              | Purchasing Managers  | Monthly   |
+| `money_supply`     | M0/M1/M2             | Monthly   |
+| `social_financing` | Social financing     | Monthly   |
+| `wz_index`         | Wenzhou private rate | Weekly    |
+
+### Interest Rates (8)
+
+| endpoint       | Data                       | Freq           |
+| -------------- | -------------------------- | -------------- |
+| `shibor`       | Shanghai Interbank Rate    | Daily          |
+| `shibor_quote` | Shibor bank-level quotes   | Daily          |
+| `shibor_lpr`   | Loan Prime Rate            | Monthly (20th) |
+| `libor`        | London Interbank Rate ⚠️   | Daily          |
+| `hibor`        | Hong Kong Interbank Rate   | Daily          |
+| `treasury_cn`  | China treasury yields      | Daily          |
+| `treasury_us`  | US treasury yields         | Daily          |
+| `index_global` | Global index (incl USDCNH) | Daily          |
+
+### FX / Currency (4)
+
+| endpoint                    | Data                | Freq     |
+| --------------------------- | ------------------- | -------- |
+| `currency/price/historical` | FX historical price | Daily    |
+| `currency/search`           | Search pairs        | —        |
+| `currency/snapshots`        | FX snapshots        | Intraday |
+| `calendar`                  | Economic calendar   | —        |
+
+### World Bank (5)
+
+| endpoint               | Data          | Freq   |
+| ---------------------- | ------------- | ------ | ----------------------------------------------- |
+| `worldbank/gdp`        | GDP           | Annual |
+| `worldbank/population` | Population    | Annual |
+| `worldbank/inflation`  | Inflation     | Annual |
+| `worldbank/indicator`  | Custom (code) | Annual |
+| `worldbank/country`    | 国别基础数据  | —      | 新兴 vs 发达市场分类、人口/面积等 (296 records) |
+
+### Common World Bank Indicator Codes
+
+`NY.GDP.MKTP.CD` GDP (US$) | `NY.GDP.MKTP.KD.ZG` GDP growth % | `FP.CPI.TOTL.ZG` Inflation % | `SL.UEM.TOTL.ZS` Unemployment % | `BX.KLT.DINV.WD.GD.ZS` FDI %
+
+### 固收利率 (fixedincome 专用路径)
+
+`fin_macro(endpoint="fixedincome/rate/shibor")` 等 4 个端点是 `shibor`/`shibor_lpr`/`libor`/`hibor` 的别名路径，返回相同数据。
+可用端点: `fixedincome/rate/shibor`, `fixedincome/rate/shibor_lpr`, `fixedincome/rate/libor`, `fixedincome/rate/hibor`。
+⚠️ **LIBOR 已于 2023 年正式终止**，DataHub 数据截止 2020-06-24。USD 浮动利率基准已迁移至 SOFR，DataHub 暂无 SOFR 端点。替代方案: 使用 `treasury_us` 短端 (2Y) 作为 USD 利率代理。HIBOR 固收路径同样停在 2020-06，使用 `economy/hibor` 获取更新数据。
+
+## Analysis Patterns
+
+### Macro Cycle Locator
+
+> 美林时钟象限由 GDP 趋势 + CPI 趋势交叉判定，辅以 PMI/社融/M1 领先指标验证。
+
+```
+Step 1: fin_macro(endpoint="gdp/real", limit=8)   → GDP trend (8 quarters)
+Step 2: fin_macro(endpoint="cpi", limit=12)        → CPI trend (12 months)
+```
+
+| Quadrant    | GDP | CPI | Asset priority               |
+| ----------- | --- | --- | ---------------------------- |
+| Recovery    | up  | dn  | Equity > Bond > Cash > Cmdty |
+| Overheat    | up  | up  | Cmdty > Equity > Cash > Bond |
+| Stagflation | dn  | up  | Cash > Cmdty > Bond > Equity |
+| Recession   | dn  | dn  | Bond > Cash > Equity > Cmdty |
+
+Lead/lag classification: **Leading** (1-3Q): `pmi`, `social_financing`, `money_supply` M1 | **Coincident**: `gdp/real`, `wz_index` | **Lagging**: `cpi`, employment
+
+Auxiliary validation:
+
+- `pmi` — PMI > 50 supports recovery/overheat; new orders sub-index is strongest lead
+- `money_supply` — M2 accel = liquidity easing; M1 accel = capital activation
+- `social_financing` — credit expansion leads GDP by 2-3 quarters
+
+### Policy Signal Matrix
+
+```
+Step 1: fin_macro(endpoint="shibor_lpr", limit=12)
+Step 2: fin_macro(endpoint="money_supply", limit=12)
+Step 3: fin_macro(endpoint="social_financing", limit=12)
+```
+
+| LPR  | M2   | Social Fin | Signal         | Market implication         |
+| ---- | ---- | ---------- | -------------- | -------------------------- |
+| cut  | rise | surge      | Full easing    | Strong bullish, dual rally |
+| cut  | rise | flat       | Targeted       | Structural positive        |
+| hold | fall | shrink     | Marginal tight | Caution, funding stress    |
+| hike | fall | shrink     | Full tight     | Bearish, leverage pressure |
+| hold | flat | flat       | Neutral        | Watch marginal changes     |
+
+Auxiliary signals:
+
+- `shibor_quote` — short > long tenor = liquidity stress (inverted term structure)
+- `wz_index` — rising = private lending demand up / formal channels tightening
+
+### CN-US Spread Trade
+
+`treasury_cn`(limit=60) + `treasury_us`(limit=60) + `currency/price/historical`(symbol="USDCNH", limit=60, provider="massive")
+
+> **字段名注意:**
+>
+> - `treasury_cn` 返回: `yield_value` (收益率) + `curve_term` (期限: 1Y/2Y/5Y/10Y/30Y)
+> - `treasury_us` 返回: `y5`/`y7`/`y10`/`y20`/`y30` (各期限收益率，非通用 `yield` 字段)
+> - ⚠️ `treasury_us` 数据源待验证 — 部分返回值与中国国债收益率相似 (10Y≈1.80%)，跨境利差计算前请人工校验
+> - `currency/price/historical` 需添加 `provider="massive"` 以获取 FX 数据
+
+| 10Y Spread (CN-US) | FX impact        | Positioning                                      |
+| ------------------ | ---------------- | ------------------------------------------------ |
+| > +50bp            | CNH appreciation | OW CN govies, long CNH, northbound inflow        |
+| 0 to -50bp         | Neutral          | Hedge FX, favor exporters (weak CNH beneficiary) |
+| < -50bp            | CNH depreciation | UW CN duration, long USD/CNH                     |
+| < -100bp           | Strong outflow   | Max UW CN duration, watch PBOC OMO for floor     |
+
+### Shibor Term Structure
+
+`fin_macro(endpoint="shibor_quote")` → O/N < 1W < 1M < 3M = normal; O/N > 1W or 1M > 3M = inverted (liquidity stress)
+
+### Scenario Modeling (3-scenario)
+
+Data inputs: `gdp/real` + `cpi` + `pmi` + `money_supply`
+
+| Dimension | Bull        | Base            | Bear           |
+| --------- | ----------- | --------------- | -------------- |
+| GDP       | +0.5% above | Trend continues | -0.5% below    |
+| CPI       | Mild 2-3%   | Current level   | Deflation < 0% |
+| Equity    | +15-20%     | +5-10%          | -10-15%        |
+| Bonds 10Y | +20bp       | +/-10bp         | -30bp          |
+| Prob      | 25%         | 50%             | 25%            |
+
+Probability adjustment rules (each trigger shifts +10pp):
+
+- Bull: PMI > 51 x3mo | 社融 beat + M2 accel > 0.5pp | LPR cut + M1 inflection up
+- Bear: PMI < 49 x2mo + PPI deflation | external shock | CPI > 3% + PBOC net drain
+
+## Data Release Calendar
+
+| Indicator | Release             | Time  |
+| --------- | ------------------- | ----- |
+| PMI       | 1st of month        | 09:00 |
+| CPI/PPI   | 9th-12th            | 09:30 |
+| M2/SocFin | 10th-15th           | PM    |
+| GDP       | 15th-18th of Q+1 M1 | 10:00 |
+| LPR       | 20th                | 09:30 |
+
+## 高级宏观分析
+
+### M1-M2 剪刀差信号
+
+`fin_macro(endpoint="money_supply", limit=24)` → Compute M1_YoY - M2_YoY
+
+| M1-M2 Gap | Signal   | Interpretation                                 |
+| --------- | -------- | ---------------------------------------------- |
+| > 0       | 资金活化 | Funds flowing to enterprises, bullish equities |
+| 0 to -5pp | 中性     | Watch trend direction for inflection           |
+| < -5pp    | 资金沉淀 | Stuck in savings, bearish equities             |
+| Gap 收窄  | 边际改善 | Equity market bottom forming (1-2Q lead)       |
+
+### CPI-PPI 剪刀差 (利润分配信号)
+
+`fin_macro(endpoint="cpi", limit=12)` + `fin_macro(endpoint="ppi", limit=12)` → CPI_YoY - PPI_YoY
+
+| CPI-PPI Gap  | Sector implication                                         |
+| ------------ | ---------------------------------------------------------- |
+| PPI > CPI    | Upstream profits expand; midstream/consumer margin squeeze |
+| CPI > PPI    | Consumer brands + retail outperform; upstream deflation    |
+| Both rising  | Commodity longs, short duration bonds                      |
+| Both falling | Long duration bonds, defensive sectors                     |
+
+### 社融-GDP 领先关系 (信贷脉冲)
+
+`fin_macro(endpoint="social_financing", limit=24)` + `fin_macro(endpoint="gdp/real", limit=8)` — 信贷脉冲 = 社融增量的二阶导 (3 月移动平均增速的变化率)，领先 GDP 2-3Q:
+
+- 脉冲转正 (社融增速加速) + PMI > 50 → high confidence GDP recovery ahead
+- 脉冲转负 (社融增速减速) + M1 下行 → GDP 下行风险，提前减仓周期股
+
+### HIBOR-LIBOR 利差 (港元联系汇率压力)
+
+`fin_macro(endpoint="hibor", limit=60)` + `fin_macro(endpoint="libor", limit=60)` → match tenor (O/N, 1M, 3M)
+
+| HIBOR-LIBOR         | Implication                                          |
+| ------------------- | ---------------------------------------------------- |
+| HIBOR > LIBOR +50bp | HKMA draining liquidity, HK equities pressure        |
+| HIBOR ≈ LIBOR       | Peg functioning normally                             |
+| HIBOR < LIBOR -30bp | Hot money inflows to HK, watch property/equity rally |
+
+### World Bank 跨国对比
+
+`worldbank/gdp` + `worldbank/inflation` (country="CN"/"US"/"JP", limit=10) → 跨国周期对比
+
+- GDP 增速差扩大 → 资金流向高增长经济体
+- 通胀差异 → 预判各央行货币政策分化方向
+
+### 经济日历交易策略
+
+**PMI surprise**: `calendar` + `pmi`(limit=6) → actual - prior trend
+
+- surprise > +1.0 → A 股跳涨, 商品走强, 债券承压
+- surprise < -1.0 → 避险: 债券走强, A 股承压, 黄金受益
+
+**LPR 传导链**: `shibor_lpr`(limit=12) → LPR 下调 → 房贷利率降 → 地产改善 → 银行 NIM 压 → 消费回升
+
+- -10bp: 地产温和利好, 银行中性偏负 | -20bp+: 地产明确利好, 银行 NIM 压力
+
+**汇率干预识别**: `currency/snapshots` + `currency/price/historical`(symbol="USDCNH", limit=30)
+
+- CNH 单日升值 > 500 pips 且无基本面驱动 → 央行入场
+- 中间价连续 3 日强于模型预测 → 逆周期因子启动
+- 离岸 CNH 利率骤升 (via `hibor` O/N) → 抽紧离岸流动性打空头
+
+## Data Notes & Output Formatting
+
+- Tushare macro: 1-2h after release, not real-time | World Bank: annual, 6-12 month lag
+- Rates (Shibor/Libor/Hibor): daily on trading days | LPR: 20th monthly, deferred on holidays
+- `worldbank/indicator`: requires indicator code (see table above)
+- `shibor_quote`: per-bank quotes by tenor, for term structure | `wz_index`: shadow banking proxy
+- GDP: 6.1% (1 decimal) | CPI/PPI: YoY +2.3% (always label YoY/MoM)
+- Rates/Yields: 3 decimals | Money: 万亿元 | FX: 4 decimals | Spread: bp
+- Always note data publication date, not query date
+- Cycle positioning must state data time window; policy reads add "不构成投资建议"

package/skills/risk-monitor/skill.md

@@ -0,0 +1,171 @@
+---
+name: fin-risk-monitor
+description: "Risk monitoring dashboard — market regime detection, rate risk (Shibor/treasury spread), leverage risk (margin), foreign capital flows, macro warning signals. Orchestrates fin_data_regime + fin_macro + fin_market + fin_index. Use when: user asks about market risk assessment, stress signals, risk dashboard, or hedging recommendations. NOT for: trade decisions (use fin-a-share), macro cycle forecasting or positioning (use fin-macro)."
+metadata: { "openclaw": { "emoji": "🚨", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# Risk Monitor Dashboard
+
+综合使用 **fin_macro**、**fin_market**、**fin_index**、**fin_data_regime** 构建红/黄/绿三色信号体系，量化系统性风险。
+
+## 综合风险评分
+
+```
+综合风险分 = Sum(各维度风险分 x 权重)
+
+0-30: [G] 低风险 | 30-60: [Y] 中等风险 | 60-80: [R] 高风险 | 80-100: [R+] 极端风险
+```
+
+## 六大风险维度 — Endpoint 映射 + 阈值简表
+
+### 1. 市场体制 (Regime) — 权重 20%
+
+| 指标        | 工具调用                                                                              | [G]      | [Y]            | [R]         |
+| ----------- | ------------------------------------------------------------------------------------- | -------- | -------------- | ----------- |
+| Regime      | `fin_data_regime(symbol="000300.SH", market="equity")`                                | bull     | sideways       | bear/crisis |
+| 全市场快照  | `fin_market(endpoint="market_snapshots")` → 12000+ 记录，快速获取涨跌家数比、成交额等 | —        | —              | —           |
+| 涨跌家数比  | `fin_market(endpoint="discovery/gainers")` vs losers                                  | > 1.5    | 0.8-1.5        | < 0.8       |
+| 涨停/跌停比 | `fin_market(endpoint="market/limit_list")`                                            | > 2      | 1-2            | < 1         |
+| 成交额变化  | `fin_index(symbol="000300.SH", endpoint="price/historical")`                          | 0.8-1.5x | 1.5-2.5x/<0.5x | >2.5x(恐慌) |
+
+### 2. 利率与流动性 — 权重 20%
+
+| 指标             | 工具调用                             | [G]    | [Y]       | [R]    |
+| ---------------- | ------------------------------------ | ------ | --------- | ------ |
+| Shibor O/N       | `fin_macro(endpoint="shibor")`       | < 2.0% | 2.0%-3.0% | > 3.0% |
+| Shibor 期限结构  | `fin_macro(endpoint="shibor_quote")` | 正常   | 短端偏高  | 倒挂   |
+| 期限利差(10Y-1Y) | `fin_macro(endpoint="treasury_cn")`  | > 50bp | 20-50bp   | < 20bp |
+| M2 增速          | `fin_macro(endpoint="money_supply")` | > 10%  | 8%-10%    | < 8%   |
+
+### 3. 杠杆风险 — 权重 15%
+
+| 指标            | 工具调用                                         | [G]  | [Y]      | [R]          |
+| --------------- | ------------------------------------------------ | ---- | -------- | ------------ |
+| 融资余额总量    | `fin_market(endpoint="margin/summary")`          | 稳定 | 快速上升 | 急降(平仓潮) |
+| 融资余额5日变化 | `fin_market(endpoint="margin/summary", limit=5)` | < 3% | 3%-5%    | > 5%(急降)   |
+| 融资交易明细    | `fin_market(endpoint="margin/trading")`          | 正常 | 集中平仓 | 大面积平仓   |
+| 质押风险        | `fin_stock(endpoint="pledge/stat")` 抽样         | < 5% | 5%-10%   | > 10%        |
+
+### 4. 外资与跨境资金流 — 权重 15%
+
+| 指标           | 工具调用                                                                    | [G]      | [Y]       | [R]        |
+| -------------- | --------------------------------------------------------------------------- | -------- | --------- | ---------- |
+| 北向日净买入   | `fin_market(endpoint="flow/hsgt_flow")`                                     | > 0      | -50~0亿   | < -50亿    |
+| 北向5日累计    | `fin_market(endpoint="flow/hsgt_flow", limit=5)`                            | > 0      | -100~0亿  | < -100亿   |
+| 北向前十活跃股 | `fin_market(endpoint="flow/hsgt_top10")`                                    | 均匀分布 | 集中卖出  | 大面积卖出 |
+| 南向月度汇总   | `fin_market(endpoint="flow/ggt_monthly")` — 中长期南向资金趋势              | 稳定流入 | 波动      | 持续流出   |
+| 人民币汇率     | `fin_macro(endpoint="currency/price/historical", symbol="USDCNH", limit=5)` | < 0.5%   | > 0.5%/周 | > 1%/周    |
+
+### 5. 宏观经济 — 权重 15%
+
+| 指标      | 工具调用                                 | [G]   | [Y]        | [R]           |
+| --------- | ---------------------------------------- | ----- | ---------- | ------------- |
+| 制造业PMI | `fin_macro(endpoint="pmi")`              | > 51  | 49-51      | < 49          |
+| CPI 同比  | `fin_macro(endpoint="cpi")`              | 1%-3% | 0-1%/3%-5% | <0%(通缩)/>5% |
+| PPI 同比  | `fin_macro(endpoint="ppi")`              | 0%-3% | -3%-0%     | < -3%         |
+| 社融增速  | `fin_macro(endpoint="social_financing")` | > 10% | 8%-10%     | < 8%          |
+
+### 6. 市场情绪 — 权重 15%
+
+| 指标            | 工具调用                                                     | [G]       | [Y]           | [R]             |
+| --------------- | ------------------------------------------------------------ | --------- | ------------- | --------------- |
+| 换手率(沪深300) | `fin_index(symbol="000300.SH", endpoint="price/historical")` | 0.5%-1.5% | 1.5%-3%/<0.3% | >3%(狂热)/<0.2% |
+| 涨停数          | `fin_market(endpoint="market/limit_list")`                   | 30-80     | > 100(过热)   | < 10(极冷)      |
+| 龙虎榜机构净买  | `fin_market(endpoint="market/top_inst")`                     | 净买入    | 中性          | 净卖出          |
+| Regime          | `fin_data_regime(symbol="000300.SH", market="equity")`       | bull      | sideways      | bear/crisis     |
+
+## 补充数据源
+
+- `fin_market(endpoint="market_snapshots")` → 全市场实时快照 (12000+ 记录)，可快速获取涨跌家数比、成交额分布等，适合风险扫描的第一步。
+- `fin_market(endpoint="flow/ggt_monthly")` → 南向月度汇总，用于中长期南向资金趋势判断。
+- **注意**: `flow/ggt_top10` 端点在 DataHub 上超时不可用，南向数据请改用 `flow/ggt_daily` 或 `flow/ggt_monthly`。
+
+## 数据缺口替代方案
+
+### VIX 恐慌指数代理 (Composite Fear Index)
+
+无 CBOE VIX，三源合成: `fin_market(market/limit_list)` 跌停数D + `fin_data_regime(000300.SH)` regime R + `fin_index(000300.SH, price/historical)` 日振幅=(high-low)/close
+
+```
+VIX_proxy = 0.3*norm(D) + 0.4*regime_score(R) + 0.3*norm(振幅)
+  regime_score: bull=0, sideways=30, volatile=60, bear=75, crisis=100
+  norm(D): <10→0, 10-50→25, 50-100→50, 100-200→75, >200→100
+  norm(振幅): <1%→0, 1-2%→25, 2-3%→50, 3-5%→75, >5%→100
+  阈值: 0-25[G] | 25-55[Y] | 55-80[R] | >80[R+]
+```
+
+### 信用风险代理 (Credit Stress Proxy)
+
+无 AA-AAA 利差，三源合成: `fin_macro(shibor)` O/N值+日变化 + `fin_macro(shibor_quote)` 期限结构 + `fin_market(margin/summary)` 融资余额5日变化
+
+```
+Credit_stress = 0.4*shibor_score + 0.3*curve_score + 0.3*margin_score
+  shibor: O/N<2%→0, 2-3%→30, 3-5%→60, >5%→100; 单日跳升>50bp额外+20
+  curve: 正常→0, 平坦化→40, 倒挂→80, 深度倒挂(1W>3M+50bp)→100
+  margin: 5日变化<-3%→80(平仓潮), -1~-3%→40, 稳定→0
+  阈值: 0-30[G] | 30-60[Y] | 60-85[R] | >85[R+]
+```
+
+### 美联储利率预期
+
+`fin_macro(treasury_us)` 10Y-2Y 利差: 走阔→预期降息, 收窄/倒挂→预期加息/衰退, 10Y日变>10bp→重大信号
+
+## 风险传导链模型
+
+| 路径 | 链路 | 频率 | 升级触发 |
+|------|------|------|---------|
+| **A 外部冲击** | 美债↑(`treasury_us`) → CNH贬(`USDCNH`) → 北向流出(`hsgt_flow`) → 大宗联动(AU/SC) → A股承压 | 日频 | 10Y日变>10bp |
+| **B 去杠杆** | 监管收紧 → 融资降(`margin/summary`) → 杠杆平仓(`margin/trading`) → 质押风险(`pledge/stat`) → 连锁跌停 | 周频 | 融资连降3日 |
+| **C 流动性危机** | Shibor飙升(`shibor`) → 债券抛售(`treasury_cn`) → 利差异常 → 股债双杀 | 日频 | O/N>3% |
+
+## 风险情景预案
+
+| 情景 | 触发条件 | 行动 |
+|------|---------|------|
+| **A 美联储冲击** | 10Y 5日升>25bp + USDCNH周升>0.8% + 北向3日出>150亿 | 减成长至30%，增配高股息，IF空头对冲 |
+| **B 信用事件** | 融资10日降>8% + O/N>3.5% + 银行地产跌停>15 | 清仓金融地产，仓位<30%，增配国债ETF(511010.SH) |
+| **C 地缘冲突** | AU日涨>2% + SC日涨>5% + USDCNH 3日升>1% | 仓位30%，加配黄金/现金/短期国债 |
+| **D 钱荒** | O/N>5% + 大面积强平 + 跌停>200 + 10Y-1Y<10bp | 全清仓转现金。恢复: O/N<2.5% + 跌停<50 |
+
+## 尾部风险预警 (Perfect Storm)
+
+3+维度同时[R]触发: **N=3** 仓位降至40%，`fin_derivatives(futures/historical, IF主力)` 空头 + `options/basic` 认沽 | **N=4** 仓位20%，加配`AU主力`黄金 | **N>=5** 仓位0-10%全现金+国债，等2+维度回[Y]
+
+## 每日快速扫描 Pattern
+
+```
+Step 1: fin_market(endpoint="flow/hsgt_flow", limit=5)            → 北向资金
+Step 2: fin_macro(endpoint="shibor", limit=5)                     → 流动性
+Step 3: fin_index(symbol="000300.SH", endpoint="price/historical", limit=5)  → 市场趋势
+Step 4: fin_macro(endpoint="currency/price/historical", symbol="USDCNH", limit=5) → 汇率
+→ 快速红黄绿判定
+
+AUTO-ESCALATION (任一Step返回[R]):
+  Step 5: fin_data_regime(000300.SH) → 体制  Step 6: margin/summary → 杠杆
+  Step 7: market/limit_list → VIX代理  Step 8: shibor_quote → 信用代理
+  Step 9: pmi → 宏观前瞻 → 综合评分 → 匹配情景预案
+```
+
+**每周深度检查:** 六维度全量并行获取 → 加权打分+VIX_proxy/Credit_stress → 与上周对比边际变化 → 输出仪表盘
+
+## 对冲建议框架
+
+| 风险等级  | 仓位建议 | 对冲工具                                                  | 现金比例 |
+| --------- | -------- | --------------------------------------------------------- | -------- |
+| [G] 低    | 80-100%  | 无需对冲                                                  | 0-20%    |
+| [Y] 中等  | 60-80%   | `fin_derivatives(options/basic)` 认沽 / 减杠杆            | 20-40%   |
+| [R] 高    | 30-60%   | `fin_derivatives(futures/historical, IF主力)` 空头 + 认沽 | 40-70%   |
+| [R+] 极端 | 0-30%    | 全面对冲 + `AU主力` 黄金 + 国债ETF                        | 70-100%  |
+
+## 输出模板
+
+```
+============= 风险仪表盘 =============
+日期: YYYY-MM-DD | 综合风险分: XX/100 [Y]
+维度: 体制[G]25 流动性[Y]55 杠杆[G]30 外资[Y]50 宏观[Y]45 情绪[G]35
+代理: VIX_proxy XX[G/Y/R] | Credit_stress XX[G/Y/R]
+变化(vs上周): ^流动性+10 | v情绪-5
+情景: 无/A预警/D触发 | 尾部: N/6维度[R]
+行动建议: (工具+比例，注明数据截止日)
+==========================================
+```

package/skills/us-dividend/skill.md

@@ -0,0 +1,162 @@
+---
+name: fin-us-dividend
+description: "US dividend strategy — Aristocrat/Achiever/King classification, payout safety scoring, dividend yield vs Treasury spread, total shareholder yield (dividend + buyback), tax-adjusted yield for non-US investors, dividend portfolio construction. Use when: user asks about dividend stocks, passive income, payout safety, ex-dividend dates, or dividend vs bond yield. NOT for: single-stock fundamentals/valuation (use fin-us-equity), A-share dividends (use fin-a-share), crypto yield (use fin-crypto-defi), macro rates only (use fin-macro)."
+metadata: { "openclaw": { "emoji": "💰", "requires": { "extensions": ["findoo-datahub-plugin"] } } }
+---
+
+# US Dividend Strategy
+
+Specialized in systematic dividend investing: Aristocrat classification, payout sustainability scoring, yield-vs-Treasury comparison, and portfolio construction. Goes beyond fin-us-equity's basic dividend lookup with a full income-investing framework.
+
+## When to Use
+
+- "美股有哪些高股息股" / "Best US dividend stocks"
+- "JNJ 连续派息多少年" / "How many years has JNJ raised dividends"
+- "股息 vs 国债收益率哪个划算" / "Dividend yield vs Treasury yield comparison"
+- "T 的股息安全吗，会不会砍息" / "Is AT&T's dividend safe"
+- "10 万美元做股息投资，30 年后多少" / "DRIP simulation for $100K over 30 years"
+- "哪些是 Dividend Kings" / "List of Dividend Kings"
+- "非美国人买美股股息要交多少税" / "Dividend withholding tax for non-US investors"
+
+## When NOT to Use
+
+- 个股基本面/估值深度分析 (PE/DCF/财务报表) -> use `/fin-us-equity`
+- A 股/港股分红分析 -> use `/fin-a-share` / `/fin-hk-stock`
+- 财报 beat/miss / earnings season 分析 -> use `/fin-us-earnings`
+- 宏观利率/GDP/CPI (非 yield spread 对比) -> use `/fin-macro`
+- 加密货币 staking/yield farming -> use `/fin-crypto-defi`
+- 期权/期货/可转债 -> use `/fin-derivatives`
+
+## Tools & Parameters
+
+### fin_stock
+
+| Parameter  | Type   | Required | Format          | Default | Example               |
+| ---------- | ------ | -------- | --------------- | ------- | --------------------- |
+| symbol     | string | Yes      | US ticker       | —       | JNJ                   |
+| endpoint   | string | Yes      | see table below | —       | fundamental/dividends |
+| start_date | string | No       | YYYY-MM-DD      | —       | 2000-01-01            |
+| end_date   | string | No       | YYYY-MM-DD      | —       | 2026-03-07            |
+| limit      | number | No       | 1-5000          | 200     | 100                   |
+| provider   | string | No       | yfinance        | auto    | yfinance              |
+
+#### Endpoints
+
+| endpoint                | Description                       | Example                                                                     |
+| ----------------------- | --------------------------------- | --------------------------------------------------------------------------- |
+| `fundamental/dividends` | Full dividend history             | `fin_stock(symbol="JNJ", endpoint="fundamental/dividends", limit=100)`      |
+| `fundamental/ratios`    | Payout ratio, dividend yield, ROE | `fin_stock(symbol="JNJ", endpoint="fundamental/ratios")`                    |
+| `fundamental/cash`      | FCF for payout sustainability     | `fin_stock(symbol="JNJ", endpoint="fundamental/cash")`                      |
+| `fundamental/metrics`   | Market cap, EV/EBITDA             | `fin_stock(symbol="JNJ", endpoint="fundamental/metrics")`                   |
+| `us/income`             | EPS/Net income for coverage       | `fin_stock(symbol="JNJ", endpoint="us/income")`                             |
+| `price/historical`      | Total return calculation          | `fin_stock(symbol="JNJ", endpoint="price/historical", provider="yfinance")` |
+| `profile`               | Sector, industry classification   | `fin_stock(symbol="JNJ", endpoint="profile")`                               |
+
+### fin_macro
+
+| endpoint      | Description  | Example                             |
+| ------------- | ------------ | ----------------------------------- |
+| `treasury_us` | US 10Y yield | `fin_macro(endpoint="treasury_us")` |
+
+## Dividend Classification System
+
+| Tier              | Criteria                           | Examples                 |
+| ----------------- | ---------------------------------- | ------------------------ |
+| **Dividend King** | 50+ consecutive years of increases | JNJ, KO, PG, MMM, CL     |
+| **Aristocrat**    | 25+ years in S&P 500               | ABBV, ABT, PEP, XOM, MCD |
+| **Achiever**      | 10-24 consecutive years            | MSFT, AAPL, HD, V        |
+| **Not qualified** | <10 years or any cut/freeze        | (evaluate case by case)  |
+
+**Detection method:** `fundamental/dividends` with long history (limit=100+) -> calculate annual totals -> count consecutive YoY increases.
+
+## Dividend Analysis Pattern
+
+1. **Dividend history & classification** `fin_stock(endpoint="fundamental/dividends", symbol="JNJ", limit=100)` — Pull full dividend history
+   - Calculate annual dividend totals for each calendar year
+   - Count consecutive years of YoY increases -> classify as King/Aristocrat/Achiever
+   - Calculate 5-year dividend CAGR = (Latest annual / 5-years-ago annual)^(1/5) - 1
+   - ⚠️ If most recent annual dividend < prior year -> dividend was CUT, immediately flag as high risk
+   - ⚠️ If dividend growth rate declining (CAGR last 3Y < CAGR last 5Y) -> growth deceleration
+
+2. **Payout safety scoring** `fin_stock(endpoint="fundamental/ratios")` + `fin_stock(endpoint="fundamental/cash")` + `fin_stock(endpoint="us/income")` — Multi-factor safety assessment
+   - **Earnings payout ratio**: Dividends per share / EPS (from ratios or compute from income)
+   - **FCF payout ratio**: Total dividends / Free Cash Flow (from cash flow statement)
+   - **FCF coverage**: FCF / Total dividends (inverse of FCF payout)
+   - Safety score matrix:
+
+   | Factor             | Green (Safe) | Yellow (Watch) | Red (At Risk) |
+   | ------------------ | ------------ | -------------- | ------------- |
+   | Earnings payout    | < 60%        | 60-80%         | > 80%         |
+   | FCF payout         | < 70%        | 70-90%         | > 90%         |
+   | FCF coverage       | > 1.5x       | 1.0-1.5x       | < 1.0x        |
+   | Consecutive growth | 10+ years    | 5-9 years      | < 5 years     |
+   | Dividend CAGR 5Y   | > 5%         | 2-5%           | < 2%          |
+   - ⚠️ If earnings payout > 90% + FCF coverage < 1.0x -> **Yield Trap** alert: "High yield but dividend may be cut"
+   - ⚠️ If FCF has been negative for 2+ quarters -> dividend funded by debt, unsustainable
+   - 💡 Cross-validate: stable payout ratio + rising FCF = safest combination (growing into the payout)
+
+3. **Yield vs Treasury spread** `fin_macro(endpoint="treasury_us")` — Compare dividend yield to risk-free rate
+   - Spread = Dividend yield - 10Y Treasury yield
+   - ⚠️ If spread < 0% (Treasury wins) -> bonds offer better risk-free income, dividend case weakens unless growth justifies
+   - ⚠️ If spread > 2% -> attractive income premium, but verify it's not a yield trap (step 2)
+   - 💡 Historical context: S&P 500 average dividend yield ~1.5%, 10Y Treasury averages ~3.5%. When spread is unusually wide, one of them is mispriced
+
+4. **Total shareholder yield** `fin_stock(endpoint="fundamental/metrics")` + `fin_stock(endpoint="fundamental/cash")` — Dividend + Buyback
+   - Buyback yield = (Share repurchases from cash flow) / Market cap
+   - Total yield = Dividend yield + Buyback yield
+   - ⚠️ If total yield > 6% but debt/equity rising -> shareholder returns funded by leverage, not operations
+   - 💡 Mega-cap tech (AAPL/MSFT/META): buyback yield 3-5% dwarfs dividend yield <1%. Total yield is the true income metric
+
+5. **Tax-adjusted yield (non-US investors)** — Calculate after-tax income
+   - Default withholding: 30% on US dividends for non-US investors
+   - Treaty rate (China-US): 10% (with W-8BEN filing)
+   - After-tax yield = Gross yield \* (1 - withholding rate)
+   - ⚠️ REITs (e.g., O, VNQ): dividends taxed as ordinary income even for US investors, higher effective tax
+   - 💡 For Chinese investors: $1.00 dividend -> $0.70 after 30% withholding (no treaty) or $0.90 after 10% (with W-8BEN)
+
+6. **Portfolio construction** — When user wants to build a dividend portfolio
+   - **Sector diversification**: No more than 25% in any single sector
+   - **Yield tier stratification**: Mix high-yield (4%+, slower growth) + growth-yield (1-3%, faster CAGR)
+   - **Classic sectors**: Staples (PG/KO/PEP), Healthcare (JNJ/ABT/ABBV), Industrials (MMM/CAT), Utilities (SO/DUK)
+   - **DRIP simulation**: Given initial amount + monthly contribution + portfolio yield + dividend CAGR -> compound over N years
+     - Formula: FV = PV _ (1 + yield + growth)^N + PMT _ [((1 + r)^N - 1) / r] (simplified)
+   - 💡 A 3.5% yield growing at 7% CAGR doubles income in ~10 years (Rule of 72)
+
+## Data Notes
+
+- **Dividend history**: `fundamental/dividends` provides ex-date + amount per share. Long history available for established payers (50+ years for Kings).
+- **US quotes**: yfinance, ~15min delay. Use `provider="yfinance"` for `price/historical`.
+- **Payout ratio**: Some providers pre-compute; otherwise calculate from `us/income` (EPS) and `fundamental/dividends`.
+- **Aristocrat list**: No official list API. Classify by counting consecutive dividend increases from history data.
+- **Ex-dividend dates**: Available in `fundamental/dividends` history but no forward calendar. Use most recent ex-date + quarterly cadence to estimate next.
+- **Treasury yield**: `fin_macro(endpoint="treasury_us")` provides current and historical 10Y yield.
+- **Buyback data**: Derived from `fundamental/cash` (financing activities) and `fundamental/metrics` (market cap). Not a direct buyback amount field.
+
+## Response Guidelines
+
+### Dollar Format
+
+- Dividend per share: $1.24/quarter or $4.96/year (specify frequency)
+- Yield: 3.42% (2 decimal places)
+- Payout ratio: 58.3% (1 decimal place)
+- Market cap: $420.5B (use $B/$M shorthand)
+- Portfolio income: $3,800/year on $100K invested
+- Tax withholding: $0.30 per $1.00 dividend (30% rate)
+
+### Must Include
+
+- Data cutoff date ("Data as of 2026-03-07")
+- Consecutive years of dividend growth (the defining metric)
+- Payout safety assessment (Green/Yellow/Red)
+- Current yield vs 10Y Treasury yield spread
+- Tax note for non-US investors when discussing income
+- Dividend growth rate (5Y CAGR) alongside current yield
+
+### Display Format
+
+- Single stock dividend analysis -> sections: Classification | Safety Score | Yield vs Treasury | History Chart Description
+- Dividend screener/comparison -> table with columns: Ticker | Yield | CAGR 5Y | Payout Ratio | Safety | Consecutive Years
+- Portfolio construction -> sector allocation table + projected income schedule
+- DRIP simulation -> year-by-year table showing: Year | Portfolio Value | Annual Dividend | Yield-on-Cost
+- Yield trap warning -> prominent callout box with risk factors
+- Always end with: "Key consideration for this dividend strategy is..."