国家外储查询（SAFE 官方储备资产）
从国家外汇管理局（SAFE）官网抓取《官方储备资产》数据，生成一份自包含 HTML：KPI 环比卡片、可交互趋势图（支持双轴·黄金）、最新月构成环形图、可折叠完整数据表。黄金同时给出市值（亿美元/亿SDR）与实物持有量（吨）。
一、快速用法
一句话上手：告诉它“看国家外储 / 外汇储备最新数据 / 黄金储备多少吨 / SAFE 官方储备资产”，由智能体运行脚本并交付 HTML。
直接运行（默认输出到当前目录 safe_reserve_assets.html）：
python3 scripts/fetch_safe_reserve.py
指定输出路径：
python3 scripts/fetch_safe_reserve.py --out /path/to/safe_reserve_assets.html
仅查看缓存 / 抓取状态（不生成 HTML）：
python3 scripts/fetch_safe_reserve.py --print-status
强制无视缓存、全量重抓（用于数据源异常或链接变更时）：
python3 scripts/fetch_safe_reserve.py --force
二、参数速查
| 参数 | 说明 |
|---|---|
--out 路径.html |
输出 HTML 路径，默认 ./safe_reserve_assets.html |
--force |
忽略本地缓存，全量重新抓取 SAFE |
--print-status |
仅打印缓存命中 / 抓取状态后退出，不落盘 HTML |
三、输出 HTML 的能力
- KPI 环比卡片：外汇储备、黄金·持有量（吨）、特别提款权、官方储备资产合计——每张卡都带环比（▲/▼ ±绝对变化（±百分比%）），按中国习惯涨红跌绿；黄金卡固定以吨为单位。
- 趋势图（三种视图）：
分项折线/累计堆叠/双轴·黄金。双轴模式下左右轴各自按数据范围缩放，黄金（吨）的起伏被明显放大，不再被外汇储备数量级压平；折线视图下把黄金切到“吨”也会自动走独立右轴。悬停显示各月明细，图例可显隐科目。 - 计价 / 单位切换：
亿美元 / 亿SDR一键切换；黄金·亿美元 / 黄金·吨切换（仅作用于黄金）。 - 构成环形图：最新月各科目占比，悬停看金额与百分比，点击图例联动趋势图显隐。
- 可折叠数据表：全部科目 × 全部月份明细，含亿美元、亿SDR、吨(持有量)三套单位。
四、缓存机制（基于日期判断是否过期）
- 抓取结果落盘到技能目录
cache/safe_reserve_cache.json，含cached_at、latest_month、xlsx_url与完整解析数据。 - SAFE 通常于每月上旬（约 7-10 日）发布上月数据。脚本据此推算“预期最新月份”：
- 若
today.day >= 10→ 预期上月；否则预期上上月（含跨年处理）。 - 若缓存
latest_month >= 预期最新月份→ 命中缓存、跳过网络，直接读盘生成 HTML。 - 否则抓取最新年份 xlsx解析，与既有缓存（如往年数据）合并后落盘；如需彻底重抓用
--force。 - 解析不依赖 pandas/openpyxl，使用标准库
zipfile + xml直接读 xlsx，便于分发与离线运行。
五、关键字段（官方储备资产科目）
| 科目 | 说明 |
|---|---|
| 外汇储备 | 头条指标，亿美元 / 亿SDR 双计价 |
| 基金组织储备头寸 | IMF reserve position |
| 特别提款权 (SDR) | SDR allocations |
| 黄金 | 市值（亿美元/亿SDR）+ 持有量（万盎司 → 吨，1 万盎司 ≈ 0.3110 吨） |
| 其他储备资产 | 轧差项，可为负值 |
| 官方储备资产合计 | = 各科目之和（KPI/环形图取非负项合计） |
六、注意事项与边界
- 数据月度发布，非日度；看变化应看环比（MoM）而非水平值。
- 双计价：亿美元与亿SDR 是同一数据的两种计价，并非两笔钱；黄金市值是重估值，随金价波动，与“吨(持有量)”口径不同。
- SAFE 无稳定公开 JSON API：xlsx 下载链接带内容哈希，脚本从官网索引页自动发现，并内置
KNOWN_XLSX兜底；若链接随发布变更导致发现失败，需更新KNOWN_XLSX或重跑--force。 - 跨年历史数据会在缓存中逐年累积；首次运行只含最新年份，欲更长周期可保留缓存多次运行或
--force后扩展KNOWN_XLSX。 - 数据版权归国家外汇管理局，引用须注明来源，勿直接再分发原始文件。
- 绝不：不使用第三方未核实数据源冒充 SAFE；不臆造历史口径；不重新分发原始版权数据。
