earnings-calendar

财报日历

概述

此技能使用 Financial Modeling Prep（FMP）API 获取美国股票即将发布的财报公告。它重点关注市值较大的公司（中盘股及以上，超过 20 亿美元），这些公司的公告可能会影响市场走势。此技能会生成条理清晰的 Markdown 报告，按日期和发布时间（开盘前、收盘后或尚未公布时间）分组，展示未来一周发布财报的公司。

主要功能：

• 使用 FMP API 获取可靠、结构化的财报数据
• 按市值（>20 亿美元）筛选，聚焦可能影响市场走势的公司
• 包含每股收益和营收预估
• 支持多种环境（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）：

export FMP_API_KEY="your-api-key-here"

Claude Desktop： 在系统中设置环境变量，或配置 MCP 服务。

Claude Web： 运行技能时会要求提供 API 密钥（仅在当前会话中存储）。

核心工作流

步骤 1：获取当前日期并计算目标周

重要：务必先获取准确的当前日期。

获取当前日期和时间：

• 使用系统日期/时间获取今天的日期
• 注意：“今天的日期”由环境提供（ 标签）
• 计算目标周：从当前日期起的未来 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 请求提供准确的日期范围

为确保 API 兼容性，日期请使用 YYYY-MM-DD 格式。

步骤 2：加载 FMP API 指南

检索数据前，请加载完整的 FMP API 指南：

Read: references/fmp_api_guide.md

此指南包含：

• FMP API 端点结构和参数
• 身份验证要求
• 市值筛选策略（通过 Company Profile API）
• 财报发布时间惯例（BMO、AMC、TAS）
• 响应格式和字段说明
• 错误处理策略
• 最佳实践和优化技巧

步骤 3：检测并配置 API 密钥

根据环境检测 API 密钥是否可用。

多环境 API 密钥检测：

3.1 检查环境变量（CLI/桌面端）

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）：

python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09

选项 B：使用会话 API 密钥（桌面端/网页端）：

python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}"

脚本工作流（自动）：

1. 验证 API 密钥和日期参数
2. 调用 FMP 财报日历 API 获取日期范围内的数据
3. 获取公司概况（市值、板块、行业）
4. 筛选市值 >$2B 的公司
5. 统一时间标记（BMO/AMC/TAS）
6. 按日期 → 时间标记 → 市值（降序）排序
7. 将 JSON 输出到 stdout

预期输出格式（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"
  },
  ...
]

保存到文件（建议与报告生成器配合使用）：

python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}" > earnings_data.json

或捕获到变量：

earnings_data=$(python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 "${API_KEY}")

错误处理：

如果脚本返回错误：

• 401 Unauthorized：API 密钥无效 → 验证密钥或重新输入
• 429 Rate Limit：已超过每天 250 次调用的限制 → 等待或升级套餐
• 结果为空：日期范围内没有财报 → 扩大日期范围或在报告中注明
• 连接错误：网络问题 → 重试；如果有缓存数据，也可以使用

第 5 步：处理和整理数据

获取财报数据（JSON 格式）后，对其进行处理和整理：

5.1 解析 JSON 数据

从脚本输出中加载 JSON 数据：

import json
earnings_data = json.loads(earnings_json_string)

或从文件加载：

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 在每个时间标记组内排序

公司已由脚本按市值降序排序：

• 先列出超大型股（>$200B）
• 再列出大型股（$10B-$200B）
• 最后列出中型股（$2B-$10B）

此优先级可确保最可能影响市场的公司排在前面。

5.6 计算汇总统计数据

计算：

• 公司总数：数据集中所有公司的数量
• 超大型股/大型股数量：marketCap >= $10B 的公司数量
• 中型股数量：marketCap 在 $2B 至 $10B 之间的公司数量
• 财报公告高峰日：财报公告数量最多的星期几
• 板块分布：按板块统计数量（Technology、Healthcare、Financial 等）
• 市值最高的公司：按市值排列的前 5 家公司

第 6 步：生成 Markdown 报告

使用报告生成脚本，根据 JSON 数据创建格式化的 Markdown 报告。

