worldcup-match-analyst

中文名：世界杯竞猜分析官

这是一个用于世界杯单场赛前分析的 Skill。它不是泛体育助手，也不是赛后复盘工具，而是一套把“用户只输入一场对阵”转成标准化赛前判断的分析工作流。

这个 Skill 能做什么

它会围绕一场世界杯比赛，稳定输出六项判断：

1. 胜负倾向
2. 总进球数
3. 明星球员上半场是否进球
4. 哪队先破门
5. 是否进入点球大战
6. 是否爆冷

它的特点不是“神预测”，而是：

• 输入门槛低
• 结论优先
• 理由可读
• 风格克制
• 适合截图传播

适合什么场景

• 你想快速分析一场世界杯比赛
• 你想得到一份结构稳定的竞猜参考
• 你想判断这场更适合顺热门还是防冷门
• 你想把复杂的赛前分析压缩成一页可读内容

不适合什么场景

• 整届世界杯趋势分析
• 非世界杯赛事的泛足球内容
• 实时伤停、首发、赔率追踪
• 赛后复盘
• 博彩网站式数据工具

如何使用

默认只需要输入一场对阵：

阿根廷 vs 法国

或者：

分析一下巴西 vs 克罗地亚

如果你想额外强调某个点，也可以补一句：

德国 vs 日本，重点看会不会爆冷

如果输入里只有日期和对阵，没有年份或赛事，系统应先识别比赛，再决定是否进入正式分析。

默认输出长什么样

这个 Skill 会按固定结构输出：

1. 一句话总判断
2. 六项竞猜结论
3. 强力理由
4. 爆冷预警
5. 一句人话建议

一般项采用：

结论｜概率：xx%｜理由：...

如果某项因比赛性质不适用，例如小组赛中的点球大战，则会明确标为：

不适用｜概率：不适用｜理由：小组赛没有点球大战决胜机制

规则边界

• 概率只用整数，并带 %
• 爆冷统一用“风险”口径，不用反向写法
• 点球大战项会按比赛性质处理，小组赛明确标注不适用
• 不编造实时伤停、临场首发和无法确认的信息
• 不伪装成精确概率模型

真正上线时如何接数据

如果你要把这个 Skill 真正上线使用，推荐按三层数据能力来接：

• L1 基础比赛数据：赛程、球队、比赛性质、状态、部分阵容信息
• L2 赔率 / 盘口 / 市场概率：用于补充市场侧判断
• L3 进阶增强：首发、伤停、事件流、球员状态等

建议的产品策略是：

• 第 1 阶段可以先上 L2
• 第 2 阶段再补 L1
• L3 作为增强项，不要阻塞主流程

API key 要不要

生产上建议按“需要 key”来设计。

• 基础比赛数据源建议使用 token / API key 方式接入
• 赔率 / 盘口 / 市场概率数据通常明确要求 API key

如果没有 key，不要伪装成实时分析器。推荐采用降级模式：

• 没有外部数据时：只做离线结构化分析
• 只有 ODDS_API_KEY 或只有 FOOTBALL_DATA_API_KEY 时：输出 basic_realtime
• 同时有 FOOTBALL_DATA_API_KEY + ODDS_API_KEY 时：输出 enhanced_realtime

建议环境变量

如果你后续要做成真正可部署产品，建议预留：

FOOTBALL_DATA_API_KEY=
ODDS_API_KEY=

也可以扩展成你自己的数据源命名，但原则是：

• 没 key 时自动降级
• 有 key 时自动增强
• 不因为缺 key 输出假信息

当前目录已经补充：

• .env.example：公共配置模板
• .env.local：本地私有配置

推荐真实 key 只写入 .env.local 或运行环境变量。

最小运行时入口

当前目录已经补了一个最小可用运行时，默认入口是：

scripts/analyze_match.py

示例：

python3 scripts/analyze_match.py France Morocco --date 2027-07-10 --focus-player "Kylian Mbappe"
python3 scripts/analyze_match.py 法国 摩洛哥 --date 2026-07-10 --focus-player "姆巴佩" --output-format xhs

它会：

• 从环境变量或 .env.local 读取 FOOTBALL_DATA_API_KEY
• 从环境变量或 .env.local 读取 ODDS_API_KEY
• 通过 football-data.org 拉取 World Cup 官方比赛信息
• 通过 Odds API 拉取 World Cup 相关赛事与赔率
• 自动提取双方近期官方赛果摘要
• 自动解析比赛
• 输出结构化 JSON 分析结果

如果你想直接拿小红书投稿版文案，可以加：

--output-format xhs

调试时也可以先看可用赛事：

python3 scripts/analyze_match.py --list-sports
python3 scripts/analyze_match.py --sport-key soccer_fifa_world_cup --list-events
python3 scripts/analyze_match.py --date 2026-07-10 --list-football-matches

如果后续你要接成 HTTP API，可以直接复用 runtime/worldcup_match_analyst/ 下的配置读取、比赛解析、赔率聚合和分析器。

无 key 时会怎样

无 key 也可以使用，但只能作为“非实时赛前分析 Skill”：

• 不输出实时伤停判断
• 不输出真实盘口 / 市场概率引用
• 点球大战、球星进球这类项只在信息足够时正常输出
• 必要时明确标注 不适用 或 暂无法可靠判断
• 会额外提示：配置 FOOTBALL_DATA_API_KEY 和 ODDS_API_KEY 后，能给出更可靠的竞猜方案
• 会附上官方获取地址和 .env.local 的快速配置方式
• 也可以直接把两个 key 发给当前助手，由助手代为写入环境配置再重跑分析

官方地址：

• football-data.org 注册页：https://www.football-data.org/client/register
• football-data.org 快速文档：https://www.football-data.org/documentation/quickstart
• The Odds API 官网：https://the-odds-api.com/
• The Odds API v4 文档：https://the-odds-api.com/liveapi/guides/v4/

目录说明

• SKILL.md：Skill 主定义，包含触发场景、工作流、输出契约和边界
• AGENTS.md：维护规范，约束后续如何修改这个 Skill
• docs/：规则文档
• docs/realtime_data_strategy.md：实时数据接入与降级策略
• docs/data_source_matrix.md：数据层级、key 要求与优先级
• docs/exception_handling.md：异常情况与降级处理
• docs/api_integration_contract.md：输入输出 JSON、数据模式、降级状态和错误响应规范
• docs/deployment_notes.md：环境变量、缓存、运行模式与部署注意事项
• docs/match_resolution_rules.md：模糊日期/模糊赛事输入时如何唯一定位比赛
• docs/focus_player_resolution.md：默认关注球星如何解析，何时降级成条件判断
• examples/：完整示例，按比赛类型拆分
• templates/：标准输出模板、降级输出模板、错误提示模板和自检清单

推荐阅读顺序

如果你是使用者：

1. 先看 SKILL.md
2. 再看 examples/

如果你是维护者：

1. 先看 AGENTS.md
2. 再看 docs/
3. 最后再改 examples/ 或 templates/