Claude Desktop Buddy

什么是 claude-desktop-buddy？

Claude Desktop Buddy (anthropics/claude-desktop-buddy) 是一个参考和示例项目，展示 Claude for macOS 和 Windows 如何通过蓝牙低功耗 (BLE) 连接“创客设备”。它专为希望构建能显示权限提示、最近消息及其他来自 Claude Cowork 和 Claude Code Desktop 交互状态的硬件的开发者和创客设计。

仓库主要提供文档和 BLE“伙伴”设备的示例固件。您无需代码即可概念性构建硬件，但可参考 REFERENCE.md 中的线协议说明，在自己的 BLE 设备中实现协议。

主要特性

• BLE 线协议参考（Nordic UART Service UUIDs、JSON 模式）：帮助您实现兼容设备行为，而无需猜测消息格式。
• Claude 交互的示例固件桥接：将设备连接到 Claude，使硬件能响应交互状态。
• 带开发者模式和硬件伙伴窗口的设备连接流程：文档说明如何将棒状 BLE 设备与 Claude Desktop 配对。
• 使用 Arduino 框架的 ESP32 固件目标：为嵌入式实现提供具体起点。
• 支持两种“宠物”显示模式——ASCII 和 GIF：示例设备可显示 ASCII 动画集，或通过 BLE 流式传输自定义 GIF 角色包。

如何使用 claude-desktop-buddy

1. 从固件示例开始：硬件固件针对 ESP32，使用 Arduino 框架。仓库示例依赖 M5StickCPlus 库用于显示、IMU 和按钮驱动；您需要该板卡或替换驱动的分支以适配您的引脚/布局。
2. 安装 PlatformIO Core，然后使用 pio run -t upload 刷写示例固件。
3. 如重新刷写已编程设备，先擦除：pio run -t erase && pio run -t upload。
4. 将设备与 Claude Desktop 配对：
   • 在 Claude Desktop 中启用开发者模式（Help → Troubleshooting → Enable Developer Mode）。
   • 打开硬件伙伴窗口（Developer → Open Hardware Buddy…），点击 Connect，从列表中选择您的设备。
   • macOS 上首次连接会提示蓝牙权限；授予权限。
5. 使用配对流程测试交互提示和设备响应。桥接会在双方唤醒时自动重连。

使用场景

• 构建 BLE“权限提示”设备：使用参考协议和示例固件行为，让设备提示用户批准或拒绝来自 Claude 的请求。
• 创建响应会话状态的交互式桌面伙伴：示例包含根据会话连接、忙碌、待批准或交互完成而变状态的设备“宠物”。
• 部署低功耗通知显示控制器：桌面宠物示例描述空闲时休眠、会话启动时唤醒。
• 使用 GIF 包自定义设备角色视觉效果：提供包含 manifest.json 和 96px 宽 GIF 文件的状态文件夹；应用通过 BLE 流式传输包并切换设备至 GIF 模式。
• 无需 BLE 往返迭代显示资源：仓库包含 tools/flash_character.py 流程，用于暂存角色数据并直接通过 USB 上传。

常见问题

构建兼容硬件需要使用提供的设备代码吗？
不需要。仓库说明无需此处代码即可构建自己的设备；REFERENCE.md 提供线协议细节（UUIDs、JSON 模式和文件夹推送传输）。

示例固件支持哪些硬件？
固件针对 ESP32，使用 Arduino 框架。当前依赖 M5StickCPlus 库用于显示、IMU 和按钮驱动，因此需要该板卡或使用不同驱动的分支。

如何将设备与 Claude Desktop 配对？
启用开发者模式，然后打开硬件伙伴窗口（Developer → Open Hardware Buddy…），点击 Connect，选择您的设备。macOS 首次连接需蓝牙权限。

如果 BLE 设备未被发现怎么办？
仓库建议确保设备已唤醒（按任意按钮），并确认设备设置菜单中蓝牙已启用。

设备能显示自定义角色动画吗？
可以。示例支持 ASCII 宠物和 GIF 宠物。GIF 模式下，提供包含 manifest.json 和 96px 宽 GIF 的角色包文件夹；状态文件可为单个文件名或动画轮播数组。

替代方案

• 使用提供的线协议实现自己的 BLE 设备：不使用参考固件，您可以编写自定义 BLE 协议栈，遵循文档化的 Nordic UART 服务 UUID 和 JSON 模式。
• 使用其他支持 BLE 的嵌入式平台，但保留相同应用逻辑：如果 ESP32 不是您的目标，您可以将协议和状态处理（休眠/唤醒、批准提示渲染以及 UI 更新）适配到首选微控制器。
• 构建纯软件“桌面伴侣”，无需 BLE 硬件：如果您仅需电脑上的界面，可考虑纯软件集成方案，而非物理显示/动画设备。