企业官网建设流程全解析

muse-gadget-sdk 仓库在 skills 目录下维护了一份社区设备 Skill 目录（skills/CATALOG.md），登记了 43 个可供 Muse 设备使用的第三方设备技能。本文完整拆解该目录的分类体系与全部条目、SKILL.md 的统一文件结构、共享的 Google Cast 协议技能，以及普通使用者与贡献者应遵循的使用与提交流程。读完后你可以准确判断某台家用设备应选用哪个 skill、如何把它交付给你的 muse，以及如何为新设备贡献一个符合规范的 SKILL.md。

Skill 目录在项目中的定位

skills/目录是社区来源（community-sourced）的设备技能集合，skills/README.md 明确声明这些 skill不是官方集成（not official integrations），而是社区成员提交、描述"如何控制某台具体设备"的 Markdown 文档。每条目录条目的写法遵循 README 中的约定：

• 目录名采用gadget-<device-name>形式，目录内放置唯一文件SKILL.md；
• 每个 SKILL.md 头部带有 YAML frontmatter，name字段必须与目录名一致，并附description；
• 正文需包含使用说明（instructions）、能力边界（limits）和来源链接（source links）；
• 保持纯 Markdown（Markdown-only）。

README 还提到，这些技能未来可能会以产品内置的形式出现在 Muse 产品中，因此目录的组织方式实际上是一套面向"设备可接入性"的文档规范：先有目录索引（skills/CATALOG.md），再有每类设备一份可被 muse 直接阅读的 skill 文档。

两种使用方式：把目录交给 muse，或手工粘贴 SKILL.md

skills/README.md 给出了两种把 skill 用起来的途径：

1. 聊天中直接给仓库链接：在与 muse 的对话中提供本仓库的链接，让 muse 自行浏览skills/CATALOG.md并找到它需要的设备 skill；
2. 手工拷贝：先在 catalog 中定位你的设备，把对应的SKILL.md内容复制粘贴到 muse 的聊天中。README 特别强调：如果该 skill 引用了共享 skill（例如 Google Cast），必须一并粘贴，否则共享协议的部分指令会缺失。

第二种方式也解释了skills/CATALOG.md第一行"Use the matching device skill for model compatibility, setup, safety and supported operations"的含义：目录条目的一句话描述就是选型依据——模型兼容性、设置方式、安全边界和受支持的操作范围。

目录总览：43 个条目 = 42 个设备/固件族 skill + 1 个共享协议 skill

skills/CATALOG.md开篇即声明规模："43 active skills: 42 device/family skills and one shared Google Cast skill."。其中 Google Cast 是唯一以"协议"而非"设备"维度组织的 skill，被多台音箱、电视和 Hub 类设备的 skill 共同引用；其余 42 个条目按设备形态分为六组。下面完整继承原文档的分类与描述，并给出每条对应的仓库相对路径，便于直接打开原文。

共享协议：Google Cast

• Google Cast — 媒体、音量与既有音箱组（原文描述：media, volume and existing speaker groups）。

这是整个目录中唯一跨设备复用的"共享协议"条目。下文单独展开其内容。

灯与插座（Lights and plugs）

• Lutron Smart Bridges — 通过 HAP 或 LEAP 控制灯具与遮阳帘；
• Shelly Gen 4 plugs — 开关与电量计量（switching and power metering）；
• Philips Hue bridges — 灯具、调光与场景；
• Elgato Key Light — 电源、亮度与色温；
• Meross smart plugs — 使用已提供的密钥做本地开关；
• TP-Link Kasa EP10 — 继电器与 LED，不带电量计量；
• TP-Link Kasa EP25 — 继电器、LED、能耗与支持范围内的自动断电（auto-off）。

值得注意的是目录把 EP10 与 EP25 拆成了两个独立 skill，而不是一个笼统的"Kasa"条目——gadget-tplink-kasa-ep25 的正文明确说明其走 SMART 本地认证协议，"not EP10 legacy XOR"，即 EP10 的旧版 XOR 协议不能替代 EP25 的认证路径。这类"同品牌不同协议族必须分开写"的粒度是整套目录的核心选型逻辑。

音箱、显示与电视（Speakers, displays and TVs）

