Homebrew 外部命令（External Commands）开发与分发指南：AbstractCommand、tap 分发与 Tap Trust 信任机制

Homebrew 允许开发者用可执行脚本或 Ruby 类扩展出 brew <command> 形式的自定义命令，而无需改动 Homebrew/brew 本体。本指南以 docs/External-Commands.md 为核心，系统讲解外部命令的三种形态、通过 tap 分发与信任授权的完整流程，并深入 AbstractCommand 与 CLI::Parser 的实现细节。读完你不仅能写出带参数解析、自动帮助和类型标注的现代 Ruby 外部命令，还能理解 Homebrew 如何查找、执行并信任这些扩展。

一、什么是 Homebrew 外部命令

Homebrew 本身是一个 Git 仓库（本仓库即其主源码），内置命令按生命周期迭代较快。为了在不修改 Homebrew/brew 的前提下扩展其能力，Homebrew 支持"外部命令（External Commands）"机制：任何命名符合约定的可执行文件或 Ruby 类，都可以被直接以 brew <command> 的方式调用。

外部命令有两种分发途径，两种途径可并存：

• 放在 PATH 中：像普通命令一样安装到可执行路径下，任何 Homebrew 安装都能发现它；
• 随 tap 分发：放进某个 tap 仓库的 cmd/ 目录，用户 brew tap 之后即可使用。

无论哪种途径，有一点必须始终牢记：外部命令以当前用户的权限运行。它本质上是用户授权执行的一段程序，因此官方文档建议在使用前审查其源码，并通过 tap trust 机制只信任确实需要的那个命令或 tap——不要盲目信任一个完整 tap 中的所有内容。

二、三种命令形态与命名规则

外部命令名为 example 时，可选用以下三种可执行文件形态之一：

形态	文件命名	运行时行为
Shell 脚本或任意可直接执行程序	brew-example	Homebrew 直接以子进程方式执行，命令行剩余参数原样传递
现代 Ruby 命令	example.rb（放在 tap 的 cmd/ 目录）	Homebrew 解析定义在其中的 AbstractCommand 子类并调用其 run 方法
旧式 Ruby 命令	brew-example.rb	Homebrew 通过 require 加载整个文件来"运行"它，不实例化任何类

2.1 直接可执行命令 brew-example

这类命令可选用任意合适的 shebang（如 #!/usr/bin/env bash、#!/bin/sh），Homebrew 不会解析其内容，只会原样执行，并把 brew example 之后的命令行参数不加改动地传给程序。

两条关键约束：

• 文件名必须严格是 brew-example，绝不能带有 .sh 之类的语言扩展名。命名带扩展名会导致查找逻辑无法匹配（详见第七节的查找路径源码）。
• 由 brew 分发的可执行命令会继承一套 Homebrew 预设的环境变量，用于定位安装目录。官方文档列出的核心变量包括：

环境变量	含义
HOMEBREW_PREFIX	Homebrew 安装前缀
HOMEBREW_CELLAR	Cellar 目录（存放已安装软件包）
HOMEBREW_REPOSITORY	Homebrew/brew 本体仓库路径
HOMEBREW_LIBRARY_PATH	Homebrew 库路径
HOMEBREW_CACHE	下载缓存目录

这些变量由 Library/Homebrew/brew.sh 在启动时根据默认前缀与实际安装位置计算并导出，因此外部脚本可以通过它们推算 Cellar、缓存等真实路径，而不必硬编码。

2.2 Ruby 命令：运行在 Homebrew 内部

Ruby 形式的外部命令运行在 Homebrew 进程内部，能够访问 Homebrew 内部的各类对象与常量，这是其相对纯脚本最大的优势——例如直接操作 Formula、读取 tap 配置、复用 Homebrew 的依赖解析等能力。

但这也意味着它依赖 Homebrew 的内部实现。内部 API 可以随时变化且不提供兼容性保证，因此最佳实践是：

• 尽量使用公开 API（如 AbstractCommand、args）；
• 让命令在当前 Homebrew 版本上保持测试覆盖，随 brew 升级持续回归验证。

三、在 tap 中分发外部命令

在 tap 仓库中分发命令，目录约定非常明确：把命令文件放进 tap 根目录下的 cmd/ 子目录即可。文档给出的结构示例为：

homebrew-example/
└── cmd/
    ├── example.rb
    └── brew-other-example

