OpenCLI hltv 适配器实战:用浏览器桥接把 CS2 战绩、地图数据与选手对决变成可查询的 CLI

原创2026-09-18 09:13:001,945 阅读
文章标签:CLI浏览器控制GUI 自动化开发工具AI 技能网页爬虫

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/:slug URL、带 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 为例,核心流程可以归纳为四步:

  1. 构建 URL:buildPlayerMatchesUrl 解析选手引用、归一化全部过滤参数,拼出 /stats/players/matches/:id/:slug?... 的完整地址(utils.js)。
  2. 导航并等待:gotoAndWait 执行 page.goto(url, { waitUntil: 'domcontentloaded', settleMs: 1000, timeout: 20000 }),再 page.wait({ selector, timeout: 15000 }) 等待关键选择器(如 .stats-matches-table)出现。超时统一转成 TimeoutError,其余导航异常转成 CommandExecutionError。
  3. 页面内解析:通过 page.evaluate 注入脚本读取表格行,从 tr.group-1 / tr.group-2 单元格中提取日期、对阵双方比分((score) 后缀)、K/D、±、Rating,并保留每行对应的 matchStatsUrl 与 matchStatsId(utils.js)。
  4. 行契约断言: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。

实现上有两个巧妙之处:

  1. 交集定位:collectCommonMapUrls 分别拉取两人的 player-matches 行,用 matchStatsId 作为主键求交集,只保留两人同场的 mapstats URL;
  2. 直接击杀矩阵:当两名选手分属不同队伍时,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 验证页。

相关仓库路径索引

登录后查看全文
OpenCLI