这是目录中最大的分组，共 16 个条目：

• Apple HomePod mini — 受支持的音量、播放控制与分组控制；
• Apple TV 4K — 已配对的遥控器、应用与键盘；
• Freebox Player Pop — Cast 与 Android TV Remote v2；
• Google Home — 纯音频 Cast；
• Google Home Max — 纯音频 Cast；
• Google Nest Audio — 纯音频 Cast；
• Google Nest Hub — 视代数而定（generation-dependent）的 Cast 媒体能力；
• Google Nest Hub Max — Cast 媒体，明确不暴露摄像头；
• Google Nest Mini / Home Mini — 纯音频 Cast；
• Google Pixel Tablet — 在受支持的入坞/锁定 Hub Mode 下使用 Cast；
• Google TV Streamer — Cast 与 Android TV Remote v2；
• LG webOS TVs — 本地遥控/应用/输入源；当广播了 Cast 时再用 Cast；
• Logitech Squeezebox — 通过既有的 Lyrion 服务器播放；
• Samsung Tizen TVs — 本地遥控与型号相关的 Frame Art；
• Sonos speakers — 播放、音量与分组；
• VIZIO D40f-G9 — SmartCast 管理；当广播了 Cast 时再用 Cast。

这一组条目集中体现了目录的"协议分层"思路：Google 系设备多数是"audio-only Cast"或"Cast media"，统一委托给共享 Cast skill 的执行流程，各自 skill 只补充型号级限制；而 webOS、Tizen 这类设备则优先走本地遥控接口，Cast 只是"当设备广播了该服务时"的补充路径。

打印机与家电（Printers and appliances）

• Brother printers — IPP 打印与任务状态；
• HP Color LaserJet Pro M254dw — IPP 打印与状态；
• Epson printers — IPP 打印；在支持时提供 eSCL 扫描；
• Dyson HP04 — 本地状态与受支持的送风/加热控制；
• Miele G 7566 — 本地状态；仅在受支持且被允许时下发指令；
• Moonraker 3D printers — 既有服务的状态与打印/任务控制。

打印机条目以 IPP 为共同协议族，但目录仍按品牌拆分条目（Brother、HP 型号级、Epson），因为各家的任务状态与附加能力（如 Epson 的 eSCL 扫描）差异足以影响 muse 的操作决策。

扫地机（Vacuums）

• iRobot Roomba / Braava — 兼容范围内的本地状态与清洁命令；
• Roborock — 兼容的加密本地 TCP 控制；
• eufy RoboVac, Tuya models — 已映射的本地命令，明确排除 AIOT/X10。

以 gadget-roborock-vacuums/SKILL.md 为例，其 frontmatter 就写明了协议边界："encrypted local TCP channel with existing credentials; not Mi Home UDP miIO or A01 wet/dry devices"，正文进一步说明本地通道使用 TCP 58867，与部分 Mi Home 设备使用的 UDP miIO 路径不是同一通道。这类"相邻协议族不可混用"的否定式说明在三个 vacuum 条目中反复出现。

网关与固件族（Gateways and firmware families）

• ratgdo v32 — 已安装的 garage-door、light 和 lock 实体；
• Zigbee2MQTT — 既有网关实际暴露的设备能力；
• ESPSomfy-RTS — 已配置的遮阳帘/组控制，位置为估算值；
• Sonoff RF Bridge R2 — 经批准的固定码码捕获/发送；
• VELUX KLF200 — 已完成组网的节点、位置与场景；
• ESPHome devices — 已安装固件所暴露的实体；
• Tuya Wi-Fi devices — 已确认的本地协议、密钥与 datapoint 映射。

这一组控制的是"网关/固件平台"而非单一设备，条目描述因此都带有"existing/installed/configured"（既有、已安装、已配置）限定词——skill 假设网关已经部署，只操作它已经暴露出来的实体。例如 gadget-zigbee2mqtt-gateways/SKILL.md 的 Limits 部分写明："This skill covers devices actually supported by the installed bridge and their exposed capabilities, not universal Zigbee support"，即能力范围以网关节点definition.exposes实际暴露的字段为准。

只读网络与摄像头访问（Read-only network and camera access）

