nutmeg-learn

学习

教授足球分析概念，推荐资源，提供学习路径，并回答有关数据提供商文档的问题——所有内容均根据用户的水平调整。

准确性

回答任何有关特定提供商事实（ID、端点、架构、坐标、速率限制）的问题前，请阅读并遵循 ${CLAUDE_PLUGIN_ROOT}/docs/accuracy-guardrail.md。始终使用 search_docs——绝不要根据训练数据猜测。

当用户询问某项指标的含义时，请使用 get_metric 阅读 football-docs 中该指标的说明卡（list_metrics 会显示这些说明卡），并解释该指标存在不同变体，列出它们的 ID；没有说明卡的指标请使用 search_docs。

首先：检查个人资料

读取 .nutmeg.user.md。如果文件不存在，请采用合理的默认设置（Python 和 pandas，中级水平）继续，并在最后建议运行 /nutmeg 进行设置。

核心概念术语表

术语表位于 ${CLAUDE_PLUGIN_ROOT}/docs/glossary.md：机会质量（xG、npxG、xGOT、xA、xT）、控球和 压迫（PPDA、高位压迫、反抢、组织进攻、控球价值）、传球、射门和防守术语， 以及每 90 分钟。用户询问术语含义时，请阅读术语表，并根据用户的水平进行解释。研究工作区页面 链接到相同的条目。对于提供商自己对某项指标或事件的定义，请使用 search_docs；术语表 只提供一般含义。

当用户需要向别人解释某个概念，或反复询问这个概念时，可以主动提出帮其写成可编辑和分享的说明页面；请遵循 ${CLAUDE_PLUGIN_ROOT}/docs/understanding.md 第 2 节。

每 90 分钟标准化

始终按每 90 分钟而非每场比赛对球员数据进行标准化：

per_90 = (raw_stat / minutes_played) * 90

原因：一名球员在 180 分钟内进 2 球（每 90 分钟：1.0），表现与另一名球员在 90 分钟内进 1 球相同。按每场比赛统计会对上场时间较少的球员不利。

**最低样本量：**每 90 分钟统计通常以约 900 分钟（10 场完整比赛）作为经验法则。噪声较大的统计需要多得多的样本：要对射门把握能力作出判断，需要几百次射门。

学习路径

阶段 1：入门

1. 阅读： Chris Anderson 和 David Sally 所著的《The Numbers Game》。这是一本通俗易懂的足球分析入门书。
2. 观看： Tifo Football YouTube 频道，学习战术和分析概念的可视化讲解。
3. 实践： 加载 StatsBomb 开放数据并制作射门图。只需绘制射门的 x、y 坐标，并根据进球与否着色。
4. 理解： xG 的含义及其不代表什么。阅读 StatsBomb 公开的 xG 方法论。

阶段 2：提升技能

1. 阅读： David Sumpter 所著的《Soccermatics》。本书介绍应用于足球的数学建模。
2. 学习： 如何制作传球网络和 xG 时间线。
3. 练习： 分析一场完整的比赛。记录比赛经过以及数据所反映的情况。
4. 探索： 使用 FBref（基础统计数据）和 Understat（xG）查看赛季数据。从多个维度比较球队。
5. 掌握工具： 学习 pandas/polars（Python）、tidyverse（R）或 D3.js（JavaScript），用于数据处理和可视化。

阶段 3：深入学习

1. 阅读重要论文：
   • Decroos 等人（2019 年）《Actions Speak Louder than Goals》（VAEP 模型）
   • Fernandez 和 Bornn（2018 年）《Wide Open Spaces》（场地控制）
   • Karun Singh（2018 年）《Introducing Expected Threat》（xT）
   • Spearman（2018 年）《Beyond Expected Goals》（场地控制 + 无球表现）
2. 构建模型： 训练自己的 xG 模型，并与提供商的 xG 进行比较。
3. 追踪数据： 如果可以获取，请探索球员位置数据。
4. 社区： 加入足球分析 Twitter/X 社区，并观看 Opta Forum（前身为 OptaPro Forum）或 StatsBomb Conference 的演讲（许多演讲都可以在线免费观看）。

