cricket-data

板球数据（ESPN + Cricsheet）

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

快速入门

建议优先使用 CLI，以避免 Python 导入路径问题。共有两个后端：ESPN（接近实时）和 Cricsheet（历史数据）。

# ESPN backend (live-ish) — discover series first, then use its numeric ID
sports-skills cricket get_series
sports-skills cricket get_scoreboard --series_id=8048
sports-skills cricket get_standings --series_id=8048
sports-skills cricket get_game_summary --series_id=8048 --event_id=1535465
sports-skills cricket get_news --series_id=8048

# Cricsheet backend (historical, completed matches) — uses letter codes
sports-skills cricket get_competitions
sports-skills cricket get_matches --competition=ipl --season=2026
sports-skills cricket get_match_deliveries --competition=ipl --match_id=1473508
sports-skills cricket get_player_stats --competition=ipl --player="V Kohli"
sports-skills cricket find_player --name=kohli

重要：执行任何查询前

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

• ESPN 系列赛 ID 按系列赛划分，而非按联赛划分。 请务必先通过 get_series 查找。周期性赛事的 ID 每个赛季都会变化（例如，每届 IPL 赛季都有不同的 ID）。切勿将 ID 写死——示例中的 8048 仅供说明，并非固定值。
• 存在两套 ID 空间。 get_series 返回 ESPN ID（实时、数字形式，例如 8048）。get_competitions 返回 Cricsheet 代码（历史数据、字母代码，例如 ipl）。两者彼此无关，但在比赛级别可以关联：Cricsheet 的 match_id 等于 ESPNcricinfo 比赛 ID，因此可以桥接这两个后端。
• Cricsheet 仅包含已结束的比赛（比赛结束后约有 1 天延迟）。对于正在进行或即将开始的比赛，请使用 ESPN 命令（get_scoreboard、get_series）。
• get_player_stats 需要使用 Cricsheet 中准确的姓名拼写（例如 "V Kohli"，而不是 "Virat Kohli"）。请先用 find_player 确认拼写。
• 没有 ICC 排名——目前没有免费的数据源（v1 限制）。系列赛积分榜由 get_standings 提供，但大多数双边巡回赛不会发布积分榜，因此结果为空（只有联赛或小组赛制的赛事会发布积分榜）。
• 每天首次调用某项赛事的 Cricsheet 数据时，会下载一个 zip 文件。 大型赛事（测试赛、ODI、IPL）的文件有几十 MB。zip 文件会在 ~/.cache/sports-skills/cricsheet/ 缓存 24 小时；当天后续调用会很快。

Agent 可以运行 scripts/validate_params.sh，在查询前预先验证 --competition、--series_id 和 --date。

命令

ESPN 后端（接近实时）

命令	必需参数	说明
get_series	—	列出当前活跃的板球系列赛、ESPN 系列赛 ID 和实时赛事
get_scoreboard	series_id（可选 date）	系列赛的比赛、比分和状态
get_standings	series_id	系列赛积分榜（大多数双边巡回赛没有积分榜）
get_game_summary	event_id、series_id（活跃系列赛可选）	比赛详情：阵容、领先者、比赛卡、每局记分卡、场地信息
get_news	series_id	系列赛相关新闻

Cricsheet 后端（历史数据，ODC-BY 1.0）

命令	必需参数	说明
get_competitions	—	列出 Cricsheet 赛事代码
get_matches	competition（可选 season）	某项赛事已结束的比赛，按时间从新到旧排列
get_match_deliveries	competition、match_id（可选 innings）	某场已结束比赛的逐球记录
get_player_stats	competition、player（可选 season）	某位球员的击球和投球汇总统计
find_player	name	搜索 Cricsheet 球员注册表；返回 ESPNcricinfo ID 映射

日期可使用 YYYYMMDD 或 YYYY-MM-DD 格式。season 为起始年份（例如，2020 会匹配 Cricsheet 的 "2020/21"）。完整参数列表和返回数据结构请参阅 references/api-reference.md。

工作流

检查实时／近期系列赛

1. get_series → 选择系列赛并记下其 series_id。
2. get_scoreboard --series_id=<id> → 按状态和比分展示比赛。
3. 查看某场比赛的详情：get_game_summary --series_id=<id> --event_id=<id>。

积分榜（联赛制赛事）

1. get_series → 找到赛事的 series_id。
2. get_standings --series_id=<id>。如果结果为空，说明这是没有公布积分榜的双边巡回赛。

历史球员统计

1. find_player --name=<substring> → 确认 name 的准确拼写。
2. get_player_stats --competition=<code> --player="<exact name>"（可选 --season）。

逐球历史记录

1. get_matches --competition=<code> [--season=<year>] → 查找 match_id。
2. get_match_deliveries --competition=<code> --match_id=<id> [--innings=N]。

板球新闻

板球新闻按系列赛划分，没有全局动态。

1. get_series → 选择相关系列赛，并记下其 series_id。
2. get_news --series_id=<id> → 展示文章。

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

• get_player / get_player_info — 不存在。使用 find_player 确定姓名对应的球员，再用 get_player_stats 获取职业生涯数据。
• get_match — 不存在。使用 get_matches 获取历史比赛列表，或用 get_game_summary 查看一场 ESPN 比赛的详情。
• get_rankings — 不存在。目前没有免费的 ICC 排名数据源（v1 的限制）。
• get_teams / get_team_roster — 不存在。阵容包含在 get_game_summary 中。
• get_play_by_play — 不存在。对于已结束的比赛，使用 get_match_deliveries 获取逐球数据。

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

署名

Cricsheet 数据采用 ODC-BY 1.0 许可。每个 Cricsheet 响应都包含一个 attribution 字段（"Data from Cricsheet (cricsheet.org), ODC-BY 1.0"）。重新发布数据时，请保留此署名字符串。