k-skill 仓库中 kleague-results 技能深度解析:基于官方 JSON 端点的 K 联赛赛果与排名查询实战指南

原创2026-09-17 13:42:171,708 阅读
文章标签:AI 技能开发工具CLI

k-skill 仓库中 kleague-results 技能深度解析:基于官方 JSON 端点的 K 联赛赛果与排名查询实战指南

本指南以 k-skill 仓库中 kleague-results 技能的装配指令(assembled instructions,见 packages/k-skill-cli/test/snapshots/kleague-results.generic.md)为核心骨架,讲解该技能如何通过 K 联赛官网的官方 JSON 端点替代 HTML 爬虫,按日期与球队查询 K리그1/K리그2 的比赛结果和实时排名。读完本文,你将掌握 kleague-results npm 包的安装、ESM 动态导入调用、球队别名归一化机制,以及 Agent 运行时的合规边界与失败兜底策略,并能直接复用其完整调用脚本。

技能定位:查询型 Skill 与适用场景

kleague-results 是一个面向韩国职业足球联赛(K리그1 / K리그2)的查询型技能(lookup-oriented skill)。从装配指令(packages/k-skill-cli/test/snapshots/kleague-results.generic.md)可以看出,它的核心职责是:

  • 使用官方 K 联赛 JSON 接口,按 YYYY-MM-DD 日期查询某一天的比赛结果;
  • 支持按球队过滤(如 FC서울、서울 이랜드、球队代码 K09);
  • 在返回赛果的同时附带当前积分榜排名。

技能元数据(kleague-results/skill.json)将其归类为 sports 类别、ko-KR 语言环境,版本阶段为 v1。它对应的典型用户提问包括:

  • "오늘 K리그1 경기 결과 알려줘"(今天 K리그1 比赛结果)
  • "2026-03-22 FC서울 경기 결과랑 현재 순위 보여줘"(2026-03-22 FC首尔比赛结果和当前排名)
  • "2026-03-22 K리그2 결과 정리해줘"(整理 2026-03-22 K리그2 的结果)

核心设计原则:文档明确强调"HTML 크롤링 대신 공식 JSON 엔드포인트를 사용"(用官方 JSON 端点替代 HTML 爬取),这决定了该技能的维护成本远低于脆弱的页面抓取方案。

前置条件与安装方式

运行该技能需要满足以下前提(见装配指令 Prerequisites 一节):

  • Node.js 18+(kleague-results 包的 package.json 中 engines.node 声明为 >=18,且源码依赖全局 fetch);
  • 全局安装 npm 包:npm install -g kleague-results。

装配指令中有一个非常关键的约束:当 npm root -g 下不存在 kleague-results 包时,不得用 HTML scraping 绕行,而是先尝试全局安装:

npm install -g kleague-results

这条规则保证了技能始终走官方 JSON 数据通道。该包以 MIT 协议发布,仓库中的实现位于 packages/kleague-results/src/index.js 与 packages/kleague-results/src/parse.js。

底层原理:官方 JSON 端点与请求参数

该技能不依赖任何爬虫库,只对接 K 联赛官网的两个公开 JSON 表面:

用途 端点 请求方式
赛程/赛果 https://www.kleague.com/getScheduleList.do POST,JSON body
球队排名 https://www.kleague.com/record/teamRank.do POST,Query 参数

从 src/index.js 的源码可以确认这两个端点的实际请求参数:

赛程请求(fetchScheduleMonth)发送 POST 请求,body 为:

{
  "year": "2026",
  "month": "03",
  "leagueId": 1
}
  • year / month:目标月份,其中月份用 padStart(2, "0") 补零;
  • leagueId:经 normalizeLeagueId 归一化后的联赛编号(1 或 2)。

排名请求(fetchStandings)则在 URL 上拼接 4 个参数:

leagueId=1&year=2026&stadium=all&recordType=rank
  • stadium=all:默认拉取全部主场/客场合并的总榜;
  • recordType=rank:排名表类型。

所有请求都携带统一的默认请求头(见 src/index.js),其中 accept-language: ko-KR 用于固定韩语响应内容,user-agent: k-skill/kleague-results 用于标识调用方。请求支持注入自定义 fetchImpl(便于测试 mock)和 signal(AbortSignal 取消),当响应非 2xx 时会抛出 K League request failed with <status> for <url> 错误。

工作流分步拆解

装配指令(packages/k-skill-cli/test/snapshots/kleague-results.generic.md 的 Workflow 一节)给出了完整的四步执行流程,以下逐一步骤结合源码进行展开。

第 0 步:缺包时先全局安装

先检查 npm root -g 目录下是否存在 kleague-results,不存在则执行 npm install -g kleague-results,禁止用 HTML 抓取绕行。

第 1 步:拉取官方 K League JSON

