macos-brew

用途

此技能可自动执行 macOS 上的 Homebrew 操作，高效管理软件包，包括 formula、cask、服务、tap 和版本锁定。它专注于 Homebrew 的核心功能，通过 /opt/homebrew PATH 处理软件包安装、更新和系统集成。

适用场景

在执行 macOS 软件包管理任务时使用此技能，例如在脚本中安装依赖项、在 CI/CD 流水线中更新工具，或配置开发环境。处理 Homebrew 专属功能（如用于 GUI 应用的 cask，或用于自定义仓库的 tap）时，尤其是在自动化工作流中或需要确保环境可复现时，均可使用此技能。

主要功能

• Formula 管理：安装、升级或移除命令行工具（例如通过 brew install wget），包括依赖项解析和使用 brew pin <formula> 锁定版本。
• Cask 管理：管理 GUI 应用（例如 brew install --cask google-chrome），并可选择忽略依赖项或强制重新安装。
• 服务控制：启动、停止或重启后台服务（例如 brew services start postgresql），并与 macOS launchd 集成。
• Tap 集成：添加外部仓库（例如 brew tap homebrew/cask），以便访问非核心软件包。
• PATH 和 Bundle 管理：在脚本的 PATH 中配置 /opt/homebrew，并使用 brew bundle 从 Brewfile 管理软件包列表，以创建可复现的环境。
• 版本锁定：锁定软件包版本以阻止更新（例如 brew pin node@14），确保生产环境的稳定性。

使用模式

在 Shell 脚本或自动化工具中直接调用 brew 命令来使用此技能。务必先使用 which brew 或 command -v brew 检查是否已安装 Homebrew。对于脚本化安装，请使用 Brewfile：创建一个文件，其中包含 brew 'git' 和 cask 'docker' 这样的行，然后运行 brew bundle --file Brewfile。在 AI Agent 中，使用 try-catch 块封装命令以处理错误，并将 /opt/homebrew/bin 添加到 PATH 开头。例如，在 bash 脚本中，可以这样安装并锁定软件包：

brew install node@14
brew pin node@14

另一种模式：对于服务，可结合条件检查，例如，仅在服务未运行时启动：brew services list | grep -q postgresql || brew services start postgresql。

常用命令/API

Homebrew 基于 CLI，因此请在脚本中直接使用这些命令。所有命令的运行格式均为 brew <subcommand> [flags] [args]。

• 安装 Formula：使用 brew install <formula> --force 覆盖现有版本；例如 brew install git --force。
• 安装 Cask：使用 brew install --cask <cask> --no-quarantine 跳过 macOS 安全提示；例如 brew install --cask visual-studio-code --no-quarantine。
• 更新软件包：运行 brew update && brew upgrade <formula>；添加 --ignore-pinned 可升级已锁定的版本。
• 管理 Tap：使用 brew tap <user/repo> 添加 tap；例如 brew tap homebrew/cask-fonts。
• 管理服务：运行 brew services start <service> 或 brew services restart <service> --all；例如 brew services stop redis。
• Bundle 操作：运行 brew bundle --file Brewfile 从文件安装；Brewfile 格式为 brew 'package' 或 cask 'app'。
• 锁定版本：使用 brew pin <formula> 锁定版本；使用 brew unpin <formula> 解除锁定；例如 brew pin [email protected]。
• 清理：运行 brew cleanup -s 移除旧版本；升级后务必运行。

若要以类似 API 的方式使用，可将输出通过管道传给脚本，例如使用 brew list --versions | grep node 查询已安装的版本。

集成说明

在脚本中集成 Homebrew 时，请确保 /opt/homebrew/bin 位于 PATH 中；将 export PATH="/opt/homebrew/bin:$PATH" 添加到 .zshrc 或脚本中。在 CI/CD（例如 GitHub Actions）中，先使用 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 安装 Homebrew。无需身份验证，但如果要扩展到私有 tap，请使用环境变量中的 Git 凭据，例如 export HOMEBREW_GIT_EMAIL="[email protected]"。要与其他工具集成，可结合使用 macOS 工具：例如，执行 brew install ffmpeg 后，在 Python 脚本中通过 subprocess 使用它。Brewfile 的配置格式为纯文本，每行类似于 brew 'jq' # JSON processor。执行复杂操作前，务必使用 brew --version 检查 Homebrew 版本。

错误处理

通过检查退出代码处理常见错误；brew 命令失败时会返回非零值。如果出现“找不到 formula”，请先使用 brew search <formula>，或通过 brew install <formula> 2>/dev/null || echo "Error: Formula missing" 安装。如果出现“权限被拒绝”，请使用 sudo 运行，或修复 /opt/homebrew 的所有权（例如，sudo chown -R $(whoami) /opt/homebrew）。如果 brew update 期间出现网络问题，请使用 brew update --verbose 重试并检查连接情况。在脚本中，可按如下方式封装命令：

if ! brew install git; then
  echo "Installation failed; check logs" >&2
  exit 1
fi

使用 brew install <formula> >> install.log 2>&1 记录输出。对于版本冲突，可使用 brew doctor 进行诊断和解决。

具体用法示例

1. 安装并固定开发工具：要使用特定版本的 Node.js 设置项目，请运行：brew install node@14，然后运行 brew pin node@14。这样可以确保版本不会自动更新，从而保持一致性。

2. 为 Web 应用管理服务：对于由 Redis 提供支持的应用，请使用 brew services start redis 启动服务，并通过 brew services list | grep redis 验证。如果失败，请使用 brew doctor 检查并重启。

图关系

• 与“macos”集群相连，以涵盖更广泛的 macOS 工具。
• 与“packages”标签相关联，链接到 apt 或 yum 等通用包管理器技能。
• 与“homebrew”标签相关联，可能链接到生态系统中的高级脚本或 CI 工具。