economic-calendar-fetcher

经济日历获取器

概述

从 Financial Modeling Prep（FMP）经济日历 API 获取即将发生的经济事件和数据发布信息。此技能可获取已安排的经济指标，包括央行货币政策决议、就业报告、通胀数据（CPI/PPI）、GDP 发布、零售销售、制造业数据，以及其他影响金融市场的重大事件。

此技能使用 Python 脚本查询 FMP API，并返回原始 JSON 或文本输出。随后，助手会筛选事件、评估市场影响，并为每个已安排的事件生成按时间顺序排列的 Markdown 报告。不会自动生成任何文件。

主要功能：

• 获取指定日期范围内的经济事件（最长 90 天）
• 支持灵活提供 API 密钥（环境变量或 CLI 参数）
• 按影响级别、国家或事件类型筛选（由助手执行筛选）
• 将筛选结果整理为结构化 Markdown 报告并进行影响分析（由助手生成，而非脚本生成）
• 默认查询接下来的 7 天，快速了解市场走势

数据来源：

• FMP 经济日历 API：https://financialmodelingprep.com/stable/economic-calendar（单数形式的“economic”）
• 覆盖主要经济体：US、EU、UK、日本、中国、加拿大、澳大利亚
• 事件类型：央行决议、就业、通胀、GDP、贸易、住房、调查
• 注意：FMP 已于 2025-08-31 完全停用旧版 api/v3/economic_calendar 端点，该端点现在会返回 403 Legacy Endpoint——请勿使用，包括将其用作备用方案。

何时使用此技能

用户提出以下请求时使用此技能：

1. 经济日历查询：

   • “本周有哪些经济事件即将发生？”
   • “显示未来两周的经济日历”
   • “下一次 FOMC 会议是什么时候？”
   • “下个月会发布哪些重要经济数据？”

2. 市场事件规划：

   • “本周我应该关注哪些市场动态？”
   • “近期是否会发布有重大影响的经济数据？”
   • “下一次就业报告 / CPI 发布 / GDP 报告是什么时候？”

3. 指定日期范围的请求：

   • “获取 1 月 1 日至 1 月 31 日的经济事件”
   • “2025 年第一季度的经济日历上有哪些安排？”

4. 特定国家的查询：

   • “显示下周美国经济数据的发布时间”
   • “安排了哪些 ECB 事件？”
   • “日本什么时候发布通胀数据？”

请勿将此技能用于：

• 过去的经济事件（历史分析请使用 market-news-analyst）
• 公司财报日历（此技能不涵盖财报）
• 实时市场数据或实时报价
• 技术分析或图表解读

前提条件

• FMP API 密钥（必需）：访问 https://financialmodelingprep.com 注册并获取免费密钥（每天 250 次请求）。通过 FMP_API_KEY 环境变量设置，或将密钥传递给脚本的 --api-key 参数。
• Python 3.10+：运行 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py 所必需。
• 无需第三方软件包：脚本仅使用 Python 标准库。

工作流

按照以下步骤获取并分析经济日历：

步骤 1：获取 FMP API 密钥

按以下优先顺序检查 API 密钥是否可用：

1. 推荐： 检查是否已设置 FMP_API_KEY 环境变量——这样可避免密钥出现在会话日志中
2. 可接受： 单次运行时使用 --api-key CLI 参数
3. 不推荐： 要求用户将密钥粘贴到聊天中——会话日志可能会保留密钥
4. 如果用户没有 API 密钥，请提供以下说明：
   • 访问 https://financialmodelingprep.com
   • 注册免费账户（每天最多 250 次请求）
   • 前往 API 仪表板获取密钥

用户交互示例：

User: "Show me economic events for next week"
Assistant: "I'll fetch the economic calendar. I'll use the FMP_API_KEY environment variable if it's set. Otherwise, please pass the key via --api-key when running the script."

第 2 步：确定日期范围

根据用户请求设置适当的日期范围：

默认（未指定具体日期）： 今天起 7 天 用户指定时段： 使用确切日期（验证格式：YYYY-MM-DD） 最长范围： 90 天（FMP API 的限制）

示例：