对应关系一目了然：cmd/example.rb 是抽象命令类形态（文件名不带 brew- 前缀），cmd/brew-other-example 是直接可执行形态（文件名为 brew-other-example）。注意两者可以共存于同一个 cmd/ 目录。

操作要点：

• 提交前先为每个命令文件加上可执行位（chmod +x）。Homebrew 枚举命令时会检查可执行性，非可执行文件不会被列为可用命令（见源码 Commands.external_commands 中的 select(&:executable?)，位于 Library/Homebrew/commands.rb）。
• 仓库本身的搭建与发布流程参见 How to Create and Maintain a Tap，其中也明确提示：自定义 brew 命令通过向 tap 添加 cmd/ 子目录来提供给用户。

3.1 信任：只信任所需命令

用户在 brew tap 之后，由于 Homebrew 6.0.0 起默认要求对非官方 tap 显式信任，外部命令不会自动被加载执行。当不值得对整个 tap 赋予全量信任时，最小化授权的方式是只信任单一命令：

brew trust --command user/example/example

其中 user/example/example 是 <user>/<tap>/<command> 形式的三段式全限定名，第三个段是命令名（不含 brew- 前缀、不含 .rb 扩展名）。信任记录会写入由 Library/Homebrew/cmd/trust.rb 描述的 ${XDG_CONFIG_HOME}/homebrew/trust.json（若未设置 $XDG_CONFIG_HOME 则为 ~/.homebrew/trust.json）。

关于信任的完整语义（包括 brew trust、brew untrust、官方 tap 隐式信任、Brewfile 中的 trust 语法及两个相关环境变量），请参考 Tap Trust。

四、现代 Ruby 命令结构：AbstractCommand 子类

tap 的 cmd/ 目录中的 example.rb（无 brew- 前缀）应采用 AbstractCommand 生命周期。下面给出官方文档的完整参考实现，存为 tap 仓库中的 cmd/example.rb：

# typed: strict
# frozen_string_literal: true

module Homebrew
  module Cmd
    class Example < AbstractCommand
      cmd_args do
        description "Describe what the command does."
        switch "--force", description: "Perform the operation without prompting."
        named_args :formula, min: 1
      end

      sig { override.void }
      def run
        args.named.to_formulae.each do |formula|
          puts formula.full_name
        end
      end
    end
  end
end

4.1 逐段拆解

• # typed: strict / # frozen_string_literal: true：分别启用 Sorbet 严格类型检查与字符串字面量冻结，符合 Homebrew 自身的源码规范。
• module Homebrew; module Cmd：命令类必须嵌套在 Homebrew::Cmd（对应 cmd/ 目录）命名空间下；若属于开发者命令则应放 Homebrew::DevCmd（dev-cmd/）。实现类可通过 Library/Homebrew/abstract_command.rb 的 dev_cmd? 判断自身归属，进而影响查找路径。
• class Example < AbstractCommand：类名由命令名转换而来——example 转 CamelCase 得 Example。反向映射由 AbstractCommand.command_name 完成，见 Library/Homebrew/abstract_command.rb：取类名末段后 underscore、把下划线转连字符、再去除 -cmd 后缀。这意味着 example ↔ Example 之间是精确的双向对应。
• cmd_args do ... end：声明式的参数解析区块（DSL 的宿主是 CLI::Parser，定义见 Library/Homebrew/cli/parser.rb）。AbstractCommand 会用它缓存 parser 描述块并动态生成一个 Args 子类常量（见 Library/Homebrew/abstract_command.rb）。
• def run：命令主体。AbstractCommand#initialize 已用解析后的 args 完成实例化，随后框架调用 run 执行（见 Library/Homebrew/abstract_command.rb）。run 标注为抽象方法，因此子类必须实现。

4.2 cmd_args DSL 常用指令

解析器围绕 CLI::Parser 实现，cmd_args 块内部可用的主要声明如下：

DSL 指令	用途	源码位置
description "..."	设置命令描述，出现在帮助与 man 页中	cli/parser.rb
switch "--force", description: "..."	布尔开关（无参数），帮助中显示为可选项；还支持 env: 与 depends_on: 等高级参数	cli/parser.rb
flag "--json=", description: "..."	带值选项，名称以 = 结尾表示必需参数，否则可选	cli/parser.rb
comma_array "--language", ...	接受逗号分隔列表的选项	cli/parser.rb
named_args :formula, min: 1	声明位置参数的类型与数量约束（详见下文）	cli/parser.rb
conflicts "--a", "--b"	声明互斥选项，同时传入时抛出 OptionConflictError	cli/parser.rb
usage_banner "..."	自定义 usage 横幅	cli/parser.rb
subcommand name, ... do ... end	定义带子命令的命令	cli/parser.rb
hide_from_man_page!	将该命令从生成的 man 页中隐藏	cli/parser.rb

