OpenCLI Homebrew 适配器实战：不登录、不打开浏览器，用三个命令查 Formula、Cask 与官方安装量排行-开发者社区

OpenCLI Homebrew 适配器实战：不登录、不打开浏览器，用三个命令查 Formula、Cask 与官方安装量排行

【免费下载链接】OpenCLIMake Any Website into CLI & Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI

本文讲解 OpenCLI 仓库中 Homebrew 适配器（docs/adapters/browser/homebrew.md）的完整用法与实现原理：通过homebrew formula、homebrew cask、homebrew popular三个只读命令，直接调用formulae.brew.sh/api的公开 JSON 端点，无需认证、无需浏览器即可获取 Formula/Cask 的元数据以及 Homebrew 官方统计的安装量排行。读完本文，你既能复制即用的命令示例与输出字段说明，也能从源码层面理解 token 校验、HTTP 错误处理与安装量数值强制转换等细节。

适配器定位：为什么 Homebrew 可以不需要浏览器

OpenCLI 的绝大多数适配器围绕"复用已登录浏览器"设计，但 Homebrew 属于例外：它在命令注册时声明browser: false、strategy: Strategy.PUBLIC、access: 'read'（见 formula.js、cask.js、popular.js 中各自的cli({...})声明），即这是一个纯公开 API 的只读适配器。

从源码注释可以看出设计取舍（utils.js）：

端点为formulae.brew.sh/api下的公开、免认证 JSON 接口，以静态文件形式从 GitHub Pages 分发、每日重新生成；
Formula/Cask 的 token 遵循 Homebrew 自身的命名规则：小写 ASCII 加-_.+@（如gcc@13、imagemagick@6、c++、0-ad、php-cs-fixer）；
所有请求都不携带登录态，适配器只是给这些静态 JSON 加一层参数校验、字段规整和表格化输出。

命令在仓库中的登记信息（站点homebrew、各命令的 args 与 columns）可以在 cli-manifest.json 中检索到homebrew站点条目，适配器总览见 docs/adapters/index.md。

三个命令速览

文档将三个命令概括为"Inspect Homebrew formulae and casks, plus the official install-rank analytics, without auth or browser. Three commands."：

命令	说明
`opencli homebrew formula <name>`	查询单个 Homebrew core formula 的元数据
`opencli homebrew cask <token>`	查询单个 Homebrew cask（macOS 应用包）的元数据
`opencli homebrew popular`	查询安装量最高的 formula 或 cask（Homebrew 官方 analytics 排行）

对应的实现文件与注册信息一一对应：clis/homebrew/formula.js、clis/homebrew/cask.js、clis/homebrew/popular.js，共享逻辑集中在 utils.js。

命令用法与示例

查询 Formula 与 Cask 元数据

# Inspect a formula opencli homebrew formula wget opencli homebrew formula gcc@13 opencli homebrew formula imagemagick # Inspect a cask (macOS package) opencli homebrew cask firefox opencli homebrew cask visual-studio-code

formula命令的 positional 参数为name（formula 名称），cask命令的 positional 参数为token（cask token），二者在 cli-manifest.json 中均标记为required: true、positional: true。

查询官方安装量排行

# 默认：formula / 30d / top 30 opencli homebrew popular # 切换类型与时间窗口 opencli homebrew popular --type cask --window 90d --limit 50 opencli homebrew popular --type formula --window 365d --limit 100 # JSON 输出 opencli homebrew popular -f json

popular命令的三个选项（默认值与来源均可在 popular.js 的args声明中确认）：

选项	说明
`--type`	`formula`（默认）或`cask`
`--window`	`30d`（默认）/`90d`/`365d`
`--limit`	最大行数（1-500，默认 30）

注意--window只有三个合法取值：源码中WINDOWS = ['30d', '90d', '365d']是一个硬编码的白名单（popular.js），因为 Homebrew analytics 端点只发布这三种窗口，传其他值会先被本地requireOneOf拦下并报ArgumentError，不会浪费一次 404 请求。

输出字段（Columns）逐列说明

命令	输出列
`formula`	`formula, tap, version, license, description, homepage, dependencies, deprecated, disabled, source, url`
`cask`	`cask, tap, name, version, description, homepage, deprecated, disabled, download, url`
`popular`	`rank, token, type, installs, percent, window, url`

各列的取值来源可以从源码直接核对：

