MLB Data 是一个用于获取美国职业棒球大联盟（MLB）数据的技能工具，数据来源为 ESPN 公开接口和 MLB 官方 Stats API。使用前建议先查阅 references/api-reference.md 了解端点、ID 约定和数据形态。
用途
该工具面向需要查询 MLB 赛事与统计数据的场景，覆盖比分、排名、球队、球员、赛程、伤病、交易、赔率市场、新闻等常见棒球数据需求，并额外提供 MLB Stats API 的深度分析数据。
主要能力
通过 ESPN 公开接口提供的命令包括：get_scoreboard（实时/近期比分）、get_standings（按联盟和分区的排名）、get_teams（全部 30 支 MLB 球队）、get_team_roster（球队完整名单）、get_team_schedule（特定球队赛程）、get_game_summary（详细技术统计和得分过程）、get_leaders（统计领先榜）、get_news（新闻文章）、get_play_by_play（完整逐球记录）、get_win_probability（胜率图表数据）、get_schedule（特定日期的比赛）、get_injuries（各队伤病报告）、get_transactions（近期交易）、get_futures（期货/赔率市场）、get_depth_chart（球队深度图）、get_team_stats（球队统计概况）、get_player_stats（球员统计概况）、find_mlb_player（按姓名搜索球员注册表）。
通过 MLB Stats API 提供的命令包括：get_mlbstats_schedule（可追溯至 1901 年的赛程，携带 gamePk ID）、get_mlbstats_player_stats（按统计组的赛季/生涯/逐年拆分，stat_type=game_log 可给出每场一条拆分）、get_mlbstats_play_by_play（逐球级数据，含球速、旋转、进垒坐标、击球初速、发射角）、get_mlbstats_boxscore（含每位球员打击/投球数据的完整技术统计）、get_mlbstats_standings（按分区排名）、get_mlbstats_leaders（任意统计类别的联盟领先者）。
使用方式
安装：先检查 CLI 是否可用，命令为 which sports-skills || pip install sports-skills。若 pip 安装因 Python 版本报错，该包需要 Python 3.10+，可用 python3 --version 检查版本；若低于 3.10，可尝试 python3.12 -m pip install sports-skills；在 macOS 配合 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_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；limit 为正整数，在排序后应用；fields 为逗号分隔的保留列表。设置这些参数后，响应会附加 total_rows 和 returned_rows；未设置时输出不变。这些参数在获取数据后应用，不会改变上游请求。
两个数据源的配合
get_mlbstats_* 命令读取 statsapi.mlb.com，即 MLB 自己的开放 API，提供 ESPN 没有的分析层：逐球速度/旋转/位置、击球初速和发射角、按统计组的生涯拆分，以及可追溯至 1901 年的赛程。两个来源使用互不相关的 ID 系统：比赛 ID 方面，MLB 使用 gamePk（如 775296），ESPN 使用 event id（如 401570367），需按比赛日期加球队进行关联；球队缩写方面，ESPN 的 ARI/CHW 与 MLB 的 AZ/CWS 不同，get_mlbstats_* 的球队过滤接受两种拼写，行中同时携带 team_abbreviation 和 team_abbreviation_espn；球员 ID 方面，MLB person id（660271）与 ESPN athlete id 无关，可用 find_mlb_player 解析姓名，ASCII 拼写可匹配带重音的名字（如 "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 条目；领先榜按组分组，如 homeRuns 同时存在于打击、接球和投球（被本垒打）中，行会标注 stat_group，可用 stat_group= 只取一组；响应包含 MLB 的版权声明。
适用场景
适用于查询当日比分、分区排名、球队名单、比赛技术统计、伤病名单、球员统计、世界大赛赔率等日常棒球数据需求，也适用于需要逐球级分析数据、历史赛程（至 1901 年）和按统计组拆分的深度统计场景。
限制
不存在 get_odds / get_betting_odds 命令，预测市场赔率需使用 polymarket 或 kalshi 技能；不存在 search_teams，应使用 get_teams；不存在 get_box_score，应使用 get_game_summary；不存在 get_player_ratings，应使用 get_player_stats。未在命令表中列出的命令均不存在。命令失败时不应向用户暴露原始错误，应静默捕获并尝试替代方案，仅在穷尽替代方案后以简洁消息报告失败。常见问题包括：sports-skills 命令未找到（需 pip install sports-skills）、球队 ID 未找到（应调用 get_teams 获取最新列表）、未来比赛无数据（ESPN 仅返回已完成或进行中的比赛，可用 get_schedule 查看即将进行的比赛）、休赛期比分板返回 0 场（11 月至 3 月无比赛，可改用 get_standings 或 get_news，休赛期交易可通过 get_transactions 获取）。