制作一个能查赛程、近五场战绩和积分榜的足球聊天机器人

Piotr Grudzień
发布日期 阅读时间约 10 分钟
Quickchat AI 中阿森纳的三行比赛简报,旁边是显示了Free订阅的 football-data.org Account Settings页面

你正围着阿森纳客战纽卡斯尔的比赛安排周六的活动。一位在纽约的朋友想知道开球时间。这时群里又有人问起阿森纳上个客场的战绩如何。第一个问题的答案就在赛程列表里。至于第二个问题,你得先弄清楚“利物浦 0-1 阿森纳”这个比分里的进球算谁的。

你将构建 Matchday Notebook——一个能查询英超未来三场赛程、读取阿森纳近五场联赛战绩并找到其积分榜排名的足球聊天机器人。本示例的时间点设定在 2026 年 11 月 18 日。客场对阵纽卡斯尔的比赛安排在 11 月 21 日星期六 17:30 UTC 开球,也就是 纽约时间下午 12:30。

纽卡斯尔的比赛在 Native Stats 中,以及 Quickchat AI 中相应的比赛日答案 数据提供商的比赛页面和你的私人 Agent 所显示的开球时间一致。这次 Quickchat AI 对话是基于一份公共数据的历史重现记录运行的,你可以在下文复现它。

查看对阵纽卡斯尔的赛程或下载 Matchday Notebook 工具包。解压后运行 python3 replay.py,无需注册账户即可查看三场赛程、五场赛果和积分榜条目。该工具包同样包含了 Action 设置和用于连接你自己数据源的 Main Prompt。

1. 聊天机器人将关注哪个俱乐部和赛事?

首先锁定俱乐部和联赛。阿森纳的联赛战绩可能会因你是否算入周中的欧战而有所不同。在本记事本中,阿森纳指球队 57,联赛指英超联赛 2021,其赛事代码为 PL。

  1. 打开 football-data.org 注册表单。输入你的名字和电子邮件地址,接受条款并选择 Create account。在覆盖范围列表中检查你的联赛。免费套餐包括英超联赛,提供延迟的赛程和比分。

football-data.org 注册表单,包含名字和电子邮件字段、Create account 按钮和 Free Tier 详情 请使用一个你能查收的电子邮件地址。注册后,football-data.org 会将 API 密钥发送到该地址。免费套餐允许每分钟10次请求。

如果你已有账户,请用你的电子邮件和 API 令牌登录。如果你需要令牌的另一份副本,请使用你注册的地址通过电子邮件请求。请保管好令牌,以便在第2步的受保护标头中使用。

football-data.org Account Settings页面显示了Free订阅和部分Available competitions列表 在 Subscription 下查看你的套餐,并在 Available competitions 下查找你的联赛。此截图显示了欧洲冠军联赛 (CL) 和德国足球甲级联赛 (BL1)。

  1. 要关注其他俱乐部,请在赛事的球队列表中查找,例如 GET /v4/competitions/PL/teams。在下面的比赛请求中使用返回的球队 ID 和赛事 ID。v4 快速入门包含这两种查找。
  2. 创建 Quickchat AI Agent,将其命名为 Matchday Notebook,并在测试期间保持私密状态。你需要有可用的点数来进行对话和模拟。打开 Identity → AI Persona → Main Prompt 并粘贴以下指令。截图和可复制的设置均使用英文界面。

阿森纳在 Native Stats 的俱乐部页面和 Matchday Notebook 在 Quickchat AI 的 Identity 设置 在两个地方保持相同的俱乐部。在产品中,Agent 的说明位于 Identity 下。

复制 Matchday Notebook Main Prompt
You are Matchday Notebook, an Arsenal Premier League companion. Use get_club_fixtures for the schedule, get_recent_results for form and get_league_standings for the league table. For match reads, use an inclusive UTC start date and an exclusive end date. Ask for dates when the window is unclear.

List up to the requested number of TIMED or SCHEDULED fixtures in kickoff order. Give the date, time and timezone; say when the hour is unconfirmed. Flag postponed or cancelled games separately. For form, sort FINISHED matches newest first, take up to five and read full-time scores home first. Judge wins, draws and losses from Arsenal's side. For standings, find Arsenal (team 57) in the TOTAL table. Give the season, position, games played and points.

