nhl-data

NHL 数据

编写查询前，请查阅 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 nhl get_scoreboard
sports-skills nhl get_standings --season=2025
sports-skills nhl get_teams

重要：执行任何查询前

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

• 赛季年份根据系统提示中的 currentDate 推导，切勿硬编码。
• 如果只提供了球队名称，请先调用 get_teams 确定球队 ID，再使用针对球队的命令。

选择赛季

根据系统提示中的日期推导当前年份（例如，currentDate: 2026-02-18 → 当前年份为 2026）。

• 如果用户指定了赛季，则按原样使用。
• 如果用户说“当前”、“本赛季”或未指定赛季：NHL 赛季从 10 月持续到次年 6 月。如果当前月份是 10 月至 12 月，当前赛季年份与当前年份相同。如果当前月份是 1 月至 6 月，当前赛季于上一日历年开始（使用该年份作为赛季年份）。
• **示例：**当前日期为 2026 年 2 月 → 当前赛季于 2025 年 10 月开始 → 使用赛季 2025。

命令

命令	说明
get_scoreboard	NHL 实时／近期比分
get_standings	按联盟和分区查看排名
get_teams	所有 NHL 球队
get_team_roster	球队完整名单
get_team_schedule	指定球队的赛程
get_game_summary	详细技术统计和得分进球记录
get_leaders	NHL 统计数据领先者
get_news	NHL 新闻文章
get_play_by_play	比赛完整逐场记录
get_schedule	指定日期的比赛（不支持按赛季筛选；参见 get_team_schedule）
get_injuries	所有球队的伤病报告
get_transactions	近期球员交易
get_futures	未来赛果／赔率市场
get_team_stats	球队统计档案
get_player_stats	球员统计档案
find_nhl_player	按姓名搜索 NHL 球员名录
get_nhlstats_schedule	通过 NHL API 获取比赛；球队赛季数据可追溯至 Original Six 时代，并提供 NHL 比赛 ID
get_nhlstats_player_stats	通过 NHL API 获取球员跨联赛的逐赛季职业生涯数据
get_nhlstats_player_game_log	通过 NHL API 获取一名球员某个赛季的比赛记录（对手、主／客场、结果、统计数据）
get_nhlstats_play_by_play	逐场记录，包含冰上 x/y 坐标、区域和射门类型
get_nhlstats_boxscore	通过 NHL API 获取完整技术统计（冰上球员和守门员）
get_nhlstats_standings	排名，可查询当前或任意历史日期（可追溯至 1917 年）
get_nhlstats_leaders	按类别查看冰上球员和守门员的领先数据

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

同时使用 ESPN 和 NHL API

get_nhlstats_* 命令读取 api-web.nhle.com——NHL 当前使用的 API。 （已停用的 statsapi.web.nhl.com 是大多数社区文档仍在介绍的 API， 但现在已无法解析。）它提供了 ESPN 不具备的分析数据：冰上射门坐标、跨联赛职业生涯数据、守门员排名，以及可追溯至 Original Six 时代的历史数据。这两个来源使用彼此无关的 ID 系统：

• 比赛 ID。 NHL ID 为 10 位数字，编码了赛季／类型／比赛 （2023030417）；ESPN 使用 9 位数字的赛事 ID（401559593）。没有可共用的列——请按比赛日期和球队联接。
• 球队缩写。 有 5 支球队的缩写不同：ESPN 使用 LA／NJ／SJ／TB／UTAH，NHL 使用 LAK／NJD／SJS／TBL／UTA。每个 get_nhlstats_* 球队筛选器都接受任一种写法，且行中同时包含两种缩写（team_abbreviation、 team_abbreviation_espn）。
• 球员 ID。 NHL 球员 ID（8478402）与 ESPN 运动员 ID 彼此无关。请使用 find_nhl_player 查询姓名；不带重音符号的拼写也能匹配带重音符号的姓名（输入 "stutzle" 可找到 "Tim Stützle"）。
• 职业生涯数据行涵盖多个联赛。 get_nhlstats_player_stats 会返回球员效力过的每个联赛的数据行，每行都标有 league 和 is_nhl——汇总职业生涯数据前，请筛选 is_nhl。赛季中途被交易的球员，每支球队各有一条 NHL 数据行，另有一条 team: "TOTAL" 数据行（is_total: true，汇总计数型数据，省略率类数据）；汇总时请跳过 is_total 行。
• 赛季。 传入起始年份（season=2024 表示 2024-25 赛季）。也接受 NHL 格式（"20242025"）。
• 比赛如何决出胜负。 status 是 NHL 的比赛状态（任何已结束比赛均为 OFF／FINAL）。赛程数据行和比赛数据统计表中的 decided_by 为 REG、OT 或 SO（比赛结束前为 null）。点球大战后的比分遵循官方结果：胜方记 1 球（1-1 的比赛在点球大战后以 2-1 获胜）。
• 封堵射门。 在 get_nhlstats_play_by_play 中，blocked-shot 行里的 team_id 和 player 指射手（NHL 事件的归属方）；比赛数据统计表中的 blockedShots 则记在防守方名下，防守球员和球队分别由 blocking_player 和 blocking_team_id 表示。统计封堵数时，请按 blocking_team_id 计数。

示例

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

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

示例 2：分区排名 用户说：“显示东部联盟排名” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_standings(season=<derived_year>)
3. 筛选东部联盟的数据 结果：东部联盟排名，包含胜-负-加时负（W-L-OTL）、积分、常规时间胜场数

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

1. 调用 get_team_roster(team_id="21") 结果：完整的枫叶队名单，包含姓名、位置、球衣号码、惯用手（射门／接球）

示例 4：比赛数据统计表 用户说：“显示昨晚棕熊队比赛的完整数据统计表” 操作：

1. 调用 get_scoreboard(date="<yesterday>") 查找 event_id
2. 调用 get_game_summary(event_id=<id>) 获取完整比赛数据统计表 结果：完整的比赛数据统计表，包含每位球员的数据和得分过程

示例 5：斯坦利杯夺冠赔率 用户说：“斯坦利杯夺冠赔率是多少？” 操作：

1. 调用 get_futures(limit=10) 结果：夺冠热门球队及其赔率

示例 6：球员数据 用户说：“显示 Connor McDavid 的数据” 操作：

1. 根据 currentDate 推算赛季年份
2. 调用 get_player_stats(player_id="3895074", season_year=<derived_year>) 结果：按类别列出的赛季数据，包含数值、排名和场均数据

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

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

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

错误处理

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

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

故障排除

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

错误：按 ID 找不到球队
原因：使用了错误或过时的 ESPN 球队 ID
解决方案：调用 get_teams，获取包含所有 NHL 球队及其 ID 的最新列表（西雅图海妖队和犹他猛犸队等扩军球队的 ID 不连续）

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

错误：休赛期——记分牌返回 0 场赛事
原因：休赛期（7 月至 9 月）没有安排比赛
解决方案：改用 get_standings 或 get_news；使用 get_schedule 查找赛季恢复时间