《Muse Gadgets 实战》第 13 章：自定义命令：让 Muse 替你干活
上一章我们用了社区现成的 43 个技能。这一章讲的就是自定义命令：不再只用别人写好的技能，而是自己定一套自定义命令，让 Muse 按你的习惯干活。
先分清两条路：
- 不写代码：直接跟 Muse 说话，让它去装软件、查状态。
- 动手写：往 Linux SDK 里加一个自己的命令，或者写一份自己的 SKILL.md。
适用范围：Linux 外设，不是 ESP32
本章的自定义命令走 Linux SDK，不是给 ESP32 重新刷固件。
ESP32 板子跑的是固件，Linux 外设（树莓派）才能跑命令。第 11 章装好的树莓派外设，就是本章的主角。
Linux 外设自带的 4 个命令
Linux 外设自带 4 个命令（来源：官方 linux/README.md 原文）：
system.run：跑一条 shell 命令，返回输出和退出码。file.read：读文件，一次 64 KB。file.write：写文件，一次 64 KB，写完才替换。device.health：报 uptime、负载、内存、磁盘和温度。
权限规则：命令以安装时那个账号的权限跑。那个账号能 sudo，Muse 就能 sudo。官方原话就是这个意思。
不写代码：直接跟 Muse 说话
你不需要写代码，直接说需求，Muse 自己拆成命令去执行。
官方 README 给了原句例子（来源：官方 linux/README.md 原文）：
- “What’s using all the disk space on my Pi?”（查磁盘是谁占满的）
- “Install Home Assistant on my Pi and tell me how to open it.”（在树莓派上装 Home Assistant，并告诉你怎么打开）
- “Every morning at 7, check if my Pi’s backups ran and tell me if they didn’t.”（每天早上 7 点查备份，没跑就告诉你）
- “Write a service that tells me when the Pi gets too hot.”（写一个服务，树莓派过热就提醒）
讲法很简单：你说清楚触发条件和结果，别含糊。Muse 会调用上面那 4 个自带命令去干活。
程序主动找 Muse：send-user-msg
这不是你问 Muse，而是机器上的程序反过来推消息给你。
用法（来源：官方 linux/README.md）：
musegadget send-user-msg "The garage door has been open for an hour."
这行命令会让你的设备给 Muse 聊天发一条消息：”车库门开了一个小时了”。
加 --session-id 可以发到一个侧聊。新 id 开新侧聊，复用 id 就续在同一个侧聊里。
完整例子在 linux 目录下的 examples/pebble_ring_bridge.py。这是一个 webhook 监听器，把 Pebble 戒指的每条提醒发到自己的 Muse 聊天。
这条路适合做提醒，不适合做开门这种高风险动作。
动手写：往 Linux SDK 里加命令
想加自己的命令，要去改代码（来源：官方 linux/README.md 原文）：
- 命令在
src/musegadget/executor.py里。 - 往
COMMAND_SPECS里加一条 spec。 - 再在
Executor.run里加一个分支。
官方 linux/AGENTS.md 里有完整走法，动手前先读它。
改完怎么试：
把改好的 linux 目录拷到设备上，跑 bash install.sh --from .（官方 README 原文）。
换账号降权限：
bash install.sh --run-as someone，可以给 Muse 一个没有 sudo 的账号。这是官方给的降权限办法，写自定义命令前先想好要不要降。
动手写：写自己的 SKILL.md
不想改代码，可以写 SKILL.md（来源：官方 skills/README.md 原文）。
格式要求：
- 目录名：
gadget-<设备名>/SKILL.md。 - YAML 里
name要和目录名对应。 - 里面要有
description、操作说明、limits、来源链接。 - 只能用 Markdown，别塞代码文件进去。
用法跟上一章一样：
把仓库链接丢给 Muse，或者把 SKILL.md 复制粘贴到对话里。如果引用了共享技能（比如 Google Cast），要一起带上。
想贡献回社区就提 PR，官方欢迎这种 PR。
Home Assistant 对接示例
官方主 README 原话：Linux Device SDK 那一行写的是 “Hack in your own commands to let Muse handle sysadmin chores or your Home Assistant setup.”（加自己的命令，让 Muse 管系统杂事或你的 Home Assistant）。
官方 linux/README.md 给的例子就是上面那句 “Install Home Assistant on my Pi and tell me how to open it.”
怎么做：
- 先让 Muse 在树莓派上把 Home Assistant 装起来、告诉你打开地址。
- 再按你家 Home Assistant 实际的设备和实体，一条一条试命令。
注意：每个家庭的设备名、实体名都不一样。这里不给一套通用的实体名和接口地址。文中没写的具体地址、实体名、调用参数，按你家实际配置来，待验证。
Home Assistant 能碰灯、锁、车库门这类实体。先从只读、只查状态的命令试起，确认无误再给写操作。
安全提醒
自定义命令权限大，风险也大。
- sudo 账号 = Muse 也能 sudo。自定义命令先想权限，再写功能。
- 没把握就用
--run-as换一个没有 sudo 的账号。 - 车库门、门锁、摄像头这类碰物理安全的，先从提醒做起，别一上来就给”能开门”。
- 先在不重要的设备上试，跑通了再接到真家伙上。
- 社区技能不是官方集成，读完 SKILL.md 的 Limits 再用。
硬件准备
- 树莓派购买链接：[联盟链接占位]
- Home Assistant 相关硬件：[联盟链接占位]
（联盟账号未下来前留空占位文字，不编造任何链接，不含返佣承诺。）
读者常问
需要会编程吗？
不写代码那条路不需要；往 executor.py 加命令那条路要会一点 Python；写 SKILL.md 那条路只要会写 Markdown。
ESP32 板子能用本章的自定义命令吗？
不能直接用。本章的命令跑在 Linux 外设上，ESP32 板子要改固件是另一条路。
自定义命令会不会把树莓派搞坏？
会。所以先降权限、先在不重要的事上试、改前备份。
Home Assistant 是不是装上就能让 Muse 全接管？
不是。先装起来、确认地址和实体，再一条一条试。文中没写的细节按实际配置来。
事实核实声明
- 仓库状态：2026-10-25 调 GitHub 页面实测——star 2406，fork 531，提交 128 次，未归档，Apache-2.0 许可证。
- 技能数量：skills/CATALOG.md 仍写 43 active skills（42 device/family skills and one shared Google Cast skill），与 2026-10-24 一致。
- 自带命令：Linux 外设 4 个命令（system.run、file.read、file.write、device.health）及权限规则，来源为官方 linux/README.md 原文，于 2026-10-25 实测读取。
- 对话示例：4 个原句例子来源为官方 linux/README.md 原文，于 2026-10-25 实测读取。
- send-user-msg：用法及 pebble_ring_bridge.py 例子来源为官方 linux/README.md，于 2026-10-25 实测读取。
- 加命令方法：executor.py 路径、COMMAND_SPECS、install.sh 参数来源为官方 linux/README.md 原文，于 2026-10-25 实测读取。
- SKILL.md 格式：格式要求来源为官方 skills/README.md 原文，于 2026-10-25 实测读取。
- Home Assistant 原话：主 README 及 linux/README.md 原话于 2026-10-25 实测读取。
相关章节
- 上一章：第 12 章 Skills 系统：40+ 智能家居玩法
- 下一章：第 14 章 从 DIY 到卖货（待发布）
本章讲了怎么让 Muse 按你的习惯干活，下一章我们聊聊怎么把这些玩法变成能卖的产品。
因信息存在时效性以及人为主动性提交的情况（比如有人故意提交错误的信息，人力有限无法进一步做背调确认），因此可能存在信息上的错误，介意请勿支付，如果支付则视为已知晓可能存在的信息错误问题，愿意承担信息错误的支付损失（本站提供的是虚拟信息服务，不支持退款，介意请勿支付）
