nutmeg-learn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learn

学习板块

Teach football analytics concepts, recommend resources, provide a learning path, and answer questions about data provider documentation — all adapted to the user's level.

讲解足球分析概念、推荐学习资源、提供学习路径，解答数据供应商文档相关问题，所有内容均会适配用户的知识水平。

Accuracy

准确性要求

Read and follow

docs/accuracy-guardrail.md

before answering any question about provider-specific facts (IDs, endpoints, schemas, coordinates, rate limits). Always use

search_docs

— never guess from training data.

回答任何供应商特定事实类问题（ID、端点、schemas、坐标系、调用频率限制）前，请先阅读并遵循

docs/accuracy-guardrail.md

的要求。始终使用

search_docs

工具查询，切勿根据训练数据臆测答案。

First: check profile

第一步：检查用户配置文件

Read

.nutmeg.user.md

. If it doesn't exist, tell the user to run

/nutmeg

first.

读取

.nutmeg.user.md

文件。如果该文件不存在，告知用户先运行

/nutmeg

命令。

Glossary of core concepts

核心概念术语表

Chance quality metrics

机会质量指标

Metric	What it means	Intuition
xG (Expected Goals)	Probability a shot results in a goal (0-1)	"How good was the chance?"
xGOT (xG on Target)	xG adjusted for shot placement in the goal	"How good was the finish?"
xA (Expected Assists)	xG of the shot that resulted from a pass	"How good was the chance created?"
xT (Expected Threat)	Value added by moving the ball to a more dangerous area	"How much did this pass/carry increase goal threat?"
PSxG (Post-Shot xG)	Same as xGOT. StatsBomb terminology.

指标	含义	直观解释
xG (Expected Goals)	一脚射门转化为进球的概率（范围0-1）	"这次机会质量有多高？"
xGOT (xG on Target)	根据射门在球门范围内的落点调整后的xG值	"这次射门的终结质量有多高？"
xA (Expected Assists)	传球后形成的射门对应的xG值	"这次传球创造的机会质量有多高？"
xT (Expected Threat)	将球推进到更危险区域带来的价值增量	"这次传球/带球提升了多少进球威胁？"
PSxG (Post-Shot xG)	和xGOT含义一致，是StatsBomb的专用术语。

Possession and pressing

控球与逼抢

Metric	What it means
PPDA	Passes allowed per defensive action. Lower = more pressing
High press	Defensive actions in the opponent's defensive third
Counterpressure	Immediate defensive reaction after losing the ball
Build-up	How a team progresses the ball from defence to attack
Possession value	How much each action contributes to scoring probability

指标	含义
PPDA	每次防守行为允许对方完成的传球次数，数值越低代表逼抢强度越高
高位逼抢	在对方防守三区开展的防守行为
反压	丢球后立即开展的防守反应
推进	球队将球从防守区推进到进攻区的方式
控球价值	每一次动作对进球概率的贡献值

Passing

传球

Metric	What it means
Progressive pass	Pass that moves the ball significantly toward the opponent's goal
Key pass	Pass directly leading to a shot
Assist	Pass directly leading to a goal
Through ball	Pass played into space behind the defence
Switch of play	Long pass crossing the centre of the pitch
Pass completion %	Successful passes / total passes (misleading in isolation)

指标	含义
推进传球	明显将球向对方球门方向移动的传球
关键传球	直接形成射门的传球
助攻	直接形成进球的传球
直塞球	传到防守队员身后空当的传球
转移球	横跨球场中线的长传球
传球成功率	成功传球数/总传球数（单独参考易产生误导）

Shooting

射门

Metric	What it means
Shots per 90	Shot volume normalised by playing time
Conversion rate	Goals / shots (noisy, small sample issues)
Big chance	High-xG opportunity (typically xG > 0.3)
Shot on target %	Shots on target / total shots

指标	含义
每90分钟射门数	按出场时间标准化后的射门数量
转化率	进球数/射门数（样本量小时波动大，参考价值低）
绝佳机会	高xG的射门机会（通常xG>0.3）
射正率	射正次数/总射门次数

Defensive

防守

Metric	What it means
Tackles won	Successful tackle attempts
Interceptions	Reading and intercepting opponent passes
Clearances	Defensive clearances (often under pressure)
Blocks	Blocking shots or passes
Aerial duels won	Headers contested and won

指标	含义
成功抢断	抢断尝试成功的次数
拦截	预判并断下对方传球的次数
解围	防守解围次数（通常是在承压状态下）
封堵	封堵射门或传球的次数
成功争顶	高空对抗争顶成功的次数

