economic-calendar-fetcher

经济日历获取器

概述

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

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

主要功能：

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

数据来源：

• FMP Economic Calendar API：https://financialmodelingprep.com/api/v3/economic_calendar
• 覆盖主要经济体：US、EU、UK、Japan、China、Canada、Australia
• 事件类型：央行决策、就业、通胀、GDP、贸易、住房、调查

何时使用本技能

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

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 年第一季度” → 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 套餐
• 网络错误 → 检查连接并重新运行脚本
• 日期格式无效 → 提供正确的格式示例

步骤 4：解析和筛选事件

处理脚本返回的 JSON 响应：

1. 解析事件数据： 从 API 响应中提取所有事件
2. 应用用户指定的筛选条件：
   • 影响级别：“High”“Medium”“Low”
   • 国家：“US”“EU”“JP”“CN”等
   • 事件类型：FOMC、CPI、就业、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 + 零售销售 + 美联储讲话 = 影响极大的日子

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. 影响级别指标： 使用 (高影响)、(中等影响)、(低影响) 标签
3. 时区清晰明确： 始终注明 UTC；ET/PT 时间换算由助手根据美国夏令时日历完成
4. 数据完整性： 包含所有可用字段（若为过去的事件，则包含 previous、estimate、actual）
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 Economic Calendar API 参考文档
  • 身份验证和 API 密钥管理
  • 请求参数和日期格式
  • 响应字段定义
  • 速率限制和错误处理
  • 缓存与效率最佳实践

API 详情：

• 端点：https://financialmodelingprep.com/api/v3/economic_calendar
• 身份验证：需要 API 密钥（免费套餐：每天 250 次请求）
• 最大日期范围：每次请求 90 天
• 响应格式：事件对象的 JSON 数组
• 速率限制：每秒 5 次请求（免费套餐）

事件覆盖范围：

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

使用提示：

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

错误处理：

• API 密钥错误：清晰指导用户如何获取免费密钥
• 速率限制（429）：建议等待或升级 FMP 套餐；等待后重新运行脚本
• 网络故障：检查连接并重新运行；脚本不会自动重试或缓存
• 无效日期：通过清晰易懂的错误消息进行验证