• UniFi Network consoles — 本地设备清单与状态；
• Wyze RTSP cameras — 在已安装兼容旧版固件的前提下进行观看/抓图；
• yi-hack cameras — 在已安装兼容固件的前提下进行快照/TCP 流。

这组条目的共同特征是"只读 + 前置条件"：gadget-unifi-network-consoles/SKILL.md 的 Limits 明确其为 read-only skill——"no restart, adoption, blocking/unblocking, port, Wi-Fi, firewall or network configuration changes"，并且要求不向用户请求之外暴露原始客户端清单。Wyze 与 yi-hack 两条同样把"兼容固件必须已经安装"作为前提，而非 skill 本身去做刷机。

深入一个条目：共享 Cast skill 的完整工作流

skills/CATALOG.md中唯一的共享协议 skill 是 gadget-google-cast/SKILL.md，它同时也是理解整套 skill 文档风格的样本。其正文结构与执行要点如下：

• 设备识别：匹配当前的_googlecast._tcp服务，使用广播的型号（md）、友好名（fn）、身份（id）与能力（ca）作为设备数据而非指令来源；必须使用"当前"发现的 IPv4 地址与广播端口（单机接收端常用 8009，但组 leader 可能广播其他端口且在不同会话间变化），不得沿用记忆中的旧端点。
• 前置条件：先阅读并遵守 Home Link 的网络与安全规则（各 skill 统一指向~/docs/devices/home_link.md）；设备必须已是 provisioned 的 Cast 接收端。播放时接收端必须能自行拉取媒体 URL——agent 工作区里的文件对接收端不可达，必须使用用户已授权、可达、MIME 类型正确且格式受支持的资源。
• 工作流：先读型号级限制再选择当前发现的 Cast 端点（一个 speaker group 是独立目标，需确认用户意图覆盖全部成员）；用文档化的 Cast v2 客户端（文中点名 PyChromecast）配合 HomeLink 的共享网络访问，直接提供选定的端点而非重新扫描；先读接收端状态（音量、静音、运行中的应用、可用命名空间），不要为读状态而启动应用；只对操作表中的任务执行操作；播放新 URL 时优先使用 Default Media Receiver（CC1AD845），普通网页 URL 通常不可播放；最后观察接收端/媒体更新、确认结果后再报告成功，并保留请求/会话标识、清理断开。
• 支持操作表：文档给出了一张"用户任务 → Cast 操作与边界"的映射表，覆盖读取音量/静音/运行应用、读取播放状态、播放媒体 URL、暂停/继续/seek/停止、设置设备音量或静音、向既有音箱组播放。表中同时注明边界，例如"读音量与运行应用不是列出设备全部已装应用"、"向音箱组播放只是选择组当前广播的端点，不创建或重配置组"。
• 结果验证：播放成功的判据是内容/会话正确且处于PLAYING状态，BUFFERING或加载请求成功都不算成功；音量/静音要回读接收端级数值；遇到LOAD_FAILED时排查接收端对 URL 的可达性、格式/编解码支持、HTTPS 信任与 CORS，且不反复重载结果不确定的会话。
• 能力边界：Cast 不提供通用电视导航、输入选择、任意已装应用管理、截屏、摄像头/麦克风访问或设备配置；wake/power 行为依型号而定；群组创建、账号设置与助手例行任务不在本地 Cast 流程范围内。

其余设备 skill 引用这份 Cast 流程时，各自型号的"纯音频""无摄像头访问"等限制（如目录中对 Google Home、Nest Hub Max、Pixel Tablet 的描述）叠加在共享流程之上，这正是"共享协议 + 型号限制"两层结构的运作方式。

单个 SKILL.md 的统一文件结构

从 gadget-tplink-kasa-ep25、gadget-roborock-vacuums、gadget-zigbee2mqtt-gateways、gadget-esphome-devices、gadget-philips-hue-bridges、gadget-unifi-network-consoles 等条目看，每个 SKILL.md 遵循一致的五段式正文（frontmatter 之外的部分）：