Keep answers short. Link a match to https://native-stats.org/match/ID using its returned ID, and the Premier League table to https://native-stats.org/competition/PL/. Attribute football-data.org, give the relevant date and identify any snapshot as a snapshot. Quote a retrieval time only if supplied. Keep null scores unknown. Report empty windows, missing scores and failed reads accurately. Stop after a rate limit. Do not predict scores.

2. 如何获取阿森纳的下一场比赛?

我们先从能回答群聊中开球时间问题的 Action 入手。一个请求就能返回对阵双方、预定时间和比赛状态。这里的状态筛选器先不设限制,这样即使比赛延期也能显示出来。状态为 TIMED 的记录会有一个确切的开球时间。对于状态为 SCHEDULED 的记录,则要告知用户具体时间仍有待确认。

  1. 打开 Actions & MCPs → Add Action → API Action → Create manually。将 API Action Name 设置为 get_club_fixtures,将 When to run 设置为 AI decides。在 What to ask the user first 下,添加所需的 Text 输入 date_from 和 date_to,两者都设置为 No default。它们的描述分别是“要包含的第一个 UTC 日期,YYYY-MM-DD”和“要排除的第一个 UTC 日期,YYYY-MM-DD”。
  2. 对于 API Endpoint,选择 GET 并输入以下 URL。打开 Query Params 并将 competitions 设置为字面值 2021。添加 dateFrom 和 dateTo。对于每个值,使用 Add AI Data → Parameters 插入匹配的日期输入。将 Body 留空。
  3. 将以下描述粘贴到API Action Description下方,然后保存 Action。在Headers下方,凭据将位于只写 X-Auth-Token 行中。在您的第一个请求之前进行设置。添加第二个普通标头,其中 Accept 作为键,application/json 作为值。在所有三个 Action 上使用相同的两个标头。
https://api.football-data.org/v4/teams/57/matches

football-data.org Team matches 路由和 Quickchat AI GET 端点,其中 Query Params 用于 2021 赛季和两个日期 按照提供商参考资料中的球队比赛路径填入 Action。阿森纳固定在 URL 中,联赛在 Query Params 中,两个日期则来自对话。

复制赛程 Action 的描述
Use for Arsenal's upcoming Premier League fixtures in the requested date window. Sort by utcDate ascending. Show TIMED or SCHEDULED matches and flag postponements or cancellations separately. State the window if fewer fixtures are returned.

提供商的请求示例将 API 密钥放在 X-Auth-Token 中。在 get_club_fixtures 的 Headers 中使用相同的标头名称。

公开的 football-data.org Sign in 表单、v4 X-Auth-Token 示例以及 Quickchat AI 中的 Headers 选项卡 登录表单需要你的电子邮件和 API 令牌。在 Quickchat AI 中,只有令牌需要填入受保护的 X-Auth-Token 行。

私密输入令牌。 仪表板可以替换保存的密钥。要首先将该标头设置为只写,每个 Action 使用一次账户连接。使用 Quickchat AI 设置指南 在 ChatGPT 或 Claude 中连接你的账户。要求连接的助手使用以下说明准备带有无害标记的标头。然后自己打开 Action 的 Headers 选项卡,将 同一行 中的值替换为你的原始 football-data.org 令牌,然后选择 Save changes。重新打开编辑器并检查它是否显示 [redacted]。将令牌保存在仪表板中,不要在对话中显示。

On Matchday Notebook, set the X-Auth-Token header of get_club_fixtures to the literal value REPLACE_IN_DASHBOARD with is_secret=true. Preserve the rest of the settings. Read the Action back and confirm that the header is secret and the value is [redacted]. Stop before testing.

“赛程” Action 中的 Headers 显示 X-Auth-Token 的值已隐去 这是已保存的标头。服务商要求只提供令牌本身,不带 Bearer 前缀。

