kbl-results 使用指南基于官方 JSON 端点封装 KBL 篮球比赛结果与球队排名查询【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本篇文章围绕开源仓库 k-skill 中独立发布的 npm 包kbl-results见 packages/kbl-results/README.md展开介绍如何用一行命令安装、通过三个核心函数查询韩国职业篮球联赛KBL按日期划分的比赛结果与实时球队排名并深入其源码实现理解日期归一化、球队别名匹配、比赛状态判定与排名数据结构化的底层原理。读完本文你将能够在自己 Node.js 项目中直接接入 KBL 官方 JSON 数据源并清楚该客户端在数据清洗、健壮性设计上的取舍。一、包定位为什么选择包装官方 JSON 端点kbl-results是一个可复用的 Node.js 客户端它直接包装 KBL 官方 JSON 端点而非对 HTML 页面做爬虫解析。这一点在文档的 Notes 中被明确强调由于基于官方 JSON 端点维护成本比 HTML 爬取简单得多——只要官方接口稳定客户端只需做一层轻量归一化即可长期使用。该包在 packages/kbl-results/package.json 中声明了其基本属性包名kbl-results版本0.2.0MIT 许可证入口文件src/index.js发布内容包含src与README.md要求 Node.js 18依赖原生fetchkeywords为k-skill、kbl、basketball、korea并配置了lintnode --check语法检查与testnode --test两个脚本。它在 k-skill 仓库中对应一个同名的 Agent 技能skill技能元数据将其归入sports分类、ko-KR语言环境见 kbl-results/SKILL.md说明其典型用途是让 AI Agent 在收到某日 KBL 比赛结果当前 KBL 排名之类的查询时通过该包快速拿到结构化数据。二、安装在任意 Node.js 18项目中执行npm install kbl-results包本身只依赖 Node 内置能力与全局fetch安装后无需额外配置 API Key 或环境变量即可开始查询。三、官方数据源与请求参数客户端背后只有两个官方端点详见 src/index.js端点用途https://api.kbl.or.kr/match/list按日期范围查询赛程 / 比赛结果https://api.kbl.or.kr/league/rank/team查询当前 KBL 球队排名关于请求参数README 的 Notes 部分给出了两点关键约定源码 fetchMatchList 中得到了完整印证日期格式为YYYYMMDDmatch/list接受fromDate/toDate客户端会把用户传入的YYYY-MM-DD或Date对象归一化为紧凑的 8 位数字串并让fromDate与toDate指向同一天从而实现按单日查询seasonGrade1表示 KBL 1 军这是查询的默认值另有tcodeList参数默认取all全部球队编码。此外requestJson 在请求时固定携带一组请求头其中accept-language: ko-KR、channel: WEB、teamcode: XX、lang: ko用于确保服务端返回韩文数据user-agent: k-skill/kbl-results用于标识调用方。若响应非 2xx会抛出KBL request failed with ${status} for ${url}错误。四、快速上手README 提供的 Usage 示例完整覆盖了三个公开函数。将其放入node --test之外的普通脚本即可运行const { getKBLSummary, getMatchResults, getStandings } require(kbl-results); (async () { // 1) 查询 2026-04-01 的赛果并只保留与 서울 SK 有关的比赛 const results await getMatchResults(2026-04-01, { team: 서울 SK, }); // 2) 查询当前球队排名 const standings await getStandings(); // 3) 一次性拿当日赛果 当前排名 const summary await getKBLSummary(2026-04-01, { team: 부산 KCC, includeStandings: true, }); console.log(results.matches[0]); console.log(standings.rows[0]); console.log(summary); })();三段输出分别对应归一化后的单场比赛对象、排名表中的一行数据、以及包含queryDate/filteredTeam/matches可选standings的汇总对象。五、API 详解README 的 API 章节定义了三个公开函数此处结合源码补充参数默认值、取值范围与扩展选项。5.1getMatchResults(date, options)返回指定日期的比赛结果列表。参数说明dateYYYY-MM-DD字符串或Date对象options.team球队短名 / 全名 / 球队编码别名均可匹配options.seasonGrade默认1KBL 1 军实现层面getMatchResults还支持以下隐藏选项tcodeList默认all对应match/list的tcodeList查询参数schedulePayload/standingsRows直接注入原始响应数据跳过网络请求测试与离线场景使用fetchImpl自定义 fetch 实现默认取global.fetchsignalAbortSignal用于取消请求。返回对象形如{ queryDate: 2026-04-01, // ISO 格式的查询日期未传日期时为 null seasonGrade: 1, filteredTeam: { input, normalized, code }, // 仅在传了 team 时存在 matches: [ /* 归一化后的比赛对象数组 */ ], }5.2getStandings(options)返回当前 KBL 球队排名支持standingsPayload/fetchImpl/signal等注入选项。返回结构为{ rows: [ /* 按 rank 升序排列的 10 支球队排名行 */ ], }5.3getKBLSummary(date, options)将某日比赛结果与当前排名合并为一次调用返回。关键开关是includeStandings默认true当includeStandings: true时会先请求排名端点再请求赛程端点最后把两者组装进一个对象当includeStandings: false时完全跳过排名请求测试用例 index.test.js 专门断言了/league/rank/team不会被请求返回对象不含standings字段。组装逻辑见 getKBLSummary先把排名数据注入比赛归一化过程用于补全球队信息再分别归一化两个数据源最终输出{ queryDate: 2026-04-01, filteredTeam: { ... }, matches: [...], standings: { rows: [...] }, // includeStandings 为 false 时不出现 }六、返回数据结构深度解析为了让读者能直接消费返回数据下面结合源码与测试夹具test/fixtures说明每个数据对象的字段含义。6.1 单场比赛对象由 normalizeScheduleItem 从原始 JSON 转换而来主要字段字段来源字段说明gameKey/gameNumber/gameCode/seasonCodegmkey/gameNo/gameCode/seasonCode比赛与赛季标识seasonGradeseasonGrade赛季级别如 1KBL 1 军competitionNameseasonName1赛季名称如2025-2026seasonCategoryseasonCategory/seasonCategoryName赛事阶段如R정규시즌 常规赛/PO플레이오프 季后赛date/dateLabel/weekDaygameDate/weekDay日期ISO 格式与星期startTime/endTimegameStart/gameEnd将HHMM紧凑格式转为HH:MM时钟格式statusisEnded/isStarted/playingQuarter归一化后的比赛状态见下文homeTeam/awayTeamtcodeH/tnameH/tnameFH等主客队对象含 code/name/fullName/logoClassscorescoreH/scoreA{ home, away }比分winner由比分与状态推导已结束且分差非零时返回{ team }否则nullvenuestadiumname/stadiumnameF场馆短名与全名broadcastChannelstv转播频道数组按/拆分去空比赛状态映射STATUS_MAP normalizeMatchStatusisEnded 1→{ code: ENDED, state: finished, label: 종료, finished: true }否则若isStarted 1→{ code: LIVE, state: live, label: 진행 중, finished: false, quarter }quarter取playingQuarter如Q3其余 →{ code: SCHEDULED, state: scheduled, label: 예정, finished: false }。在测试夹具 schedule-kbl-2026-04.json 中可以看到上述原始字段的完整形态例如부산 KCC对阵서울 SK的比赛同时具备isEnded: 1、scoreH: 81、scoreA: 79、stadiumnameF: 부산사직체육관、tv: tvN SPORTS。6.2 排名行对象由 normalizeStandingsResponse 生成每行字段字段来源字段说明rankrank排名升序输出teamtcode/tname/tnameF/teamLogoClass球队对象win/loss/drawwin/loss/draw胜 / 负 / 平gamesBehindwinDiff胜场差winningPercentage由胜平负计算胜率保留 3 位小数home/awayhwin/hloss/awin/aloss主客场的胜负数streakcontiWin/contiLoss当前连胜 / 连败maxStreakmaxWin/maxLoss赛季最长连胜 / 连败lastFivelastRecord最近 5 场结果1→W0→L测试断言index.test.js验证了该结构서울 SK排名第 4、32 胜 22 负、胜场差 4、近 5 场为[L,L,W,L,L]与夹具 standings-kbl-2026.json 数据一致。七、源码级原理三处关键设计7.1 日期归一化与闰年校验normalizeDateInput 同时接受YYYY-MM-DD也兼容.分隔符与Date对象字符串输入会经过正则^(\d{4})-.-.$校验再交给isValidCalendarDate做真实日历校验含闰年 2 月 29 日判断见 isLeapYearDate输入会通过Intl.DateTimeFormat(en-CA, { timeZone: Asia/Seoul })转换为首尔时区下的年月日避免 UTC 与韩国本地时间错位最终产出{ isoDate: 2026-04-01, compactDate: 20260401, ... }两组格式分别用于返回给调用方与拼进match/list的fromDate/toDate参数。无效日期如2026-13-40会在发起任何网络请求之前抛出date must be a valid Date or YYYY-MM-DD string.测试 index.test.js 用fetchCalled false证明了这一先校验后请求的顺序。7.2 球队目录与别名解析客户端内置了 10 支 KBL 球队的静态目录KNOWN_TEAMSparse.js包含球队编码如60 부산 KCC、短名、全名、logo 类名与别名如KCC、이지스、EGIS。真正的球队目录由 buildTeamDirectory 动态构建先注入静态 10 队再用赛程与排名原始数据中的tcodeH/tnameH/tnameFH、tcode/tname/tnameF等字段实时补充或覆盖——这样即使官方更新了球队名称也能从响应本身获取最新名称。别名解析 resolveTeamQuery 的匹配规则是将查询串通过 normalizeToken 做 NFKC 归一化、大写、剔除空白与非字母数字韩文符号先做精确匹配别名 token 完全相等无精确命中时退化为包含匹配一方包含另一方若恰有一个匹配球队则返回该队多候选或零候选时返回一个code: null的占位对象后续按文本 token 做兜底过滤itemMatchesRequestedTeam。因此调用方写KCC、부산 KCC或부산 KCC 이지스都能命中同一支球队而filteredTeam.normalized会回显标准全名。7.3 请求响应与数据清洗requestJson统一负责 GET 请求、合并默认请求头与错误抛出normalizeNumber把null/undefined/ 空串统一收敛为null避免脏数据compactDateToIso与compactTimeToClock分别把 8 位日期串、4 位时间串转为YYYY-MM-DD与HH:MM。最终比赛数组还会按日期 开赛时间 场次号排序compareMatches保证输出顺序稳定。八、测试与验证方式仓库内置基于node:test的测试套件test/index.test.js覆盖四类场景日期解析接受YYYY-MM-DD与Date输入、拒绝不可能日期赛程过滤验证按日期 球队别名过滤后부산 KCC编码 60与서울 SK编码 55的比赛字段、比分、胜者、场馆、转播频道全部正确排名归一化验证 10 行排名、서울 SK第 4 位及各统计字段组合调用与副作用通过 mockglobal.fetch断言fromDate20260401参数被正确拼入 URL、请求头携带ko-KR、以及includeStandings: false时排名端点不被调用。本地复现验证cd packages/kbl-results npm test # 运行 node --test npm run lint # 对 src 与 test 做 node --check 语法检查九、注意事项与边界数据实时性getStandings()返回的是官方接口的当前排名快照适合赛事进行期间轮询状态字段语义status.finished由isEnded决定平局时winner为null1 军默认值seasonGrade默认1且归一化时还会按seasonGrade对返回行做二次过滤确保只输出 1 军比赛运行环境包要求 Node.js 18使用全局fetch在更早版本中需自行注入fetchImpl官方端点约定match/list使用YYYYMMDD格式的fromDate/toDate这是官方接口硬性约定客户端已在内部透明处理。十、小结kbl-results以包装官方 JSON 端点 客户端归一化的轻量设计屏蔽了 KBL 原始响应中韩文缩写、紧凑日期、零值缺失等细节对外暴露getMatchResults、getStandings、getKBLSummary三个简洁函数。无论你是想快速做一个 KBL 赛程小工具还是让 Agent 在对话中即时回答今天有哪些比赛、谁排名第一都可以直接复用该包而源码中日期校验、别名解析、状态机映射等实现也为自行对接同类体育数据接口提供了可参考的工程范式。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考