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. 從韌體範例開始：硬體韌體以 Arduino 框架針對 ESP32。儲存庫範例依賴 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 結構描述及資料夾推送傳輸)。

範例韌體支援哪些硬體？ 韌體以 Arduino 框架針對 ESP32。目前寫法依賴 M5StickCPlus 函式庫來驅動顯示器、IMU 和按鈕，因此你需要該板子或使用不同驅動的分支。

如何將裝置與 Claude Desktop 配對？ 啟用開發者模式，然後開啟硬體夥伴視窗 (Developer → Open Hardware Buddy…)，點擊 Connect 並選擇你的裝置。macOS 首次連線需藍牙權限。

如果 BLE 裝置未被發現怎麼辦？ 儲存庫建議確認棒子已喚醒 (按任意按鈕)，並確認棒子的設定選單中藍牙已啟用。

裝置能否顯示自訂角色動畫？ 可以。範例支援 ASCII 寵物與 GIF 寵物。GIF 模式需提供包含 manifest.json 及 96px 寬 GIF 的角色包資料夾；狀態檔案可為單一檔名或陣列以輪播動畫。

替代方案

• 使用提供的線路協定自行實作 BLE 裝置：不使用參考韌體，您可以撰寫自訂 BLE 堆疊，遵循文件化的 Nordic UART Service UUID 與 JSON 結構描述。
• 使用其他具 BLE 的嵌入式平台，但相同應用邏輯：若 ESP32 不是您的目標，您可以將協定與狀態處理（睡眠/喚醒、批准提示渲染，以及 UI 更新）調整至偏好的微控制器。
• 建置純軟體的「桌面夥伴」，無需 BLE 硬體：若您僅需電腦上的介面，可考慮純軟體整合方式，而非實體顯示/動畫裝置。