内容
# BarKeep
[](LICENSE)
[](https://www.apple.com/macos/)
[](https://github.com/unipheas/barkeep/releases/latest)
Busy Bar 的 macOS 状态栏伴侣 - 通过 USB 或 Wi-Fi 控制状态栏，自动化忙碌状态，将 LED 显示屏变成开发者外设。
核心设备控制无需 BarKeep 云、账户或遥测：BarKeep 直接与状态栏的本地 HTTP API 通信，通过 USB (`http://10.0.4.20/api`) 或 Wi-Fi（状态栏的本地 IP 地址和本地 HTTP API 密码）。可选的 Slack 同步、天气和更新检查仅在您启用或请求这些功能时联系其各自的外部服务。
BarKeep 是在 [MIT License](LICENSE) 下的免费开源软件。欢迎您使用、fork、修改、重新分发或从中构建自己的项目。欢迎贡献。
## 透明开发
BarKeep 在大量生成式 AI 工具的协助下构建，主要包括 OpenAI ChatGPT/Codex 和 Anthropic Claude。AI 协助了产品探索、实施、调试、测试、文档和发布自动化。
Brian Phillips 是人类维护者，负责审查、测试、签名并对每个官方版本负责。本披露描述了软件的开发方式：BarKeep 在正常运行期间不需要或联系 AI 服务。其可选的钩子和 MCP 服务器仅在您明确配置它们时连接到 AI 工具。
## 功能
**状态栏应用** （标签页弹出窗口：设备 / 消息 / 计时器 / 游戏 / 设置）
- 🎙 **自动开启通话** - 当任何应用程序打开麦克风时（Teams、Zoom、FaceTime ...），将状态栏切换到 *On Air* 状态，当麦克风空闲时清除。使用 CoreAudio 设备状态 - 无需麦克风权限，无音频被捕获。
- 📺 **实时预览** - 在弹出窗口中查看状态栏显示的内容。
- 💬 **消息** - 在状态栏的位图字体中发送滚动文本，并带有可搜索的全表情符号选择器（表情符号渲染为 Mac 上的图像）。保存预设，一键发送。
- 🎨 **像素画布** - 在真正的 72×16 网格上绘图并发送到显示屏。
- 🍅 **计时器** - 番茄工作法（工作/休息/循环）和简单倒计时，由状态栏的原生计时器引擎驱动。
- 📅 **日历** - 在日历事件期间自动忙碌；状态栏上一键倒计时至下一次会议。
- 🔔 **通知转发** - 在状态栏上滚动 macOS 通知（默认为 Teams，任何应用程序均可过滤），带有每个应用程序的 LED 颜色，可选的提示音和通话期间的队列重播。
- 🌐 **环境小部件** - 在显示屏的角落显示实时 ping 延迟徽章和本地天气（图标 + 温度）。
- 🕹 **Busy Bar 游戏** - 使用 Mac 键盘在物理 72×16 显示屏上玩 Snake、Tetris、Pong 和 Breakout。Mac 预览是可选的，默认关闭。
- 💤 **Slack 同步** - 状态栏变为忙碌 → 您的 Slack 状态变为 "🎧 On a call" + 请勿打扰；完成后清除。
- ⚙️ 亮度/音量控制、设备重命名、固件更新检查、登录时启动。
**开发者工具**
- 🖥 **`barkeep` 命令行工具** - `barkeep send "build done" -c green`、`barkeep busy on -T coding`、`barkeep timer 45`、`barkeep pomodoro`... 零依赖，从任何地方可脚本化。
- 🤖 **Claude Code 钩子** - 状态栏成为您的代理状态灯：绿色滚动 + 提示音时长任务完成，红色闪烁时 Claude 等待输入。
- 🔌 **MCP 服务器** - 将状态栏暴露为工具（`bar_send_message`、`bar_set_busy`、`bar_start_timer` ...），以便 Claude、Codex 和 ChatGPT 桌面可以直接驱动它。
## 安装
需要 macOS 14+ 和通过 USB 连接或可在同一 Wi-Fi 网络上访问的 Busy Bar。
### 下载
从 [Releases](https://github.com/unipheas/barkeep/releases) 获取 `BarKeep-x.y.z.zip`，解压并将 `BarKeep.app` 移至 /Applications。
发布版本使用开发者 ID 证书签名，并由 Apple notarized，因此它们可以正常打开。通过 Gatekeeper。如果您想自己构建，请使用下面的源代码说明。
### Homebrew
```bash
brew tap unipheas/barkeep
brew install --cask barkeep
```
Homebrew 直接将 `BarKeep.app` 安装到 `/Applications`。要安装 `barkeep` 命令行工具、MCP 服务器和 Claude Code 钩子：
```bash
brew install barkeep-cli
```
升级时，请先退出正在运行的状态栏应用程序，以便 macOS 不会在内存中保留旧的可执行文件：
```bash
osascript -e 'quit app "BarKeep"' 2>/dev/null || true
brew upgrade --cask barkeep
open -a BarKeep
```
运行的应用程序版本在菜单底部右侧显示。
### 连接 Busy Bar
USB 在固定地址 `10.0.4.20` 工作，不需要密码。对于 Wi-Fi：
1. 打开 Busy Bar 的网页界面并进入 **Network → HTTP API**。
2. 启用 HTTP API 访问并设置其本地数字密码。
3. 在 BarKeep → **设置** 中，输入状态栏的 Wi-Fi IP 地址和相同的密码作为 **Wi-Fi 密码**。
密码是物理状态栏上配置的密码。在 `cloud.busy.app` 上创建的令牌用于云 API，将被本地设备 API 拒绝。
### 从源代码构建
```bash
git clone https://github.com/unipheas/barkeep.git
cd barkeep
./make-app.sh
```
这会构建并启动 `dist/BarKeep.app`（仅状态栏，没有 Dock 图标）。签名优先使用开发者 ID 应用程序标识，然后是 Apple 开发，最后是显式设置的 `$BARKEEP_SIGN_IDENTITY`；否则，它会回退到临时签名。
可选的额外功能：
```bash
ln -s "$PWD/bin/barkeep" /opt/homebrew/bin/barkeep # CLI on PATH
claude mcp add --scope user barkeep -- /usr/bin/python3 "$PWD/mcp/barkeep_mcp.py" # MCP server
```
Claude Code 钩子：参见 [hooks/](hooks/) - 在 `~/.claude/settings.json` 中连接它们（`UserPromptSubmit` → `claude-prompt-submit.sh`、`Stop` → `claude-stop.sh`、`Notification` → `claude-notification.sh`）。
### Codex 和 ChatGPT 桌面
ChatGPT 桌面应用程序、Codex CLI 和 Codex IDE 扩展程序共享本地 MCP 配置。安装开发者工具，然后注册 BarKeep：
```bash
brew install barkeep-cli
codex mcp add barkeep -- /usr/bin/python3 "$(brew --prefix barkeep-cli)/libexec/barkeep_mcp.py"
```
对于通过 Wi-Fi 访问的 Busy Bar：
```bash
codex mcp add barkeep \
--env BARKEEP_HOST=YOUR_BAR_IP \
--env BARKEEP_TOKEN=YOUR_HTTP_API_PASSWORD \
-- /usr/bin/python3 "$(brew --prefix barkeep-cli)/libexec/barkeep_mcp.py"
```
在添加服务器后重启 ChatGPT 桌面、Codex 或 IDE 扩展程序。使用 `/mcp` 确认 `barkeep` 已连接。
## 权限
| 功能 | 权限 | 原因 |
|---|---|---|
| Busy Bar 连接 | 本地网络 | 对于通过 USB 网络接口和 Wi-Fi 的本地 HTTP API 均需要。BarKeep 在首次启动时询问。 |
| 通知转发 | 完全磁盘访问 | macOS 将已传递的通知存储在受 TCC 保护的 SQLite 数据库（`~/Library/Group Containers/group.com.apple.usernoted/db2/db`）中。BarKeep 读取它仅读；只有标题/正文与您的应用程序过滤器匹配的通知会被读取，并直接通过您的本地 USB 或 Wi-Fi 连接发送到状态栏。 |
| 日历自动忙碌 | 日历（完全访问） | 为了知道您何时有事件。 |
| 麦克风检测 | 无 | 麦克风检测读取 CoreAudio 设备状态，而不是音频。 |
在系统设置 → 隐私和安全 → 完全磁盘访问 → 添加已安装的 `BarKeep.app` 中授予完全磁盘访问。官方发布版本使用稳定的开发者 ID 签名，因此该权限在升级过程中保持不变。本地重建的临时签名副本可能需要再次授予该权限。
## Slack 设置
1. 在 https://api.slack.com/apps 创建应用 → *从零开始*
2. *OAuth & Permissions* → **用户令牌范围**：`users.profile:write`，`dnd:write`
3. *安装到工作区*，复制 **用户 OAuth 令牌** (`xoxp-…`)
4. 粘贴到 BarKeep → 设置 → Slack
## Busy Bar 游戏
打开 BarKeep → **游戏**，然后选择一个游戏。BarKeep 在透明的仅输入窗口中捕获键盘输入，因此物理 Busy Bar 是游戏显示屏，Mac 上无需保持游戏窗口可见。
| 键 | 操作 |
|---|---|
| `1` / `2` / `3` / `4` | 切换到 Snake / Tetris / Pong / Breakout |
| 箭头键 | 移动（所有游戏） |
| `W` / `S` | 替代 Pong 控制 |
| `↑` | 旋转 Tetris 方块 |
| `↓` | 使 Tetris 方块软降落 |
| 空格 | 使 Tetris 方块硬降落 |
| `R` | 重启当前游戏 |
| Esc | 停止街机游戏并将键盘焦点返回到之前的 Mac 应用程序 |
如果您想在游戏选项卡中进行故障排除预览，请启用 **在 BarKeep 中显示预览**。在原生忙碌/定时会话活动时，游戏无法运行，因为 Busy Bar 固件在这些会话期间拒绝自定义绘图。
## 配置
所有配置都在应用程序的设置选项卡中 - 设备主机、本地 HTTP API 密码（Wi-Fi 需要）、忙碌主题、通知过滤器、Slack 令牌、ping 目标、天气单位和位置（输入城市，它会自动为您定位；留空则使用基于 IP 的自动定位）。无需配置文件，无需终端。
CLI 环境变量：`BARKEEP_HOST`（设备地址，默认为 `10.0.4.20`）、`BARKEEP_TOKEN`（Wi-Fi 的本地 HTTP API 密码）和 `BARKEEP_THEME`（忙碌主题，默认为 `on_air`）。
### 连接故障排除
- **通过 USB 无法访问：** 重新连接电缆，等待几秒钟以建立 USB 网络接口，并将主机设置为 `10.0.4.20`。
- **通过 Wi-Fi 无法访问：** 确认 Mac 和 Busy Bar 可以在同一网络上通信。访客网络和一些手机热点隔离客户端。
- **令牌被拒绝 / HTTP 403：** 使用状态栏自己的网页界面中的本地数字 HTTP API 密码，而不是 `cloud.busy.app` 上的令牌。
- **无本地网络：** 打开系统设置 → 隐私和安全 → 本地网络并启用 BarKeep。如果已启用，请切换关闭并重新打开，然后重新启动 BarKeep。
- **粘贴了完整 URL：** BarKeep 接受 IP/主机名或 URL，例如 `http://busy-bar.local/login`，并将其规范化为主机。
## 设备 API 说明
验证针对固件 1.0.2 / API 24.3.0
([官方本地 HTTP API 文档](https://docs.busy.app/bar/dev/http-api))：
- 通过 USB，API 在 `http://10.0.4.20/api/*` 上提供，无需身份验证。通过 Wi-Fi，在状态栏的本地网页界面中启用 HTTP API 访问，配置其数字密码，然后在 BarKeep 设置中输入相同的密码。BarKeep 使用固件 API 的文档化 `X-API-Token` 头部发送它。 在 `cloud.busy.app` 上生成的令牌用于互联网 API，不会对本地 IP 地址进行身份验证。 文档中的 `/busybar/*` 前缀是针对云代理的；BarKeep 直接与设备通信。
- 文本元素仅接受可打印的 ASCII（位图字体）；BarKeep 将表情符号/unicode 渲染为 PNG 并将它们上传为资产。
- `/api/screen` 返回原始 **GRB** 像素数据的 base64（LED 字节顺序），72×16×3。
- 固件在忙碌会话活动时拒绝 *所有* 绘图请求，无论优先级如何。
- 忙碌主题是设备存储上的目录（`/ext/apps_assets/busy/themes`）- BarKeep 动态发现它们。
- 通知数据库 `rec_id`s 在删除后循环；BarKeep 通过通知 UUID 进行差异。
## 开发
```bash
swift test # 运行测试套件
swift build # 调试构建
./make-app.sh # 签名发布构建 + 启动
```
图标生成：`cd assets && swift gen_icon.swift 1024 icon.png`（参见 `gen_icon.swift` 获取像素网格）。
发布打包验证签名应用程序，然后存档并使用
[`scripts/verify-release-archive.sh`](scripts/verify-release-archive.sh) 验证新提取的副本，因此损坏的发布存档在发布前会失败。
## 贡献
欢迎提交错误报告、功能想法、文档改进、代码贡献和个人分支。参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发工作流程和拉取请求检查清单。
请使用 GitHub 的安全咨询表单私下报告潜在的漏洞；参见 [SECURITY.md](SECURITY.md) 获取详细信息。
## 许可证
BarKeep 在 [MIT License](LICENSE) 下发布。实际上，您可以自由使用、复制、修改、合并、发布、分发、许可和出售软件的副本。保留副本或项目的重要部分时，请附上版权和许可证声明。
贡献者提交到此存储库的贡献也受相同的 MIT 条款许可。
不隶属于 Busy Inc. Busy Bar 是 https://busy.app 的产品。