formula（formula.js）：formula取 API 的name字段；version取versions.stable；dependencies是依赖数组join(', ')后的逗号串；source取urls.stable.url（源码 tarball 地址）；url是拼接出的https://formulae.brew.sh/formula/<name>详情页；deprecated/disabled为布尔值。
cask（cask.js）：与 formula 类似，但name可能是数组（cask 的友好名列表），源码会filter(Boolean).join(', ')拼成可读串；download取 API 的url字段，即实际的 .dmg/.pkg 下载地址。
popular（popular.js）：rank优先取 API 的row.number，缺失时回退为i + 1；token根据type分别取row.formula或row.cask；installs经过强制数值转换（见下节）；url指向https://formulae.brew.sh/{cask|formula}/<token>。

一个关键用法：popular输出的token列可以直接回灌到formula/cask命令——type=formula时喂给homebrew formula <token>，type=cask时喂给homebrew cask <token>。这让"先排行、后详情"的两段式查询可以完全脚本化，例如opencli homebrew popular -f json解析出 token 后逐条查元数据。

实现细节：token 校验、HTTP 处理与数值规整

Homebrew 适配器最值得参考的是它对"公共静态 API"这一前提的防御式处理，全部集中在 utils.js。

token 正则与长度上限

requireToken使用正则/^[A-Za-z0-9][A-Za-z0-9._+@-]*$/校验 token（utils.js），且长度上限 100 字符。这与文档 Caveats 一节的描述一致：不合法输入会抛出ArgumentError，错误提示还附带示例（e.g. "wget", "gcc@13", "firefox"）和允许的字符集说明。校验在本地完成，意味着非法输入不会发起任何网络请求。

统一的 fetch 封装与错误语义

brewFetch（utils.js）对三个命令共用，行为包括：

固定User-Agent为opencli-homebrew-adapter (+https://github.com/jackwener/opencli)，并声明accept: application/json；
网络异常（DNS、超时等）包装为CommandExecutionError，并提示"检查 formulae.brew.sh 是否可达"；
HTTP 404 抛EmptyResultError（资源不存在）；HTTP 429 抛带"等待几秒后重试"建议的CommandExecutionError（Homebrew 会对突发流量限流）；
其余非 2xx 状态码以及 JSON 解析失败都归为CommandExecutionError，避免把上游的畸形响应静默吞掉。

安装量的字符串数字强转

Homebrew analytics 把安装量发布为带千分位逗号的字符串（如"139,972"）。parseInstallCount（utils.js）先replace(/,/g, '')去掉逗号再转数字，非有限值返回null。这就是文档 Caveats 中"we coerce them to plain numbers"的落地实现——不经过这一步，installs列会输出带引号语义的字符串，无法排序或做数值比较。

行数截断与空结果

popular先取body.items全量数组，再slice(0, limit)截取前 N 行（popular.js）；若items为空则抛EmptyResultError并说明type/window组合，而不是输出空表格。limit由requireBoundedInt保证为正整数且不超过 500。

已知限制（Caveats）

文档明确列出四条限制，结合源码可以确认其成因：

token 校验规则[A-Za-z0-9][A-Za-z0-9._+@-]*、最长 100 字符，非法输入报ArgumentError；
--type与--window只接受 Homebrew analytics 实际发布的值（formula/cask；30d/90d/365d），其余取值报ArgumentError；
analytics 的安装量是逗号格式字符串，适配器已强制转换为普通数字；
端点是每日重新生成的静态 GitHub Pages JSON，数据最多滞后约 24 小时——用popular做决策时应记住这一点，它反映的是"截至上一次每日构建"的匿名聚合安装统计，不是实时计数。

前置条件与适用前提

无浏览器依赖、无认证依赖：仅使用三个公开端点：
- https://formulae.brew.sh/api/formula/<name>.json
- https://formulae.brew.sh/api/cask/<token>.json
- https://formulae.brew.sh/api/analytics/(install|cask-install)/<window>.json
基础 URL 常量BREW_BASE = 'https://formulae.brew.sh/api'定义在 utils.js。
网络需能访问formulae.brew.sh；受网络限制时命令会给出明确的可达性提示，被限流时提示等待重试。
命令声明为access: 'read'，纯查询、无副作用，适合放进 Agent 工具链或 CI 脚本中做软件包元数据查询。

小结

Homebrew 适配器是 OpenCLI 中典型的"公开 API 型"命令组：不依赖已登录浏览器，靠严格的本地参数校验（token 正则、枚举白名单、有界整数）、统一的 HTTP 错误映射（404/429/5xx）和数值规整（千分位安装量转数字），把三个静态 JSON 端点包装成可直接表格化、可 JSON 化、可被popular → formula/casktoken 回灌串联使用的命令行工具。源码集中在 clis/homebrew/ 四个文件（formula.js、cask.js、popular.js、utils.js），若要编写类似的公共数据源适配器，这是一个紧凑且完整的参考实现。

【免费下载链接】OpenCLIMake Any Website into CLI & Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考