知体育 | 体育数据分析

概述

体育数据与赛事分析

仅使用随本 Skill 发布的 sportkit 查询本地目录和体育 API。不得直接读取catalog CSV、直接调用 HTTP API，也不得自行拼接 URL、推断 materialIndexList或重写素材计费逻辑。

只有本次答复实际调用了知体育服务接口（包括鉴权、权限预检、数据或素材请求）时，才必须以$SKILL_ROOT/references/service-operations.md 定义的账户信息区块收尾。纯安装、版本检查、目录查询，以及未调用知体育接口的普通答复不得附加该区块。只能展示本次已获得的服务端余额；无法获得或未登录时明确说明，不得编造账户、套餐或积分值。账户中心仅在本次config token-status --json 输出非空 token_url 时使用参考资料中的 Markdown 超链接模板展示。

在仓库开发时，可查阅 docs/cli-usage.md 了解人工安装和命令示例。接口契约还包括docs/01 至 docs/04 的近期状态、未来赛程、实时事件/统计和即时赔率文档；以下内容与Skill 包中的 references/ 共同构成运行时规则。

范围与数据原则

支持足球 ft 与篮球 bk 的实体查询、赛程发现、积分榜和赛季背景、球队/球员研究、赔率背景，以及赛前、赛中背景和赛后分析。API 返回值是事实来源；答复中必须区分：

• 知体育赛事数据：成功的 API 响应。
• 联网公开资料：仅用于补充成功 API 响应中缺失且任务允许公开检索的事实，给出链接和

发布日期或获取时间。

• 助手判断：基于证据的归纳、推断、情景分析和不确定性。

不要把助手判断或媒体观点表述为知体育官方结论，也不要用公开资料绕过权限不足、607、鉴权失败、预检失败或服务故障。

“知体育｜体育数据分析”仅用于 Skill 入口、账户信息和规定的答复页脚，不要在普通分析正文中反复出现。询问功能或用法时直接回答，不索取 API Key、手机号或验证码。

何时读取参考资料

• 涉及鉴权、账户、错误、素材数据或多步骤分析时，先读

$SKILL_ROOT/references/service-operations.md。它定义鉴权、权限预检、任务续办、证据、积分和错误处理。

• 单接口直查且属于下方“直查”表时，先做简短权限预检；只有预检需要配置、失败，或答案

需要更多证据时，才继续读服务或运动项目参考资料。

• 确认运动项目后，按需读取一个项目参考：足球读

$SKILL_ROOT/references/football.md，篮球读$SKILL_ROOT/references/basketball.md。参考资料是业务路由指南，不替代 CLI 目录。

每次素材请求前，都用目录确认准确路由、必填参数和当前支持的素材索引。按渐进式工作流决定暴露多少目录信息，不要一次列出或调用全部能力。

运行时 CLI 规则

正常的数据调用使用可由 PATH 解析、由宿主预装的统一 sportkit；不得调用 git、cargo、rustup 或任何仓库构建命令，也不得使用项目内 node_modules、Skill 目录或沙箱中的CLI 副本。打包产物根目录的 sportkit-dependency.json 记录目标 npm package、version 和agent_channel。先读取该文件，将 agent_channel 保存为本次答复的渠道变量。本包构建时已将渠道写入此 Skill：2335427。该值只用于替换命令中的渠道参数，不得自行改成主站或其他渠道。

除纯本地目录查询外，每一条 sportkit 命令都必须带上该渠道：sportkit --agent-channel <agent_channel> <command>；Windows Git Bash、MSYS/MSYS2 或 Cygwin使用 sportkit.cmd --agent-channel <agent_channel> <command>。不要猜测、修改或省略渠道号。

如需把渠道写入用户配置文件供后续调用复用，可执行一次：sportkit config set-channel --channel 2335427 --json。该命令只更新sportkit.json 顶层的 agent_channel，不会改动认证信息；显式的 --agent-channel 优先级更高。

首次使用前直接运行：

sportkit --agent-channel 2335427 --version
npm ls --global --depth=0 --json