由于技能运行时无法假设包相对于仓库或已安装技能的位置,装配指令要求通过 npm root -g 动态解析全局安装路径,再用 pathToFileURL 构造 ESM 导入地址,完整可复制的脚本如下:

GLOBAL_NPM_ROOT="$(npm root -g)" node --input-type=module - <<'JS'
import path from "node:path";
import { pathToFileURL } from "node:url";

const entry = pathToFileURL(
  path.join(process.env.GLOBAL_NPM_ROOT, "kleague-results", "src", "index.js"),
).href;
const { getKLeagueSummary } = await import(entry);

const summary = await getKLeagueSummary("2026-03-22", {
  leagueId: "K리그1",
  team: "FC서울",
  includeStandings: true,
});

console.log(JSON.stringify(summary, null, 2));
JS

这段脚本等价于调用 getKLeagueSummary("2026-03-22", { leagueId: "K리그1", team: "FC서울", includeStandings: true })。从 src/index.js 可以看到 getKLeagueSummary 的组合逻辑:

  1. 先调用 getMatchResults(date, options) 获取当日赛果;
  2. 当 includeStandings !== false 时(默认开启),再按赛果所属年份调用 getStandings({ leagueId, year, clubs, ... }) 获取排名;
  3. 最终返回 { queryDate, leagueId, filteredTeam, matches, standings } 聚合对象。

第 2 步:面向人类归一化输出

装配指令明确要求:不要把原始 JSON 直接抛给用户,而要按以下维度整理:

  • 主队 vs 客队(homeTeam / awayTeam);
  • 比赛时间 / 比赛是否结束(kickOff / status);
  • 比分(score.home / score.away);
  • 当前排名(standings);
  • 若指定了球队,只保留该队比赛。

这一点与 src/parse.js 中 normalizeScheduleItem 的输出字段一一对应:每场比赛会被归一化为 { leagueId, competitionName, round, gameId, date, kickOff, status, homeTeam, awayTeam, score, winner, venue, audience, broadcastChannels, matchCenterUrl },其中 matchCenterUrl 会根据 gameId 与 meetSeq 生成官方赛事中心链接。

第 3 步:保持回答紧凑

装配指令规定输出策略:若用户要的是当日赛果面板(scoreboard),先给每场比赛一行摘要;若是特定球队请求,则先展示该队比赛与当前排名,再补充其余信息。

输入参数与别名归一化机制

技能输入参数如下:

参数 说明 默认值
날짜(日期) YYYY-MM-DD 字符串或 Date 对象 必填
리그(联赛) K리그1 / K리그2(也接受数字 1/2 及英文别名) K리그1
팀(球队,可选) 短名、全名或球队代码,如 서울 / FC서울 / K09 无(全部球队)

联赛别名表

normalizeLeagueId(src/parse.js)内部维护一张别名映射表:

输入 归一化结果
1、K1、KLEAGUE1、K리그1 1
2、K2、KLEAGUE2、K리그2 2

别名的匹配基于 NFKC 规范化 + 大写 + 去除非字母数字字符(normalizeToken),因此像 k league 2、kleague2 这类带空格/大小写差异的输入也能正确解析;而 K리그3 这类非法值会直接抛出 leagueId must resolve to K League 1 or 2 错误。

日期校验

normalizeDateInput(src/parse.js)接受 YYYY-MM-DD 或 YYYY.MM.DD 格式,并做真实日历校验(含闰年判断,如 2026-13-40 会被拒绝)。这一点有测试兜底:getMatchResults 会先在发起网络请求前抛错(见 test/index.test.js 中断言 fetchCalled === false)。此外,用户说"오늘/어제"(今天/昨天)时,必须转换为绝对日期 YYYY-MM-DD 再执行,避免时区偏差——排名默认年份也取自韩国时区(Intl.DateTimeFormat("en-CA", { timeZone: "Asia/Seoul" }),见 src/index.js)。

球队别名解析

resolveTeamQuery(src/parse.js)会先从响应中的 clubList 构建球队目录(buildClubDirectory),每个球队的短名、全名、代码都作为 alias token 收录。例如测试夹具(test/fixtures/schedule-kleague1-2026-03.json)显示:teamId: "K09"、teamNameShort: "서울"、teamNameFull: "FC서울" 三者指向同一支球队,因此输入 서울、FC서울、K09 都能过滤出 FC首尔的比赛,并返回 filteredTeam.normalized === "FC서울" 作为确认信息。

比赛状态码映射

normalizeMatchStatus 使用 STATUS_MAP(src/parse.js)将官方状态码翻译为统一状态:

官方状态码 state label
FE finished 종료(已结束)
NS scheduled 예정(未开始)
LIVE / IN live 진행 중(进行中)
HT halftime 하프타임(中场)
PP postponed 연기(延期)
CAN cancelled 취소(取消)