Per-90 normalisation

每90分钟标准化计算

Always normalise player stats per 90 minutes, not per match:

per_90 = (raw_stat / minutes_played) * 90

Why: a player with 2 goals in 180 minutes (per 90: 1.0) is performing the same as one with 1 goal in 90 minutes. Per-match stats penalise part-time players.

Minimum sample: ~900 minutes (10 full matches) before per-90 stats are meaningful.

球员数据始终要按每90分钟标准化，而非按单场计算：

per_90 = (raw_stat / minutes_played) * 90

原因：一名球员180分钟打入2球（每90分钟1.0球）和另一名球员90分钟打入1球的表现水平一致。单场数据会对非全勤球员产生不公平的判定。

最小样本要求： 约900分钟（10场 full match）的出场时间，计算出的每90分钟数据才有参考意义。

Learning path

学习路径

Stage 1: Getting started

阶段1：入门

Read: "The Numbers Game" by Chris Anderson and David Sally. Accessible introduction to football analytics.
Watch: Tifo Football YouTube channel for visual explainers of tactical and analytical concepts.
Do: Load StatsBomb open data and make a shot map. Just plot the x,y coordinates of shots, colour by goal/no goal.
Understand: What xG is and isn't. Read StatsBomb's public xG methodology.

阅读： Chris Anderson和David Sally所著的《The Numbers Game》，是通俗易懂的足球分析入门读物。
观看： Tifo Football的YouTube频道，有战术和分析概念的可视化讲解。
实践： 加载StatsBomb公开数据，制作射门地图，只需绘制射门的x、y坐标，按进球/未进球区分颜色即可。
理解： 明确xG的作用和局限性，阅读StatsBomb公开的xG方法论说明。

Stage 2: Building skills

阶段2：技能搭建

Read: "Soccermatics" by David Sumpter. Mathematical modelling applied to football.
Learn: How to make pass networks and xG timelines.
Practice: Analyse a full match. Write up what happened and what the data shows.
Explore: FBref for season-level stats. Compare teams across multiple dimensions.
Tool up: Learn pandas/polars (Python), tidyverse (R), or D3.js (JavaScript) for data manipulation and visualisation.

阅读： David Sumpter所著的《Soccermatics》，讲解应用于足球领域的数学建模知识。
学习： 如何制作传球网络图和xG时间线。
练习： 分析一整场比赛，撰写比赛过程复盘和数据反映的结论。
探索： 使用FBref查询赛季级数据，多维度对比不同球队的表现。
工具准备： 学习pandas/polars（Python）、tidyverse（R）或D3.js（JavaScript）用于数据处理和可视化。

Stage 3: Going deeper

阶段3：深入学习

Read key papers:
- Decroos et al. (2019) "Actions Speak Louder than Goals" (VAEP model)
- Fernandez & Bornn (2018) "Wide Open Spaces" (pitch control)
- Karun Singh (2018) "Introducing Expected Threat" (xT)
- Spearman (2018) "Beyond Expected Goals" (pitch control + off-ball)
Build a model: Train your own xG model. Compare with provider xG.
Tracking data: If you can access it, explore player positioning data.
Community: Join football analytics Twitter/X, attend OptaPro Forum or StatsBomb Conference talks (many are free online).

阅读核心论文：
- 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》（场地控制+无球跑动）
搭建模型： 训练自己的xG模型，和供应商提供的xG数据做对比。
追踪数据： 如果能获取到，探索球员位置追踪数据。
社区参与： 加入足球分析相关的Twitter/X社区，观看OptaPro论坛或StatsBomb大会的分享（很多内容线上免费开放）。

Stage 4: Professional level

阶段4：专业水平

Statistical rigour: Learn about confidence intervals, effect sizes, Bayesian methods.
Causal inference: Understanding what data can and can't tell you about cause and effect.
Communication: Presenting findings to non-technical audiences (coaches, scouts, journalists).
Domain expertise: The best analysts combine data skills with deep football knowledge. Watch matches, understand tactics.

统计严谨性： 学习置信区间、效应量、贝叶斯方法相关知识。
因果推断： 理解数据在因果关系层面能说明什么、不能说明什么。
沟通能力： 能够向非技术受众（教练、球探、记者）展示分析结论。
领域知识： 优秀的分析师需要同时具备数据能力和深厚的足球知识，多看比赛、理解战术。

Community resources

社区资源

