Mac · 客户端

bluebell hub 使用指南

bluebell hub 是本机 Event Hub：保持运行，接收 bluebellctl 事件，保存、去重并按你的开关决定是否发送到 Apple 设备。

程序边界

一个 App，内含命令行工具

程序	职责
bluebell hub.app	本机 IPC、2 秒结算、历史、去重、Mac 通知、CloudKit outbox 与重试。
bluebellctl	解析参数或 JSON，然后通过本机 Unix Domain Socket 把事件交给客户端。

日常使用

收起窗口，继续接收事件

启动 bluebell hub 后，菜单栏会显示应用图标。主窗口右上角、设置按钮左侧的“收起到菜单栏”只隐藏窗口；应用继续接收本机 Agent 事件并处理发送队列。普通关闭窗口也不会退出服务。

Mac 本地通知：切换这台 Mac 的通知偏好，与远程推送独立。
推送到其他 Apple 设备：切换远程发送，与主窗口总开关保持一致。
打开 bluebell hub：恢复主窗口，包括窗口已关闭或最小化的情况。
退出 bluebell hub：结束应用，停止接收事件和处理发送队列。

Dock 图标和 Command-Tab 入口会保留，菜单栏空间不足时也有返回入口。收起状态不会延续到下次正常启动；下次仍显示主窗口。

首页

四个主要区域

接入你的终端

复制当前真实 CLI 路径，打开离线接入教程；不会扫描或显示工具“已安装”。

多设备测试提醒

输入 1–128 个字符，在 iCloud 就绪且总推送已开启时加入云端发送队列。

提醒送达

分别显示本机 IPC、iCloud 与发送队列，不把“账号可用”误写成“通知已送达”。

“推送到其他 Apple 设备”总开关

该开关覆盖安装了 bluebell 的 iPhone、iPad 与 Apple Watch，不保证所有设备同时提醒。它默认开启，并与 Event Hub 状态一起持久化。它只控制远程 CloudKit 路径；Mac 本地通知有独立开关。

操作	具体结果
关闭	清空所有账号的远程 outbox，包括待发送、重试与正在发送条目；未完成 2 秒结算的候选改为仅本机。
关闭期间收到事件	在接收时直接持久化为 `localOnly`，不等待 iCloud，不进入远程队列。
重新开启	只发送重新开启后收到的新事件；不会补发此前清除或关闭期间收到的事件。
关闭时的 UI	禁用多设备测试与手动发送重试。

从旧版升级后，请手动将自己 Agent 配置中已识别的 bluebellMac.app helper 路径更新为 bluebell hub.app，保留其他 hooks。新路径含空格，须保留引号；实际路径以客户端教程显示为准。

先分层测试

本机测试与多设备测试不同

1. 终端本机测试

Terminal

'/Applications/bluebell hub.app/Contents/Helpers/bluebellctl' emit \
  --source '我的 Agent' \
  --workspace-name '接入测试' \
  --dedupe-key "bluebell-test:$(uuidgen)" \
  --local

这个命令验证 CLI → IPC → Event Hub → 最近提醒，不进入 CloudKit。Mac 横幅还需要独立开启 Mac 本地通知并允许系统权限。

2. 首页多设备测试

在“多设备测试提醒”输入通知正文并发送。按钮只有在总推送开启、iCloud 就绪、正文非空且不超过 128 字符时可用。反馈“已加入队列”不是 Watch 送达回执。

诊断

读懂发送状态

本机接入：bluebellctl 是否能连接 Event Hub。
iCloud：当前 CloudKit 账号是否可用于远程写入。
发送队列：待发送和重试中的数量；只有持续错误才展开重试卡。

Outbox 的“待发送 / 重试中”表示 CloudKit 写入尚未成功，不是因为 iPhone 或 Watch 版本。配置型错误会提示检查容器环境、Schema、Entitlements 与当前构建。

本机数据