前言¶
做足球类内容的开发者大概都遇到过两种麻烦：一是数据东拼西凑，赛程来自一个站、xG 来自另一个站，口径对不上；二是让模型自己回忆「皇马这个赛季场均 xG 是多少」，它会一本正经地编一个数字。球小策足球数据（QiuXiaoCe Football Data）要解决的就是这件事——把权威、结构化的足球赛事事实源做成 Skill，让智能体按接口取数，而不是凭记忆作答。
下面介绍这个 Skill 是什么、能干什么、怎么装、怎么调，以及几个实际使用中会踩的点。
这是什么¶
一句话定位：球小策官方出品的足球大数据与 AI 赛前分析技能包，面向自媒体创作者、数据分析师与球迷，为大模型智能体提供结构化的赛事事实源。
出品方与维护方是球小策团队（www.qiuxiaoce.com），Skill 以社区（community）来源发布在 SkillHub，坐标 @user_e5e08891/qiuxiaoce-football-data，分类 professional。官方地址：
https://api.skillhub.cn/user_e5e08891/qiuxiaoce-football-data
包内是一个标准 SKILL.md 主入口加若干 workflow 分支：意图路由、取数脚本、本地缓存、内容模板、回测模板和自更新脚本。主入口文件只负责理解用户意图并分流，不凭自身内容直接回答数据问题。
需要说明一个版本差异：SkillHub 列表页标注的版本是 2.8.0，而官方版本接口当前返回的最新版本是 2.16.0（发布日期 2026-10-25）。以官方接口为准。
覆盖范围与核心能力¶
数据覆盖欧洲五大联赛（英超、西甲、意甲、德甲、法甲）、欧冠欧联及全球 80+ 主流联赛。官方站公开了 88 项赛事数据项，含赛程比分、首发阵容、球员与球队统计、进阶指标、伤停、天气等，每日自动统计。
能力分两层：
1、免费层，无需密钥：实时积分榜、球队与联赛中英文检索、射手榜与助攻榜。
2、需密钥层：注册球小策开发者控制台（https://www.qiuxiaoce.com/data-account/ ）可领取 500 点体验金，解锁单场全景数据包等更深层数据。
技能包明确列出的指标包括：
- 球队高阶画像：xG、xGA、战术指纹
- 球员高阶评分：综合评分、OTI 进攻威胁（OTI 与 OTI-XG 双口径）、DII 防守参与度、GIM 比赛影响力，另有状态、稳定性、疲劳，以及 xG 预期进球、xA 预期助攻
- 单场射门图：逐次射门坐标、单次 xG/PSxG、门将超额表现
- 其他：球队主场档案、市场行为指数、伤停名单、历史交锋、转会记录、教练履历、裁判执法风格
单场全景数据包号称 200+ 维，涵盖攻防均值、伤停量化折损、历史交锋等。技能触发词包括：查比赛、今天比赛、明天赛程、积分榜、射手榜、伤停、历史交锋、转会、教练、裁判、赛前分析、帮我预测、出报告、查额度、更新 Skill。
安装与启用¶
官方没有提供一行安装命令，安装走「取版本信息 → 下载 → 校验 → 解压 → 配密钥」的流程，全部在代码块里给出。
第一步，取最新版本信息，返回 version、download_url、sha256 校验清单、文件列表与更新说明：
curl -s "https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/skill/version"
第二步，按返回的 download_url 下载技能包，并用返回的 sha256 逐文件校验。当前版本的下载地址形如：
curl -LO "https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/skill/download?v=2.16.0"
第三步，解压到本地技能目录，保持包内顶层目录结构，按包内 SKILL.md 完成初始化。包内文件包括 SKILL.md、scripts/（fetch_match.py、query_backtest.py、check_quota.py、update_skill.py、local_store.py）、prompts/、references/、templates/、workflows/。
第四步，配置密钥。密钥形如 qxck_xxxxxxxx，可写入环境变量 QIUXIAOCE_API_KEY，或由技能写入本地 .qiuxiaoce_key。免费层接口不需要密钥，可以先跑通再配。
第五步，环境自检。脚本依赖 Python（≥3.8，仅用标准库，无需 pip install），每次会话第一次跑脚本前先确认：
python3 --version || python --version
两条都报错时不要自己折腾安装，直接告诉宿主 AI 工具需要 Python 3 环境并配置到 PATH。初始化本地库（不建也行，首次调用会自动建）：
python3 scripts/local_store.py init
环境类差异如实说明：官方声明 WorkBuddy、Qoder、Trae 等第三方客户端的安装配置、运行环境以及客户端内 Skill 如何导入加载，属于第三方软件自身的通用技能范畴，球小策不提供此类免费人工咨询与技术支持。只能在网页对话框里对话、访问不了文件系统的环境（豆包、通义千问、Kimi 等），装不了 Skill，官方建议的替代路径是直接给 AI 你的 API Key，按接口文档取数分析。
典型用法¶
接口根地址：
https://www.qiuxiaoce.com/wp-json/abv2-creator/v1
认证方式是请求头带上 X-API-Key，按次扣点，60 秒内同请求不重复扣。官方文档给出的最小可复现示例是今日总览：
curl -H "X-API-Key: 换成你的Key" \
"https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/today/digest"
想在调接口前先读文档，用公开的文档接口（无需密钥）：
# 取全量文档目录，返回所有篇章的标题与 slug
curl -s "https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs"
# 读单篇正文
curl -s "https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs/{slug}"
人读版页面在 https://www.qiuxiaoce.com/creator-docs/{slug}/，完整接口文档在 https://www.qiuxiaoce.com/data-docs/（48 个数据接口，逐个标注用途、参数、单次价格和真实返回示例）。
取数逻辑是「本地优先」：先查本地 SQLite，未命中或过期才调接口，接口拿到的重要数据必须落库。遇到报错先查官方排障手册 https://www.qiuxiaoce.com/creator-docs/api-error-codes-troubleshooting/，常见码：
- 401：Key 缺失、格式不对，或已被重置/吊销（
api_key_revoked），到控制台复制最新完整 Key 并同步更新所有已配置该 Key 的脚本与客户端 - 402：点数不足或已过期，需到 https://www.qiuxiaoce.com/data-service/ 充值
- 403：接口未开放，或权限不足（个别场次报告需要订阅）
- 404：实体 ID 或接口路径写错
- 429：请求过快，按响应头
Retry-After等待后重试
大批量调用前先查一次剩余点数，避免跑到一半失败。技能包本身也内置了更新流程（update_skill.py），升级前会逐项对比官方新版和你改过的文件，由你决定直接用新版还是保留改动合并升级。
适用场景与注意¶
适合三类人：做足球自媒体的创作者（赛前研报、文案生成）、做数据科学建模的分析师（需要可核对口径的结构化数据）、以及想给智能体接上赛事事实源的开发者。
几个限制与坑：
1、环境前提硬。需要能读写本地文件、能执行命令的桌面或终端类 AI 工具，且要有 Python 3。纯网页对话框用不了 Skill 本体。
2、点数制计费。按次扣点，60 秒内同请求不重复扣；免费层只有积分榜、球队联赛检索、射手榜助攻榜，单场全景包等深层数据要消耗点数。注册送 500 点体验金。
3、口径要先校正。技能要求使用 xG、xGA、OTI、DII 这类指标前先按官方文档校正口径，样本不足要在结论里注明；缺数据就说缺什么，不允许用「大概」「可能」糊过去。
4、版本差异。SkillHub 列表页显示的版本（2.8.0）落后于官方接口的最新发布（2.16.0），装完要核对实际版本号。
5、服务边界。官方明确声明不提供投注建议，也不做准确率承诺。技能包内容仅供赛事研究、数据科学建模与足球爱好者交流使用，不构成任何投注或投资建议。
6、数据降级要留意。近期版本增加了降级包标注：单场全景包新增 meta.quality（complete/degraded），降级包会自动退还点数，后台重建后重取即得完整版。
结尾¶
球小策足球数据的价值在于把「权威 + 结构化 + 可核对口径」这件事做成了智能体能直接调用的 Skill，省掉了自己接多个数据源和对口径的工作量。免费层可以先试，需要深层数据再配 Key。
官方地址：https://www.qiuxiaoce.com
SkillHub 页面：https://www.skillhub.cn/skills/user_e5e08891/qiuxiaoce-football-data
接口文档：https://www.qiuxiaoce.com/data-docs/