Windows 的 Git Bash、MSYS/MSYS2 或 Cygwin 是例外：这些 shell 中所有 CLI 调用（包括版本检查）都使用 sportkit.cmd，例如 sportkit.cmd --agent-channel 2335427 --version。npm 为 Windows 生成的裸 sportkit 命令是POSIX shell shim，受限 Bash 环境可能缺少其依赖的基础命令；不要改为硬编码全局 node 或包路径。Windows PowerShell、cmd.exe、Linux 和 macOS 继续使用 sportkit。

成功时输出 sportkit <version>。版本检查确认宿主提供了可运行的 sportkit，并记录当前版本；依赖清单中的 version 是本 Skill 推荐使用的 CLI 版本。版本不一致只提示，不阻断可运行的通用 CLI，但安装、迁移和缺少 CLI 时的引导必须使用该固定版本。渠道检查使用sportkit --agent-channel <agent_channel> channel check --json，输出中的 agent_channel 必须与依赖清单一致。--version 会在渠道解析前短路，只验证版本元数据；必须依靠后续的 channel check 验证渠道值。新版统一包还会在 stderr 输出 Package: sportkit@<version> 和 Update command。必须同时读取 stdout、stderr 和退出码，不能只按语义版本号、内置渠道或命令名判断安装来源。Update command 是通用 CLI提示；Skill 的安装、迁移和版本差异引导必须以依赖清单中的固定版本命令为准。

为迁移历史渠道包，读取 npm ls --global --depth=0 --json 的 dependencies 键及其版本信息。只有精确发现sportkit-cli、sportkit-cli-w 或 sportkit-cli-h 中的一个或多个时，才将它们认定为旧渠道包；不能用通配符、相似名称、CLI 语义版本或 PATH 推测卸载目标。发现旧渠道包后，agent 必须自动卸载实际发现的旧包，再安装依赖清单中指定版本的统一包并复查：

npm uninstall --global <detected legacy package: sportkit-cli, sportkit-cli-w, or sportkit-cli-h>
npm install --global <package>@0.1.26
sportkit config set-channel --channel 2335427 --json
sportkit --agent-channel 2335427 --version
npm ls --global --depth=0 --json
sportkit --agent-channel 2335427 channel check --json

复查的 npm JSON 必须包含统一 <package>，且不再含上述三个旧包；版本检查 stderr 必须显示Package: <package>@<version>，渠道检查必须匹配依赖清单。任一步失败、npm 输出无法解析，或卸载后仍解析到未知来源的 sportkit 时，报告冲突并停止，绝不能删除未被上述精确列表确认的软件包。

未发现旧渠道包时，不能因为通用 <package> 的版本较旧、版本检查失败或缺少 Package: 行而卸载或自动重新安装。若当前版本与依赖清单中的 version 不一致，提示用户按固定版本命令更新：npm install --global <package>@0.1.26；版本差异只作提示，不阻断可运行的通用 CLI。命令不存在时，本次无法通过 sportkit 执行数据调用，同样建议用户或管理员执行该固定版本命令。依赖清单中的package 用于确定统一包名，不能使用渠道专用包、npx、项目副本或修改其他 npm 包替代。

CLI 使用原有 Token 认证并把配置保存在用户目录，不要把 Token 写入 Skill 目录或提交到仓库。

不同平台的 npm 安装会提供对应的原生 sportkit，不需要 Skill 调用仓库或包内 wrapper。环境准备好后，除Git Bash、MSYS/MSYS2 或 Cygwin 使用 sportkit.cmd 外，所有数据和认证命令直接使用 PATH 中的sportkit。sportkit --agent-channel 2335427 version check --json 查询 /ai-api/version/latest，只报告当前版本、最新版本和下载地址；检测到更高版本时仍按依赖清单中的固定版本提示更新命令，不要改用 @latest。除上述已确认的旧渠道包迁移外，不能自行安装、卸载或切换版本。

同一次用户答复的首次 CLI 调用前创建一个 trace ID（优先 UUID；不可用时用当前时间加随机后缀），并在全部 call、request build、鉴权和权限命令中复用：--header "chat-trace-id=<trace-id>"。新答复才创建新 ID。

调用 CLI

将 SKILL_ROOT 设为本 SKILL.md 所在目录，然后直接调用：

