mlb-matchup-analyzer

MLB 对阵分析器

目录

• 示例
• 工作流
• 信号输出
• 防护措施
• 快速参考

示例

场景：用户需要决定是否让 Junior Caminero（TB，右打）参加今天的比赛。比赛：Tampa Bay Rays @ Colorado Rockies，2026-04-17，Coors Field。

调研环节（网页搜索，每个 URL 都要注明出处）：

• MLB.com 预计先发投手 -> COL 先发投手为 German Marquez（右投），2026 赛季 ERA 5.10，K% 19.0%，硬击球率 43%
• FanGraphs 2026 年球场系数 -> Coors Field：wOBAcon 1.18（联盟最有利于击球手的球场）
• RotoWire 天气预报（Denver，当地时间 7:10 首球）-> 82F，降水概率 0%，风向朝 CF、风速 9 mph
• RotoBaller 终结者图表 -> COL 牛棚：终结者状态良好，布局投手组合稳定；TB 牛棚：终结者最近 4 场中出战 3 场，可能无法上场

归一化环节：

• opp_sp_quality（从 TB 击球手的角度评估 COL 先发投手）：Marquez 低于平均水平 -> 对击球手而言，对手投手实力较弱。评分 = 30（50 = 联盟平均先发投手；分数越低，对击球手而言对阵越轻松）。
• park_hitter_factor：Coors 的 wOBAcon 为 1.18 -> 归一化，使 1.00 = 50。评分 = 74（非常有利于击球手）。
• park_pitcher_factor：与上述指标相反。评分 = 26（对投手非常不利）。
• weather_risk：降水概率 0% + 气温温和 + 风向有利 -> 8（天气造成比赛中断的风险极低）。
• bullpen_state（主队 COL）：终结者休息充足，布局投手状态良好 -> 65。（TB：终结者疲惫不堪 -> 35。）

左右打者对位解读（通俗表述，不使用术语）： “Caminero 是右打者，将面对一名右投手。这是中性的左右打者对位，并无对位优势。不过，Caminero 对阵右投手时的强劲击球率高于赛季平均水平，而且 Coors Field 是棒球界最有利于击球手的球场，因此整体对位优势明显。”

下游组合结果：mlb-player-analyzer 会读取这些信号并计算出 matchup_score = 40% opp_sp + 25% park_hitter + 25% platoon + 10% weather -> Caminero 今日得分约为 72。该结果会影响 daily_quality -> START。

工作流

复制此清单并跟踪进度：

MLB Matchup Analysis Progress:
- [ ] Step 1: Collect game identifiers (home, away, date, first pitch time)
- [ ] Step 2: Identify both probable starting pitchers + handedness
- [ ] Step 3: Pull park factors (home park)
- [ ] Step 4: Pull weather forecast for first-pitch window
- [ ] Step 5: Assess bullpen state for both teams
- [ ] Step 6: Normalize each signal to 0-100 (50 = neutral)
- [ ] Step 7: Write platoon narrative (plain English)
- [ ] Step 8: Emit signal file and validate

步骤 1：收集比赛标识信息

• 主队、客队、当地比赛日期、首球时间、比赛场地
• 确认比赛尚未延期或改期

步骤 2：确定可能的先发投手

从 MLB.com 的可能先发投手页面获取信息（https://www.mlb.com/probable-pitchers）。搜索流程和备用方案见 resources/methodology.md。

• 主队 SP：姓名、惯用手（L/R）、赛季 ERA、K%、xFIP
• 客队 SP：相同字段
• 角色确定性：先发已确认，还是仅为预测？

步骤 3：获取球场因素

使用 FanGraphs 2026 年球场因素（guts.aspx?type=pf）。归一化公式（原始因素 -> 0-100 分）见 resources/methodology.md。

• 综合球场因素（击球手视角）
• 综合球场因素（投手视角）
• 惯用手相关因素（L/R），如有明显影响

步骤 4：获取天气预报

使用 RotoWire 天气预报（rotowire.com/baseball/weather-forecast.php）。风险公式见 resources/methodology.md。

• 首球时间段的降水概率
• 气温 + 风向 + 风速
• 是否为室内球场 / 可伸缩屋顶球场？（天气因素不适用）
• 比赛重要性乘数（对排名至关重要的比赛，延期或改期的阻力更大）

步骤 5：评估牛棚状态

使用 RotoBaller 终结者深度图表 + 过去 7 天的使用情况报告。参见 resources/methodology.md。

• 终结者是否可用（过去 3 天的出场情况、投球数）
• 高杠杆局面的中继投手是否可用
• 过去 72 小时内是否有球员加入伤病名单（IL）或被下放

步骤 6：归一化信号

所有信号都必须归一化到 0-100 分，且 50 = 联盟平均 / 中性。各信号的公式见 resources/methodology.md。

• 从双方各自的视角计算 opp_sp_quality
• 以中性球场 = 50 为基准计算 park_hitter_factor
• park_pitcher_factor = 100 - park_hitter_factor（近似反向）
• weather_risk = 降雨概率百分比 x 重要性乘数，最高为 100
• 按球队计算 bullpen_state（主队 + 客队）