• “下周” → 今天至 7 天后
• “接下来两周” → 今天至 14 天后
• “2025 年 1 月” → 2025-01-01 至 2025-01-31
• “2025 年第 1 季度” → 2025-01-01 至 2025-03-31

验证日期范围：

• 确保开始日期 ≤ 结束日期
• 确保范围 ≤ 90 天
• 查询过去日期时发出警告

第 3 步：执行 API 获取脚本

使用适当的参数运行 get_economic_calendar.py 脚本：

基本用法（默认 7 天）：

python3 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py --api-key YOUR_KEY

指定日期范围：

python3 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py \
  --from 2025-01-01 \
  --to 2025-01-31 \
  --api-key YOUR_KEY \
  --format json

使用环境变量（无需 --api-key）：

export FMP_API_KEY=your_key_here
python3 skills/economic-calendar-fetcher/scripts/get_economic_calendar.py \
  --from 2025-01-01 \
  --to 2025-01-07

脚本参数：

• --from：开始日期（YYYY-MM-DD）- 默认值：今天
• --to：结束日期（YYYY-MM-DD）- 默认值：今天 + 7 天
• --api-key：FMP API 密钥（若已设置 FMP_API_KEY 环境变量则可省略）
• --format：输出格式（json 或 text）- 默认值：json
• --output：输出文件路径（可选，默认值：stdout）

处理错误和空结果：

• API 密钥无效 → 请用户验证密钥
• 超出速率限制（429）→ 建议等待或升级 FMP 套餐
• 端点受限（402 Payment Required）→ 脚本会明确报错，指出当前 FMP 订阅套餐不包含 Economic Calendar 端点。告知用户需要在 https://financialmodelingprep.com/ 升级 FMP 套餐——不要将其视为“零个事件”，也不要回退到旧版 v3 端点（该端点已于 2025-08-31 停用，并会返回 403 Legacy Endpoint）。
• 网络错误 → 检查网络连接并重新运行脚本
• 日期格式无效 → 提供正确的格式示例
• 对于合理的当前/未来日期范围，返回空列表 []： 根据当前脚本版本，API 返回空列表表示确实“没有事件”——现在，404 或端点受限响应会触发明确错误，而不会再被静默转换为 []。如果仍怀疑数据缺失，请重新验证日期范围和 API 密钥，而不要假设端点已损坏。

第 4 步：解析并筛选事件

处理脚本返回的 JSON 响应：

1. 解析事件数据： 从 API 响应中提取所有事件
2. 按需应用用户筛选条件：
   • 影响级别：“高”“中”“低”
   • 国家：“US”“EU”“JP”“CN”等
   • 事件类型：FOMC、CPI、Employment、GDP 等
   • 货币：USD、EUR、JPY 等

筛选示例：

• “仅显示高影响事件” → 筛选 impact == "High"
• “仅显示美国事件” → 筛选 country == "US"
• “央行决策” → 在事件名称中搜索 "Rate"、"Policy"、"FOMC"、"ECB"、"BOJ"

事件数据结构：

{
  "date": "2025-01-15 14:30:00",
  "country": "US",
  "event": "Consumer Price Index (CPI) YoY",
  "currency": "USD",
  "previous": 2.6,
  "estimate": 2.7,
  "actual": null,
  "change": null,
  "impact": "High",
  "changePercentage": null
}

步骤 5：评估市场影响

评估每个事件对市场的重要性：

影响级别分类（来自 FMP）：

• 高影响： 重大市场波动事件

  • FOMC 利率决议、ECB/BOJ 政策会议
  • 非农就业人数（NFP）、CPI、GDP
  • 市场盘中波动通常为 0.5-2% 或更高

• 中等影响： 影响显著，但波动较小

  • 零售销售、工业生产
  • PMI 调查、消费者信心
  • 住房数据、耐用品订单

• 低影响： 影响较小的指标

  • 每周初请失业金人数（极端情况除外）
  • 区域制造业调查
  • 次要拍卖结果

其他背景因素：

1. 当前市场敏感度：

   • 高通胀环境 → CPI/PPI 重要性上升
   • 经济衰退担忧 → 就业数据更加关键
   • 降息预期 → 央行会议至关重要

