OpenCLI hltv 适配器实战:用浏览器桥接把 CS2 战绩、地图数据与选手对决变成可查询的 CLI
OpenCLI hltv 适配器实战:用浏览器桥接把 CS2 战绩、地图数据与选手对决变成可查询的 CLI
本文基于 OpenCLI 仓库中的 HLTV 适配器文档 与其对应源码 clis/hltv/ 编写,完整讲解这组 13 个 opencli hltv 命令的用法、实体引用格式、过滤参数与错误行为,并结合 utils.js 的实现说明 DOM 解析、超时与错误分类的底层机制。读完本文,你可以直接在 Chrome 登录会话中查询 HLTV 的选手战绩、地图池、系列赛详情,并用源码级知识定位命令失败原因。
为什么 HLTV 需要 Browser 模式适配器
HLTV 是 CS2/CS:GO 电竞赛事数据的主要站点,但它的这些统计视图(选手 stats、mapstats、系列赛页面)没有稳定的公开 JSON API。OpenCLI 的 HLTV 适配器因此采用 Browser 模式(文档中 Mode 标记为 🌐 Browser,域名为 hltv.org):命令通过 Browser Bridge 扩展驱动你正在使用的 Chrome 会话,等待页面渲染完成后解析可见 DOM,把搜索结果、选手统计、比赛地图数据、队伍战绩和系列赛页面统一转换为结构化的表格行输出。
从源码看,所有命令都注册为 strategy: Strategy.UI、browser: true、domain: 'www.hltv.org'(见 clis/hltv/search.js、clis/hltv/player-duel.js),并复用 clis/hltv/utils.js 中统一的导航、解析与断言工具。
完整命令清单
文档定义的 13 个命令如下,全部为只读操作:
| 命令 | 说明 |
|---|---|
opencli hltv search <query> |
搜索选手、队伍、赛事与文章 |
opencli hltv player-summary |
读取选手概览页与完整 stats 链接 |
opencli hltv player-matches |
读取选手 stats 的 Matches 标签页 |
opencli hltv player-form |
按汇总、地图、对手聚合选手近期地图表现 |
opencli hltv player-map-pool |
将选手近期地图聚合为地图池分桶 |
opencli hltv player-vs-team <team> |
过滤选手对阵某一队伍的所有地图 |
opencli hltv player-teammate-impact <playerA> <playerB> |
对比两名队友“共同出现”与“未共同出现”的地图样本 |
opencli hltv player-duel <playerA> <playerB> |
在共同地图上对比两名选手,含可得时的直接击杀数据 |
opencli hltv match-map <match> |
读取单个 mapstats 页面的全部选手行 |
opencli hltv match-series <match> |
将 BO1/BO3/BO5 展开为 summary、map、player 三类行 |
opencli hltv team-matches <team> |
读取队伍近期地图战绩 |
opencli hltv team-map-pool <team> |
读取队伍可见的地图池统计 |
opencli hltv event-matches <event> |
读取单个赛事的 stats 比赛行 |
用法示例(可直接复制运行)
# 搜索并发现 HLTV 实体链接
opencli hltv search niko --limit 5
# 读取选手页面与近期状态
opencli hltv player-summary --player 3741/niko
opencli hltv player-matches --player 3741/niko --limit 10 -f json
opencli hltv player-form --player 19230/m0nesy --limit 30
# 对比两名选手
opencli hltv player-duel 3741/niko 21167/donk
opencli hltv player-duel 19230/m0nesy 3741/niko --mode history --limit 10
# 展开一个系列赛或检查单个 mapstats URL
opencli hltv match-series https://www.hltv.org/stats/matches/126993/spirit-vs-falcons
opencli hltv match-map "https://www.hltv.org/stats/matches/mapstatsid/231594/falcons-vs-natus-vincere" -f json
# 队伍与赛事视图
opencli hltv team-matches 6667/falcons --limit 10
opencli hltv team-map-pool 11283/falcons
opencli hltv event-matches 8301 --limit 10
推荐工作流:先用 search 拿到目标实体的 id/slug 与 URL,再用具体的 player-* / match-* / team-* 命令深入;输出加 -f json 便于脚本处理。
实体引用格式(Common Subjects)
四类命令主体都接受多种等价写法,这是文档与源码(utils.js 中的 parsePlayerRef / parseTeamRef / parseEventRef / normalizeMatchUrl)共同定义的契约:
- 选手引用:接受
id/slug(如3741/niko)、选手 URL(/player/:id/:slug)、以及 stats 选手 URL(/stats/players/:id/:slug)。parsePlayerRef按顺序用三种正则依次匹配,slug 会被统一转小写;player参数的默认值是3741/niko。 - 队伍引用:接受
id/slug、队伍 URL(/team/:id/:slug)、stats 队伍 URL(/stats/teams/:id/:slug及/stats/teams/matches/:id/:slug)。 - 比赛引用:接受常规比赛 URL(
/matches/:id/)、stats 系列赛 URL(/stats/matches/:id/)、mapstats URL(/stats/matches/mapstatsid/:id/)。 - 赛事引用:接受纯数字赛事 ID、
/events/:id/:slugURL、带event=<数字ID>查询参数的 stats URL;特殊值all表示不限赛事。
单测 clis/hltv/hltv.test.js 固化了这些行为,例如 parsePlayerRef('https://www.hltv.org/player/3741/niko') 应得到 { playerId: '3741', slug: 'niko' },而 parseEventRef 遇到 event=not-an-id 这类非数字查询参数必须抛 ArgumentError。
过滤参数全解:period、eventType、ranking、map、version
player-matches、player-form、player-map-pool、player-vs-team、team-matches 等命令共用一套命名过滤选项。buildPlayerMatchesUrl / buildTeamMatchesUrl 会把它们翻译成 HLTV 页面的查询参数:
| 选项 | 取值 | 映射到的 URL 参数 |
|---|---|---|
--period |
all / lastMonth / last3Months / last6Months / last12Months / YYYY / YYYY-MM-DD:YYYY-MM-DD |
startDate + endDate(all 时置 startDate=all) |
--event-type |
all / majors / bigEvents / mvpEvents / lan / online |
matchType(如 Majors、BigEvents) |
--ranking |
all / top5 / top10 / top20 / top30 / top50 |
rankingFilter |
--map |
all 或 13 张地图:ancient / anubis / dust2 / inferno / mirage / nuke / overpass / cache / cobblestone / season / train / tuscan / vertigo |
maps(映射为 de_* 内部名) |
--version |
both / cs2 / csgo |
csVersion |
--event |
all / 赛事 ID / events URL / 带 event= 的 stats URL |
event |
--offset |
非负整数,必须是 100 的倍数 | offset |
几个实现细节值得注意(均来自 utils.js):
normalizeLimit要求 limit 为正整数且不超上限(search上限 50,多数 stats 命令 100);normalizeOffset强制 offset 为 100 的倍数,这是因为 HLTV 选手/队伍比赛页本身就是每页 100 行的分页;resolvePeriod把lastMonth这类相对周期换算为startDate/endDate日期对,YYYY会展开为整个自然年;- 非法取值一律抛
ArgumentError,错误信息会列出全部合法取值,便于直接修正。
源码视角:一次命令的完整调用链
以 player-matches 为例,核心流程可以归纳为四步:
- 构建 URL:
buildPlayerMatchesUrl解析选手引用、归一化全部过滤参数,拼出/stats/players/matches/:id/:slug?...的完整地址(utils.js)。 - 导航并等待:
gotoAndWait执行page.goto(url, { waitUntil: 'domcontentloaded', settleMs: 1000, timeout: 20000 }),再page.wait({ selector, timeout: 15000 })等待关键选择器(如.stats-matches-table)出现。超时统一转成TimeoutError,其余导航异常转成CommandExecutionError。 - 页面内解析:通过
page.evaluate注入脚本读取表格行,从tr.group-1 / tr.group-2单元格中提取日期、对阵双方比分((score)后缀)、K/D、±、Rating,并保留每行对应的matchStatsUrl与matchStatsId(utils.js)。 - 行契约断言:
assertRequiredFields校验每行必须含rank、date、playerTeam、opponent、map、playerId、matchStatsId等字段——任一字段为空即抛CommandExecutionError,整页无行则抛EmptyResultError。这套“必填字段契约”保证下游(Agent 或脚本)拿到的 JSON 结构稳定。
match-map 更进一步:从 .match-info-box 解析赛事、日期时间、地图、双方比分,再遍历 .stats-table.totalstats 的选手行,提取 Kills/Deaths(括号内分别为爆头数、闪爆助攻)、ADR、KAST%、Rating、OP/KD、多杀、残局等字段(utils.js)。
重点命令解析
player-duel:三种对比模式与直接击杀矩阵
player-duel.js 是功能最重的命令,核心参数:
--mode:lastEncounter(默认,找两人最近一次同场系列赛)/intersection(按过滤条件取两人比赛记录的交集)/history(把交集地图进一步展开为各自完整系列赛的所有地图);--match:直接指定一个比赛/系列赛/mapstats URL,此时忽略--mode;--recent-maps:lastEncounter模式下从 playerA 最近多少张地图中扫描(默认 100,上限 500);--scan-pages:广义模式扫描的分页数,每页 100 行,上限 5;--limit:最多对比多少张共同地图,上限 100。
实现上有两个巧妙之处:
- 交集定位:
collectCommonMapUrls分别拉取两人的player-matches行,用matchStatsId作为主键求交集,只保留两人同场的 mapstats URL; - 直接击杀矩阵:当两名选手分属不同队伍时,
readPerformanceKillMatrix会把 mapstats URL 改写成/stats/matches/performance/mapstatsid/:id/的 performance 页,解析“谁击杀谁”的交叉矩阵,从而得到directKillDiff——同一张地图上 A 击杀 B 与 B 击杀 A 的差值(utils.js、player-duel.js)。
输出行分 summary / map 两类:summary 行给出两人 rating 差、总击杀差、直接击杀差与样本区间;map 行给出每场比赛的 ratingDiff、killDiff、directKillDiff 及双方完整数据。
player-form 与 player-map-pool:聚合分桶
player-form.js 拉取 --limit 张近期地图后,构建三层分桶:summary(总体)、按地图(key 为地图名)、按对手(key 为对手队名),每桶统计 maps、avgRating、kdRatio、killsPerMap、plusMinusTotal、winMaps/lossMaps 以及 best/worst rating 区间。player-map-pool.js 类似,但额外输出 winRatePct(胜率百分比),更适合回答“这名选手在 Mirage 上胜率如何”这类问题。
match-series:把一个系列赛展开成三类行
readMatchSeries(utils.js)先通过 resolveMatchMapUrls 在系列赛页抓取全部 mapstats 链接,逐图调用 readMatchMap,然后输出三种 rowType:
summary行:每队一图一行,含maps、mapWins、总 K/D、平均 rating 与mapScores(每张图比分的拼接串);map行:每队每图一行,含该图比分与队伍级 K/D;player行:每个选手每图一行,含 ADR、KAST、爆头、闪爆助攻、traded deaths 等完整明细。
这让一条命令就能同时回答“系列赛结果如何”“哪张图翻盘”“谁carry”三层问题。
search:四类结果的统一发现入口
search.js 请求 /search?query=...,遍历页面所有 <table>,按首行表头(Player / Team / Event / Article)识别结果类型,每类最多 --limit 行(默认 10,上限 50)。每行输出 rank、type、id、name/title、date、author、url,且 id 缺失时会用 extractIdFromUrl 从 URL 路径兜底提取——这条兜底逻辑同样受“行契约”保护:id 与 url 为必填字段(见 hltv.test.js 中 assertRequiredFields 的正反用例)。
前置条件与运行环境
- Chrome 已安装并启用 Browser Bridge 扩展(OpenCLI 的浏览器命令通过“扩展 + 微型 daemon”复用你已登录的 Chrome 会话,零配置自动启动;可用
opencli doctor检查扩展与 daemon 连通性); - 活动浏览器会话中可以访问 HLTV;
- 若 HLTV 弹出 Cloudflare 或人机验证页,先在 Chrome 中手动完成验证,再重试命令。
- 适配器为只读,不需要 HLTV 登录。
排障与调优
- 重型命令(
player-duel、match-series等)会串行加载多个 HLTV 页面,耗时明显长于search/player-summary; - 调试 HLTV 页面结构变化或 Cloudflare 拦截时,加
--window foreground --keep-tab true,让浏览器窗口前置并保留标签页,方便人工观察 DOM; - 设计约定:主体实体用位置参数(如
player-duel的两个选手、team-matches的队伍),--limit、--period、--ranking、--map、--version等过滤条件保持为命名选项。
错误行为对照表
文档与源码共同定义了四种典型失败模式(对应 utils.js 的断言与超时逻辑):
| 触发条件 | 错误类型 |
|---|---|
| 玩家、队伍、赛事、比赛、limit、offset 或过滤参数非法 | ArgumentError |
| 可见 HLTV 页面中没有请求主体/过滤条件下的任何行 | EmptyResultError |
| HLTV 页面结构变化,或解析器返回了意外形状(含必填字段缺失) | CommandExecutionError |
| 浏览器导航或选择器等待超过命令超时 | TimeoutError |
实际排障时可以按此表反推原因:参数报错先看错误信息里列出的合法取值;EmptyResultError 通常是过滤条件过严或页面未加载完;CommandExecutionError 大概率意味着 HLTV 改版了页面结构;TimeoutError 则优先用 --window foreground 观察是否卡在 Cloudflare 验证页。
相关仓库路径索引
- 适配器文档:docs/adapters/browser/hltv.md,全部命令一览见 docs/adapters/index.md
- 命令实现目录:clis/hltv/(
search.js、player-summary.js、player-matches.js、player-form.js、player-map-pool.js、player-vs-team.js、player-teammate-impact.js、player-duel.js、match-map.js、match-series.js、team-matches.js、team-map-pool.js、event-matches.js) - 共享工具与断言:clis/hltv/utils.js
- 契约测试:clis/hltv/hltv.test.js
- 浏览器桥接说明:docs/guide/browser-bridge.md