步骤 7：撰写左右打者对位说明

根据 yahoo-mlb/CLAUDE.md 规则 5：避免使用术语，或在行文中解释术语。对于每位重点关注的打者，说明其惯用手和 SP 的惯用手，然后用通俗语言描述是否存在对位优势。参见 resources/template.md。

步骤 8：输出并验证

使用 resources/template.md 写入 signals/YYYY-MM-DD-matchup.md。调用 mlb-signal-emitter 进行验证。根据 resources/evaluators/rubric_mlb_matchup_analyzer.json 进行核验。最低标准：平均分达到 3.5+。

信号输出

信号	范围	含义
opp_sp_quality	0-100	对方先发投手的真实能力 + 今日对位情况。50 = 联盟平均水平的 SP。分数越高，对面对该投手的击球手越不利。
park_hitter_factor	0-100	50 = 中性。>50 = 有利于击球手（Coors、Cincinnati）。<50 = 有利于投手（Oracle、T-Mobile）。
park_pitcher_factor	0-100	50 = 中性。>50 = 有利于投手。通常 ~= 100 - park_hitter_factor，并根据球场特有影响（界外区等）稍作修正。
weather_risk	0-100	0 = 室内球场或天气条件理想。100 = 延期风险高 + 比赛过程中受到天气干扰的风险高。
bullpen_state	0-100	按球队计算。50 = 正常。>50 = 牛棚健康且休息充足。<50 = 疲惫 / 人手不足 / 因伤病名单（IL）而减员。

另附一段说明，涵盖双方阵容的左右打者对位影响。

注意事项

1. 50 始终代表中性。 每个信号都以 50 为锚点，即联盟平均水平。如果你的公式生成的分布中位数不是 50，公式就有问题——请重新设定锚点。

2. 为每个 URL 标注来源。 每个信号值都必须能追溯到 source_urls: 中的特定来源 URL。如果某项事实无法通过网络搜索验证，请将 confidence 降至 0.3 或更低，并在红队评估中标出。

3. 球场系数取决于具体情况。 左右打者的差异很重要：Yankee Stadium 有利于左打者；Fenway 的 Green Monster 有利于拉打的右打者。如果关键击球手的左右打者数据差异极大，请使用对应打者惯用手的球场系数，而非综合系数。

4. 天气风险 = 降雨概率 x 重要性乘数。 9 月份的冠军争夺战中，30% 的降雨概率比 4 月份更重要。重要性乘数请参阅方法说明。

5. 牛棚状态按球队计算，而非按比赛计算。 输出两个值：bullpen_state_home 和 bullpen_state_away。下游使用方会选取所需的值（例如，直播策略师会关注比赛后段对手的牛棚状态）。

6. 左右投手对位的描述必须避免行话。 不要写“对右投手有正向分项数据”，而应写“对阵右投手时比对阵左投手时表现更好”。每项统计数据首次出现时都要加以解释。

7. 有顶棚的球场不考虑天气。 如果主队球场有顶棚（或已确认顶棚关闭），无论天气预报如何，都将 weather_risk 设为 0，并在信号正文中说明顶棚状态。

8. 双方先发投手、双方视角。 信号文件应从两个视角报告 opp_sp_quality：主队击球手面对客队先发投手，反之亦然。不要只报告其中一方。

快速参考

关键公式：

park_hitter_factor = 50 + (raw_wOBAcon_factor - 1.00) * 200
  (clamped to [0, 100]; neutral park wOBAcon ~ 1.00 -> 50)

park_pitcher_factor = 100 - park_hitter_factor (first-order approximation)

opp_sp_quality = 50 + (lg_avg_xFIP - SP_xFIP) * 15
  (better SP = higher score = tougher on opposing hitters)

weather_risk = min(100, rain_prob_pct * importance_multiplier)
  importance_multiplier: 1.0 (early season) .. 1.5 (playoff push) .. 2.0 (postseason)

bullpen_state = 50
  - 15 if closer unavailable
  - 10 per high-leverage arm unavailable
  + 5 if closer had 2+ days rest and full bullpen rested
  (clamped [0, 100])

主要来源（完整列表见 context/frameworks/data-sources.md）：

• 可能的先发投手：https://www.mlb.com/probable-pitchers
• 球场系数：https://www.fangraphs.com/guts.aspx?type=pf&season=2026
• 天气：https://www.rotowire.com/baseball/weather-forecast.php
• 牛棚：https://www.rotoballer.com/mlb-saves-closers-depth-charts/226767
• 左右投手对位数据：FanGraphs 球员页面 -> Splits 选项卡

所需输入：主队、客队、日期（YYYY-MM-DD）、开球时间（可选）。

生成的输出：一个位于 signals/YYYY-MM-DD-matchup.md 的信号文件，包含 frontmatter、对阵摘要表、左右投手对位说明和来源 URL。

主要资源：

• resources/template.md：信号文件模板，包含 YAML frontmatter、对阵摘要表和左右投手对位说明区块
• resources/methodology.md：搜索位置、归一化公式、球场系数换算、天气风险计算和牛棚评估
• resources/evaluators/rubric_mlb_matchup_analyzer.json：包含 8 项标准的质量评分细则