2. 意外可能性：

   • 比较预估值与前次读数
   • 预期变化较大 = 关注度更高
   • 共识不确定 = 潜在影响更大

3. 事件聚集：

   • 同一天发生多个相关事件 = 影响放大
   • 示例：CPI + 零售销售 + Fed 发言 = 影响极大的交易日

4. 前瞻性重要意义：

   • 该事件是否会影响央行即将作出的决策？
   • 这是初步读数还是最终读数？
   • 这项数据之后会修订吗？

步骤 6：生成输出报告

职责： 脚本输出原始 JSON 或文本。此步骤由助手使用脚本输出完成。不会自动生成 Markdown 文件；结果会显示在聊天中，并可根据要求保存到 reports/。

创建包含以下部分的结构化 Markdown 报告：

报告标题：

# Economic Calendar
**Period:** [Start Date] to [End Date]
**Report Generated:** [Timestamp]
**Total Events:** [Count]
**High Impact Events:** [Count]

事件列表（按时间顺序）：

对于每个事件，提供：

## [Date] - [Day of Week]

### [Event Name] ([Impact Level])
- **Country:** [Country Code] ([Currency])
- **Time:** [HH:MM UTC]
- **Previous:** [Value]
- **Estimate:** [Consensus Forecast]
- **Impact Assessment:** [Your analysis]

**Market Implications:**
[2-3 sentences on why this matters, what markets watch for, typical reaction patterns]

---

事件条目示例：

## 2025-01-15 - Wednesday

### Consumer Price Index (CPI) YoY (High Impact)
- **Country:** US (USD)
- **Time:** 14:30 UTC (8:30 AM ET)
- **Previous:** 2.6%
- **Estimate:** 2.7%
- **Impact Assessment:** Very High - Core inflation metric for Fed policy decisions

**Market Implications:**
CPI reading above estimate (>2.7%) likely strengthens hawkish Fed expectations, potentially pressuring equities and supporting USD. Reading at or below 2.7% could reinforce disinflation narrative and support risk assets. Options market pricing 1.2% S&P 500 move on release day.

---

摘要部分：

在末尾添加分析摘要：

## Key Takeaways

**Highest Impact Days:**
- [Date]: [Events] - [Combined impact rationale]
- [Date]: [Events] - [Combined impact rationale]

**Central Bank Activity:**
- [Summary of any scheduled Fed/ECB/BOJ meetings or speeches]

**Major Data Releases:**
- Employment: [NFP, Unemployment Rate dates]
- Inflation: [CPI, PPI dates]
- Growth: [GDP, Retail Sales dates]

**Market Positioning Considerations:**
[2-3 bullets on how traders might position around these events]

**Risk Events:**
[Highlight any particularly high-uncertainty or surprise-potential events]

筛选说明：

如果用户指定了筛选条件，请在顶部注明：

**Filters Applied:**
- Impact Level: High only
- Country: US
- Events shown: [X] of [Y] total events in date range

输出：

• 结果会显示在聊天中。不会自动生成文件。
• 如需保存原始 JSON/文本数据：运行脚本时使用 --output reports/economic_calendar_[START]_to_[END].json。
• 如需保存 Markdown 报告：在聊天中生成报告后，请助手将其写入 reports/。

助手生成的报告格式

Markdown 结构要求：

1. 按时间顺序排列： 按日期和时间对事件排序（由早到晚）
2. 影响级别标记： 使用 (High Impact)、(Medium Impact)、(Low Impact) 标签
3. 明确时区： 始终注明 UTC；ET/PT 时间转换由助手根据美国夏令时日历完成
4. 数据完整性： 包含所有可用字段（过去事件的前次值、预估值和实际值）
5. 空值处理： 对空值显示“N/A”或“无预估值”
6. 影响评估： 所有高影响/中等影响事件都必须包含市场影响分析

表格格式选项（适用于密集列表）：

| Date/Time (UTC) | Event | Country | Impact | Previous | Estimate | Assessment |
|-----------------|-------|---------|--------|----------|----------|------------|
| 01-15 14:30 | CPI YoY | US | High | 2.6% | 2.7% | Core inflation metric |

