Claude Desktop Buddy 自定义 GIF 角色：manifest.json 配置与蓝牙拖拽推送完整指南

【免费下载链接】claude-desktop-buddyReference and an example for the Bluetooth API for makers in Claude Cowork & Claude Code Desktop项目地址: https://gitcode.com/gh_mirrors/cl/claude-desktop-buddy

想让 Claude 桌面上的硬件伴侣 M5StickC Plus 换上你亲手设计的角色吗？claude-desktop-buddy 是 Claude Cowork / Claude Code Desktop 官方提供的蓝牙 API 桌面硬件参考示例，你只需准备一个包含manifest.json和七种状态 GIF 动画的角色包文件夹，通过 Hardware Buddy 窗口的拖拽目标经 BLE 蓝牙推送到设备，桌面宠物就会实时切换到你的专属 GIF 角色。本指南带你从素材规格、manifest.json 配置，到蓝牙推送与 USB 烧录，一步步完成整个过程。

角色包长什么样：manifest.json 配置详解

每个角色包就是一个普通文件夹，包含manifest.json和对应的 GIF 文件。参考仓库里的官方示例：characters/bufo/manifest.json。

{ "name": "bufo", "colors": { "body": "#6B8E23", "bg": "#000000", "text": "#FFFFFF", "textDim": "#808080", "ink": "#000000" }, "states": { "sleep": "sleep.gif", "idle": ["idle_0.gif", "idle_1.gif", "idle_2.gif"], "busy": "busy.gif", "attention": "attention.gif", "celebrate": "celebrate.gif", "dizzy": "dizzy.gif", "heart": "heart.gif" } }

三个字段各有用途：

• name：角色名，推送时会作为设备 LittleFS 存储的目录名。
• colors：屏幕配色方案，GIF 透明区域会用bg颜色填充，避免残影。
• states：七种状态的动画映射。状态值可以是单个文件名，也可以是数组——数组会在每次循环结束后轮换到下一张 GIF，让主屏不断切换眨眼和眼神动画，而不是永远循环同一段。

七种状态分别对应不同的触发场景：

GIF 素材准备：96px 宽是硬性规格

设备屏幕是 135×240 的竖屏，GIF 素材有明确的规格要求：

• 宽度固定 96px，高度控制在约 140px 以内以保证完整显示；
• 紧贴角色裁剪——透明边距只会浪费屏幕面积、让角色显得更小；
• 整个角色文件夹不超过 1.8MB，超出会被桌面端拒绝安装。

手动逐张处理很繁琐，仓库提供了专门的工具：tools/prep_character.py。把任意尺寸的原始 GIF 目录（或 zip）交给它：

python3 tools/prep_character.py my_character_dir

它会把所有状态统一缩放到 96px 宽、用同一套跨状态裁剪框保证角色在每种动画里比例一致，自动压到 64 色，并输出到characters/<角色名>/，同时重写manifest.json。如果产物超过 1.8MB 上限，脚本会直接打印一条gifsicle --lossy=80 -O3 --colors 64的压缩命令帮你瘦身（通常能减掉 40–60% 体积）。

蓝牙拖拽推送：角色包上机两种方法

方法一：Hardware Buddy 窗口拖拽（无线）

先打开开发者模式（Help → Troubleshooting → Enable Developer Mode），然后在Developer → Open Hardware Buddy…打开窗口：

点击Connect配对设备后，把角色文件夹直接拖进右侧的 "Drop a data folder here" 区域，点Send to Device：

应用会通过 BLE 把整个文件夹流式传到设备。传输走的是 src/xfer.h 定义的文件夹推送协议：char_begin报头声明总大小并做容量检查 → 每个文件逐块 base64chunk传输并逐块确认 →char_end结束，设备随即加载新角色并实时切换到 GIF 模式。

方法二：USB 直接烧录（调试迭代更快）

频繁调整角色时，跳过蓝牙往返更省事：

python3 tools/flash_character.py characters/bufo

tools/flash_character.py 会把角色包暂存到data/分区目录，然后直接执行pio run -t uploadfs经 USB 写入 LittleFS 文件系统。烧录完成后，在设备上长按 A → Settings → Species → GIF即可启用。

设备端如何运行你的 GIF 角色

角色包落地后，固件由 src/character.cpp 接管：开机自动扫描/characters/加载最近安装的角色，解析 manifest 中的配色与状态映射；characterSetState()负责状态切换时打开对应 GIF，characterTick()每帧推进动画解码。idle 多帧数组会在同一动画驻留约 5 秒后轮换到下一张，暂停 0.8 秒再播放，营造自然的"环顾四周"效果。

想让设备退回内置的 18 种 ASCII 宠物？在设备Settings → delete char删除角色即可。完整的 BLE 线协议细节（UUID、JSON 模式）见 REFERENCE.md，动手前值得浏览一遍。

现在，打开你的画图工具，把专属角色送上 Claude 的桌面吧 🐸

【免费下载链接】claude-desktop-buddyReference and an example for the Bluetooth API for makers in Claude Cowork & Claude Code Desktop项目地址: https://gitcode.com/gh_mirrors/cl/claude-desktop-buddy