需要查询 NCAA 越野/田径运动员的 TFRRS 资料…

适用于通过 TFRRS 和 The Stride Report 查询 NCAA 越野/田径运动员资料、个人最好成绩、赛季比赛结果、团队名单、比赛结果及新闻。

适用场景

解决思路

1. 首次使用前检查 CLI 是否可用：运行 `which sports-skills || pip install sports-skills`；如果 `pip install` 失败，则运行 `pip install git+https://github.com/machina-sports/sports-skills.git`。需要 Python 3.10+，无需 API key，数据来自 TFRRS 公共页面和 The Stride Report RSS feed。
2. 在编写查询前，查阅 `references/api-reference.md`，了解参数、URL 约定和返回结构。
3. 使用 CLI（首选）：`sports-skills xctf get_athlete_profile --athlete_id=9230145 --school=BYU --name=Jane_Hedengren`；获取新闻：`sports-skills xctf get_news --limit=5`。
4. 或使用 Python SDK：`from sports_skills import xctf`，然后 `profile = xctf.get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren")`。
5. 任何查询前注意：`athlete_id`、`school`、`name` 三个参数都必需，且必须与运动员的 TFRRS URL 完全匹配：`https://www.tfrrs.org/athletes/{athlete_id}/{school}/{name}.html`；`athlete_id` 是数字 ID；`school` 是学校 slug，用下划线而非空格；`name` 是运动员姓名 slug；不要猜 slug，应通过浏览 tfrrs.org 上的运动员页面并复制 URL 获取。
6. 使用 `search_athlete` 按姓名搜索当前团队名单，返回 `athlete_id`、`school`、`name` slug 供 `get_athlete_profile` 使用；自动搜索男女；仅限当前运动员，已毕业运动员需要直接 TFRRS URL。
7. 使用 `get_athlete_profile` 获取运动员姓名、学校、资格、所有 PR 和完整逐赛季比赛结果。
8. 使用 `get_team_roster` 获取团队完整 XC 和/或 TF 名单。
9. 使用 `get_meet_results` 获取 TFRRS 比赛的所有项目结果和团队得分。
10. 使用 `get_news` 获取 The Stride Report 最近的 XC/TF 文章。
11. 示例：查询当前运动员 PR 时，先调用 `search_athlete(name="Jane Hedengren", school="UT_college_f_BYU")`，从 `data.matches` 获取 `athlete_id`、`school`、`name` slug；再调用 `get_athlete_profile(athlete_id="9230145", school="BYU", name="Jane_Hedengren")`；结果中 `data.prs` 包含按项目划分的所有 PR，例如 `{"1500": "4:10.24", "5000": "14:44.79", "6K (XC)": "18:29.6", ...}`。
12. 示例：查询某运动员的越野赛季时，先 `search_athlete` 再 `get_athlete_profile`；然后过滤 `data.meets`，取日期在 2025 年秋季（Sep–Nov 2025）的条目，得到包含日期、项目、成绩和名次的比赛列表。
13. 示例：处理已毕业或转学运动员时，调用 `search_athlete(name="Katelyn Vuong", school="CA_college_f_UC_Davis")`；若 `data.matches` 为空，告知用户该运动员不在当前名单，请用户在 tfrrs.org 找到其资料 URL 并分享；用户提供如 `https://www.tfrrs.org/athletes/7899206/UC_Davis/Katelyn_Vuong.html` 后，从 URL 提取参数并调用 `get_athlete_profile(athlete_id="7899206", school="UC_Davis", name="Katelyn_Vuong")`；注意 TFRRS 会为 XC 和 TF 创建单独资料，如果两者都存在，需获取两个 ID 以得到完整 PR。
14. 示例：查询团队当前名单时，调用 `get_team_roster(school="CA_college_f_UC_Davis", sport="xc")`，返回运动员姓名、年级和资料 slug。
15. 示例：查询比赛结果时，在 tfrrs.org 找到比赛并从 URL 复制 `meet_id` 和 `slug`（如 `tfrrs.org/results/95890/Stanford_Invitational`），然后调用 `get_meet_results(meet_id="95890", slug="Stanford_Invitational")`，返回所有项目结果和团队得分。
16. 示例：查询最新 XC/TF 新闻时，调用 `get_news(limit=10)`，返回标题、日期、摘要和链接。
17. 不要调用不存在的命令：`get_team_rankings` 不存在，应使用 `get_athlete_profile` 获取个人数据；`search_athletes` 不存在，正确命令是 `search_athlete`（无末尾 s）；`fetch_news` 不存在，正确命令是 `get_news`；如果命令未列在 Commands 表中，则它不存在。
18. 命令失败时不要向用户暴露原始错误；对于 `get_athlete_profile`，确认 `athlete_id`、`school`、`name` 与 TFRRS URL 完全匹配（区分大小写）。
19. 对于 `search_athlete`，通过检查团队 TFRRS 页面 URL 验证团队 slug 是否正确。
20. 对于 `get_meet_results`，验证 `meet_id` 和 `slug` 与比赛 TFRRS URL 完全匹配。
21. 对于 `get_team_roster`，验证 `school` slug 是否正确。
22. 对于 `get_news`，如果 feed 失败，告知用户 The Stride Report 可能暂时不可用。
23. 只有在穷尽替代方案后，才用干净消息报告失败。
24. 故障排除：若提示 `sports-skills` command not found，运行 `pip install sports-skills` 或按 Setup 从 GitHub 安装。
25. 故障排除：若运动员资料返回 HTTP 404，说明 `school` 或 `name` slug 与 TFRRS URL 不完全匹配；slug 区分大小写且使用下划线，应直接从 tfrrs.org 复制。
26. 故障排除：若 `prs` 返回空 dict，运动员资料页可能很新或结构不同，直接在 tfrrs.org 检查 URL。
27. 故障排除：若 `search_athlete` 返回空 matches，运动员可能已毕业或转学，按 Example 3 处理。
28. 故障排除：若 `get_meet_results` 返回无 events，`meet_id` 或 `slug` 可能不正确，直接从比赛 TFRRS URL 复制两者。
29. 故障排除：若 `get_news` 失败或返回无文章，The Stride Report RSS feed 可能暂时不可用，稍后重试。
30. 故障排除：若出现连接错误或超时，TFRRS 可能暂时不可用；请求已自动限流为 1 次/秒，稍等并重试。

适用边界 · 注意事项

• 不要用于职业田径、Diamond League 或其他运动；其他运动应使用对应的 nfl-data、nba-data、wnba-data、nhl-data、mlb-data、golf-data、cricket-data、cfb-data、cbb-data、tennis-data、fastf1 或 volleyball-data。
• 不要用于投注；投注应使用 polymarket 或 kalshi。
• 当运动员已毕业或转学且没有直接 TFRRS URL 时，`search_athlete` 无法找到，需先获取 TFRRS 资料 URL。