用途
Nutmeg 的凭证（Credentials）技能用于帮助用户安全管理足球数据提供商的 API 密钥，并了解自己拥有哪些数据访问权限。当用户询问 API 密钥、身份验证、如何接入 Opta、StatsBomb 等数据源时，可使用该技能。
使用方式
第一步：检查配置文件
读取 .nutmeg.user.md。如果该文件不存在，提示用户先运行 /nutmeg:init。
密钥管理
API 密钥绝不应提交到 git。应引导用户将密钥存放在以下位置：
- .env 文件（已加入 gitignore）——用于项目级密钥
- 环境变量——用于系统级密钥
- .nutmeg.credentials.local（已加入 gitignore）——用于 nutmeg 专用配置
当用户想要添加密钥时，协助他们：
- 在 .env 中创建/更新该密钥
- 确认 .gitignore 已包含 .env 和 *.local
- 用一次最小 API 调用测试密钥是否可用
数据源访问参考
免费（无需密钥）
| 数据源 | 访问方式 | 可获得内容 |
|---|---|---|
| StatsBomb 开放数据 | GitHub 下载 / statsbombpy | 部分赛事的逐事件数据（世界杯、FA WSL、部分联赛赛季） |
| FBref | 网页抓取（soccerdata） | 赛季汇总数据：传球、射门、防守、GCA、控球统计 |
| Understat | 网页抓取（soccerdata） | 逐场 xG、逐射门数据，欧洲五大联赛 |
| ClubElo | HTTP API（无需密钥） | 欧洲俱乐部的历史 Elo 评分 |
| football-data.co.uk | CSV 下载 | 带博彩赔率的历史比赛结果 |
| Transfermarkt | 网页抓取 | 转会身价、阵容信息（较脆弱，条款可能禁止） |
付费 / 需密钥
| 提供商 | 是否有免费层 | 密钥类型 | 环境变量约定 |
|---|---|---|---|
| SportMonks | 有（有限） | API token | SPORTMONKS_API_TOKEN |
| Opta/Perform | 无（存在非官方 feed key） | Feed token | OPTA_FEED_TOKEN |
| StatsBomb API | 无 | API key + password | STATSBOMB_API_KEY、STATSBOMB_API_PASSWORD |
| Wyscout | 无 | API key | WYSCOUT_API_KEY |
数据市场
| 来源 | 关注点 |
|---|---|
| Kaggle | 搜索 "football events"、"soccer xG"。检查许可证（许多为 CC-BY）。核实数据新鲜度。 |
| GitHub | 搜索 "football data"、"soccer analytics"。StatsBomb 开放数据是黄金标准。 |
| data.world | 偶有足球数据集。检查质量与文档。 |
适用场景
当用户询问“我可以免费访问什么？”时，根据其 .nutmeg.user.md 配置给出具体方案：
- 初学者：从 StatsBomb 开放数据开始。它是文档最完善、质量最高的免费来源。
- Python 用户：安装 statsbombpy 和 soccerdata，即可立即访问开放数据以及 FBref/Understat。
- R 用户：安装 StatsBombR 和 worldfootballR，可获得类似覆盖范围。
- JS/TS 用户：StatsBomb 开放数据可直接从 GitHub 以 JSON 形式获取。FBref 需要抓取。
限制与警告
- 抓取网站可能违反其服务条款，应谨慎行事。
- 商业 API 密钥通常禁止再分发数据，需检查许可证。
- 免费层速率限制可能非常低（SportMonks 免费层在某些方案下为每天 5 次请求）。
- 绝不要打印或记录 API 密钥。使用 process.env 或等效方式。