sportkit --agent-channel 2335427 <command>

在 Windows Git Bash、MSYS/MSYS2 或 Cygwin 中，将本节以下每一条 sportkit 命令替换为sportkit.cmd；不得通过全局安装目录中的 node 直接调用 bin/sportkit.js。

目录和请求命令传 --json，JSON 是稳定的调用接口；不要解析供人阅读的制表符输出。--json 下，本地校验失败也会在 stdout 输出一个 ok: false 的 JSON 对象；若携带 --route-id，其中会包含完整的 route.query_parameters 和route.required_query_parameters。修正请求前先读该对象与 stderr，绝不猜参数名重试。

每个完整的 NAME=VALUE 必须在调用处作为一个参数：

# Linux 或 macOS（bash）
sportkit --agent-channel 2335427 request build --route-id ft.data.hot-match --param "startDate=2026-08-21" --param "endDate=2026-08-22" --json

# Windows PowerShell
sportkit --agent-channel 2335427 request build --route-id ft.data.hot-match --param "startDate=2026-08-21" --param "endDate=2026-08-22" --json

# Windows cmd.exe
sportkit --agent-channel 2335427 request build --route-id ft.data.hot-match --param "startDate=2026-08-21" --param "endDate=2026-08-22" --json

# Windows Git Bash、MSYS/MSYS2 或 Cygwin
sportkit.cmd --agent-channel 2335427 request build --route-id ft.data.hot-match --param "startDate=2026-08-21" --param "endDate=2026-08-22" --json

PowerShell 与 cmd.exe 都要保留每个 --param 后完整值的引号；bash 也必须让一个带引号的参数对应一个键值对。结构化参数数组中同样把完整 NAME=VALUE 保存在一个元素里。日期值绝不能写成未加引号的 --param startDate=2026-08-21。

直查

当前任务没有可用的 ready 权限快照时，先运行sportkit --agent-channel 2335427 auth api-permissions --brief --json，并在 authorized_interfaces 中只检查拟调用路由。权限已就绪后，以下高频、小型只读问题只发起一次 call --output -，不要额外做工作流或目录发现：

ft.data.hot-match 始终要求明确的 startDate 和 endDate。不得省略，也不得称其结果为完整赛程。

受保护查询与渐进式发现

调用受保护路由前必须遵循 service-operations.md 的鉴权和权限预检。只有权限快照显示该准确route_id 可调用，且每个请求的素材索引均可用时，才能调用。多接口、素材、实体解析或分析任务先按业务工作流发现，而不是直接罗列全部路由和索引：

sportkit --agent-channel 2335427 catalog workflows --sport ft --intent match_analysis --json
sportkit --agent-channel 2335427 catalog workflow --workflow-id ft.match-analysis --level overview --json

概览会给出入口、比赛锚点、阶段、所需上下文和主题。正常依赖顺序为：

identify -> context -> linked_entities -> summary/analysis

以唯一 matchId 之后的 context 为锚点；只有需要联赛、球队、球员、裁判或教练 ID 时再展开linked_entities。阶段是依赖图，不是批量请求清单。用户选定主题后，先读 plan，只在已知比赛与所需 ID 后展开一个主题到 full：

sportkit --agent-channel 2335427 catalog workflow --workflow-id ft.match-analysis --level plan --topic form --json
sportkit --agent-channel 2335427 catalog workflow --workflow-id ft.match-analysis --level full --topic form --json

用返回的 sources[].route_id 和 sources[].indexes 分别执行 request build --json。不得跨路由合并索引、假定一个主题的路由支持全部索引，或默认展开所有主题。bk.match-analysis 使用相同过程，但主题和素材含义以篮球目录为准。

选择路由与参数

1. 识别项目：足球为 ft，篮球为 bk。
2. 多步骤任务先读 catalog workflow 的 overview/plan；直查或需精确检查工作流来源时才列路由：

   sportkit --agent-channel 2335427 catalog routes --sport ft --kind material --json

1. 每个依赖调用前，先检查参数契约；catalog params 不需要素材索引：

   sportkit --agent-channel 2335427 catalog params --route-id ft.material.match --json