语言： 所有报告均使用英文

资源

Python 脚本：

• skills/economic-calendar-fetcher/scripts/get_economic_calendar.py：主 API 获取脚本，带有 CLI 接口

参考文档：

• references/fmp_api_documentation.md：完整的 FMP 经济日历 API 参考
  • 身份验证和 API 密钥管理
  • 请求参数和日期格式
  • 响应字段定义
  • 速率限制和错误处理
  • 缓存和提高效率的最佳实践

API 详情：

• 主要端点：https://financialmodelingprep.com/stable/economic-calendar（使用单数形式的 “economic”；复数形式的 economics-calendar 是已失效的 URL，会返回 404）
• 旧版端点已停用：FMP 于 2025-08-31 关闭了 https://financialmodelingprep.com/api/v3/economic_calendar，现在会返回 403 Legacy Endpoint。请勿使用或回退到该端点。
• 受限端点注意事项：稳定版经济日历端点可能需要付费 FMP 订阅等级。如果 API 密钥没有相应权限，端点会返回 402 Payment Required；脚本会将其显示为明确错误，而不是返回空列表。
• 日期范围注意事项：响应可能包含请求的 from/to 时间范围以外的行；获取后请按解析后的 date 在本地筛选事件，确保只报告请求日期范围内的事件。
• 身份验证：需要 API 密钥（免费等级：每天 250 次请求）
• 最大日期范围：每次请求 90 天
• 响应格式：事件对象组成的 JSON 数组
• 速率限制：每秒 5 次请求（免费等级）

事件覆盖范围：

• 主要经济体：美国、欧盟、英国、日本、中国、加拿大、澳大利亚、瑞士
• 事件类别：货币政策、就业、通胀、GDP、贸易、住房、调查
• 更新频率：实时（按计划添加/更新事件）
• 历史数据：提供已发生事件的实际值

使用提示：

1. 缓存结果以尽量减少 API 调用（事件一经安排便很少变动）
2. 查询 7-30 天的范围，以获得最佳请求效率
3. 不要查询超过未来 6 个月的日期（数据稀疏，日期带有推测性）
4. 每天刷新未来一周的缓存，以捕获时间变动
5. 使用较短的范围（1-7 天）监控实时事件

错误处理：

• 格式错误的事件行、缺失或重命名的字段、类型变更、无效的 UTC 事件时间戳以及非有限读数，都会在格式化或打开输出文件之前导致失败。Stderr 中会包含 ZERO_RESULT_REASON=economic_calendar_schema_drift；退出代码为 1。支持正常的 null 读数，且 "None" 是有效的提供方字符串。
• 提供方返回空数组表示未经验证，并不能证明没有安排事件：Stderr 中会包含 ZERO_RESULT_REASON=empty_calendar_unverified；退出代码为 1，且会保留任何现有输出文件。写入日历无事件报告前，请检查提供方和日期范围。
• 获取失败时会输出 ZERO_RESULT_REASON=calendar_fetch_failed 并以代码 1 退出。这包括 HTTP/等级/网络故障，以及生成的客户端的一般失败情况（经过有限次数重试后仍返回 HTTP-200 null 或无效 JSON）。非 null 的非数组 JSON 响应属于架构漂移。错误诊断信息会删去 API 密钥；不会打印格式错误的事件值。
• API 密钥错误：提供获取免费密钥的清晰指引
• 速率限制（429）：建议等待或升级 FMP 等级；等待后重新运行脚本
• 受限端点（402）：脚本会引发明确错误，指出 FMP 订阅等级无权访问此端点；请引导用户前往 https://financialmodelingprep.com/ 升级。请勿回退到已停用的 v3 旧版端点（于 2025-08-31 停用，返回 403）。
• 网络故障：显示清晰的 Network error: ... 消息并重新运行；单次 429 重试、超时和每次调用的速率限制由随附的生成版 fmp_client.py 处理（Issue #495）
• 真正的 404：脚本现在会引发错误，而不是静默返回空列表；请进行调查，不要假定事件数为零。
• 无效日期：验证时提供有帮助的错误消息