1. 开头一段：声明该 skill 的触发条件（"Use this skill when …"），通常绑定"fresh discovery identifies …"，即必须以当前发现结果为准；
2. Identify the Device：如何确认设备身份与协议族，普遍包含否定式断言（仅凭厂商名/端口/广播标签不能确认协议支持）；
3. Prerequisites：统一要求先读~/docs/devices/home_link.md的 Home Link 网络与安全规则，再列出凭据、固件状态等前置条件；
4. Workflow / Verify the Result：编号工作流 + 结果验证判据，强调"确认回执不代表动作完成"、"不确定时先读状态再重试"；
5. Limits / Sources：明确列出该 skill 不做的事（无云端回退、无重置/重配对/固件更新等）以及来源链接。

frontmatter 的description字段承担双重职责：既供目录与检索使用，也在语义上界定"用什么协议、不用什么协议"，例如 EP25 条目写"Use the confirmed SMART local protocol and approved credentials, not EP10 legacy XOR"，ESPHome 条目写"prefer the ratgdo skill for ratgdo garage controllers"——后者同时展示了 skill 之间的互相引用（gadget-esphome-devices/SKILL.md 正文中也以相对链接指向更专门的 ratgdo skill）。

贯穿全部条目的安全与边界原则

把 43 个条目放在一起看，skills/CATALOG.md隐含了一组跨 skill 的约束，这也是评估某个设备能否接入、以及 muse 执行操作时的默认行为边界：

• 本地优先、拒绝云端回退：凭据均为本地认证凭据（本地密钥、本地应用 key、已存储的凭据哈希），多个 skill 明文禁止 cloud bootstrap/fallback（如 Roborock、Kasa EP25 条目）；
• 只操作已安装、已配置、已暴露的东西：网关类条目反复使用 existing/installed/configured/commissioned 限定词，不代为部署、刷机或组网；
• 能力以设备自报为准：写操作前必须读取当前状态与能力字段（Zigbee2MQTT 的exposes与access位掩码、Hue 灯光的能力字段、Cast 接收端的应用命名空间），只发送设备实际支持的字段；
• 物理动作需授权且可验证：涉及机器人移动、打印、车库门等物理动作的条目要求事先许可，并规定"回执不等于完成，状态回读才是确认"；
• 只读条目的只读边界：如 UniFi 控制台 skill 禁止任何重启、准入、封禁或配置变更。

这些原则保证了目录中任何一个 skill 都能被独立粘贴进 muse 对话后，行为范围与 skills/README.md 的"community-sourced, not official integrations"定位相匹配。

为新设备贡献一个 skill

skills/README.md 欢迎贡献者为"已在 Home Link 下验证可用"的设备提交 PR，提交规范如下：

• 目录与文件：gadget-<device-name>/SKILL.md；
• 内容要求：YAML frontmatter 中name与目录名一致，附description；正文包含 instructions（操作步骤）、limits（能力边界）与 source links（来源链接）;
• 格式要求：Keep skills Markdown-only，纯 Markdown，不引入其他格式；
• 提交后需要使新条目出现在 skills/CATALOG.md 的对应分组中——目录按"灯与插座 / 音箱显示电视 / 打印机家电 / 扫地机 / 网关与固件族 / 只读网络与摄像头"六组组织，共享协议单独成节，新 skill 应归入语义最贴近的一组；若依赖共享协议（如 Cast），条目描述与 SKILL.md 正文都应显式引用它。

贡献前建议通读同组既有条目（例如新增一款插座 skill 时可对照 gadget-tplink-kasa-ep10/SKILL.md 与 gadget-tplink-kasa-ep25/SKILL.md），确保协议族识别、前置凭据、工作流、验证判据与 Limits 五段齐全，并保持"同品牌不同协议必须拆分条目"的粒度惯例。

小结

skills/CATALOG.md 是 muse-gadget-sdk 社区设备技能的唯一索引入口：43 个条目 = 42 个设备/固件族 skill + 1 个共享 Google Cast skill，覆盖灯与插座、音箱显示电视、打印机家电、扫地机、网关固件族、只读网络与摄像头六大分组。它的价值不在于提供代码，而在于为每个设备定义了"如何用本地协议识别、操作、验证与设限"的可执行文档，配合 skills/README.md 的两种交付方式（仓库链接或手工粘贴 SKILL.md）与统一的gadget-<device-name>/SKILL.md贡献规范，构成了一个可扩展的设备接入文档体系。