mlb-data

MLB 数据

编写查询前，请查阅 references/api-reference.md，了解端点、ID 约定和数据结构。

设置

首次使用前，请检查 CLI 是否可用：

which sports-skills || pip install sports-skills

如果 pip install 因 Python 版本错误而失败，则该软件包需要 Python 3.10 或更高版本。请查找兼容的 Python 版本：

python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills

无需 API 密钥。

快速开始

建议优先使用 CLI，以避免 Python 导入路径问题：

sports-skills mlb get_scoreboard
sports-skills mlb get_standings --season=2025
sports-skills mlb get_teams

重要：执行任何查询前

重要：调用任何数据端点前，请确认：

• 赛季年份是根据系统提示词中的 currentDate 推导得出的，绝不可硬编码。
• 如果只提供了球队名称，请先调用 get_teams 解析出球队 ID，再使用特定球队的命令。

选择赛季

根据系统提示词中的日期推导当前赛季，而不仅仅是日历年份。

• 如果用户指定了赛季，请按指定使用。
• 如果用户说“当前赛季”“本赛季”或未指定赛季：MLB 赛季从 3 月下旬或 4 月持续到 10 月。如果当前月份是 1 月至 3 月，则最近结束的赛季是上一日历年。从 4 月起，使用当前日历年。

命令

命令	说明
get_scoreboard	MLB 实时／近期比分
get_standings	按联盟和分区查询排名
get_teams	全部 30 支 MLB 球队
get_team_roster	球队完整名单
get_team_schedule	指定球队的赛程
get_game_summary	详细记分表和得分过程
get_leaders	MLB 各项统计排名领先者
get_news	MLB 新闻文章
get_play_by_play	比赛完整逐球记录
get_win_probability	胜率图表数据
get_schedule	指定日期的比赛（不支持赛季筛选；请参阅 get_team_schedule）
get_injuries	所有球队的伤病报告
get_transactions	近期球员交易
get_futures	未来赛事／赔率市场
get_depth_chart	球队阵容深度图
get_team_stats	球队统计概况
get_player_stats	球员统计概况
find_mlb_player	按姓名搜索 MLB 球员登记信息
get_mlbstats_schedule	通过 MLB Stats API 查询比赛——历史数据可追溯至 1901 年，并包含 gamePk ID
get_mlbstats_player_stats	通过 MLB Stats API 按统计类别查询赛季／生涯／逐年拆分数据；stat_type=game_log 会为每场比赛返回一个拆分条目
get_mlbstats_play_by_play	投球级逐球记录（PBP）——球速、旋转、投球坐标、击球初速、发射角
get_mlbstats_boxscore	通过 MLB Stats API 获取完整记分表，含每位球员的击球／投球数据
get_mlbstats_standings	通过 MLB Stats API 按分区查询排名
get_mlbstats_leaders	通过 MLB Stats API 查询任意统计类别的联盟领先者

完整参数列表和返回数据结构请参阅 references/api-reference.md。

整理逐球记录结果

get_mlbstats_play_by_play 和 get_mlbstats_player_stats 支持 sort_by、descending、limit 和 fields。 如果只需要打席结果，使用 fields 是移除逐投球列表最快的方法：

sports-skills mlb get_mlbstats_play_by_play --game_pk=775296 --fields=event,rbi

• sort_by：用于排序的单个列。数字（以及数字字符串）按数值排序；缺失值始终排在最后。
• descending：true（默认值）或 false；仅在设置了 sort_by 时使用。
• limit：正整数，在排序后应用。
• fields：以逗号分隔的保留列列表。inning、half、batter、pitcher（逐球记录）或 season、team、game_pk、game_date（球员统计；homeRuns 等统计键可直接指定），以及 sort_by 列始终保留。
• 未知的 sort_by／fields 列会返回错误，并列出有效列。
• 设置其中任一选项后，响应会增加 total_rows（应用 limit 前的匹配行数）和 returned_rows。未设置任何选项时，输出保持不变。这些选项在获取数据后应用，因此不会改变上游请求或其重放记录。

同时使用 ESPN 和 MLB Stats API

get_mlbstats_* 命令会读取 statsapi.mlb.com——MLB 自己的开放 API。它提供了 ESPN 不具备的分析数据层：每球的球速、旋转和位置，击球出局时的击球初速和发射角，按统计类别划分的生涯数据，以及可追溯至 1901 年的赛程。两个来源使用互不相关的 ID 系统：