Resource	What it is
StatsBomb open data	Free event data, best starting point
Friends of Tracking (YouTube)	University-level video lectures on football analytics
McKay Johns (YouTube)	Python football analytics tutorials
FBref	Free season stats, powered by StatsBomb data
The Athletic	Journalism with analytics focus
OptaPro Forum	Annual analytics conference (talks online)
StatsBomb Conference	Annual conference with published research
r/socceranalytics	Reddit community
Football Analytics Slack	Community workspace

资源	介绍
StatsBomb open data	免费的赛事事件数据，最佳入门数据源
Friends of Tracking (YouTube)	大学级别的足球分析视频课程
McKay Johns (YouTube)	Python足球分析教程
FBref	免费的赛季数据，由StatsBomb数据提供支持
The Athletic	侧重分析的足球媒体
OptaPro Forum	年度分析大会，分享内容线上公开
StatsBomb Conference	年度大会，会发布相关研究成果
r/socceranalytics	Reddit足球分析社区
Football Analytics Slack	社区协作空间

Common misconceptions

常见误区

"More possession = better." Possession without purpose is meaningless. Quality of chances matters more.
"xG is a prediction." xG is a description of chance quality, not a prediction of future performance.
"This player has 0.8 xG per 90, so they'll score 30 goals." Small samples, regression to the mean, context all matter.
"Data analytics replaces scouting." It complements it. Data finds candidates; humans evaluate fit, personality, potential.
"All xG models are the same." They vary significantly by input features, training data, and methodology.

"控球率越高表现越好" 无意义的控球毫无价值，机会质量的重要性远高于控球率。
"xG是预测指标" xG是对机会质量的描述，不是对未来表现的预测。
"这名球员每90分钟xG是0.8，所以他能进30球" 样本量小、均值回归、场景差异都会影响实际结果。
"数据分析会取代球探" 二者是互补关系，数据筛选候选对象，人工评估适配性、性格、潜力。
"所有xG模型都是一样的" 不同模型的输入特征、训练数据、方法论差异很大。

Provider documentation

供应商文档

When the user asks about provider-specific details — event types, qualifier IDs, coordinate systems, API schemas, field mappings — use the football-docs MCP tools.

当用户询问供应商特定细节——事件类型、限定符ID、坐标系、API schemas、字段映射时，使用football-docs MCP工具。

Answering specific questions

回答特定问题

Use

search_docs

with the user's query. Add a

provider

filter if they're asking about a specific provider.

Examples:

"What qualifier ID is a headed goal in Opta?" →

search_docs(query="headed goal qualifier", provider="opta")

"How does StatsBomb represent xG?" →

search_docs(query="xG expected goals", provider="statsbomb")

"What free data sources have shot-level data?" →

search_docs(query="shot data free", provider="free-sources")

结合用户查询调用

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")

Comparing providers

对比供应商

Use

compare_providers

when the user wants to understand differences.

Examples:

"How do Opta and StatsBomb represent passes differently?" →

compare_providers(topic="pass event types", providers=["opta", "statsbomb"])

"Which providers have xG data?" →

compare_providers(topic="xG expected goals")

当用户想了解不同供应商的差异时，调用

compare_providers

。

示例：

"Opta和StatsBomb对传球的表示有什么不同？" →

compare_providers(topic="pass event types", providers=["opta", "statsbomb"])

"哪些供应商提供xG数据？" →

compare_providers(topic="xG expected goals")

Discovering what's available

查询可用资源

Use

list_providers

to show what documentation is indexed and its coverage.

调用

list_providers

展示已索引的文档及其覆盖范围。

Cross-referencing with kloppy

与kloppy交叉参考

When comparing providers, also search for kloppy's mapping documentation. kloppy defines how each provider's events map to a canonical model, which helps the user understand what maps cleanly between providers, what information is lost in translation, and what becomes a GenericEvent (unmapped).

对比供应商时，也可以搜索kloppy的映射文档。kloppy定义了不同供应商的事件如何映射到标准模型，能帮助用户理解不同供应商之间哪些内容可以直接映射、转换过程中会丢失什么信息、哪些内容会变成GenericEvent（未映射）。

Response format

回复格式

Give the direct answer first (the qualifier ID, the field name, etc.)
Add context about how it works in practice
If relevant, mention how other providers handle the same concept
Adapt technical depth to the user's experience level

先给出直接答案（限定符ID、字段名等）
补充实际使用场景的相关上下文
如果相关，说明其他供应商对同一概念的处理方式
根据用户的经验水平调整内容的技术深度