pp-espn

ESPN — Printing Press CLI

前提条件：安装 CLI

此技能使用 espn-pp-cli 二进制文件。调用此技能中的任何命令前，必须确认 CLI 已安装。 如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install espn --cli-only
   

2. 验证：espn-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-cli@latest

如果安装后 --version 报告 "command not found"，则运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿执行此技能中的命令。

何时使用此 CLI

当用户想快速查询体育信息时，请使用此 CLI，例如当前比分、排名、即将开始的赛程、交锋记录，或丰富的单场比赛摘要（技术统计、领先者、得分回合、赔率、获胜概率）。它也适用于跨联盟查询（today）和搜索已同步数据。

如果用户拥有 Stats Perform 或 Sportradar 等付费数据源（可提供更整洁的数据），或需要实时 websocket 更新（ESPN 的端点仅支持轮询），则不适合使用此 CLI。若只想查询投注赔率，单场比赛的 summary 数据中包含赔率，但没有全联盟赔率命令。

独特功能

这些命令依赖本地同步和跨联盟工具，因此只能通过此 CLI 使用。

跨联盟查询

• today — 一次调用即可查询所有主要体育项目的今日比分。无需先选择体育项目，即可最快回答“今晚有什么比赛”。

• trending — 显示所有联盟中当前最受关注的运动员和球队，并按当前热度排序。适合在不指定体育项目的情况下查询“现在谁最火”。

• dashboard — 从 ~/.config/espn-pp-cli/config.toml 读取 [favorites]，并通过一次调用显示各联盟中每支收藏球队的比分。

• watch <sport> <league> --event <game_id> — 持续更新特定比赛的实时比分（每 30 秒轮询一次）。使用 scores 或 today 查找比赛，然后用 watch 实时关注。

比赛状态信息

• summary <sport> <league> --event <game_id> — 详细的比赛摘要，包括技术统计、领先者、得分回合、赔率和获胜概率。每场比赛中信息最丰富的数据。

• boxscore <event_id> — 仅显示指定事件 ID 的球员技术统计；若近期记分牌缓存命中，则自动推断体育项目和联盟。传入 --sport/--league 可跳过推断。

• plays <sport> <league> --event <id> — 指定事件的逐回合数据流。可选参数 --limit（默认值为 200）。

• recap <sport> <league> — 显示该联盟最近一场已结束比赛的赛后回顾，包括技术统计和领先者。

• scoreboard <sport> <league> — 实时记分牌，支持按日期筛选、按周/组选择，并提供赛事元数据。

• odds <sport> <league> — 显示今晚赛程的让分、大小分和独赢赔率，数据来自记分牌，无需逐场调用摘要。

排名与榜单

• standings <sport> <league> — 分区/赛区排名。

• rankings <sport> <league> — 当前 AP、Coaches 和 CFP 民意调查排名（NCAAF/NCAAM）。

• streak <sport> <league> — 显示联盟中各队当前的连胜/连败情况，根据已同步数据计算。

• rivals <sport> <league> — 显示联盟中球队之间的交锋记录，数据来自已同步数据。

• h2h <team1> <team2> --sport <s> --league <l> — 深入展示指定两支球队的交锋详情，包括平均比分和近期交锋列表。

• sos <sport> <league> — 根据排名数据，为各队计算赛程强度并按降序排列。

球员与人员

• leaders <sport> <league> [--category <name>] — 查看各类别的统计领先者，可选筛选条件。

• compare <athlete1> <athlete2> --sport <s> --league <l> — 并排比较两位运动员的赛季数据。若姓名不明确，将列出候选项并以退出码 2 结束。

• injuries <sport> <league> — 查看联盟内各球队的现役伤病报告。

• transactions <sport> <league> — 查看近期交易、签约和弃用球员信息。

本地存储

• sync — 将某项运动和联盟的数据集拉取到本地 SQLite，以供离线分析。

• search "<query>" — 在已同步的赛事和新闻中进行全文搜索。

• sql <query> — 对本地数据库执行只读 SQL 查询。

命令参考

实时操作：

