infometa SKILL.md - worldcup-api
概述
worldcup-api 是对 API-Football v3 的薄封装，通过 curl 调用REST API获取2026美加墨世界杯数据。
只管调API拿原始数据，不管数据组装和输出格式。 组装逻辑由Agent在AGENTS.md各路由中定义。
认证
# API Key写死在这里，用户无需配置
API_KEY="6e64675f99537c10f8fb793fd8e818d2"
BASE_URL="https://v3.football.api-sports.io"
# 认证头（不是x-rapidapi-key，是x-apisports-key）
curl -H "x-apisports-key: $API_KEY" "$BASE_URL/fixtures?league=1&season=2026"
额度
- Mega套餐：150,000次/天
- 赛季2026全解锁（赛程/球员/榜单/积分榜/H2H均可用）
- 预估日均消耗：~19次，额度极其充裕
- 429（限流）或402（额度用完）→ 触发降级（几乎不会触发）
端点调用
1. 查赛程
# 按日期
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures?league=1&season=2026&date=2026-06-23"
# 按分组
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures?league=1&season=2026&group=A"
# 按球队
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures?team=26&season=2026"
返回关键字段：
fixture.id— 比赛ID（复盘用）fixture.date— 开球时间（UTC，需+8转北京时间）fixture.venue.name/city— 场馆fixture.status.short— NS(未开始)/1H/HT/2H/FTteams.home/away.name— 球队名goals.home/away— 比分score.halftime/fulltime— 半场/全场比分
2. 查实时比赛
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures?live=all"
返回：所有进行中的比赛，结构同赛程但自带 events
events字段：
time.elapsed— 发生时间（分钟）team.name— 哪个队player— 球员名assist— 助攻球员（如有）type— Goal / Card / substdetail— Normal Goal / Penalty / Yellow Card / Red Card / Missed Penalty / VAR Decisioncomments— 犯规原因等
⚠️ 字段含义澄清（重要）：
detail: "Missed Penalty"= 点球没进，不是数据缺失。Agent应将其解读为"球员罚丢点球"，而非"API未返回该数据"。detail: "Penalty"= 点球罚进。- 同理，events中
type: "Goal"且detail: "Missed Penalty"是矛盾的吗？不矛盾——API先记录一次Penalty事件，如果没进则detail标为Missed Penalty，表示这是一次未命中的点球尝试。 - 其他含"missed"的字段（如
shots.missed在statistics中）同理："missed" = 射偏/未命中，是有效的统计数据，不是数据缺失。
实时能拿到：比分、状态、已用时间、进球、黄红牌、换人 实时拿不到：控球率、射门数（赛后用端点3获取）
3. 查单场完整数据（瑞士军刀端点）
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures?id=979139"
一次调用返回全量数据：
| 字段 | 内容 | 示例数据量 |
|---|---|---|
| events | 进球/换人/黄红牌/点球 | ~35条 |
| lineups | 两队首发+替补+阵型+教练 | 2队 |
| statistics | 控球率/射门/角球/犯规等 | 17项/队 |
| score | 半场/全场/加时/点球 | — |
⚠️ events中 detail: "Missed Penalty" = 点球没进，不是数据缺失。详见端点2的字段说明。
statistics 17项：
Shots on Goal, Shots off Goal, Total Shots, Blocked Shots, Shots insidebox, Shots outsidebox, Fouls, Corner Kicks, Offsides, Ball Possession, Yellow Cards, Red Cards, Goalkeeper Saves, Total passes, Passes accurate, Passes %
lineups 结构：
formation— 阵型（如 "4-3-3"）coach— 教练名startXI[11]— 首发11人substitutes[~12]— 替补
4. 查球队信息
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/teams?id=26"
返回：name, code, logo, country
5. 查球员
# 必须带team或league参数，否则报错
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/players?team=26&season=2026"
返回：name, age, position, games, goals, assists
6. 查积分榜
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/standings?league=1&season=2026"
返回：各组积分榜，含 group, position, team.name, points, won/draw/lost, goalsFor/Against
7. 查射手榜
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/players/topscorers?league=1&season=2026"
返回：player.name, statistics.goals, statistics.assists, team.name
8. 查历史交锋
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures/headtohead?h2h=26-2"
返回：历史交锋记录列表，结构同赛程
9. 查助攻榜
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/players/topassists?league=1&season=2026"
返回：player.name, statistics.assists, statistics.goals, team.name
10. 查黄牌榜
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/players/topyellowcards?league=1&season=2026"
返回：player.name, statistics.cards.yellow, team.name
11. 查红牌榜
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/players/topredcards?league=1&season=2026"
返回：player.name, statistics.cards.red, team.name
12. 查赛程轮次
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/fixtures/rounds?league=1&season=2026"
返回：所有轮次名称列表，如 Group Stage - 1, 8th Finals, Quarter-finals 等
13. 查联赛信息
curl -s -H "x-apisports-key: $API_KEY" \
"$BASE_URL/leagues?id=1"
返回：name, type, logo, seasons（历史赛季列表）
错误处理
| HTTP状态 | 原因 | 处理 |
|---|---|---|
| 429 | 限流 | 降级 |
| 402 | 额度用完 | 降级 |
| 401 | Key无效 | 检查Key |
| 404 | 参数错误 | 检查参数 |
| 超时 | 网络 | 重试1次后降级 |
降级触发条件
当API返回429/402/超时/网络错误时：
- 不再重试API
- 判断当前路由能否web_search兜底（见AGENTS.md降级策略总表）
- 能兜 → web_search → 标注来源
- 不能兜 → 回复兜底文案
实测参考数据
以下数据来自2026-06-18测试（免费层），2026-06-23升级Mega后全端点解锁 2026-06-23 Pro验证：16/16端点全部OK，season=2026返回72场比赛
2022决赛（fixture_id=979139）
events（35条）：
[23'] Goal Messi (Argentina) — Penalty
[36'] Goal Di María (Argentina) — Normal Goal — 助攻: Mac Allister
[41'] subst Giroud→Thuram (France)
[80'] Goal Mbappé (France) — Penalty
[118'] Goal Mbappé (France) — Penalty
[120+3'] Goal Messi (Argentina) — Normal Goal
statistics（17项/队）： 阿根廷：控球率54%、射门20（射正10）、角球6、犯规26、黄牌5、传球635（准确525/83%） 法国：控球率46%、射门10（射正3）、角球2、犯规23、黄牌4
lineups： 阿根廷 4-3-3（教练Scaloni），法国 4-2-3-1（教练Deschamps）
2026小组赛实时（乌兹别克 vs 哥伦比亚）
status: 2H, elapsed: 51'
比分: 0-1 (halftime: 0-1)
events:
[7'] Card J. Mojica (Colombia) — Yellow Card — "Tripping"
[34'] Card A. Khusanov (Uzbekistan) — Yellow Card
[40'] Goal D. Munoz (Colombia) — Normal Goal — 助攻: L. Diaz
[46'] subst Urunov→Khamdamov (Uzbekistan)
[46'] subst Nasrullaev→Sayfiev (Uzbekistan)