Buddy
协议深潜

4.1 / 为什么是 BLE 而不是 WiFi / USB / UWB

候选方案对比：

Buddy 选 BLE 的理由可以反推：

• · 桌面级范围正好——既不限制在物理接触（USB），也不会无意中被楼下办公室嗅到（WiFi）
• · 配对一次，重连自动——符合"放工位上不管它"的交互
• · 极低功耗——纽扣电池 / USB-C 待机几天没问题
• · 现成生态——任何 ESP32 / nRF52 / 树莓派+dongle 都能广播
• · 物理半径即信任半径（§ 11 详述）

USB 也是合理候选，但要求设备线连主机；BLE 让设备自由放置——这个自由度对 ambient device 很重要。

4.2 / Nordic UART Service —— 为什么不发明新 GATT

NUS 是事实标准，三个 GATT 特征：

Service:  6e400001-b5a3-f393-e0a9-e50e24dcca9e
RX (W):   6e400002-b5a3-f393-e0a9-e50e24dcca9e   // 主机→设备 Write
TX (N):   6e400003-b5a3-f393-e0a9-e50e24dcca9e   // 设备→主机 Notify

为什么用 NUS 而不是设计 Buddy-specific 的 GATT profile？

• · 生态一致性：NUS 在 Nordic SoftDevice、ESP32 NimBLE、Apple CoreBluetooth、Linux BlueZ、Python bleak 都是 first-class
• · 调试可观测性：nRF Connect、bluetoothctl、hcitool 都能直接订阅。设计者主动让协议变得容易嗅探——开放性信号
• · 范式天然匹配：NUS 本质就是双向"串口"，正好对应"主机推状态、设备回决策"的对称结构
• · 姿态信号：选事实标准而不是发明——表明这份协议定位在"应用层规范"，基础设施留给生态

和 MCP 的 JSON-RPC 2.0 over stdio/SSE 一致——都是复用现有标准当传输底座，把新意全部投入应用语义层。

4.3 / 广播命名前缀：Claude*

设备广播名字必须以 Claude 开头。这是个简单约定，代替了几种更复杂方案：

• ❌ Manufacturer-specific data（要去 Bluetooth SIG 注册 16-bit Company ID）
• ❌ 自定义 Service UUID 用于 advertise（占 advertising payload，128-bit 占 16 字节）
• ✅ 名字前缀——零注册成本，扫描时一行代码过滤

副作用：任何人都可以广播 Claude_xxx 假冒设备。但这在 BLE 范围内本来就要靠加密层防护（§ 11），不是命名约定该解决的。用对工具。

6.1 / 心跳快照（设备 ← 桌面）

{
  "total": 3,
  "running": 1,
  "waiting": 1,
  "msg": "approve: Bash",
  "entries": ["10:42 git push", "10:41 yarn test", "10:39 reading file..."],
  "tokens": 184502,
  "tokens_today": 31200,
  "prompt": {
    "id": "req_abc123",
    "tool": "Bash",
    "hint": "rm -rf /tmp/foo"
  }
}

关键合约

6.2 / 权限审批（设备 → 桌面）

{"cmd":"permission","id":"req_abc123","decision":"once"}
{"cmd":"permission","id":"req_abc123","decision":"deny"}

合约：

• · id 必须 byte-for-byte 等于上一条心跳的 prompt.id
• · decision 只有两个值：once 或 deny
• · 没有 always / forever / whitelist——协议层主动不暴露持久授权

最后一点是关键。Claude Code 桌面端本身有"始终允许"模式，Buddy 故意不让设备触发。

6.3 / Turn 事件（设备 ← 桌面，异步）

{
  "evt": "turn",
  "role": "assistant",
  "content": [{"type": "text", "text": "..."}]
}

每个 Claude 回复完成后触发一次。content 数组是 SDK 原生格式（text / tool_use / tool_result）。超过 4 KB 的事件被丢弃。

为什么 4 KB？工程约束驱动：

• · BLE Notify 实测吞吐 ~10–20 KB/s（取决于连接参数）
• · 4 KB 一帧约 200–400 ms 传输完
• · 超过 4 KB 的回复一般是大段代码或长解释，反正小屏幕展示不下
• · 4 KB 也够 ESP32 RAM 缓冲一帧（这块 SoC 默认 RAM 320 KB）