• espn-pp-cli scores <sport> <league> — 当前比分
• espn-pp-cli today — 所有主要运动项目今天的比分
• espn-pp-cli scoreboard <sport> <league> — 记分牌，可选按日期筛选
• espn-pp-cli watch <sport> <league> --event <game_id> — 轮询一场比赛的实时比分
• espn-pp-cli standings <sport> <league> — 联盟排名
• espn-pp-cli trending — 各联盟中最受关注的运动员和球队
• espn-pp-cli dashboard — 从 ~/.config/espn-pp-cli/config.toml 获取收藏快照

球队详情：

• espn-pp-cli teams <sport> <league> <team_id> — 单支球队的赛程（已结束和即将举行）
• espn-pp-cli teams get <sport> <league> <team_id> — 球队战绩、链接和标志
• espn-pp-cli teams list <sport> <league> — 联盟中的所有球队
• espn-pp-cli streak <sport> <league> — 根据已同步数据查看当前连胜／连败
• espn-pp-cli rivals <sport> <league> — 根据已同步数据查看球队之间的交锋记录
• espn-pp-cli h2h <team1> <team2> --sport <s> --league <l> — 查看两支球队交锋的更多详情（平均比分、交手次数）
• espn-pp-cli sos <sport> <league> — 按降序排列的赛程强度

比赛详情：

• espn-pp-cli summary <sport> <league> --event <game_id> — 完整比赛摘要（技术统计、领先者、得分回合、赔率、获胜概率）
• espn-pp-cli boxscore <event_id> — 仅查看技术统计子树（根据缓存推断运动项目／联盟）
• espn-pp-cli plays <sport> <league> --event <id> — 逐回合比赛数据流（可选 --limit，默认值为 200）
• espn-pp-cli recap <sport> <league> — 最近一场已结束比赛的回顾
• espn-pp-cli odds <sport> <league> — 今晚赛程的让分、大小分和独赢盘赔率

球员与人员：

• espn-pp-cli leaders <sport> <league> [--category <name>] — 按类别查看统计领先者
• espn-pp-cli compare <athlete1> <athlete2> --sport <s> --league <l> — 并排比较运动员数据
• espn-pp-cli injuries <sport> <league> — 查看现役伤病报告
• espn-pp-cli transactions <sport> <league> — 查看近期交易、签约和弃用球员信息

民意调查和排名：

• espn-pp-cli rankings <sport> <league> — AP、教练协会和 CFP 民意调查排名

信息：

• espn-pp-cli news <sport> <league> — 最新新闻

发现和本地操作：

• espn-pp-cli search "<query>" — 在已同步的赛事和新闻中进行全文搜索
• espn-pp-cli sync — 将某项运动和联盟的数据同步到本地 SQLite
• espn-pp-cli sql "<query>" — 对本地存储执行只读 SQL 查询
• espn-pp-cli load — 显示各受派人的工作负载分布（已同步数据）
• espn-pp-cli orphans / stale — 本地存储的维护视图
• espn-pp-cli doctor — 验证连接状态和配置

运动项目值：football、basketball、baseball、hockey、soccer。 联盟值：nfl、nba、mlb、nhl、ncaaf、ncaam、ncaaw、mls、eng.1（EPL）、wnba。

示例

晨间体育速览

espn-pp-cli today --agent --select events.shortName,events.status
espn-pp-cli scores football nfl --agent --select events.shortName,events.competitions.competitors.team.displayName,events.status.type.detail
espn-pp-cli standings football nfl --agent

一次 today 调用即可涵盖多个联盟的赛事活动，再对你关注的联盟调用一次 scores，并调用一次 standings 了解排名情况。嵌套的 --select 路径可将记分牌负载从数十 KB 缩减到仅保留真正重要的字段，这对于控制 Agent 上下文大小至关重要。

从同步数据进行赛前研究

espn-pp-cli sync --sport football --league nfl
espn-pp-cli rivals football nfl --agent         # historical records from synced data
espn-pp-cli streak football nfl --agent         # current streaks
espn-pp-cli summary football nfl --event <id> --agent   # full game payload incl. odds and box score

运行一次 sync，之后 rivals 和 streak 就能从本地存储中即时作答。对于特定比赛，summary 能提供内容最丰富的单个数据包（技术统计、领先者、得分回合、赔率、获胜概率）。

同步后离线搜索

espn-pp-cli sync --sport football --league nfl
espn-pp-cli search "Mahomes"                    # finds in local store

