Mac · 命令行

bluebellctl

bluebellctl 是 bluebell Mac 内置的轻量命令行入口。工具完成回调调用它；它把事件交给正在运行的 Event Hub。

安装位置

从客户端复制真实路径

bluebell 不安装全局命令，也不修改 PATH。请在 Mac 首页“接入你的终端”中点击“复制 CLI 路径”。App 位于 Applications 时，常见路径是：

CLI path

/Applications/bluebellMac.app/Contents/Helpers/bluebellctl

在 hook 配置里用引号包住完整路径。移动或改名 App 后必须更新；如果客户端提示缺少 bluebellctl，说明安装包不完整。

最小命令

先发送一条仅本机事件

Terminal

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

约 2 秒后，Mac 首页“最近提醒”应出现这条事件。--local 永不进入云端队列，适合验证命令、socket 和 Event Hub。

本机验证成功后，在正式 hook 中移除 --local。如果 Mac 的总推送开关关闭，默认的多设备事件仍会在 Event Hub 接收时降级为仅本机，重新开启后不会补发。

Flags

命令与参数

Syntax

bluebellctl emit --source <name> --dedupe-key <stable-key> [options]
bluebellctl emit --stdin
bluebellctl --help
bluebellctl emit --help

参数	是否必填	说明
`--source`	是	1–64 字符的用户自定义来源名；不是可执行路径。
`--dedupe-key`	是	一次逻辑完成的全局稳定身份，最长 512 字符。
`--event completed`	否	当前只接受 completed，默认就是该值。
`--workspace-name`	否	设备上显示的项目名，最长 128 字符。
`--summary`	否	短摘要，最长 280 字符；用户应自行避免敏感信息。
`--session-id` / `--turn-id`	否	本机诊断字段，各最长 256 字符。
`--workspace`	否	完整路径只保存在 Mac 本机，不上传 CloudKit。
`--occurred-at`	否	ISO-8601 时间；未来最多允许 5 分钟。
`--local`	否	明确设为仅本机，不进入 CloudKit。

机器输入

通过 stdin 发送 JSON

JSON

{
  "source": "我的 Agent",
  "workspaceName": "bluebell",
  "summary": "实现已完成",
  "dedupeKey": "my-agent:session-42:turn-7",
  "sessionID": "session-42",
  "turnID": "turn-7",
  "deliveryScope": "localOnly"
}

只有 source 与 dedupeKey 必填。stdin 输入上限 64 KiB，写完后必须关闭；--stdin 不能与其他事件 flags 混用。省略 deliveryScope 时默认为 allDevices。

最重要的可靠性规则

重试复用同一个 dedupeKey

同一次逻辑完成的重试必须复用同一个键；不同完成必须产生不同键。去重键在客户端内是全局的，不会按 source 自动分区，建议组成 来源:会话:轮次。

如果工具没有轮次 ID，需要适配脚本自己持久化本轮身份。不能只使用会话 ID，也不能在每次重试时重新生成时间戳或 UUID。Event Hub 的 2 秒 settlement 只合并重复候选，不能判断你选的生命周期是否正确。

脚本处理

stdout 与退出码

stdout

{"accepted":true,"duplicate":false,"eventID":"…","message":"…"}

退出码	含义
0	客户端接收，包括重复事件；不表示 CloudKit 写入或设备送达。
2	参数、JSON 或 IPC 传输错误。
4	客户端拒绝事件。