# brewbar —— 使用手册

[English](USAGE.md) · [中文](USAGE.zh.md)

本手册逐一讲解 brewbar 界面的每个部分。安装方式见 [README](../README.zh.md)。

## 快速开始

运行 `bunx brewbar`(或全局安装后运行 `brewbar`)。brewbar 会在浏览器中打开形如 `http://127.0.0.1:4321/?token=…` 的地址。其中 `token` 用于授权本次会话,每次启动都会变化——请使用 brewbar 自动打开的标签页,或复制终端里打印的 URL。在终端按 `Ctrl-C` 可停止服务。

如果尚未安装 Homebrew,会先看到引导页;安装好 Homebrew 后重新加载即可。

## 核心概念

### 提供方(Provider)

**提供方**就是一个包管理器。Homebrew 是默认项;**提供方切换器**(在「已安装 / 更新 / 发现 / 安全」页顶部附近的药丸按钮行)可切换到任意已检测到的管理器:npm、pip、cargo、go、gem、bun、pnpm。每个提供方的"作用域"(如*全局 npm 包*)和「源」(registry)会在相关处显示。

### 命令预览

每当你触发一个操作(安装、升级、卸载、添加 tap……),都会弹出一个对话框,展示 brewbar 将要运行的**确切命令**,并标注危险/交互式标志。在你确认之前什么都不会执行——而你确认的,正是将要执行的。在底层工具支持时,你还可以选择**演练(Dry run)**。

### 「活动」坞与终端

固定在底部的那条是**活动**坞。点击展开后是一个真实终端(xterm.js)加**操作队列**。任务的输出会实时流式显示;如果命令需要你的密码(`sudo`)或 `[Y/n]` 确认,直接在终端里输入即可。在队列里可以取消运行中的任务、重试失败的任务。**历史**链接会打开过往操作的持久化记录。

### 命令面板

在任意位置按 `⌘K`(Cmd-K)即可打开模糊搜索的命令面板,用于快速导航和操作。

## 各页面

### 仪表盘(Dashboard)

一目了然的概览:Homebrew 的计数(formula、cask、可更新、tap)以及一张**包管理器**卡片,列出每个已检测到的管理器及其版本。右上角的快捷按钮可执行 更新 / 全部升级 / 清理。点击某个管理器可直接跳到它的包列表。

### 已安装(Installed)

当前所选提供方的已安装包列表。可搜索,并(对 Homebrew)按 formula / cask / 可更新 / 依赖 过滤。点击任意一行打开**详情抽屉**——简介、版本、磁盘占用、源、主页/仓库;对 Homebrew 还包括 tap、安装日期、注意事项(caveats)、依赖,以及一个依赖关系图按钮。多选若干行可作为一个排队操作一并卸载。

**扫描占用** —— 点击此按钮,带进度条地测量磁盘占用。完成后每行显示其占用、顶部显示总占用,列表可按占用大小排序(就像垃圾清理工具)。结果会被缓存,再次访问该页面不会重复扫描。

### 更新(Updates)

当前所选提供方的可更新包,显示 已安装 → 最新 版本,每行一个**升级**按钮(在支持时还有**全部升级**)。

- 对 Homebrew,更新会自动加载;**greedy** 开关会把自动更新的 cask 也纳入。
- 对其他提供方,更新是**按需**的:点击**检查更新**,带进度条地逐包查询各自的注册中心。即便是没有原生"检查更新"命令的管理器(bun、cargo、go)也能查。结果跨页面保留;无法访问的包会被明确报告,而不会被悄悄当作"已是最新"。

### 发现(Discover)

搜索软件目录并安装新包。Homebrew 和部分管理器支持完整搜索;其他(如 pip、go)则切换为**按名安装**表单,你输入确切的包名即可。

### 服务(Services)

通过 `launchd` 管理的 Homebrew 服务(数据库、守护进程)——启动、停止、重启后台服务,每个服务带一个状态圆点。

### Tap 源(Taps)

管理 Homebrew 的 **tap**——提供核心仓库之外 formula 与 cask 的第三方仓库。以 `owner/repo` 形式添加;用垃圾桶图标移除。(其他管理器没有 tap 的概念——它们从单一配置的「源」安装,可在「管理器」页和各包详情里查看。)

### 管理器(Managers)

展示每个包管理器:已安装的显示版本、作用域和配置的源;未安装的提供一个**安装**按钮(通过 Homebrew 安装)。在支持自更新时,可就地更新某个管理器。

### 维护(Maintenance)

Homebrew 日常维护:释放磁盘空间(清理 / 修剪)、移除无用依赖(autoremove)、运行诊断(`brew doctor`),以及查看占用最大的已安装包。

### 安全(Security)

通过 [OSV.dev](https://osv.dev) 进行免费 CVE 漏洞扫描。选择一个有受支持生态的提供方(npm/PyPI/crates.io/RubyGems/Go),点击扫描,查看漏洞及其严重程度、修复版本和链接。Homebrew 没有对应的 OSV 生态,此处不可扫描。

### 助手(Assistant)

可选的 AI 助手。在**设置**中配置一个提供方:选择预设(OpenAI / Anthropic / DeepSeek / 智谱 GLM / 月之暗面 Kimi / xAI Grok / Google Gemini)或自定义的 OpenAI 兼容端点,设置 base URL、模型和 API 密钥。助手可以分析磁盘占用、安全发现、更新、依赖、替代方案,或回答自由提问,并以流式输出。你的密钥仅存本地(`~/.config/brewbar/ai.json`,权限 `0600`),绝不下发到浏览器。

### Brewfile

针对 `Brewfile` 备份、恢复并**对比**你的 Homebrew 配置:看清哪些已安装但未声明(多余)、哪些已声明但未安装(缺失),然后同步。

### 设置(Settings)

语言(English / 简体中文)、主题(明 / 暗)、默认 Brewfile 路径、AI 助手配置,以及诸如"依赖检查""默认 greedy"等开关。

## 小贴士

- brewbar 绝不会执行你未确认的操作;拿不准时,看一眼命令预览对话框。
- 重操作(占用、更新、CVE)一律**按需**——不点击就不会发生任何慢操作。
- 一切都在本地:无账号、无遥测、除你明确扫描的注册中心和你配置的 AI 端点外不联网。