设计意图：Turn 不是为了让设备完整复制对话，是为了触发"Claude 说话了"动画。如果想要完整记录，应该用别的传输（USB 直连、WiFi）。Buddy 在 BLE 上的角色是"状态指示器"，不是"日志同步器"。

6.4 / 状态上报 ack（桌面 ← 设备）

{
  "ack": "status",
  "ok": true,
  "data": {
    "name": "Clawd",
    "sec": true,
    "bat": {"pct": 87, "mV": 4012, "mA": -120, "usb": true},
    "sys": {"up": 8412, "heap": 84200},
    "stats": {"appr": 42, "deny": 3, "vel": 8, "nap": 12, "lvl": 5}
  }
}

桌面 poll，设备答。协议里最弱合约的部分——每个字段都是可选，设备不支持就不填。

stats.lvl 是设备自己跟踪的"等级"（每 5 万 token 升一级），上报给桌面。这个状态桌面不维护——设备的 NVS 是单一真相源。又一个克制设计：让设备拥有它显示的状态，桌面只是消费方。

6.5 / Folder Push — 流式角色包传输

协议里最复杂的部分。Hardware Buddy 窗口的 drop target 收到一个文件夹后触发：

设计要点

7.1 / M5StickC Plus 按键映射

屏幕 30 秒无操作自动关闭，有审批待处理时保持常亮。

注意"按键含义随状态变化"——同一个按钮在不同 page 下意思完全不同。这是协议设计上让设备自己决定按键语义的体现：协议只规定"设备发 once/deny"，不规定"哪个按键发哪个"。设备开发者完全自由。

7.2 / 刷机方法

# 安装 PlatformIO Core，然后：
pio run -t upload

# 从全新设备开始先清除：
pio run -t erase && pio run -t upload

仓库 platformio.ini 已经把 board、partitions、文件系统都配好。uploadfs target 单独写文件系统（用于角色包热更新）。

攻击面

Buddy 协议传输：

• · 工具调用预览（prompt.hint）—— 含路径、命令、URL
• · 对话片段（Turn 事件 4 KB）
• · token 累计、会话计数

未加密的 BLE 链路在 ~10m 范围内可被廉价 nRF 嗅探器（< $30）实时记录。文档明确建议实现 LE Secure Connections bonding，但没有强制。

为什么不强制加密？

1. 1. Maker 友好：很多 maker 用的开发板默认不开 BLE 加密。强制会大幅提高接入门槛
2. 2. 配对 UX 痛：BLE bonding 需要用户输入 6 位 passkey 或 yes/no——没屏幕的设备很麻烦
3. 3. 威胁模型现实主义：能物理接近你工位的人，多半已经能看到屏幕——加密 BLE 不能阻止 over-the-shoulder

我的判断：对个人 dev 桌面 OK，对企业环境完全不 OK。Anthropic 想推 Buddy 进 SOC2/HIPAA 合规环境，bonding 必须强制。这就需要协议层加 sec: required 字段。

vs MCP — 都是 JSON 但目标受众相反

虽然都用 JSON、都被 Anthropic 设计、传输层都可能是 stdio/socket——面向的人和场景天差地别。把它们合并是错误——协议设计要适配读者，不是追求统一。

vs Remote Control — 同样的问题，相反的解

Remote Control（2026-02 推出）和 Buddy 都解决"如何不在主机前操作 agent"。但解法相反：

vs Computer Use — 方向相反的可见性

Computer Use 让 agent 看到屏幕、操作鼠标——agent 看见桌面。Buddy 让桌面看到 agent 的内部状态——桌面看见 agent。

Computer Use:    agent ──观察 / 操作──→ desktop   // agent 是主动方
Buddy:           desktop ──状态 / 决策──→ agent     // 人/物理设备是主动方

两者都是 agent 与物理世界的接口，但方向相反。组合起来——agent 看屏幕调试代码、人在 ambient 设备上批准 git push——是 2026 年 agent 工作流的完整形态。