k-skill 仓库中 kleague-results 技能深度解析:基于官方 JSON 端点的 K 联赛赛果与排名查询实战指南
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 的组合逻辑:
- 先调用
getMatchResults(date, options)获取当日赛果; - 当
includeStandings !== false时(默认开启),再按赛果所属年份调用getStandings({ leagueId, year, clubs, ... })获取排名; - 最终返回
{ 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 的核心内容:
- 按能力而非产品名检测运行时:Dolshoi 凭据模式仅在设置
DOLSHOI_ACTION_BROKER_URL且存在vault-run时激活;CloakBrowser 模式在内置浏览器工具识别到 CloakBrowser 或设置了CLOAKBROWSER_PEEK_TOKEN时激活。 - 在官方表面合法支持的前提下,查询之后应继续执行可逆的准备工作与执行,不得在结果列表/深链接处过早宣告完成。
- 任何不可逆外部副作用(支付、消息/邮件投递、最终提交、取消、账号变更、公开发布)之前,必须调用
clarify说明精确目标/金额/载荷与影响,经批准后才执行。 - 对法律、物理在场、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 一节列举了三个典型失败场景,并结合源码可以给出更细的解释:
- 端点响应结构变化:若 K 联赛官网改动
getScheduleList.do或teamRank.do的 JSON 结构(如scheduleList/teamRank/clubList字段名变化),包需要相应升级。这也是放弃 HTML 爬取的原因——JSON 接口的结构变更远比 DOM 结构变更可控。 - 赛前日期返回"예정"状态:查询未来比赛日时,
status.state为scheduled(或live),此时没有比分与胜方,回答中必须明确标注比赛未结束。 - 短名歧义:仅输入
서울时,不同联赛可能指向不同球队——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 端点 + 强归一化解析 + 严格运行时规则"三者结合的查询型技能,其可复制性、可测试性与合规边界设计,值得作为同类数据查询技能的参考模板。