• 比赛 ID。 MLB 使用 gamePk（例如 775296）；ESPN 使用赛事 ID（例如 401570367）。没有可共用的列——请按比赛日期和球队关联。
• 球队缩写。 两支球队的缩写不同：ESPN 使用 ARI/CHW，而 MLB 使用 AZ/CWS。所有 get_mlbstats_* 球队筛选条件都接受任一种写法，数据行中也包含两种缩写（team_abbreviation、team_abbreviation_espn）。
• 球员 ID。 MLB 球员 ID（660271）与 ESPN 运动员 ID 互不相关。使用 find_mlb_player 查询姓名；不带重音符号的拼写也能匹配带重音符号的姓名（"acuna" 可找到 "Ronald Acuña Jr."）。
• 延期比赛会重复出现。 在 get_mlbstats_schedule 中，延期或中止的比赛会以同一个 game_pk 列出两次：原定日期的条目带有 rescheduled: true（以及 rescheduled_to），补赛条目带有 rescheduled_from。统计比赛场次时，请排除带有 rescheduled 的行。
• 赛程时间。 start_time 使用 UTC；venue_timezone 是球场所在的 IANA 时区（例如 America/New_York；如果 MLB 未提供，则为 null）；local_date 是 MLB 官方（当地）日期。
• 季后赛 game_type 会按日期筛选。 在世界大赛日期范围以外使用 game_type="worldseries"，不会返回比赛，并会在 warnings 条目中给出提示；请移除 game_type，或同时传入 team + season，以列出该轮系列赛的日期。
• 排行榜按类别分组。 像 homeRuns 这样的类别会出现在打击、接捕和投球数据中（投球数据中的本垒打指被打出的本垒打）；数据行会标注 stat_group——传入 stat_group= 可只获取其中一组。

响应中包含从 API 原样传递的 MLB copyright 声明。

示例

示例 1：今天的比分
用户说：“今天 MLB 的比分是多少？”
操作：

1. 调用 get_scoreboard() 结果：所有正在进行和近期 MLB 比赛的逐局比分及状态

示例 2：分区排名
用户说：“给我看看 AL East 的排名”
操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_standings(season=<derived_year>)
3. 筛选出 American League East 的结果 结果：AL East 排名，包含胜-负、胜率、与分区领先者的胜场差以及得失分差

示例 3：球队名单
用户说：“洋基队名单上有哪些球员？”
操作：

1. 调用 get_team_roster(team_id="10") 结果：完整的洋基队名单，包含姓名、位置、惯用打击/投球手、身高和体重

示例 4：比赛数据统计表
用户说：“给我看看道奇队昨晚那场比赛的完整数据统计表”
操作：

1. 调用 get_scoreboard(date="<yesterday>") 查找 event_id
2. 调用 get_game_summary(event_id=<id>) 获取完整数据统计表 结果：完整数据统计表，包含每位球员的打击/投球数据

示例 5：伤病名单
用户说：“洋基队有哪些球员在 IL 上？”
操作：

1. 调用 get_injuries()
2. 筛选出纽约洋基队的结果（team_id=10） 结果：洋基队 IL 名单，包含球员姓名、位置、IL 类型和伤情详情

示例 6：球员数据
用户说：“给我看看 Shohei Ohtani 的数据”
操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_player_stats(player_id="39832", season_year=<derived_year>) 结果：按类别（打击、投球）划分的赛季数据，包含数值、排名和每场平均值

示例 7：世界大赛夺冠赔率
用户说：“哪支球队最被看好赢得世界大赛？”
操作：

1. 调用 get_futures(limit=10) 结果：最有望夺冠的球队及赔率

不存在的命令——切勿调用

• get_odds / get_betting_odds — 不可用。查询预测市场赔率时，请使用 polymarket 或 kalshi skill。
• search_teams — 不存在。请改用 get_teams。
• get_box_score — 不存在。请改用 get_game_summary。
• get_player_ratings — 不存在。请改用 get_player_stats。

如果命令未列在上方的命令表中，则该命令不存在。

错误处理

命令失败时，不要向用户显示原始错误。请改为：

1. 静默捕获错误并尝试其他方案
2. 如果提供的是球队名称而非 ID，先使用 get_teams 查找 ID
3. 穷尽其他方案后，再用清晰简洁的消息报告失败

故障排除

错误：找不到 sports-skills 命令 原因：未安装软件包 解决方案：运行 pip install sports-skills

错误：按 ID 找不到球队 原因：使用了错误或过时的 ESPN 球队 ID 解决方案：调用 get_teams，获取当前全部 30 支 MLB 球队及其 ID 列表

错误：未返回未来比赛的数据 原因：ESPN 仅返回已结束或正在进行的比赛数据 解决方案：使用 get_schedule 查看即将进行的比赛详情；get_scoreboard 仅涵盖正在进行或近期的比赛

错误：休赛期——记分牌返回 0 场赛事 原因：休赛期（11 月至 3 月）没有安排比赛 解决方案：改用 get_standings 或 get_news；MLB 休赛期的交易信息可通过 get_transactions 获取