尝试首次读取。 在 Test Response → Test the API 中,提供开始日期和你所需时段结束日期的后一天。然后启用该 Action,并在 AI Preview 中请求该时段内接下来的三场联赛赛程。如需在线构建,请选择未来的日期。存档示例使用了 2026-11-18 和 2026-12-03,所以12月2日晚的比赛也被计入。你可以打开最近一场比赛的源链接进行核对。v4 日期筛选参考解释了结束日期不包含在内。

11 月 18 日(含)至 12 月 3 日(不含)之间的三个比赛日期 数据重演中,11月21日是客场对阵纽卡斯尔,11月29日是主场对阵曼城,12月2日是客场对阵布伦特福德。如果请求在12月2日截止,对阵布伦特福德的比赛就会被漏掉。

3. 如何读取阿森纳最近五场比赛的战绩?

本例中最关键的一场比赛是 利物浦 0-1 阿森纳。如果聊天机器人总是把第一个数字当作阿森纳的得分,就会把一场客场胜利误判为失利。所有比分都应保持“主队-客队”的顺序,并根据球队ID来判断阿森纳的赛果。

  1. 创建第二个名为 get_recent_results 的 API Action。使用相同的 GET 端点、日期输入、日期芯片和赛事筛选器。添加查询行 status,其字面值为 FINISHED。
  2. 设置以下描述。为 get_recent_results 重复只写标头设置,检查掩码并启用 Action。
  3. 请求指定时段内最近的五场联赛。例如,使用2026年10月1日到11月17日。先按 utcDate 排序,再取五场。如果该时段只返回三场比赛,就显示这三场,并询问用户是否需要继续向更早查询。
复制“战绩” Action 的描述
Use for Arsenal's recent Premier League form in the requested date window. Sort FINISHED matches newest first, then take up to five. Use both full-time goals and the home and away team IDs to judge each result from Arsenal's perspective.

源比赛页面显示利物浦 0-1 阿森纳,并标出阿森纳的客场得分 先在客队一侧找到阿森纳,再读取客队进球数。利物浦的零分代表被零封。

从最近的比赛开始看。 阿森纳 1-0 击败赫尔城,客场 1-0 战胜利物浦,2-0 击败埃弗顿,客场 1-0 战胜诺丁汉森林,2-1 击败利兹联。这就是五连胜,进7球失1球。由于获胜方排在第二位,对阵利物浦的比赛记录是一个很好的测试用例。

在保存的测试数据中,返回的列表特意以利兹联的比赛开始,以赫尔城的比赛结束。按开球时间戳排序会将赫尔城的比赛移至回复的顶部。打开聊天旁边的 Action 响应,并比较两个列表中第一场和最后一场比赛。

按日期顺序显示的阿森纳五场已结束比赛,包含主客场比分 五场胜利可能隐藏一个重要细节。其中两场是客场比赛,所以获胜的数字在右侧。

4. 联赛排名和积分从哪里来?

五连胜告诉你过去几周的战绩。但联赛排名还取决于此前的所有比赛以及其他所有球队的赛果。请为你的智能体提供一个单独的“积分榜” Action。

  1. 将其命名为 get_league_standings。选择 GET,粘贴下方的端点,并将输入、查询参数和正文留空。使用 AI decides,添加下方的描述,并为该 Action 重复只写标头的设置。
  2. 在 Test Response 中,于 standings 内查找 type 为 TOTAL 的条目。在该条目的 table 中,找到 team.id 等于 57 的那一行。启用该 Action ,然后问“阿森纳在英超积分榜上排第几?”
  3. 将 position、playedGames 和 points 与同一赛季和日期的源数据进行比较。11月18日,Native Stats 上的英超积分榜显示第1名,已赛10场,27分。随着其他俱乐部进行比赛,你当前的积分榜会发生变化。
https://api.football-data.org/v4/competitions/PL/standings
复制积分榜Action描述
Use for the current Premier League table. Find team ID 57 in standings where type is TOTAL. Report season, position, playedGames and points. If the row is missing, say the position is unavailable.

阿森纳在英超积分榜上的第一名行以及笔记本使用的字段 在TOTAL中横向阅读一行。27分涵盖了快照中的全部十场联赛。

5. 您能追溯比赛日简报的来源吗?

