NBA Data 是一个用于获取 NBA 数据的技能工具，数据来源包括 ESPN 公开接口、NBA 实时 CDN 以及 NBA Stats（stats.nba.com）。使用前建议先查阅 references/api-reference.md 了解端点、ID 约定和数据形态。
用途 该工具面向需要查询 NBA 比赛、球队、球员和统计数据的使用场景，覆盖实时比分、历史统计、伤病、交易、盘口等多个方面。
主要能力 命令覆盖：get_scoreboard（实时/近期比分）、get_standings（分区排名）、get_teams（全部 30 支球队）、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_nba_player（搜索 NBA Stats 球员注册表，覆盖所有时代）、get_nbastats_game_log（联盟比赛日志，历史可追溯至 1946 年）、get_nbastats_player_career（球员逐赛季生涯统计）、get_nbastats_team_stats（联盟球队统计，含进阶效率、节奏、四要素）、get_nbastats_shot_chart（逐次投篮坐标）、get_nbastats_play_by_play（含坐标的逐回合，用于过往赛季）、get_nbastats_advanced_boxscore（进阶技术统计，含效率与使用率）、get_live_scoreboard（实时比分，主用 cdn.nba.com，回退 ESPN）、get_live_boxscore（实时技术统计）、get_live_playbyplay（实时逐回合，最新回合在前）、get_player_live_stats（今日比赛中单个球员的实时统计）。
使用方式 安装：先检查 CLI 是否可用：which sports-skills || pip install sports-skills。若 pip install 因 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 密钥。
快速开始示例：sports-skills nba get_scoreboard；sports-skills nba get_standings --season=2025；sports-skills nba get_teams。
查询前注意事项：赛季年份应从系统提示的 currentDate 推导，不要硬编码；若只提供球队名称，需先调用 get_teams 解析球队 ID。赛季选择规则：NBA 赛季为 10 月至次年 6 月；若当前月份为 10 月至 12 月，当前赛季年份等于当前年份；若为 1 月至 6 月，当前赛季开始于上一年，应使用上一年作为赛季年份。
长结果整形：get_nbastats_game_log、get_nbastats_team_stats 和 get_nbastats_shot_chart 支持 sort_by、descending、limit 和 fields 参数，可按需返回行列。示例：sports-skills nba get_nbastats_game_log --season=2025 --team=MIA --sort_by=pts --limit=5 --fields=wl,pts。sort_by 指定排序列，数字按数值排序，缺失值排最后；descending 默认 true；limit 在排序后应用；fields 为逗号分隔的保留列，身份列和排序列始终保留。未知列会返回错误并列出有效列。设置这些参数后，响应会附加 total_rows 和 returned_rows；未设置时输出不变。这些参数在获取后应用，不改变上游请求。
ESPN 与 NBA Stats 配合使用：get_nbastats_* 命令读取 stats.nba.com，提供 ESPN 端点不具备的分析层数据（进阶效率、投篮坐标、深层历史）。两者 ID 体系不互通：比赛 ID 方面，NBA Stats 使用 10 位 ID（如 "0022400061"），ESPN 使用事件 ID（如 "401704627"），需按比赛日期加两队缩写关联；球队缩写方面，六支球队拼写不同（ESPN 的 GS/NO/NY/SA/UTAH/WSH 对应 NBA 的 GSW/NOP/NYK/SAS/UTA/WAS），get_nbastats_* 的球队筛选接受任一拼写，结果行同时携带两种缩写；球员 ID 方面，NBA 人员 ID（如 "203999"）与 ESPN 运动员 ID 无关，可用 find_nba_player 解析名称，ASCII 拼写可匹配带重音名称（如 "jokic" 可找到 "Nikola Jokić"）；赛季参数传起始年份（season=2024 表示 2024-25），也接受 "2024-25" 格式；日期在比赛日志和投篮图中均为 YYYY-MM-DD。
stats.nba.com 会按客户端和请求量限流：大量突发请求（以及许多数据中心/云 IP）会被静默延迟而非拒绝，命令会快速失败并给出说明性错误，此时应等待后重试，不要持续请求。响应有缓存，ESPN 支持的命令和 get_live_* 命令不受影响。
适用场景 适用于查询当日比分、分区排名、球队名单、比赛技术统计、伤病报告、球员赛季统计等。示例包括：查询今日 NBA 比分（调用 get_scoreboard）；查询西部排名（从 currentDate 推导赛季年份，调用 get_standings，筛选西部）；查询湖人名单（调用 get_team_roster，team_id="13"）；查询凯尔特人比赛技术统计（先 get_scoreboard 找到 event_id，再 get_game_summary）；查询湖人伤病（调用 get_injuries，筛选 team_id=13）；查询詹姆斯赛季统计（推导赛季年份，调用 get_player_stats，player_id="1966"）。
限制 不存在的命令不要调用：get_odds / get_betting_odds 不可用（预测市场盘口可使用 polymarket 或 kalshi 技能）；search_teams 不存在，应使用 get_teams；get_box_score 不存在，应使用 get_game_summary；get_player_ratings 不存在，应使用 get_player_stats。未在命令表中列出的命令均不存在。错误处理方面，命令失败时不要向用户暴露原始错误，应静默捕获并尝试替代方案；若提供的是球队名称而非 ID，先用 get_teams 查找 ID；仅在穷尽替代方案后以简洁消息报告失败。常见问题：sports-skills 命令未找到说明包未安装，运行 pip install sports-skills；球队 ID 未找到说明使用了错误或过时的 ESPN 球队 ID，调用 get_teams 获取当前 30 支球队列表；未来比赛无数据说明 ESPN 仅返回已完成或进行中的比赛，可用 get_schedule 查看即将到来的比赛详情；休赛期（7 月至 9 月）比分板返回 0 场比赛，可改用 get_standings 或 get_news，并用 get_schedule 查看赛季恢复时间。