适用于网络连接不佳时的重复查询，或批量分析历史数据。

收藏夹仪表板

在 ~/.config/espn-pp-cli/config.toml 中添加一个 [favorites] 块：

[favorites]
nfl = ["KC", "BAL"]
nba = ["LAL"]

然后：

espn-pp-cli dashboard --agent

一次调用即可按联赛分组，显示所有收藏球队今晚的对阵状态。各联赛的数据获取会并行运行；部分失败时，会与成功结果一并报告。

赛前赔率与球员查询

espn-pp-cli odds basketball nba --agent          # tonight's spreads / totals / moneylines
espn-pp-cli leaders basketball nba --category points --agent
espn-pp-cli compare "LeBron James" "Stephen Curry" --sport basketball --league nba --agent
espn-pp-cli boxscore <event_id> --agent          # post-game player stats
espn-pp-cli plays basketball nba --event <id> --limit 50 --agent

odds 读取比分板中的单场赛事赔率（不调用单场比赛摘要）。leaders --category 可筛选单个统计类别。compare 会按姓名解析运动员 ID，列出候选项；若存在歧义，则以状态码 2 退出。boxscore 会根据最近的缓存命中推断运动项目和联赛；传入 --sport/--league 可跳过推断。

身份验证设置

无需身份验证。 ESPN 的公共端点不需要 API 密钥。auth 命令是为保持一致性而提供的，但不执行任何操作。

可选配置：

• ESPN_CONFIG — 覆盖配置文件路径
• ESPN_BASE_URL — 覆盖基础 URL（用于代理或镜像）
• NO_COLOR — 标准的禁用颜色环境变量

Agent 模式

为任意命令添加 --agent。该选项会展开为 --json --compact --no-input --no-color --yes。使用 --select 挑选字段，使用 --dry-run 预览请求，使用 --no-cache 绕过 GET 缓存。

筛选输出

--select 接受点分路径，用于深入访问嵌套响应；数组会逐元素遍历：

espn-pp-cli <command> --agent --select id,name
espn-pp-cli <command> --agent --select items.id,items.owner.name

使用此功能可将庞大的数据包缩减到你实际需要的字段——这对于深度嵌套的 API 响应至关重要。

响应封装

数据层命令会将输出封装为 {"meta": {...}, "results": <data>}。解析 .results 获取数据，并检查 .meta.source 以了解数据来自 live 还是本地。仅当 stdout 是 TTY 时，才会将 N results (live) 摘要打印到 stderr；通过管道处理的内容和 Agent 消费者在 stdout 上只会看到纯 JSON。

退出代码

代码	含义
0	成功
2	用法错误
3	未找到（球队、比赛、运动员）
5	API 错误
7	请求过于频繁

安装

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-cli@latest
espn-pp-cli doctor

MCP 服务

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn/cmd/espn-pp-mcp@latest
claude mcp add espn-pp-mcp -- espn-pp-mcp

参数解析

给定 $ARGUMENTS：

1. 空、help 或 --help → 运行 espn-pp-cli --help
2. install → CLI；install mcp → MCP
3. 其他任何内容 → 根据用户意图解析 <sport> <league>（例如，“Lakers” → basketball nba），检查 which espn-pp-cli（若未找到，则提供安装选项），并使用 --agent 运行。

自动学习

双调用协议：发现前调用 recall，输出前调用 teach &。CLI 会执行实体感知的匹配验证，并展示与查询类别对应的已存储操作手册；你需要读取封装内容并遵循六分支决策树。跳过任一环节，都会让你失去未来会话中的免费召回命中。

步骤 1：任何发现操作前先调用 recall

针对新的用户问题，在运行 scoreboard、teams、boxscore、search、standings 或任何其他发现命令前，先运行：

espn-pp-cli recall "<user's question>" --agent

响应封装如下：

{
  "query": "...",
  "normalized": "game tonight",
  "query_entities": ["Niners"],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "events|news|...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "teams basketball nba {team.id}", "purpose": "..." }, ... ],
      "entity_slots": ["$TEAM", "$STATS"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$TEAM": { "token": "pistons", "canonical": "Detroit Pistons" } },
    "notes": "byathlete needs seasontype=2; categories has dup labels"
  },
  "notes": "byathlete needs seasontype=2; categories has dup labels"
}