开始一段新的 AI Preview 对话。先问接下来三场赛程,然后追问“我们最近五场联赛踢得怎么样?”,给出查询时段,再问“那我们现在排在积分榜什么位置?”在 Inbox 中,为每个回答打开已调用的 Action 标记。通过 Action 的 View logs,你可以比较请求参数和响应数据与球迷看到的内容。构建 API Action 的指南说明了在哪里可以找到这些控件。

要获取文章开头展示的综合比赛日摘要,请使用下方问题和已保存示例中的日期。如需获取最新摘要,请使用未来的日期查询赛程,使用最近的日期查询赛果。

Arsenal briefing for 18 Nov 2026: next away kickoff this week (UTC), last five since 1 Oct, and table position. Three short lines.

Quickchat AI中的赛程Action调用及其请求和返回的比赛记录 检查调用中的日期和比赛ID。在本地数据重演中,560651 是对阵纽卡斯尔的赛程。

为了可重复检查,打开Conversations → Testing,创建一个数据集并保存这三个问题。添加下面显示的两个边界问题。更改Action描述后运行数据集,并检查调用和回复。使用受控响应来测试罕见状态或错误。单独的假设问题测试答案的措辞。

Quickchat AI 中的 Matchday Notebook 数据集,包含关于赛程、近期战绩、积分榜和边界问题的提问 每次编辑后使用相同的问题。客场结果会捕捉到主场测试会遗漏的得分错误。

测试用例球迷应该听到的内容
一场比赛延期,双方进球数均为 null。这是平局吗?比赛已延期,没有比分记录。
成功搜索返回一个空的matches列表。整个赛季都是空的吗?在该时段内没有找到比赛。请告知你搜索的日期。
提供商返回401或403。查询失败。请检查已保存的令牌和赛事覆盖范围。
提供商返回429。已达到请求次数上限。请稍后重试。

Quickchat AI返回空结果,表示请求成功但未找到任何比赛 即使窗口为空,也代表请求成功。此时,AI助手可以建议用户放宽日期范围。

如需再次核对已更改的开球时间,请参考联赛发布的赛程变更通知。请一并记下原定日期、时区以及您的查询日期。免费数据源的更新可能落后于转播方通知的变更,当球迷需要根据查询结果来安排周末时,这一点尤其重要。

Football data provided by the Football-Data.org API. 本文中的旧示例使用了该服务商的公开Native Stats页面。请参阅订阅方案和请求频率限制以了解当前的数据覆盖范围和更新频率。

常见问题

我可以使用哪个足球 API 来构建赛程聊天机器人?

football-data.org v4 API 提供其所涵盖赛事的赛程、赛果和积分榜。使用球队比赛接口可获取赛程和近期战绩,使用赛事积分榜接口可获取联赛排名。

football-data.org 的免费套餐是否提供实时比分?

免费套餐包含延迟更新的比分和赛程、所涵盖赛事的联赛积分榜,以及每分钟 10 次的 API 请求上限。每个回答都应注明来源和日期。如需实时比分,请检查你的套餐计划。

如何将阿森纳更改为其他球队?

在 football-data.org 中找到该俱乐部的球队 ID 和其所在赛事 ID。在两个比赛 Action 中替换球队 ID 57,更改数字赛事筛选器和积分榜 URL,然后更新机器人指令中的俱乐部名称和球队 ID。用一场你熟悉的比赛来测试结果。

如何从球队的角度获取最近五场比赛?

在指定日期范围内筛选已结束的联赛比赛,按开球时间从新到旧排序,最多取五场。对于每个比分,在判断胜、平、负之前,检查你的球队是主场还是客场。如果符合条件的比赛少于五场,则显示找到的场次。

推迟的比赛中,空白比分意味着什么?

空白比分意味着提供商没有提供该队的进球总数。保持比赛状态可见,比分未知。无进球平局需要一场已结束的比赛,其中记录了两个零。

如何将足球开球时间转换为我的时区?

从比赛的 UTC 开球时间开始,使用命名时区,例如 America/New_York,并在答案中保留日期。夏令时和日历日期的变化都可能影响显示的时间。

Quickchat AI Quickchat AI Ask Quickchat AI a question