named_args 的参数约束语义：type 可以是符号或符号数组（如 [:formula, :cask]），并用 number:/min:/max: 指定数量；type == :none 表示不接受位置参数；number 与 min/max 不可混用，解析器会显式报错。声明之后，parse（见 cli/parser.rb）会按约束校验参数个数，不足或超量时抛出对应异常。

全局的 -d/--debug、-q/--quiet、-v/--verbose、-h/--help 四个选项由 Parser 初始化时自动注入，所有 Ruby 命令一律拥有，无需手工声明（见 cli/parser.rb 与 Parser.global_options）。

4.3 通过 args 访问解析结果

在 run 中，位置参数与选项统一通过 args 对象访问：

• args.named 返回位置参数集合，示例中的 args.named.to_formulae 将命名参数逐一解析为 Formula 实例（参数声明为 :formula 时才有意义），从而可读取 formula.full_name 等属性；
• 布尔开关经 set_switch 注册为带 ? 后缀的查询方法，例如声明 --force 后可写 args.force?（见 cli/parser.rb）；
• 值选项注册为同名方法，如 args.json 返回传入值。

4.4 一个真实参照：内置命令的写法

本仓库 Library/Homebrew/cmd/info.rb 是典型的 AbstractCommand 内部实现，集中展示了混合使用 switch、flag、named_args [:formula, :cask] 以及定义子命令等的实战写法；Library/Homebrew/cmd 与 Library/Homebrew/dev-cmd 两个目录中全部命令都是现成的、持续的解析器用法范例，可随时参考。

五、旧式 Ruby 命令 brew-example.rb（legacy）

在 AbstractCommand 机制成熟之前，外部 Ruby 命令的形态是 brew-example.rb。需要明确其运行语义与新版有本质区别：

• Homebrew 只是把该文件 require 进来并把文件作为整体执行（文件的顶层代码会在加载时运行）；
• Homebrew 不会去实例化任何 AbstractCommand 子类，也不会主动调用某个 run 方法；
• 帮助文本的生成规则也不同（见下节）。

因此，新开发的命令应优先采用 cmd/example.rb + AbstractCommand 的形态；brew-example.rb 仅在维护既有扩展时才有存在意义。

六、帮助输出机制

6.1 Ruby 命令：cmd_args 自动生成

凡使用 cmd_args 声明描述与选项的 Ruby 命令，都会获得一致的、由解析器生成的帮助文本。用户执行 brew example --help（或 -h）时，parse 检测到 args.help? 后调用 generate_help_text 输出并退出（见 Library/Homebrew/cli/parser.rb）。文本包含 Usage 行、描述、选项说明列表，格式由解析器统一排版，保证所有命令的 --help 观感一致。

6.2 脚本命令：#: 注释帮助

Shell 脚本或 Ruby 脚本若无法使用 cmd_args DSL，可提供以 #: 开头的注释行作为帮助源。Homebrew 内置脚本即采用此约定，例如 Library/Homebrew/help.sh：

#:  * `help`
#:
#:  Outputs the usage instructions for `brew`.

需要说明的格式规则：首行给出 brew <command> 用法摘要，随后以 #: 前缀继续写描述与 -x/--option 说明。Commands.command_options 与 Commands.command_description 在实现上会读取命令文件中匹配 ^#: 的行，跳过前两行用法摘要后，再用正则逐行提取 -/-- 开头的选项及其描述（见 Library/Homebrew/commands.rb 与 Library/Homebrew/commands.rb），供补全脚本与 brew help 使用。

6.3 其他命令的回退路径

• 非 Ruby 可执行程序：当 brew-example 既没有 cmd_args 解析器、也没有 #: 注释时，Homebrew 可能尝试以 --help 参数执行它，由程序自行输出帮助。
• 旧式 Ruby 命令（brew-example.rb）：若没有 #: 注释帮助，则回退到一段通用帮助文本。

七、Homebrew 如何发现与执行外部命令：实现剖析

外部命令之所以能无缝接入 brew，是因为命令入口在启动时统一走 Commands.path(cmd) 的查找管线。其查找顺序在 Library/Homebrew/commands.rb 中一目了然：