步骤 2：六分支决策树

依次读取 playbook、notes、results[0] 和警告：

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via teach-playbook at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel
       (e.g., espn-pp-cli boxscore <eid> for an event, espn-pp-cli teams ... for a team)

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (e.g., a "Cowboys" learning won't satisfy a "Niners" query — different canonical)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward AND record
       a playbook + notes via teach --playbook-file --playbook-notes-file so the
       next session of the same family is faster.

操作手册和备注与每个资源的处理路径相互独立。recall 响应可能同时包含操作手册和 Results[] 命中——两者都要使用：操作手册会告诉你要运行哪种调用流程；资源命中则会跳过特定步骤。默认跳过 mismatches；仅在调查冷启动时的意外情况时传入 --debug-mismatches。

步骤 3：始终读取 warnings

• low_confidence：存在 confidence<2 的行。将其视为提示，而非跳过发现流程的依据。
• resource_not_in_store：本地存储中没有学习记录所指向的资源。匹配验证器无法对实体进行分类——直接获取并重新评估。
• 顶层 no_learnings_for_query_family：表中没有高于 Jaccard 下限的行。属于纯冷启动。

步骤 4：完成回复后执行 teach &

在组装好包含赛事／球队 ID 的面向用户回复后、发出回复前，在后台触发 teach 调用。在命令末尾追加 shell &，使其立即返回，不阻塞面向用户的回复：

espn-pp-cli teach --query "<user's question>" --resource-type <events|news|teams> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功时不输出任何信息。选择最具体的资源进行学习——如果用户问“下一场 Spurs 比赛是什么时候”，而你查看球队赛程后找到了赛事 401747632，就学习该赛事 ID，而不是球队 ID。CLI 会使用预置的 entity_lookups（含别名的 NFL/NBA/MLB/MLS 球队名册，例如 Niners/49ers/SF）在回忆时进行跨别名解析，因此，以“Niners”为对象进行学习，也会自动满足今后关于“49ers”的查询。

步骤 5：如果发现过程超过 5 次调用，则记录操作手册

如果你为了回答问题运行了超过 5 次工具调用，并且发现了 CLI 未提示的变通方法（被静默丢弃的标志、未记录的参数、分页技巧、负载注意事项），请记录下来，以便下一次同类查询跳过这些发现工作。可使用两个位置：

# Common case: along with the resource teach
espn-pp-cli teach --query "<question>" --resource-type <type> --resource <id> \
  --playbook-file ~/playbooks/season-recap.json \
  --playbook-notes-file ~/playbooks/season-recap-notes.md
# (append shell `&` to background it)

# Standalone: notes-only or recipe-only
espn-pp-cli teach-playbook --query "<question>" \
  --playbook-file ~/playbooks/season-recap.json \
  --notes "byathlete needs seasontype=2; categories has dup labels"

操作手册文件为包含 steps、entity_slots、expected_tool_calls 的 JSON 文件。备注文件为记录原始注意事项的 Markdown 文件。任一字段都可以为空；但两者都为空时会被拒绝。操作手册按结构化查询类型（去除实体后）建立索引，因此，从“Warriors 如何结束赛季”得出的操作流程，也适用于 Pistons、Heat 以及所有其他同类型球队查询。

今后回忆时如果找到操作手册，请将其视为事实依据：使用 slots_resolved 替换项重放步骤，跳过操作流程中已有记录的发现工作，并在执行任何步骤前阅读 notes。

步骤 6：如果调试回复指出需要修正的内容，则执行 playbook amend &

如果你的调试协议回复指出备注或操作手册应记录的具体修正内容——例如变通方法、未记录的端点结构、过时的字段名、观察到的架构变更或空负载的回退方案——请在发出面向用户的回复前触发 playbook amend。执行方式与 teach 相同，采用即发即弃模式。

espn-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

值得补充的内容包括：你在本次会话中观察到、未来的自己会受益的行为。值得补充的示例：

• “摘要端点将响应封装在 {meta, results} 中——数据位于 .results.header，而非 .header”
• “对于球队当前未进入季后赛的运动员，compare 会返回空的 team 字段”
• “本赛季 byathlete 的 avgRebounds 类别索引从 general[9] 变为 general[11]”

以下内容不应写入备注：

• 针对特定年份的答案（“Curry 上一场比赛投篮 4-16”）。这是回复内容，不是学习记录。
• 操作手册已在运行时获取的球队或运动员数据。
• 只是换种说法重复现有备注的陈述。

amend 命令会在该查询类型的现有备注后追加带时间戳的标记（[amend YYYY-MM-DDTHH:MMZ]: <text>）。多次 amend 会累积，并保留可见的审计记录。如果该查询类型尚无操作手册，amend 会创建一个仅包含备注的操作手册（因此，冷启动时发现的修正也会被记录下来）。

示例

1. 冷启动：“马刺队下一场比赛是什么时候？” — recall 返回 found=false。遍历球队比分板，找到马刺队下一场即将举行的赛事 ID，然后作答。记录该赛事：

   espn-pp-cli recall "when's next Spurs game?" --agent
   # found=false -> discovery
   espn-pp-cli teams basketball nba 24 --agent --select events.id,events.shortName,events.date
   # ...answer "Tue May 26 SA @ OKC, event 401747632"...
   espn-pp-cli teach --query "when's next Spurs game?" --resource-type events --resource 401747632
   # (append shell `&` to background it)
   

2. 已学习：“今晚的 49 人队比赛” — recall 返回 found=true、results[0].entity_match="exact"、results[0].confidence>=2。跳过发现步骤，直接获取比赛数据：

   espn-pp-cli recall "Niners game tonight" --agent
   # found=true, results=[{resource_id: "401547432", entity_match: "exact"}]
   espn-pp-cli boxscore 401547432 --agent
   

3. 跨别名命中：“今晚的 49 人队比赛” — 从未直接记录过。recall 通过 entity_lookups（nfl_team 类型）将“49ers”解析为规范实体“San Francisco 49ers”，找到“今晚的 Niners 比赛”这条学习记录（规范实体相同），返回 found=true。跳过发现步骤。

4. 实体不匹配：“今晚的牛仔队比赛” — 在非实体词元（game、tonight）上，高于 Jaccard 阈值的 Niners 学习记录，但实体规范名称不同（Dallas Cowboys ≠ San Francisco 49ers）。该记录被归入 mismatches；recall 返回 found=false。按冷启动处理。

循环中断时：learnings list --warnings 会显示本地问题；espn-pp-cli feedback "<what tripped you up>" 会记录遇到的障碍，以便下一次输出修复。

---

Agent 工作流功能

此 CLI 提供了三项共享的 Agent 工作流能力，这些能力移植自 cli-printing-press PR #218。

命名配置文件

将一组选项保存在名称下，并在多次调用中重复使用。

# Save the current non-default flags as a named profile
espn-pp-cli profile save <name>

# Use a profile — overlays its values onto any flag you don't set explicitly
espn-pp-cli --profile <name> <command>

# List / inspect / remove
espn-pp-cli profile list
espn-pp-cli profile show <name>
espn-pp-cli profile delete <name> --yes

选项优先级：显式选项 > 环境变量 > 配置文件 > 默认值。

--deliver

将命令输出路由到 stdout 以外的目标。当 Agent 需要将结果交给文件、Webhook 或其他进程而无需处理数据传递时，此功能很有用。

espn-pp-cli <command> --deliver file:/path/to/out.json
espn-pp-cli <command> --deliver webhook:https://hooks.example/in

文件目标会以原子方式写入（临时文件 + 重命名）。Webhook 目标会发送 POST 请求，内容类型为 application/json（设置 --compact 时为 application/x-ndjson）。未知方案会返回结构化拒绝信息，并列出受支持的方案。

feedback

从 Agent 端的工作循环中记录对此 CLI 的内联反馈。默认仅在本地记录，无需配置即可安全调用。

espn-pp-cli feedback "what surprised you or tripped you up"
espn-pp-cli feedback list         # show local entries
espn-pp-cli feedback clear --yes  # wipe

条目会以 JSON 行的形式追加到 ~/.espn-pp-cli/feedback.jsonl。设置 ESPN_FEEDBACK_ENDPOINT 且传入 --send 或设置 ESPN_FEEDBACK_AUTO_SEND=true 时，该条目也会通过 POST 请求发送到上游（不会阻塞——本地写入始终会成功）。