脚本位置：

scripts/generate_report.py

执行：

选项 A：输出到 stdout：

python scripts/generate_report.py earnings_data.json

选项 B：保存到文件：

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 和营收格式
• 汇总统计数据计算

报告结构：

# 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 家公司发布财报，Apple 和 Microsoft 将于周一发布”）

示例摘要：

✓ 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. 获取财报数据：

   python scripts/fetch_earnings_fmp.py 2025-11-03 2025-11-09 > earnings_data.json
   

6. 生成 Markdown 报告：

   python scripts/generate_report.py earnings_data.json earnings_calendar_2025-11-02.md
   

7. 向用户发送通知和摘要

完整单行命令：

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：聚焦大型市值公司

用户请求：“展示下周市值超过 1,000 亿美元的公司的财报”

工作流：

1. 获取完整财报数据（脚本已筛选出市值 >$2B 的公司）
2. 按常规处理并整理数据
3. 生成报告时，在顶部添加“大型市值公司聚焦”部分
4. 筛选表格，仅显示市值 >$100B 的公司
5. 注意：附录中仍应包含完整数据以供参考

使用场景 4：特定行业

用户请求：“下周有哪些科技公司发布财报？”

工作流：

1. 获取完整财报数据
2. 按常规处理并整理数据
3. 按行业 = “Technology” 筛选结果
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 密钥存储在环境变量中 ✓ 按市值排序，优先显示影响较大的公司 ✓ 先按日期、再按时间安排分组，以便逻辑清晰 ✓ 提供汇总统计信息，便于快速了解概况 ✓ 在报告页脚注明数据来源 ✓ 使用简洁的 Markdown 表格，提升可读性 ✓ 提供时间安排参考部分，以便清晰查看 ✓ 注明数据时效性以及信息可能发生变化 ✓ 在有数据时，纳入 EPS 和营收预估

不应做事项

✗ 不要在未根据当前日期进行计算的情况下假定“下周” ✗ 不要省略时间信息（BMO/AMC/TAS） ✗ 不要在同一份报告中混用日期格式（保持一致） ✗ 除非有特别要求，否则不要纳入微型或小型市值公司 ✗ 不要忘记在各部分中按市值排序 ✗ 不要在对话或报告中分享 API 密钥 ✗ 不要纳入本周或过去日期的财报 ✗ 不要在未进行质量检查的情况下生成报告 ✗ 不要将 API 密钥提交到版本控制系统

安全说明

API 密钥安全

重要提醒：

1. ✓ 使用免费层级的 API 密钥进行测试
2. ✓ 定期轮换密钥
3. ✓ 不要分享包含 API 密钥的对话
4. ✓ 在命令行中将 API 密钥设置为环境变量
5. ✓ 在聊天中提供的密钥仅在当前会话中有效（会话结束后即被遗忘）
6. ✗ 切勿将 API 密钥提交到 Git 仓库
7. ✗ 切勿将生产环境 API 密钥用于访问敏感数据

最佳实践： 对于 Claude Code（CLI），始终使用环境变量：

# 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
• 随附的 FMP 兼容模块：scripts/_fmp_compat.py（v3→stable 重写垫片）
• 随附的 FMP 客户端：scripts/fmp_client.py（生成文件；处理速率限制、单次 429 重试和标头认证）——请注意：发生 HTTP 故障时，会打印一条通用的 ERROR: API request failed: … 客户端日志，以及脚本映射的 ❌ ERROR: 消息
• 报告模板：assets/earnings_report_template.md

---

摘要

此技能提供了一种可靠、由 API 驱动的方法，用于生成美国股票的每周财报日历。通过使用 FMP API，它可确保数据结构清晰、准确，并提供 EPS/营收预估等额外信息。多环境支持使其可灵活用于 CLI、桌面端和 Web，而回退模式则确保即使无法访问 API，也能正常运行。

关键工作流：日期计算 → API 密钥设置 → API 数据获取 → 数据处理 → 报告生成 → QA → 交付

输出：整洁、有序的 Markdown 报告，按日期/时间/市值归类财报，并包含摘要统计和交易注意事项。