determineWinner 只在 finished 状态下判定胜方(home / away / draw),未结束的比赛返回 null。

运行时规则:合规边界与完成判定

装配指令开头的 Runtime rules 是 Agent 必须遵守的行为约束,也是本文档区别于普通 README 的核心内容:

  1. 按能力而非产品名检测运行时:Dolshoi 凭据模式仅在设置 DOLSHOI_ACTION_BROKER_URL 且存在 vault-run 时激活;CloakBrowser 模式在内置浏览器工具识别到 CloakBrowser 或设置了 CLOAKBROWSER_PEEK_TOKEN 时激活。
  2. 在官方表面合法支持的前提下,查询之后应继续执行可逆的准备工作与执行,不得在结果列表/深链接处过早宣告完成。
  3. 任何不可逆外部副作用(支付、消息/邮件投递、最终提交、取消、账号变更、公开发布)之前,必须调用 clarify 说明精确目标/金额/载荷与影响,经批准后才执行。
  4. 对法律、物理在场、CAPTCHA、身份核验、电子签名与不支持的官方表面保持硬边界:完成最远可合法执行的步骤,并为用户打开/准备好下一步官方入口。

具体到本技能:它是查询型技能,完成即意味着"所需数据已取回、附带来源(表/端点、周期、单位)的摘要、并把后续动作连接到支持它的官方表面"。Done when 判定条件为:

  • 已按日期给出比赛摘要;
  • 若有球队请求,只剩该队比赛;
  • 当前排名已一并整理。

打包资产访问同样有硬性约束:辅助脚本只能通过 npx -y @nomadamas/k-skill@0 exec kleague-results scripts/<file> -- <args> 执行;需要文件系统路径时用 npx -y @nomadamas/k-skill@0 path kleague-results <relative-path>;读取附带参考文档用 npx -y @nomadamas/k-skill@0 read kleague-results references/<file>——不得假定仓库相对路径或已安装技能相对路径。完整的技能入口指令位于 kleague-results/instruction.md 与 kleague-results/SKILL.md。

失败模式与注意事项

装配指令的 Failure modes 一节列举了三个典型失败场景,并结合源码可以给出更细的解释:

  1. 端点响应结构变化:若 K 联赛官网改动 getScheduleList.do 或 teamRank.do 的 JSON 结构(如 scheduleList / teamRank / clubList 字段名变化),包需要相应升级。这也是放弃 HTML 爬取的原因——JSON 接口的结构变更远比 DOM 结构变更可控。
  2. 赛前日期返回"예정"状态:查询未来比赛日时,status.state 为 scheduled(或 live),此时没有比分与胜方,回答中必须明确标注比赛未结束。
  3. 短名歧义:仅输入 서울 时,不同联赛可能指向不同球队——K리그1 是 FC서울(K09),K리그2 则是 서울 이랜드,需要结合 leagueId 确认归属。

其他注意事项还包括:

  • getScheduleList.do 返回的是月度数据,所以无论查询哪天,都需在客户端按 gameDate(YYYY.MM.DD 点号格式)精确过滤——这正是 normalizeScheduleResponse 中 item.gameDate === queryDate.dottedDate 的逻辑;
  • 排名默认取 stadium=all 的总榜;
  • 包为新增发布,合并后需通过 Changesets 触发 npm publish,全局安装流程才能生效。

源码级验证:测试与夹具

仓库为该包提供了完整的 Node 原生测试(packages/kleague-results/test/index.test.js),覆盖四个关键行为:

  • 联赛别名归一化:normalizeLeagueId 接受数字、韩文与英文别名,非法值抛错;
  • 月度载荷过滤:用夹具 test/fixtures/schedule-kleague1-2026-03.json 验证 2026-03-22 的 FC서울 主场比赛被正确筛出,比分 5:0、状态 FE/종료、主场 서울 월드컵 경기장;
  • 排名表结构:用夹具 test/fixtures/standings-kleague1-2026.json 验证 12 支球队的完整排名形状,K09 队 4 战 12 分排名第 1,近期战绩 ["승","승","승","승"];
  • 端到端组合:通过 mock global.fetch 断言 getKLeagueSummary 依次请求赛程与排名两个端点、赛程请求携带 "month":"03" 载荷、且所有请求都带有 ko-KR 语言头。

运行测试与代码检查的方式(见 package.json 的 scripts):

cd packages/kleague-results && npm test
cd packages/kleague-results && npm run lint

功能层面的使用手册可进一步参考 docs/features/kleague-results.md 与 packages/kleague-results/README.md。总体而言,kleague-results 是一个"官方 JSON 端点 + 强归一化解析 + 严格运行时规则"三者结合的查询型技能,其可复制性、可测试性与合规边界设计,值得作为同类数据查询技能的参考模板。

登录后查看全文
k-skill