介绍
# Earnings Calendar
## 概述
本技能使用 Financial Modeling Prep (FMP) API 获取美国股票的即将发布的财报公告。它专注于具有显著市值（中盘股及以上，超过 20 亿美元）且可能影响市场走势的公司。该技能生成结构化的 Markdown 报告，显示未来一周有哪些公司发布财报，并按日期和时间（盘前、盘后或时间未公布）进行分组。
**核心功能**： - 使用 FMP API 获取可靠、结构化的财报数据 - 按市值过滤（>20 亿美元）以专注于影响市场的公司 - 包含每股收益（EPS）和营收预估 - 多环境支持（CLI、桌面端、Web） - 灵活的 API 密钥管理 - 按日期、时间和市值整理
## 前置条件
### FMP API 密钥
本技能需要一个 Financial Modeling Prep API 密钥。
**获取免费 API 密钥**： 1. 访问：https://site.financialmodelingprep.com/developer/docs 2. 注册免费账户 3. 立即获取 API 密钥 4. 免费层级：每天 250 次 API 调用（足以满足每周财报日历需求）
**按环境设置 API 密钥**：
**Claude Code (CLI)**： ```bash export FMP_API_KEY="your-api-key-here" ```
**Claude 桌面端**： 在系统中设置环境变量或配置 MCP 服务器。
**Claude Web**： 将在技能执行期间请求 API 密钥（仅存储用于当前会话）。
## 核心工作流程
### 步骤 1：获取当前日期并计算目标周
**关键**：始终先获取准确的当前日期。
获取当前日期和时间： - 使用系统日期/时间获取今天的日期 - 注意：“今天的日期”在环境（<env> 标签）中提供 - 计算目标周：从当前日期开始的未来 7 天
**日期范围计算**： ``` Current Date: [e.g., November 2, 2025] Target Week Start: [Current Date + 1 day, e.g., November 3, 2025] Target Week End: [Current Date + 7 days, e.g., November 9, 2025] ```
**为何重要**： - 财报日历具有时效性 - “下周”必须根据实际当前日期计算 - 为 API 请求提供准确的日期范围
请将日期格式化为 YYYY-MM-DD 以兼容 API。
### 步骤 2：加载 FMP API 指南
在检索数据之前，加载全面的 FMP API 指南：
``` Read: references/fmp_api_guide.md ```
该指南包含： - FMP API 端点结构和参数 - 身份验证要求 - 市值过滤策略（通过公司概况 API） - 财报时间约定（BMO、AMC、TAS） - 响应格式和字段描述 - 错误处理策略 - 最佳实践和优化技巧
### 步骤 3：API 密钥检测和配置
根据环境检测 API 密钥的可用性。
**多环境 API 密钥检测**：
#### 3.1 检查环境变量（CLI/桌面端）
```bash if [ ! -z "$FMP_API_KEY" ]; then echo "✓ API key found in environment" API_KEY=$FMP_API_KEY fi ```
如果设置了环境变量，请继续执行步骤 4。
#### 3.2 提示用户输入 API 密钥（桌面端/Web）
如果未找到环境变量，请使用 AskUserQuestion 工具：
**问题配置**： ``` Question: "This skill requires an FMP API key to retrieve earnings data. Do you have an FMP API key?" Header: "API Key" Options: 1. "Yes, I'll provide it now" → Proceed to 3.3 2. "No, get free key" → Show instructions (3.2.1) 3. "Skip API, use manual entry" → Jump to Step 8 (fallback mode) ```
**3.2.1 如果用户选择“不，获取免费密钥”**：
提供说明： ``` To get a free FMP API key:
1. Visit: https://site.financialmodelingprep.com/developer/docs 2. Click "Get Free API Key" or "Sign Up" 3. Create account (email + password) 4. Receive API key immediately 5. Free tier includes 250 API calls/day (sufficient for daily use)
Once you have your API key, please select "Yes, I'll provide it now" to continue. ```
#### 3.3 请求 API 密钥输入
如果用户有 API 密钥，请求输入：
**提示**： ``` Please paste your FMP API key below:
(Your API key will only be stored for this conversation session and will be forgotten when the session ends. For regular use, consider setting the FMP_API_KEY environment variable.) ```
**将 API 密钥存储在会话变量中**： ``` API_KEY = [user_input] ```
**与用户确认**： ``` ✓ API key received and stored for this session.
Security Note: - API key is stored only in current conversation context - Not saved to disk or persistent storage - Will be forgotten when session ends - Do not share this conversation if it contains your API key
Proceeding with earnings data retrieval... ```
### 步骤 4：通过 FMP API 获取财报数据
使用 Python 脚本从 FMP API 获取财报数据。
**脚本位置**： ``` scripts/fetch_earnings_fmp.py ```
**执行**：
**选项 A：使用环境变量（CLI）**： ```bash python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 ```
**选项 B：使用会话 API 密钥（桌面端/Web）**： ```bash python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}" ```
**脚本工作流程**（自动）： 1. 验证 API 密钥和日期参数 2. 调用 FMP 财报日历 API 获取日期范围数据 3. 获取公司概况（市值、板块、行业） 4. 筛选市值 >20 亿美元的公司 5. 标准化时间（BMO/AMC/TAS） 6. 按日期 → 时间 → 市值（降序）排序 7. 将 JSON 输出到 stdout
**预期输出格式**（JSON）： ```json [ { "symbol": "AAPL", "companyName": "Apple Inc.", "date": "2025-11-04", "timing": "AMC", "marketCap": 3000000000000, "marketCapFormatted": "$3.0T", "sector": "Technology", "industry": "Consumer Electronics", "epsEstimated": 1.54, "revenueEstimated": 123400000000, "fiscalDateEnding": "2025-09-30", "exchange": "NASDAQ" }, ... ] ```
**保存到文件**（推荐用于配合报表生成器使用）： ```bash python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}" > earnings_data.json ```
或捕获到变量： ```bash earnings_data=$(python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}") ```
**错误处理**：
如果脚本返回错误： - **401 Unauthorized**：无效的 API 密钥 → 验证密钥或重新输入 - **429 Rate Limit**：超过每天 250 次调用 → 等待或升级套餐 - **Empty Result**：日期范围内无财报 → 扩大日期范围或在报告中注明 - **Connection Error**：网络问题 → 重试或使用缓存数据（如果有）
### 步骤 5：处理和整理数据
一旦获取到财报数据（JSON 格式），请处理并整理它：
#### 5.1 解析 JSON 数据
从脚本输出加载 JSON 数据： ```python import json earnings_data = json.loads(earnings_json_string) ```
或者如果已保存到文件： ```python with open('earnings_data.json', 'r') as f: earnings_data = json.load(f) ```
#### 5.2 验证数据结构
确认数据包含必需字段： - ✓ symbol（代码） - ✓ companyName（公司名称） - ✓ date（日期） - ✓ timing（时间 BMO/AMC/TAS） - ✓ marketCap（市值） - ✓ sector（板块）
#### 5.3 按日期分组
按日期对所有财报公告进行分组： - 星期日，[完整日期]（如果适用） - 星期一，[完整日期] - 星期二，[完整日期] - 星期三，[完整日期] - 星期四，[完整日期] - 星期五，[完整日期] - 星期六，[完整日期]（如果适用）
#### 5.4 按时间子分组
在每个日期内，创建三个子部分： 1. **盘前交易前 (BMO)** 2. **盘后交易后 (AMC)** 3. **时间未公布 (TAS)**
数据已按脚本输出的时间排序，因此请保持此顺序。
#### 5.5 在每个时间组内
公司已按市值降序排列（脚本输出）： - 超大盘股（>2000 亿美元）在前 - 大盘股（100 亿-2000 亿美元）其次 - 中盘股（20 亿-100 亿美元）再次
这种优先级排序确保列出最能影响市场的公司。
#### 5.6 计算汇总统计数据
计算： - **公司总数**：数据集中所有公司的计数 - **超大盘/大盘股数量**：marketCap >= 100 亿美元的计数 - **中盘股数量**：marketCap 在 20 亿到 100 亿美元之间的计数 - **高峰日**：财报公告最多的星期几 - **板块分布**：按板块计数（科技、医疗保健、金融等） - **最高市值公司**：按市值排名的前 5 家公司
### 步骤 6：生成 Markdown 报告
使用报表生成脚本从 JSON 数据创建格式化的 Markdown 报告。
**脚本位置**： ``` scripts/generate_report.py ```
**执行**：
**选项 A：输出到 stdout**： ```bash python scripts/generate_report.py earnings_data.json ```
**选项 B：保存到文件**： ```bash python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md ```
**脚本功能**： 1. 从 JSON 文件加载财报数据 2. 按日期和时间分组（BMO/AMC/TAS） 3. 在每个组内按市值排序 4. 计算汇总统计数据 5. 生成格式化的 Markdown 报告 6. 输出到 stdout 或保存到文件
该脚本会自动处理所有格式，包括： - 正确的 Markdown 表格结构 - 日期分组和星期名称 - 市值排序 - EPS 和营收格式化 - 汇总统计计算
**报告结构**：
```markdown # Upcoming Earnings Calendar - Week of [START_DATE] to [END_DATE]
**Report Generated**: [Current Date] **Data Source**: FMP API (Mid-cap and above, >$2B market cap) **Coverage Period**: Next 7 days **Total Companies**: [COUNT]
---
## Executive Summary
- **Total Companies Reporting**: [TOTAL_COUNT] - **Mega/Large Cap (>$10B)**: [LARGE_CAP_COUNT] - **Mid Cap ($2B-$10B)**: [MID_CAP_COUNT] - **Peak Day**: [DAY_WITH_MOST_EARNINGS]
---
## [Day Name], [Full Date]
### Before Market Open (BMO)
| Ticker | Company | Market Cap | Sector | EPS Est. | Revenue Est. | |--------|---------|------------|--------|----------|--------------| | [TICKER] | [COMPANY] | [MCAP] | [SECTOR] | [EPS] | [REV] |
### After Market Close (AMC)
| Ticker | Company | Market Cap | Sector | EPS Est. | Revenue Est. | |--------|---------|------------|--------|----------|--------------| | [TICKER] | [COMPANY] | [MCAP] | [SECTOR] | [EPS] | [REV] |
### Time Not Announced (TAS)
| Ticker | Company | Market Cap | Sector | EPS Est. | Revenue Est. | |--------|---------|------------|--------|----------|--------------| | [TICKER] | [COMPANY] | [MCAP] | [SECTOR] | [EPS] | [REV] |
---
[Repeat for each day of week]
---
## Key Observations
### Highest Market Cap Companies This Week 1. [COMPANY] ([TICKER]) - [MCAP] - [DATE] [TIME] 2. [COMPANY] ([TICKER]) - [MCAP] - [DATE] [TIME] 3. [COMPANY] ([TICKER]) - [MCAP] - [DATE] [TIME]
### Sector Distribution - **Technology**: [COUNT] companies - **Healthcare**: [COUNT] companies - **Financial**: [COUNT] companies - **Consumer**: [COUNT] companies - **Other**: [COUNT] companies
### Trading Considerations - **Days with Heavy Volume**: [DATES with multiple large-cap earnings] - **Pre-Market Focus**: [BMO companies that may move markets] - **After-Hours Focus**: [AMC companies that may move markets]
---
## Timing Reference
- **BMO (Before Market Open)**: Announcements typically around 6:00-8:00 AM ET before market opens at 9:30 AM ET - **AMC (After Market Close)**: Announcements typically around 4:00-5:00 PM ET after market closes at 4:00 PM ET - **TAS (Time Not Announced)**: Specific time not yet disclosed - monitor company investor relations
---
## Data Notes
- **Market Cap Categories**: - Mega Cap: >$200B - Large Cap: $10B-$200B - Mid Cap: $2B-$10B
- **Filter Criteria**: This report includes companies with market cap $2B and above (mid-cap+) with earnings scheduled for the next week.
- **Data Source**: Financial Modeling Prep (FMP) API
- **Data Freshness**: Earnings dates and times can change. Verify critical dates through company investor relations websites for the most current information.
- **EPS and Revenue Estimates**: Analyst consensus estimates from FMP API. Actual results will be reported on earnings date.
---
## Additional Resources
- **FMP API Documentation**: https://site.financialmodelingprep.com/developer/docs - **Seeking Alpha Calendar**: https://seekingalpha.com/earnings/earnings-calendar - **Yahoo Finance Calendar**: https://finance.yahoo.com/calendar/earnings
---
*Report generated using FMP Earnings Calendar API with mid-cap+ filter (>$2B market cap). Data current as of report generation time. Always verify earnings dates through official company sources.* ```
**格式化最佳实践**： - 使用 Markdown 表格进行清晰展示 - 如果需要，加粗重要的公司名称（超大盘股） - 包含人类可读格式的市值（$3.0T、$150B、$5.2B）——已由脚本格式化 - 按日期然后按时间逻辑分组 - 在顶部包含摘要部分以便快速概览 - 如果可用，添加 EPS 和营收预估
### 步骤 7：质量保证
在定稿报告之前，请验证：
**数据质量检查**： 1. ✓ 所有日期都落在目标周内（未来 7 天） 2. ✓ 所有公司都存在市值值 3. ✓ 每个公司都指定了时间（BMO/AMC/TAS） 4. ✓ 公司在每个部分内按市值排序 5. ✓ 汇总统计数据准确 6. ✓ 明确说明报告生成日期 7. ✓ 包含可用的 EPS 和营收预估
**完整性检查**： 1. ✓ 包含目标周的所有天数（即使没有财报） 2. ✓ 没有遗漏主要知名公司（如需要，与外部来源核实） 3. ✓ 包含可用的板块信息 4. ✓ 存在时间参考部分 5. ✓ 注明数据来源（FMP API）
**格式检查**： 1. ✓ Markdown 表格格式正确 2. ✓ 日期格式一致 3. ✓ 市值使用一致单位（B 代表十亿，T 代表万亿） 4. ✓ 所有部分遵循模板结构 5. ✓ 没有占位符文本（[PLACEHOLDER]）保留 6. ✓ EPS 和营收预估格式正确
### 步骤 8：保存并交付报告
使用适当的文件名保存生成的报告：
**文件名约定**： ``` earnings_calendar_[YYYY-MM-DD].md ```
示例：`earnings_calendar_2025-11-02.md`
文件名日期表示报告生成日期，而不是财报周。
**交付**： - 将 Markdown 文件保存到工作目录 - 通知用户报告已生成 - 提供主要发现的简要摘要（例如，“下周 45 家公司发布财报，苹果和微软在周一”）
**示例摘要**： ``` ✓ Earnings calendar report generated: earnings_calendar_2025-11-02.md
Summary for week of November 3-9, 2025: - 45 companies reporting earnings - 28 large/mega-cap, 17 mid-cap - Peak day: Thursday (15 companies) - Notable: Apple (Mon AMC), Microsoft (Tue AMC), Tesla (Wed AMC)
Top 5 by market cap: 1. Apple - $3.0T (Mon AMC) 2. Microsoft - $2.8T (Tue AMC) 3. Alphabet - $1.8T (Thu AMC) 4. Amazon - $1.6T (Fri AMC) 5. Tesla - $800B (Wed AMC) ```
## 备用模式（步骤 8 的替代方案）：手动数据输入
如果无法访问 API 或用户选择跳过 API：
**提供手动输入说明**：
``` Since FMP API is not available, you can manually gather earnings data:
1. Visit Finviz: https://finviz.com/screener.ashx?v=111&f=cap_midover%2Cearningsdate_nextweek 2. Or Yahoo Finance: https://finance.yahoo.com/calendar/earnings 3. Note down companies reporting next week
Please provide the following information for each company: - Ticker symbol - Company name - Earnings date - Timing (BMO/AMC/TAS) - Market cap (approximate) - Sector
I will format this into the standard earnings calendar report. ```
**处理手动输入**： 1. 解析用户提供的财报数据 2. 按日期、时间和市值整理 3. 使用相同的模板生成报告 4. 在报告中注明：“数据来源：手动输入”
## 用例和示例
### 用例 1：每周回顾（主要用例）
**用户请求**：“获取下周的财报日历”
**工作流程**： 1. 获取当前日期（例如，2025 年 11 月 2 日） 2. 计算目标周（2025 年 11 月 3 日至 9 日） 3. 加载 FMP API 指南 4. 检测/请求 API 密钥 5. 获取财报数据： ```bash python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json ``` 6. 生成 Markdown 报告： ```bash python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md ``` 7. 向用户通知摘要
**完整的一行命令**： ```bash python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json && \ python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md ```
### 用例 2：专注于特定日期
**用户请求**：“周一有哪些财报发布？”
**工作流程**： 1. 获取当前日期并确定下一个周一（例如，2025 年 11 月 4 日） 2. 获取整周数据（与用例 1 相同） 3. 生成完整报告，但突出显示周一部分 4. 提供周一财报的口头摘要并强调重点
### 用例 3：专注于超大盘股
**用户请求**：“显示下周市值超过 1000 亿美元的公司财报”
**工作流**： 1. 获取完整的财报数据（脚本已过滤超过 20 亿美元的公司） 2. 按常规方式处理和组织 3. 生成报告时，在顶部添加“大盘股聚焦”部分 4. 过滤表格，仅显示市值超过 1000 亿美元的公司 5. 注意：在附录中仍包含完整数据以供参考
### 用例 4：特定行业
**用户请求**：“下周有哪些科技公司发布财报？”
**工作流**： 1. 获取完整的财报数据 2. 按常规方式处理和组织 3. 按行业 = “科技”过滤结果 4. 生成侧重于科技行业的报告 5. 注意：模板结构保持不变；内容经过筛选
## 故障排除
### 问题：API 密钥无效
**解决方案**： - 验证 API 密钥是否正确（小心复制粘贴） - 检查 API 密钥是否处于激活状态（登录 FMP 仪表板） - 确保密钥前后没有多余空格 - 尝试从 FMP 仪表板生成新的 API 密钥
### 问题：脚本返回空结果
**解决方案**： - 验证日期范围是在未来（而不是过去的日期） - 检查日期格式是否为 YYYY-MM-DD - 尝试更宽的日期范围（例如，14 天而不是 7 天） - 验证该周公司是否确实已宣布财报日期
### 问题：缺少主要公司
**解决方案**： - 公司可能尚未宣布财报日期 - 有些公司宣布日期很晚（前 1-2 天） - 与公司投资者关系网站进行交叉参考 - 市值可能已跌至 20 亿美元阈值以下
### 问题：达到速率限制（429 错误）
**解决方案**： - 免费层：250 次/天 - 每份周报告使用约 3-5 次 API 调用 - 检查是否有其他工具/脚本正在使用相同的 API 密钥 - 等待 24 小时以重置速率限制 - 如果频繁需要，请考虑升级到付费层
### 问题：脚本执行错误
**解决方案**： - 验证已安装 Python 3：`python3 --version` - 安装 requests 库：`pip install requests` - 检查脚本是否具有执行权限：`chmod +x fetch_earnings_fmp.py` - 显式使用 python3 运行：`python3 fetch_earnings_fmp.py ...`
## 最佳实践
### 建议做的事 ✓ 在进行任何数据检索之前，务必先获取当前日期 ✓ 使用 FMP API 作为主要数据源以确保可靠性 ✓ 将 API 密钥存储在环境变量中以供 CLI 使用 ✓ 按市值排序以优先考虑高影响力的公司 ✓ 按日期和时间分组，以便逻辑组织 ✓ 包含汇总统计数据以便快速概览 ✓ 在报告页脚注明数据来源 ✓ 使用简洁的 Markdown 表格以提高可读性 ✓ 提供时间参考部分以确保清晰 ✓ 注明数据的新鲜度和潜在变化 ✓ 在可用时包含 EPS 和营收预估
### 不建议做的事 ✗ 不要在未根据当前日期计算的情况下假设“下周” ✗ 不要遗漏时间信息（BMO/AMC/TAS） ✗ 不要在报告中混合日期格式（保持一致） ✗ 除非特别要求，否则不要包括微型/小盘股 ✗ 不要忘记在部分内按市值排序 ✗ 不要在对话或报告中分享 API 密钥 ✗ 不要包含本周或过去日期的财报 ✗ 不要在没有质量检查的情况下生成报告 ✗ 不要将 API 密钥提交到版本控制
## 安全说明
### API 密钥安全
**重要提醒**： 1. ✓ 使用免费层 API 密钥进行测试 2. ✓ 定期轮换密钥 3. ✓ 不要分享包含 API 密钥的对话 4. ✓ 对于 CLI，将 API 密钥设置为环境变量 5. ✓ 聊天中提供的密钥仅限会话使用（会话结束后被遗忘） 6. ✗ 永远不要将 API 密钥提交到 Git 存储库 7. ✗ 永远不要使用具有敏感数据访问权限的生产 API 密钥
**最佳实践**： 对于 Claude Code (CLI)，始终使用环境变量： ```bash # Add to ~/.zshrc or ~/.bashrc export FMP_API_KEY="your-key-here" ```
对于 Claude Web，请了解： - 在聊天中输入的 API 密钥是临时的 - 仅存储在对话上下文中 - 不保存到磁盘 - 会话结束时被遗忘
## 资源
**FMP API**： - 主文档：https://site.financialmodelingprep.com/developer/docs - 获取 API 密钥：https://site.financialmodelingprep.com/developer/docs - 财报日历 API：https://site.financialmodelingprep.com/developer/docs/earnings-calendar-api - 公司简介 API：https://site.financialmodelingprep.com/developer/docs/companies-key-metrics-api - 定价/速率限制：https://site.financialmodelingprep.com/developer/docs/pricing
**补充来源**（用于验证）： - Seeking Alpha：https://seekingalpha.com/earnings/earnings-calendar - Yahoo Finance：https://finance.yahoo.com/calendar/earnings - MarketWatch：https://www.marketwatch.com/tools/earnings-calendar
**技能资源**： - FMP API 指南：`references/fmp_api_guide.md` - Python 脚本：`scripts/fetch_earnings_fmp.py` - 报告模板：`assets/earnings_report_template.md`
---
## 总结
此技能提供了一种可靠的、由 API 驱动的方法来生成美国股票的每周财报日历。通过使用 FMP API，它确保了结构化、准确的数据，并提供了 EPS/营收预估等额外见解。多环境支持使其灵活适用于 CLI、桌面和 Web 使用，而回退模式确保即使在没有 API 访问的情况下也能正常运行。
**关键工作流**：日期计算 → API 密钥设置 → API 数据检索 → 处理 → 报告生成 → QA → 交付
**输出**：简洁、有组织的 Markdown 报告，按日期/时间/市值分组的财报，包括汇总统计数据和交易考量。