xctf-data

XC/TF 数据（TFRRS — NCAA 越野跑与田径）

编写查询前，请查阅 references/api-reference.md，了解参数、URL 约定和返回结构。

设置

首次使用前，请检查 CLI 是否可用：

which sports-skills || pip install sports-skills

如果 pip install 失败，请从 GitHub 安装：

pip install git+https://github.com/machina-sports/sports-skills.git

需要 Python 3.10+。无需 API 密钥。所有数据均来自 TFRRS 公开页面和 The Stride Report RSS feed。

快速开始

CLI（推荐）：

sports-skills xctf get_athlete_profile --athlete_id=9230145 --school=BYU --name=Jane_Hedengren
sports-skills xctf get_news --limit=5

Python SDK：

from sports_skills import xctf

profile = xctf.get_athlete_profile(
    athlete_id="9230145",
    school="BYU",
    name="Jane_Hedengren",
)

重要：执行任何查询前

必须提供全部三个参数，且必须与运动员的 TFRRS URL 完全匹配：

https://www.tfrrs.org/athletes/{athlete_id}/{school}/{name}.html

• athlete_id — 数字 ID（例如 9230145）
• school — 学校的 slug，使用下划线而非空格（例如 BYU）
• name — 运动员姓名的 slug（例如 Jane_Hedengren）

切勿猜测 slug。请前往 tfrrs.org 上的运动员页面并复制 URL，以查找这些值。

命令

命令	说明
search_athlete	按姓名搜索当前队伍名单；返回 athlete_id、school 和 name slug，供 get_athlete_profile 使用。自动搜索男女运动员。仅包含当前运动员 — 已毕业运动员需使用 TFRRS 直达 URL
get_athlete_profile	运动员姓名、学校、参赛资格、所有个人最佳成绩（PR）以及完整的逐赛季比赛结果
get_team_roster	队伍完整的 XC 和／或 TF 名单
get_meet_results	TFRRS 比赛中的所有项目成绩和队伍得分
get_news	The Stride Report（thestridereport.com）的近期 XC/TF 文章

完整参数详情和返回结构请参阅 references/api-reference.md。

示例

示例 1：查询现役运动员的个人最佳成绩 用户说：“Jane Hedengren 的个人最佳成绩是什么？” 操作：

1. 调用 search_athlete(name="Jane Hedengren", school="UT_college_f_BYU") 结果：data.matches 包含带有 athlete_id、school 和 name slug 的条目
2. 调用 get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren") 结果：data.prs 包含各项目的所有个人纪录（例如 {"1500": "4:10.24", "5000": "14:44.79", "6K (XC)": "18:29.6", ...}）

示例 2：查询跑步运动员的越野赛季 用户说：“显示 Jane Hedengren 2025 年越野赛季的成绩” 操作：

1. 调用 search_athlete(name="Jane Hedengren", school="UT_college_f_BYU")
2. 使用匹配到的运动员参数调用 get_athlete_profile
3. 筛选 data.meets，保留 date 在 2025 年秋季（2025 年 9 月至 11 月）的条目 结果：比赛列表，包含日期、项目、成绩和名次

示例 3：已毕业或转学的运动员 用户说：“Katelyn Vuong 在 UC Davis 的个人最佳成绩是什么？” 操作：

1. 调用 search_athlete(name="Katelyn Vuong", school="CA_college_f_UC_Davis") 结果：data.matches 为空——该运动员已毕业
2. 告诉用户：“Katelyn Vuong 不在 UC Davis 当前的运动员名单中。请在 tfrrs.org 上找到她的个人资料 URL（例如，搜索 'Katelyn Vuong UC Davis tfrrs'）并分享给我。”
3. 用户提供：https://www.tfrrs.org/athletes/7899206/UC_Davis/Katelyn_Vuong.html
4. 从 URL 中提取参数，并调用 get_athlete_profile(athlete_id="7899206", school="UC_Davis", name="Katelyn_Vuong") 注意：TFRRS 会为越野赛和田径赛分别创建个人资料。如果两者都存在，请获取两个 ID，以完整查询个人最佳成绩。

示例 4：查询队伍当前阵容 用户说：“显示 UC Davis 女子越野队的阵容” 操作：

1. 调用 get_team_roster(school="CA_college_f_UC_Davis", sport="xc") 结果：运动员列表，包含姓名、年级和个人资料 slug

示例 5：查询一场比赛的成绩 用户说：“显示 Stanford Invitational 的比赛成绩” 操作：

1. 在 tfrrs.org 上找到这场比赛，并从 URL 中复制 meet_id 和 slug（例如 tfrrs.org/results/95890/Stanford_Invitational）
2. 调用 get_meet_results(meet_id="95890", slug="Stanford_Invitational") 结果：该比赛的所有项目成绩和队伍得分。每条成绩包含 place、name、year、team、marks（记录的成绩，例如 ["9.72"] 或 ["DNF"]）以及 score（队伍得分；未计分的比赛中为 null）；如果项目包含 wind、conversion（英制成绩）和接力赛 athletes，也会一并显示。

对于越野比赛（URL 格式如 tfrrs.org/results/xc/28714/Gans_Creek_Classic），请传入 sport="xc"：get_meet_results(meet_id="28714", slug="Gans_Creek_Classic", sport="xc")。XC 的 team_scores 按比赛名称编制索引。XC ID 使用独立编号范围，因此如果不传入 sport="xc"，XC ID 会返回一场无关的田径比赛（并在 warnings 中标记）。

示例 6：获取最新的越野赛／田径赛新闻 用户说：“最新的大学田径新闻是什么？” 操作：

1. 调用 get_news(limit=10) 结果：The Stride Report 的近期文章，包含标题、日期、摘要和链接

不存在的命令——绝不可调用

• get_team_rankings——不存在。个人数据请使用 get_athlete_profile。
• search_athletes——不存在。正确的命令是 search_athlete（末尾不带 's'）。
• fetch_news——不存在。正确的命令是 get_news。

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

错误处理

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

1. 对于 get_athlete_profile：确认 athlete_id、school 和 name 与 TFRRS URL 完全一致（区分大小写）
2. 对于 search_athlete：检查队伍的 TFRRS 页面 URL，确认队伍 slug 正确
3. 对于 get_meet_results：确认 meet_id 和 slug 与赛事的 TFRRS URL 完全一致
4. 对于 get_team_roster：确认学校 slug 正确
5. 对于 get_news：如果订阅源加载失败，告知用户 The Stride Report 可能暂时无法使用
6. 穷尽其他方法后，再用简洁的消息报告失败

故障排除

找不到 sports-skills 命令 运行 pip install sports-skills，或从 GitHub 安装（参见上文的设置）。

运动员个人资料出现 HTTP 404 school 或 name slug 与 TFRRS URL 不完全一致。Slug 区分大小写，并使用下划线。请直接从 tfrrs.org 复制。

prs 返回空字典 运动员的个人资料页面可能刚上线不久，或结构有所不同。请直接在 tfrrs.org 上检查 URL。

search_athlete 返回的匹配结果为空 该运动员可能已毕业或转学。有关如何处理，请参见上文示例 3。

get_meet_results 未返回任何赛事 meet_id 或 slug 可能不正确。请直接从赛事的 TFRRS URL 复制两者。如果 URL 包含 /results/xc/，请传入 sport="xc"。

get_news 失败或未返回文章 The Stride Report RSS 订阅源可能暂时无法使用。请稍后重试。

连接错误或超时 TFRRS 可能暂时无法使用。请求会自动限制为每秒 1 次，请稍等片刻后重试。