1. 只有查看某个素材能力时才使用 catalog show 和 --material-index：

   sportkit --agent-channel 2335427 catalog show --route-id ft.material.match --material-index 17 --json

素材能力以 (route_id, material_index) 识别，不以 path 或 domain 单独识别。数据路由不得传--material-index。catalog params 的 param_name、类型和必填标记是唯一权威，不得猜测。

每次数据或素材调用都可能扣积分。billing_key 是本地能力标识，不是价格；调用前目录中credit_cost: null 与 credit_cost_source: "server_response_only" 是有意设计。只能把调用结果中的credit_cost 和 rest_points_count 作为计费证据，不得假设数据接口免费。

解析用户目标

调用依赖接口前先解析 ID，绝不把名称、leagueId、stageId、seasonId、teamId、playerId、refereeId 或 coachId 互相替代。推荐顺序：

1. 用户给出 matchId：调用 ft.data.match-info 或 bk.data.match-info。
2. 用户给出球队名：调用 *.data.team-query，消歧后再用 *.data.team-match-schedule 或

*.data.team-info。

1. 用户给出联赛名：调用 *.data.league-query，再按需解析 league-info、league-stage 或

league-match。

1. 指定日期的已列足球比赛：调用带两个日期边界的 ft.data.hot-match；已知联赛或要求完整联赛

赛程时使用 *.data.league-match。

1. 已有两支球队 ID 且需要交锋背景：调用 *.data.h2h-matches 或对应 H2H 素材。

名称查询有多个合理实体时请用户选择或报告歧义，不可静默选定。保留 API 返回的 ID 和比赛元数据；素材往往需要从实体或比赛响应取得 seasonId、stageId、teamId、playerId，不能猜。

常见字段约定：*.data.league-query 的联赛 ID 是 id 而不是 leagueId；*.data.league-stage 的赛季和阶段 ID 分别位于 seasonList[].seasonId 与stageList[].stageId；足球 ft.data.team-info 为教练查询提供 coachId；ft.material.season-player 需要 materialIndexList、seasonId、teamId、playerId。它们不是替代目录检查的规则，每次依赖调用仍先执行 catalog params --route-id <route>。

业务码 606 即使 HTTP 为 2xx 也表示失败：call 会给出 ok: false 与退出码 2。保留结果后改用更宽的历史窗口或其他支持实体，不能原样盲重试。intelligence-match 与按裁判姓名查询的覆盖有限，首次无数据后不要反复尝试任意名称。

构建与发送请求

先使用 request build 校验而不发送请求。它仍会读取配置并要求本地 token格式有效，因为输出代表一个可发送的认证请求；它不会访问服务端：

sportkit --agent-channel 2335427 request build --route-id ft.material.match --param "matchId=10001" --param "materialIndexList=17,25" --json

它会校验必填参数、整数、正数、枚举、布尔值和日期格式、每个素材索引的路由支持情况，以及未知查询参数；会保持materialIndexList 的顺序，同时为每个索引输出唯一的 capability_id 和 billing_key。重复索引仍按传入值发送，但计费身份列表中仅出现一次。

不得把 agent key 放入 --param。sportkit 使用 X-Agent-Key 发送它并在输出中脱敏；每个请求还会携带统一 sportkit 的 X-Agent-Client、运行时 X-Agent-Channel、X-Agent-Version，它们不是调用者参数。

权限与索引预检已通过后，才使用 call。小型直查用 --output -（或省略 --output）从 stdout读取 JSON；多路由、大响应或需续办的证据使用 $TASK_DATA_DIR 下唯一文件：

# Linux 或 macOS
response_file="$TASK_DATA_DIR/ft.data.match-info-10001.json"
sportkit --agent-channel 2335427 call --route-id ft.data.match-info --param "matchId=10001" --json --output "$response_file"

# Windows PowerShell
$responseFile = Join-Path $TASK_DATA_DIR "ft.data.match-info-10001.json"
sportkit --agent-channel 2335427 call --route-id ft.data.match-info --param "matchId=10001" --json --output "$responseFile"

