earnings-trade-analyzer

财报交易分析器——财报后五因素评分

使用五因素加权评分系统分析近期财报发布后的股票，找出反应最强劲、具有潜在动量交易机会的股票。

适用场景

• 用户要求分析财报发布后的交易机会，或筛选财报跳空股票
• 用户想寻找近期财报反应最佳的股票
• 用户要求对财报动量进行评分或评级
• 用户询问财报后累积日（PEAD）候选股票

前提条件

• FMP API 密钥（设置 FMP_API_KEY 环境变量或传入 --api-key）
• 免费套餐（每天 250 次调用）足以完成默认筛选（回溯 2 天，前 20 名）
• 回溯窗口更长或完整筛选时，建议使用付费套餐

工作流

第 1 步：运行财报交易分析器

执行分析器脚本：

# Default: last 2 days of earnings, top 20 results
python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py --output-dir reports/

# Custom lookback and market cap filter
python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py \
  --lookback-days 5 \
  --min-market-cap 1000000000 \
  --top 30 \
  --output-dir reports/

# Deterministic anchor date (America/New_York); the window is anchored on the
# ET calendar date, not the runner's local clock. For reproducible runs/tests.
python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py \
  --as-of 2026-09-15 \
  --output-dir reports/

# With entry quality filter
python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py \
  --apply-entry-filter \
  --output-dir reports/

定时审查时的端点降级／预算回退

如果分析器报告 404、财报日历结果异常为空，或在定时盘后／盘前运行时耗尽 API 调用预算，未能生成评分候选项，请勿立即报告“没有财报反应”。若日期范围内至少包含一个 XNYS 交易日，但返回的空结果正常，则以退出码 1 退出，且 ZERO_RESULT_REASON=earnings_calendar_empty_with_market_sessions。如果共享的 XNYS 日历无法判定该日期范围，则以退出码 1 退出，且 ZERO_RESULT_REASON=market_calendar_unavailable。获取公司概况时预算耗尽或达到每日速率限制，则以退出码 1 退出，且 ZERO_RESULT_REASON=profiles_budget_exhausted。以上情况都应视为运行失败，需要重试或回退，而非静默处理。只有当交易日数为零的日期范围正常返回空结果时，才会以退出码 0 退出，且 ZERO_RESULT_REASON=no_earnings_rows。

1. 首先使用范围更窄、流动性更高的股票池配置重试一次，让完整的五因素评分器有机会完成运行，例如：

python3 skills/earnings-trade-analyzer/scripts/analyze_earnings_trades.py \
  --lookback-days 2 \
  --min-market-cap 5000000000 \
  --top 20 \
  --max-api-calls 600 \
  --output-dir reports/<routine-date>

2. 如果评分运行仍未返回候选项或无法完成，请通过兼容性垫片使用的稳定端点核验同一日期范围，并明确将结果标注为未评级的回退结果：

curl "https://financialmodelingprep.com/stable/earnings-calendar?from=YYYY-MM-DD&to=YYYY-MM-DD&apikey=$FMP_API_KEY"

然后可选地通过分析器的稳定端点优先 FMP 客户端，或逐个调用 /stable/quote?symbol=<ticker>，为返回的美国股票代码补充信息，并按当日 changesPercentage、市值和流动性排序。只有稳定端点失败后，才使用旧版 /api/v3 报价调用作为旧版密钥回退方案。由于五因素评分器未运行，请将这些结果标注为初步／未评级的反应；不要仅凭回退结果指定 A/B/C/D 评级。

无候选项输出的注意事项： 分析器可能会打印 Candidates after filtering: 0／No candidates found matching criteria. 并成功退出，却不生成 earnings_trade_analyzer_*.json 文件。在这种情况下，不要尝试从不存在的候选文件运行 PEAD Mode B。请明确说明未生成评分分析器 JSON；如果常规流程需要财报板块，请运行上述端点／报价补充信息回退流程，并将任何股票名称标注为仅供人工审核。此成功退出路径不适用于获取公司概况时预算耗尽的情况：该情况会以退出码 1 退出（ZERO_RESULT_REASON=profiles_budget_exhausted）。

空窗口和仅运行当天数据

财报日历窗口采用包含首尾的日期范围，并使用 --as-of 指定的 America/New_York 日历日期（或当前 ET 日期）。只有当共享的 XNYS 日历成功确认该精确窗口内的交易时段数为零（例如周末或节假日）时，干净的服务提供方 [] 才表示无异常的静默窗口结果。如果窗口内包含 XNYS 交易时段，同样干净的 [] 会以状态码 1 退出，并设置 ZERO_RESULT_REASON=earnings_calendar_empty_with_market_sessions，以免将服务提供方的数据缺失误报为平静交易日。如果无法查询 XNYS 日历，本次运行也会以状态码 1 退出，并设置 ZERO_RESULT_REASON=market_calendar_unavailable。

--lookback-days 0 有效，只会查询单个 ET 基准日期。请在相关公告发布后使用（通常在交易时段收盘后）；如果 XNYS 交易时段当天仍返回空响应，系统会有意按失败关闭处理。非空响应中的行若没有 symbol，则仍会触发独立的 ZERO_RESULT_REASON=no_earnings_rows 行为；这与上述字面上的空列表交易时段检查不同。

第 2 步：查看结果

1. 阅读生成的 JSON 和 Markdown 报告
2. 加载 references/scoring_methodology.md，了解评分解读背景
3. 重点关注 A 级和 B 级股票，寻找可采取行动的交易机会

第 3 步：呈现分析

针对每个优选候选项，列出：

• 综合评分和字母等级（A/B/C/D）
• 财报跳空幅度及方向
• 财报前 20 日趋势
• 成交量比率（20 日与 60 日均值）
• 股价相对于 200 日和 50 日移动平均线的位置
• 评分最低和最高的组成项

第 4 步：提供可执行建议

根据等级：

• A 级（85+）： 财报后反应强劲，且有机构资金累积——可考虑入场
• B 级（70-84）： 财报后反应良好，值得关注——等待回调或确认
• C 级（55-69）： 信号不一——谨慎行事，并需进一步分析
• D 级（<55）： 交易形态较弱——避免入场或等待更好的条件

输出

• earnings_trade_analyzer_YYYY-MM-DD_HHMMSS.json - 结构化结果，包含 schema_version "1.0"
• earnings_trade_analyzer_YYYY-MM-DD_HHMMSS.md - 含表格的易读报告

未知的财报时间

FMP 并未为每条财报记录确认盘前或盘后时段；未确认的记录会报告 earnings_timing: "unknown"，并在缺口计算中以 AMC 时段作为后备假设。两份报告都会显示 timing_unknown_count 与 timing_candidates_total，让这一假设清晰可见，避免在不知情的情况下混入评分。

资源

• references/scoring_methodology.md - 5 因子评分系统、等级阈值和入场质量筛选规则