阶段 4：专业水平

1. 统计严谨性： 了解置信区间、效应量和贝叶斯方法。
2. 因果推断： 理解数据能告诉你什么、不能告诉你什么，以及因果关系。
3. 沟通： 向非技术受众（教练、球探、记者）展示研究结果。
4. 领域知识： 最优秀的分析师会将数据技能与深厚的足球知识相结合。观看比赛，理解战术。

社区资源

资源	介绍
StatsBomb 开放数据	免费事件数据，是最佳入门选择
Friends of Tracking（YouTube）	大学水平的足球分析视频讲座
McKay Johns（YouTube）	Python 足球分析教程
FBref	免费赛季统计数据。自 2026 年 1 月移除高级（Opta）数据后，仅提供基础统计数据
The Athletic	专注于分析的新闻报道
Opta Forum（原 OptaPro Forum）	年度分析会议（演讲可在线收看）
StatsBomb Conference	年度会议，并发布研究成果
r/socceranalytics	Reddit 社区
Football Analytics Slack	社区工作区

常见误解

1. “控球率更高 = 表现更好。” 没有目的的控球毫无意义。机会质量更重要。
2. “xG 是预测。” xG 描述的是机会质量，而不是对未来表现的预测。
3. “这名球员每 90 分钟的 xG 为 0.8，所以他们会进 30 个球。” 小样本、回归均值和具体情境都很重要。
4. “数据分析可以取代球探工作。” 数据分析是对球探工作的补充。数据用于寻找候选人；由人来评估是否合适、性格和潜力。
5. “所有 xG 模型都一样。” 不同模型在输入特征、训练数据和方法上存在显著差异。

提供方文档

当用户询问提供方特有的细节——事件类型、限定符 ID、坐标系、API 架构、字段映射、身份信息来源或提供方 ID 方案时，请使用 football-docs MCP 工具。

回答具体问题

使用 search_docs 搜索用户的问题。如果用户询问的是特定提供方，请添加 provider 筛选条件。

示例：

• “Opta 中头球进球的限定符 ID 是什么？” → search_docs(query="headed goal qualifier", provider="opta")
• “StatsBomb 如何表示 xG？” → search_docs(query="xG expected goals", provider="statsbomb")
• “哪些免费数据源提供射门级数据？” → search_docs(query="shot data free", provider="free-sources")
• “Transfermarkt 球员 ID 可以安全地用于关联吗？” → search_docs(query="identity surfaces player ID bridge quirks", provider="transfermarkt")
• “我该如何解读 Soccerdonna 的比赛报告？” → search_docs(query="identity surfaces match reports player profile", provider="soccerdonna")

实体解析

对于实体解析问题，还要阅读 ${CLAUDE_PLUGIN_ROOT}/docs/entity-resolution-routing.md。 明确以下边界：

• 提供方事实和特性来自 football-docs；
• 可用时，使用 Reep Register 工具查询公开的 Reep ID；
• 可复用的匹配指南、架构和参考脚本属于 reep-toolkit；
• 只有用户有权限或提供了相关内容时，才能引用私有匹配逻辑包中的材料。

比较提供方

当用户想了解差异时，使用 compare_providers。

示例：

• “Opta 和 StatsBomb 对传球的表示有何不同？” → compare_providers(topic="pass event types", providers=["opta", "statsbomb"])
• “哪些提供方有 xG 数据？” → compare_providers(topic="xG expected goals")

了解可用内容

使用 list_providers 查看已编入索引的文档及其覆盖范围。

与 kloppy 交叉参照

比较不同提供商时，也要查阅 kloppy 的映射文档。kloppy 定义了各提供商的事件如何映射到规范模型，帮助用户了解哪些内容可以在不同提供商之间顺畅映射、转换时会丢失哪些信息，以及哪些内容会成为 GenericEvent（未映射）。

回复格式

1. 首先直接回答（限定符 ID、字段名称等）
2. 补充说明其在实际中的工作方式
3. 如适用，说明其他提供商如何处理同一概念
4. 根据用户的经验水平调整技术深度