# Windows cmd.exe
set "RESPONSE_FILE=%TASK_DATA_DIR%ft.data.match-info-10001.json"
sportkit --agent-channel 2335427 call --route-id ft.data.match-info --param "matchId=10001" --json --output "%RESPONSE_FILE%"

文件输出时 stdout 只有 result_path<TAB><PATH>；读取制表符后的路径并只读取所需字段，不要用 > 截取 call 响应，也不要把完整证据文件粘回对话。保存结果含 HTTP 状态、脱敏请求、billing_keys与服务端响应。服务端对访问、套餐、倍率、余额和实际扣分有最终解释权；本地权限快照只是当前任务的调用边界。

401001、401007、HTTP 401 或 HTTP 403 均停止受影响路径，按service-operations.md 的 token 重置规则处理；607 表示额度不足，按其中的积分不足规则保留已完成数据并引导账户中心。只有ok: true 的保存结果才能进入正常推理链。失败请求不可盲重试或称为成功/已扣费。

查询与分析方法

直查时调用能回答问题的最小数据路由：赛程用 league-match、team-schedule、team-match-schedule 或 hot-match；比赛资料/比分/状态用 match-info；赛前近期状态和交锋分别用 team-recent-form-*、h2h-record-*；未来赛程用 match-future-schedule；近期技术画像用 team-recent-technical-*；赛前赔率用 match-odds，赛中赔率用match-live-odds；赛中事件和统计用对应的 match-live-* 路由；可用素材用match-material；实体查询用对应 *-query 或 *-info。返回所需事实和相关 ID，不要为比分、赛程或资料请求深层素材。

深度比赛分析按以下顺序：

1. 识别项目与唯一 matchId；无法唯一识别时先消歧。
2. 调用 *.data.match-info，取得参赛方、联赛、赛季、阶段、时间、状态和比分，作为分析锚点。
3. 读取项目参考和工作流概览，只选择用户真正需要的主题：状态/H2H、阵容伤停、技术统计、赔率、

动机、资讯或供应商分析。

1. 在 plan 层检查选定主题。需要从比赛派生联赛、球队、球员、裁判或教练素材时，优先用

*.material.match-material；比赛级素材用 *.material.match；已知球队或球员再用专用统计路由。

1. 只把选定主题展开到 full，每个素材请求先运行 request build --json，检查

capability_ids 和 billing_keys。索引仅在同一路由支持时成组；文档中的 64-68 表示64,65,66,67,68，CLI 仅接受逗号分隔整数。

1. 调用获准请求并保存每项的 materialIndex、materialName、materialContent、

materialDesc；一个索引可返回多条记录，必须保留实体关联。

1. 对不同证据求证与比对，明确一致、矛盾、过期、缺失与不支持的维度，不以常识填补空白。

按需使用比赛背景、近期状态与交锋、可用性、技术画像、市场背景、积分/动机与资讯等视角。赔率变动、供应商分析或资讯片段都不是确定结果。用户要求预测时，只给出数据支持的倾向、反向信号、置信限制和失效条件；不得保证结果或编造 API 未返回、也未说明计算方法的概率。

• 赛前：标明为赛前快照，区分预计阵容与确认阵容。
• 赛中背景：足球可用 match-live-event、match-live-statistics 和 match-live-odds，

篮球可用 match-live-statistics 和 match-live-odds。保留响应中的 dataTime、queryTime和空数据标记；接口有缓存时不要高频轮询，不能编造缺失事件、统计、节次或赔率。

• 赛后：区分观察到的赛果/统计与赛前信号；不能用最终比分单独证明预测有效。

深度分析答复依次给出：比赛识别与可用时间背景、附路由或 materialIndex 标签的关键事实、适用的状态/可用性/技术/市场/动机分析、冲突信号与数据缺口，以及克制的结论或情景展望。纯查询先给简洁结果，不附加未被要求的叙述；绝不暴露 agent key 或原始含密请求头。

完成答复

完成受保护调用后，或出现鉴权、权限、积分、数据或服务错误时，必须读取$SKILL_ROOT/references/service-operations.md 并执行其中的数据来源、积分页脚、恢复和账户规则。保留已经完成的证据，不要重试已成功保存的请求。