Muse Gadgets SDK 深度解析：一块 ESP32，把家里的设备接进 AI 助手
Muse Gadgets SDK 深度解析：一块 ESP32，把家里的设备接进 AI 助手
Agent 生态里最缺的一环，可能不是更聪明的模型，而是"能摸到物理世界的手"。
10 月 2 日，Meta 在 facebookincubator 下开源了 Muse Gadget SDK，仓库描述只有一句："Open source SDK to build Muse gadgets"。四天之内它涨到 1,442 stars、273 forks，用 C 写成，Apache-2.0 许可。这个增速说明了一件事：很多人早就在等一个"让 AI 助手接上真实设备"的官方路径。
它和我们这几天写过的项目都不太一样。LangGraph、AgentScope、Claude Agent SDK 解决的是"Agent 怎么思考、怎么协作"；Muse Gadgets 解决的是**"Agent 怎么伸手"**——用一块几十块钱的 ESP32，或者一台吃灰的树莓派，把屏幕、按钮、传感器、家电变成 Agent 能操作的对象。
仓库自己的开场白很有味道，我原样翻译：
Muse gadgets 是你自己动手做的开源设备。给一块现成的 ESP32 开发板写程序，或者用我们的设备 SDK 配好一台树莓派，然后把 Muse 连接到你的显示器、按钮、传感器、执行器，以及工作台上所有躺着的玩意。
这些 SDK 和固件就是给黑客造的，由黑客造的，纯属好玩。折腾的副作用可能包括：变砖的开发板、作废的保修、电压跌落，或者破产。风险自负！
这篇就拆这份"给黑客的说明书"：两条 SDK 路线、20 多块开发板、43 个设备技能，以及它相当坦率的安全模型。
本文提纲
- 它是什么：给 AI 助手做物理接口
- 两条路线：ESP32 与 Linux 的能力面
- ESP32 上手：一句话让 Agent 帮你烧录，或者自己动手
- 支持的开发板与状态灯语义
- Linux 上手：把树莓派变成 Agent 的执行节点
- 安全模型：官方写得比多数产品诚实
- 真正的杀手锏：43 个设备技能
- AI 原生的开发方式：AGENTS.md 就是文档
- 模拟器、生态与边界
它是什么：给 AI 助手做物理接口
先理清定位。Muse 是 Meta 的 AI 助手产品，Muse Home Link 是它的官方硬件（USB-C 供电，让 Muse 接入家庭网络与电视、音响等设备）。这次开源的 SDK 让你自己做同类设备：
- ESP32 Device SDK：把开源固件烧进任何 ESP32 兼容开发板，让 Muse 接入你的家庭 Wi-Fi；带家庭网络隧道的板子，Muse 还能访问你已有的设备和任何带本地 HTTP API 的东西——加个屏幕显示图片、接音频输入输出，或者挂上你自己的传感器。
- Linux Device SDK：把树莓派或任意 Linux 机器变成 Muse gadget，让 Muse 在上面跑命令、读写文件。
两条路线对应两种"伸手"：
| ESP32 Device SDK | Linux Device SDK | |
|---|---|---|
| 载体 | 现成 ESP32 开发板 | 树莓派 3B+/4/5/Zero 2 W 或任意带 BLE 的 Linux 机器 |
| 语言/栈 | C + ESP-IDF | Python（安装到 /opt/musegadget） |
| 能力重心 | 屏幕、按钮、音频、传感器、家庭网络隧道 | shell 命令、文件读写、设备健康 |
| 典型用途 | 桌面显示器、语音终端、自制外设 | 家庭服务器运维、Home Assistant、定时任务 |
一个共同前提：每个 gadget 都需要一个 SDK token（在 gadgets.muse.ai 的 Account > SDK tokens 生成），哪怕是你自己做给自己用的。还要先读一遍 Gadget SDK Terms。
两条路线：ESP32 与 Linux 的能力面
Linux 那条的能力面小得可爱，但极其实用——四个命令就是它的全部武器：
| 命令 | 作用 |
|---|---|
system.run |
执行 shell 命令，返回输出与退出码 |
file.read |
读文件，每次 64 KB |
file.write |
写文件，每次 64 KB，只在完整时才替换原文件 |
device.health |
上报 uptime、负载、内存、磁盘与温度 |
注意 file.write 那句"只在完整时才替换"——这是分布式写入里最基本的原子性意识，一个小工具做到了。
ESP32 那条则是完整的嵌入式固件工程。按 esp32/AGENTS.md 的描述，这个叫 muse-gadget 的固件：
- 通过 BLE 与手机配对；
- 加入 Wi-Fi；
- 与一个 VM 保持加密的 Noise 会话，并可选启用家庭网络隧道；
- 代码入口在
main/main.c，主要逻辑在main/app.c，components/muse提供了带屏板子上的头像 / 语音 / 设置界面。
也就是说，它不是"把设备连到手机 App"那么简单，而是一条手机 → BLE 配对 → Wi-Fi → 加密隧道 → 云端的完整链路。
ESP32 上手：一句话让 Agent 帮你烧录，或者自己动手
官方给了两条路，而且把 AI Agent 驱动的路径放在前面。
路径一：让 Muse Code 干。 先装 Meta 的编码 Agent：
curl -fsSL https://dev.meta.ai/install.sh | sh然后插上板子，在 esp32 目录里启动它：
git clone https://github.com/facebookincubator/muse-gadget-sdk
cd muse-gadget-sdk/esp32
muse --disable-sandbox--disable-sandbox 的作用是让它能访问板子的 USB 串口并下载 ESP-IDF 工具链——注意它仍然要你逐条批准命令。接着用自然语言提需求就行，官方给的示例包括：
Build this firmware for my ESP32-C5 DevKitC-1 and flash it.
Watch the serial log and tell me when it's ready to pair.
I have a Waveshare ESP32-S3 AMOLED board. Build the UI for it.
Add support for my board. It's an ESP32-S3 with 16 MB flash,
a button on GPIO 0 and no PSRAM.
Make the status light half as bright.最后一条特别有意思："把状态灯调暗一半"——这种程度的自然语言驱动硬件，说明它准备好让你把 Agent 当日常工具用了。
它凭什么能这么干？因为 Muse Code 会读 AGENTS.md，而那份文件里写着"如何搭工具链、为你的板子构建、烧录、读日志"。而且官方明确说了：任何会读 AGENTS.md 的 Agent 都能用——不是 Muse Code 专属。
路径二：自己动手。 需要严格使用 ESP-IDF v6.0.1（其它版本不支持）：
git clone -b v6.0.1 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v6
~/esp/esp-idf-v6/install.sh esp32c5,esp32s3,esp32c6,esp32
. ~/esp/esp-idf-v6/export.sh然后配 token、构建、烧录：
idf.py menuconfig # ESP32 Device SDK > Muse Gadgets SDK token
idf.py build
idf.py -p /dev/cu.usbmodem1101 flash monitor几个实用细节：menuconfig 里填的是 SDK token；默认构建目标是 ESP32-C5 DevKitC-1；烧录失败时按住 BOOT、点一下 RESET、松开 BOOT 再试；重新烧录会保留配对与 Wi-Fi 设置，想彻底重置才用 idf.py erase-flash。
支持的开发板与状态灯语义
esp32/devices/ 下有 26 个板级 overlay 配置，AGENTS.md 的表格里列了约 20 块已验证的开发板，覆盖从入门到带屏的各类形态：
| 开发板 | 目标芯片 |
|---|---|
| ESP32-C5 DevKitC-1（默认，开箱可用） | esp32c5 |
| ESP32-C6 devkit（无 PSRAM） | esp32c6 |
| Espressif ESP32-S3-DevKitC-1 v1.1（N8R8） | esp32s3 |
| ideaspark ESP32 + 1.9" ST7789 | esp32 |
| Waveshare ESP32-C6-LCD-1.47 / C6-Touch-AMOLED-1.8 | esp32c6 |
| Seeed SenseCAP Indicator / reTerminal E1001 / E1002 | esp32s3 |
| Home Assistant Voice Preview Edition | esp32s3 |
| Seeed reSpeaker Lite with XIAO ESP32-S3（实验性） | esp32s3 |
| Waveshare ESP32-S3-Touch-AMOLED-1.75 / 1.75C | esp32s3 |
| Espressif ESP32-S3-BOX-3 | esp32s3 |
| Seeed SenseCAP Watcher / AIPI Lite | esp32s3 |
| M5Stack Cardputer ADV（实验性）/ StickS3 / StopWatch / Core2 / CoreS3 / StickC Plus2 | esp32s3 |
机制上，每块板对应一个 sdkconfig overlay（比如 devices/sdkconfig.muse-waveshare-s3-175c），部分板子还有 tools/board.sh 辅助脚本；带屏的板子要叠加 sdkconfig.muse。devices/ 目录里还有一份 AGENTS.md，专门教 Agent"如何新增一块开发板的支持"——加板子这件事被当成可复制的配方。
烧录完成后，状态灯就是全部的交互界面：
| 灯效 | 含义 |
|---|---|
| 橙色呼吸 | 已就绪，等待配网 |
| 蓝色呼吸 | 按按钮确认配对 |
| 蓝色常亮 | 正在加入 Wi-Fi |
| 绿色 | Muse 已连接 |
配对动作在手机端：Muse App 的 Settings > Devices 里先打开 Developer mode，再添加设备，它会以 MuseGadget-XXXXXX 的名字出现。
Linux 上手：把树莓派变成 Agent 的执行节点
Linux 那条路简单到有点危险：
curl -fsSL https://raw.githubusercontent.com/facebookincubator/muse-gadget-sdk/main/linux/install.sh -o install.sh
less install.sh # 先读一遍
bash install.sh --sdk-token mgst_…安装脚本会把依赖装到 /opt/musegadget，起一个 musegadget 服务；在把账号交给 Muse 之前它会明确征求同意，并告诉你这个账号是否能用 sudo。配对窗口开放 10 分钟，之后想重新配对需要在机器上执行 sudo musegadget pair。
它能干什么，官方给的例子很生活化：
What's using all the disk space on my Pi?
Install Home Assistant on my Pi and tell me how to open it.
Every morning at 7, check if my Pi's backups ran and tell me if they didn't.扩展方式有三种，从轻到重：
- 让 Muse 自己写——它能在机器上跑命令，所以"写个服务，在我树莓派过热时通知我"是可以直接提的需求；
- 让机器主动给 Muse 发消息（不需要任何自己的凭证）：
musegadget send-user-msg "The garage door has been open for an hour."
musegadget send-user-msg --session-id 6f1c2d4e-0b7a-4c3e-9f5d-2a8b1e0c7d93 "Posted to a side chat"--session-id 用来投递到侧边会话：新 id 会开一个新会话，复用同一个 id 则后续消息继续留在那里。仓库里有个完整示例 examples/pebble_ring_bridge.py——一个 webhook 监听器，把 Pebble 指环记录的每条笔记发进它自己的 Muse 会话。
- 加自定义命令：命令定义在
src/musegadget/executor.py，往COMMAND_SPECS加一条、在Executor.run加一个分支即可，AGENTS.md里有完整走查。想换执行账号用--run-as someone（比如换成一个没有 sudo 的账号），换 token 用--sdk-token（保存在/var/lib/musegadget/sdk_token，仅 root 可读）。
安全模型：官方写得比多数产品诚实
这部分我认为是全篇最值得读的，因为它没有把"安全"讲成营销话术。
ESP32 侧：设备通过 BLE 与手机配对，加入 Wi-Fi 后与一个 VM 保持 Noise 加密会话；配对必须先用 SDK token 生成，且手机端必须手动打开 Developer mode 才能看到设备。
Linux 侧，官方直接写明了两条硬事实：
- "Muse 对这台机器拥有和你安装时所用账号完全相同的权限。" 如果那个账号能用 sudo，Muse 也能。所以
--run-as不是可选项而是安全边界，把 Muse 跑在专用低权限账号上是官方支持的用法。 - "因为这些是社区设备，配对没有厂商验证，也无法阻止主动的中间人攻击。请在可信网络上完成设置。"
第二条尤其难得——厂商主动声明"我防不住 MITM"。它给出的缓解手段是：每次设置都创建全新的加密会话、配对只在你本机运行安装脚本或 musegadget pair 时才打开、窗口只有 10 分钟、且手机端会明确警告"这是社区设备"。
一句话总结这套信任模型：它把安全责任清晰地交给了设备主人——token 是身份、Developer mode 是开关、可信网络是前提、账号权限是边界。对"给黑客做的玩具"这个定位来说，这种诚实比虚假的安心更有价值。
真正的杀手锏：43 个设备技能
如果说 SDK 解决"怎么造设备"，那么 skills/ 目录解决的是"造出来能控制什么"——这里才是这个仓库最让我意外的地方。
skills/CATALOG.md 明确写着：43 个活跃技能 = 42 个设备/设备族技能 + 1 个共享的 Google Cast 技能。分类大致是：
| 类别 | 代表设备 |
|---|---|
| 共享协议 | Google Cast（媒体、音量、已有音箱分组） |
| 灯与插座 | Lutron Smart Bridges（灯与窗帘）、Shelly Gen 4、Philips Hue、Elgato Key Light、Meross、TP-Link Kasa EP10 / EP25 |
| 音箱、显示与电视 | Apple HomePod mini、Apple TV 4K、Google Home / Home Max / Nest Audio / Nest Hub / Nest Hub Max（明确无摄像头访问） / Nest Mini、Pixel Tablet、Google TV Streamer、LG webOS、Samsung Tizen、Sonos、Logitech Squeezebox、Freebox Player Pop、VIZIO D40f-G9 |
| 打印机与家电 | Brother 打印机（IPP 打印与任务状态）、HP Color LaserJet、Epson、Dyson Pure Hot+Cool、Miele G7566 洗碗机、Moonraker 3D 打印机、iRobot Roomba/Braava、Roborock、Eufy 扫地机、ratgdo 车库门、Velux KLF200 天窗、UniFi 网络控制台、Wyze / Yi 摄像头、Zigbee2MQTT 网关、ESPHome 设备、Sonos 音箱… |
这份清单的价值在于：它把"Agent 能对某个真实设备做什么"预先写成了 Markdown。每个 gadget-<device>/SKILL.md 里包含 YAML 元数据（name、description）、操作指令、**限制（limits）**和来源链接——限制这一项尤其关键，比如 "Nest Hub Max 不能访问摄像头"、"Kasa EP10 没有计量功能"，这类"能做什么、不能做什么"正是 Agent 最容易想当然的地方。
使用方式也很轻：把仓库链接丢给 Muse 让它自己找；或者查 CATALOG，把对应 SKILL.md 复制粘贴进对话（引用到共享技能比如 Google Cast 时要一并带上）。
要注意官方的定性："这些是社区贡献的技能，不是官方集成"，贡献者按 gadget-<device-name>/SKILL.md 格式提 PR，保持 Markdown-only，未来可能会进入 Muse 产品。这个"先用社区 Markdown 趟出设备兼容性，再产品化"的路径，是相当务实的生态打法。
AI 原生的开发方式：AGENTS.md 就是文档
这个仓库还有一个特征，我觉得比它的功能更值得注意：它把 AGENTS.md 当成一等公民。
- 根目录 README 明确说"每个目录都有
README.md供人上手，以及一份AGENTS.md给 Muse Code 这类编码 Agent"； esp32/AGENTS.md有 28 KB，是一份完整的构建与架构手册：前置条件、支持的开发板表、每块板的 overlay、工具链、构建、烧录、读日志，甚至排错提示（"关于gcm.h、gpio_ll.h缺失的报错，通常意味着 IDF 版本不对"）；esp32/devices/AGENTS.md专门讲"怎么加一块新板子"；linux/AGENTS.md对应 Linux 侧的贡献流程。
也就是说：同一件事有两份文档，一份给人看，一份给 Agent 看，而后者才是"可执行的"那份。 它甚至提醒：如果 Agent 跑在沙箱里，要放行 flash 和 monitor 命令到沙箱外执行（因为需要 USB 串口访问）。
模拟器、生态与边界
UI 模拟器是这个仓库里另一个实用工具：在桌面上以 412×412 的 SenseCAP Watcher 窗口预览 Muse 界面，它编译的是生产环境的 muse_ui.c、状态与文本代码、以及头像渲染器；SDL 负责显示、鼠标输入与计时，小型 host adapter 顶替 ESP-IDF、FreeRTOS、Wi-Fi、蓝牙、Link、设置与电源服务。构建只需 CMake 3.24+ / Ninja / C11 编译器 / Python 3.9+，不需要 ESP-IDF，会拉取固定版本的 SDL 2.32.10 与 LVGL 9.5.0（生产 UI 依赖其私有 API）。
但官方把它的边界写得很清楚：它不模拟 ESP32-S3 的 CPU、Watcher 的 Himax 摄像头、音频硬件、蓝牙射频、内存压力与电源时序——这些路径仍然必须在真机上构建与测试。"能快速做 UI、能重复截图"就是它的全部承诺，没有夸大。
许可与生态：项目整体 Apache-2.0，但有三处例外写在 README 里——minimp3（CC0-1.0）、pixel_font.c（来自 Adafruit GFX 的 glcdfont.c，BSD-2-Clause）、以及Jollybot 头像不在 Apache 许可覆盖范围内；构建时拉取的 ESP-IDF 组件与模拟器的 LVGL/SDL 各自沿用上游许可。社区在 Discord。
最后说说该不该玩。 官方那句玩笑话其实是最好的风险提示：变砖、保修作废、电压跌落、破产。具体一点：
- 它是给个人折腾的项目——设计目标是"工作台上有块板子的人"，不是"要塞进量产产品的人"；
- 别把 Linux SDK 装在你重要的机器上：Muse 会拿到该账号的全部权限（包括 sudo），正确做法是专用账号 + 专用机器（一台树莓派）；
- 社区设备没有厂商验证，官方自己说了防不住主动 MITM，所以配对要在可信网络上做；
- ESP-IDF 版本要求很严（v6.0.1），别指望用你手上旧版本的工具链一路顺下去；
- 四天 1,442 stars 说明热度很高，但也意味着生态与文档还在快速变化，56 个 open issues 就摆在那里。
值得玩的地方也很清楚：它是目前少有的、"官方开源 + 真能上手 + 又有社区设备技能库"的 AI 物理接口方案。一块 ESP32-C5 开发板加一根数据线，就能让 AI 助手第一次"看见"你桌上的屏幕、"按"你墙上的开关——这件事的想象力，比它现在能做的多得多。
参考链接
- GitHub: facebookincubator/muse-gadget-sdk — 1,442 stars / 273 forks，Apache-2.0
- ESP32 Device SDK 说明 — 开发板、ESP-IDF 流程与配对指引
- ESP32 AGENTS.md — 28 KB 的构建与架构手册（含支持的开发板表）
- Linux Device SDK 说明 — 安装、命令面、扩展与安全说明
- 设备技能目录 — 43 个活跃技能的分类清单
- 技能贡献说明 — Markdown-only 的
SKILL.md格式 - 开发板目录与新增板卡配方
- UI 模拟器 — 桌面预览与它不模拟的部分
- Muse Code（编码 Agent） — 官方推荐的构建方式
- Muse Gadgets 站点 / SDK token 管理 / Gadget SDK Terms
- 社区 Discord
- ESP-IDF v6.0.1 文档 — 工具链前置依赖
- 今日日报：Meta 开源 Muse Gadgets — 事件背景
你会用这块板子做什么——桌面信息屏、语音终端，还是把家里的灯和音箱接进去？评论区聊聊你的想法，觉得这份拆解有用就点个赞。
作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top
本文首发于 AI人工智能时代，转载请注明出处。
