用途
volleyball-data 用于获取荷兰排球（Nevobo，即 Nederlandse Volleybalbond 荷兰排球协会）的公开数据。所有数据来自 Nevobo 开放 API，无需 API 密钥。该技能覆盖荷兰排球金字塔体系，包括顶级联赛和低级别联赛。
主要能力
该技能提供以下命令：
- get_competitions：列出所有可用赛事和联赛
- get_standings：联赛积分榜（排名、球队、场次、积分）
- get_schedule：即将进行的比赛（球队、场地、日期）
- get_results：比赛结果（比分、逐局比分）
- get_clubs：列出排球俱乐部（名称、城市、省份）
- get_club_schedule：俱乐部所有球队的即将进行的比赛
- get_club_results：俱乐部所有球队的比赛结果
- get_poules：浏览 Nevobo 小组（用于发现低级别联赛）
- get_tournaments：赛事日历
- get_news：协会新闻
预配置了荷兰排球前三个级别的 8 个联赛，competition_id 遵循 nevobo-<league>-<gender>[-<pool>] 模式：
- Eredivisie（第 1 级，8 支球队）：nevobo-eredivisie-heren、nevobo-eredivisie-dames
- Topdivisie（第 2 级，每组 10 支球队）：nevobo-topdivisie-heren-a、nevobo-topdivisie-heren-b、nevobo-topdivisie-dames-a、nevobo-topdivisie-dames-b
- Superdivisie（第 3 级，10 支球队）：nevobo-superdivisie-heren、nevobo-superdivisie-dames
对于更低级别联赛（1e/2e/3e Divisie、地区、青年、沙滩——超过 6,400 个小组），可使用 get_poules 发现。
使用方式
安装
首次使用前，检查 CLI 是否可用：
which sports-skills || pip install sports-skills
如果 pip install 失败（找不到包或 Python 版本错误），从 GitHub 安装：
pip install git+https://github.com/machina-sports/sports-skills.git
该包需要 Python 3.10+。如果默认 Python 版本较旧，请使用特定版本：
python3 --version # 检查版本
如果 < 3.10，尝试：python3.12 -m pip install sports-skills
在 macOS 上使用 Homebrew：/opt/homebrew/bin/python3.12 -m pip install sports-skills
快速开始
推荐使用 CLI，可避免 Python 导入路径问题：
sports-skills volleyball get_competitions sports-skills volleyball get_standings --competition_id=nevobo-eredivisie-heren sports-skills volleyball get_results --competition_id=nevobo-eredivisie-dames sports-skills volleyball get_schedule --competition_id=nevobo-topdivisie-heren-a
Python SDK（替代方式）：
from sports_skills import volleyball
standings = volleyball.get_standings(competition_id="nevobo-eredivisie-heren") results = volleyball.get_results(competition_id="nevobo-eredivisie-dames")
查询前的重要事项
在调用任何数据端点之前，请确认：
- competition_id 使用 references/competition-ids.md 中的有效值，切勿猜测。
- 对于俱乐部相关命令，需要有效的 Nevobo club_id（使用 get_clubs 查找，organisatiecode 字段）。
- 不要猜测俱乐部 ID 或赛事 ID。使用 get_competitions 或 get_clubs 发现它们。
不存在的命令
以下命令不存在，切勿调用：
- get_scoreboard——不存在。使用 get_results 获取近期比赛结果。
- get_rankings——不存在。排球使用 get_standings 获取联赛积分榜。
- get_team_roster——不存在。使用 get_clubs 获取俱乐部信息。
- get_player_info——不存在。此 API 不提供球员级别数据。
如果命令未在上方命令表中列出，则它不存在。
适用场景
- 查询荷兰排球 Eredivisie、Topdivisie、Superdivisie 的积分榜、赛程和比赛结果
- 查找荷兰排球俱乐部信息及其所有球队的赛程和结果
- 发现低级别联赛（1e/2e/3e Divisie、地区、青年、沙滩）的小组
- 获取赛事日历和协会新闻
限制
- 仅限当前赛季。Nevobo 会移除过去赛季的小组和导出数据，因此 get_standings、get_schedule 和 get_results 始终覆盖当前赛季。其可选的 season 参数（"2026-2027" 或 2026）对其他赛季会返回明确错误。
- 尚无日期的比赛 date 为 null；取消的比赛带有 status: "vervallen"。
- 不提供球员级别数据。
- 需要 Python 3.10+。
- 数据来自 Nevobo 公开 API，可能偶尔出现短暂中断。
错误处理
当命令失败时，不要向用户展示原始错误。应：
- 静默捕获并尝试替代方案
- 如果给出的是俱乐部名称而非 ID，先使用 get_clubs 查找 organisatiecode
- 如果 competition_id 返回无数据，使用 get_competitions 验证可用联赛
- 仅在穷尽替代方案后，以简洁消息报告失败
故障排除
- 错误：sports-skills 命令未找到。原因：包未安装。解决：运行 pip install sports-skills。如果不在 PyPI 上，从 GitHub 安装：pip install git+https://github.com/machina-sports/sports-skills.git
- 错误：积分榜返回空列表。原因：该赛事的常规赛阶段可能已结束，或赛季尚未开始。解决：使用 get_results 检查近期结果，或使用 get_poules 发现当前活跃的小组路径。
- 错误：赛程返回 0 场比赛。原因：该赛事阶段已完成，该小组没有更多比赛安排。解决：这在赛季阶段之间是正常的。检查其他联赛（Topdivisie/Superdivisie 可能仍活跃）。
- 错误：俱乐部赛程/结果返回错误。原因：club_id 可能不正确。解决：使用 get_clubs 查找有效俱乐部 ID（organisatiecode 字段，例如 "CKL5C67"）。
- 错误：连接错误或超时。原因：Nevobo API 可能暂时不可用。解决：稍等片刻后重试。该 API 是公开且无需认证的，但可能有短暂中断。