1. internal_cmd_path：Library/Homebrew/cmd/ 下的 .rb 或 .sh 内置命令；
2. internal_dev_cmd_path：Library/Homebrew/dev-cmd/ 下的开发者命令；
3. external_ruby_v2_cmd_path：在 tap 的 cmd/ 目录中查找 <cmd>.rb（现代 AbstractCommand 形态）；
4. external_ruby_cmd_path：在 PATH 与 tap cmd/ 目录中查找 brew-<cmd>.rb（旧式 Ruby 形态）；
5. external_cmd_path：在 PATH 与 tap cmd/ 目录中查找可执行文件 brew-<cmd>。

其中后三类就是"外部命令"。tap 命令目录的收集方式是 Pathname.glob HOMEBREW_TAP_DIRECTORY/"*/*/cmd"，即遍历所有 user/repo 形式 tap 的 cmd/ 子目录（见 Library/Homebrew/commands.rb），这也解释了一个命令名只需与 brew-example 精确匹配即可被调用，而带 .sh 扩展名的 brew-example.sh 则因查找模式是裸的 brew-#{cmd} 而无法命中。

加载来自 tap 的命令前，系统会调用 require_trusted_command!（见 Library/Homebrew/commands.rb）：若命令路径位于 tap 目录之下，则要求该 tap 已被整库信任，或该命令已被 brew trust --command 单独信任，否则直接拒绝加载。类似的信任判定在 Trust.require_trusted_command! 中完成，其内部会把文件名去掉 brew- 前缀和扩展名、拼接成 tap/command 全限定名后与 trust store 比对（见 Library/Homebrew/trust.rb）。

命令的可发现列表（供 brew commands 与补全脚本使用）同样只收录 tap cmd/ 目录下可执行且受信任的文件，见 Commands.external_commands（Library/Homebrew/commands.rb）。

八、安全与 Tap Trust：最小化信任范围

外部命令直接执行用户机器上的代码，以下实践应视为开发与使用两侧的底线：

1. 运行权限：外部命令以当前用户权限运行，因此安装/使用前应审查源码与分发来源。
2. 按需信任而非整库信任：非官方 tap 自 Homebrew 6.0.0 起默认要求显式信任（参见 Tap Trust）。仅当需要安装单个命令时使用 brew trust --command user/repo/command；只有当你接受该 tap 现在与未来所有公式、cask 和命令时，才使用 brew trust user/repo 整库信任。
3. 信任存储的防护：信任数据写入 trust.json，Homebrew 对存储目录与文件有严格的属主与权限校验（拒绝写入非本人所有或 group/world 可写的路径），写入采用加锁与原子写，避免并行进程丢失条目（见 Library/Homebrew/trust.rb）。
4. 信任开关：默认强制要求信任，HOMEBREW_REQUIRE_TAP_TRUST=1 显式保持该行为；HOMEBREW_NO_REQUIRE_TAP_TRUST=1 是临时的全局豁免开关（不推荐在生产使用，官方会在后续版本移除）。

对外部命令的信任只是 Homebrew 整体供应链安全策略的一部分，更完整的论述见 Homebrew-Security-and-Supply-Chain。

九、测试与类型检查建议

Homebrew 官方建议对扩展命令保持测试，以对抗内部 API 漂移：

• 参数解析冒烟测试：仓库内所有命令都复用了 it_behaves_like "parseable arguments" 共享示例，并配以 integration_test 标签调用真实 brew 二进制断言输出，例如 Library/Homebrew/test/cmd/commands_spec.rb。外部命令可以照搬这套模式。
• Sorbet 签名生成：为 AbstractCommand 子类生成 args 的方法签名可运行 brew typecheck --update（AbstractCommand 文档注释中明确推荐，见 Library/Homebrew/abstract_command.rb）。AbstractCommand 相关的单元测试可参考 Library/Homebrew/test/abstract_command_spec.rb。

十、小结

Homebrew 外部命令是官方设计的一等扩展机制：纯脚本用 brew-example 快速接入并继承预设环境变量；需要强类型、参数解析、自动帮助与内部 API 时，用 AbstractCommand 子类（cmd/example.rb）分发到 tap；旧式 brew-example.rb 则仅作兼容保留。查找管线（Commands.path）、帮助回退规则与 Tap Trust 信任校验共同构成完整的执行链路，开发者可顺着本文引用的源码路径逐一深入验证。更进一步，可阅读 How to Create and Maintain a Tap 了解 tap 仓库搭建，以及 Tap Trust 掌握信任模型的全部命令与语义。