andyed/suffuse

suffuse 是做什么的？

将此 Skill 与本地 MCP 服务器一起使用，作为 Govee 照明控制的两个面向 Agent 的组件。Skill 提供工作流程和判断；MCP 提供类型化工具和运行时门控。检查已安装的设备，将意图转化为一个小型 LightScore，根据公布的设备能力进行确定性编译，预览产生的操作，并且仅当用户明确请求设备更改时才执行写入操作。CLI 是两个界面的共享基础设施；感知调色板编写是可选的。

当前的执行提供者是 Govee 官方文档化的开发者平台。特定于提供者的 MCP 工具保留 govee_ 名称，直到实现其他提供者。这是一个非官方的社区项目，与 Govee 无任何关联或背书。

遵循控制工作流程

1. 确定请求是调色板编写、只读检查、已编译的预览还是设备写入。
2. 当传输清单或跨源身份标识很重要时，使用 govee_inspect_household，然后在承诺分段、场景或恢复之前，检查确切的已安装设备。家庭快照引用是只读且临时的。
3. 在编写或修改调色板或 LightScore 时，阅读 references/color-theory.md、references/palettes.md 和 references/light-score.md。
4. 根据返回的能力文档编译分数。永远不要根据 SKU 或产品页面推断能力支持。
5. 除非用户已经直接命令更改灯光，否则显示一个经过编辑的试运行。
6. 对于写入，使用 --confirm-write 并将收据保存到私有路径。分段写入还需要 --confirm-segments，直到可见独立性得到确认。
7. 报告结果时检查收据证据。保持协议接受状态、查询状态、视觉观察和剩余不确定性之间的分离。
8. 根据请求从收据中恢复。解释 API 何时无法精确捕获先前的分段状态；恢复尝试将持久化回收据。

阅读 references/govee-platform.md 了解端点、能力形态、速率限制以及公共/私有 API 边界。在决定是否应使用已记录的云 API、LAN、MQTT、BLE 或现有 MCP 实现来执行操作时，阅读 references/ecosystem.md。在将成功的 API 响应解释为可视证据之前，阅读 references/device-evidence.md。在更改设备、处理标识符或声称恢复能力之前，阅读 references/safety.md。在对每 LED LAN 通道做出任何声明之前，阅读 references/lan-razer.md——该通道未被 Govee 文档化，并且该页面是 Suffuse 依赖的每个声明的出处链。 在解释或跨传输扩展收据证据之前，阅读 references/evidence-transactions.md。 在使用家庭观察结果进行传输选择、持久化或组设计之前，阅读 references/device-registry.md。

使用确定性 CLI

需要 Node.js 20 或更高版本。GOVEE_API_KEY 可以解锁发现账户支持的设备、它们最新的能力和可查询状态、它们的原生和 DIY 场景以及经过身份验证的控制请求。该密钥本身并不授权 Suffuse 进行写入操作。CLI 仅从进程环境中读取该变量，并且从不接受它作为命令行参数。

无需凭据即可列出捆绑的自定义调色板：

node scripts/govee.mjs palettes

无需更改设备即可检查实时能力：

node scripts/govee.mjs inspect --sku H608B

在凭据不可用时检查灯具：

node scripts/govee.mjs inspect \
  --fixture tests/fixtures/segmented-device.json --sku H0001

针对捕获的能力或灯具固定装置编译分数：

node scripts/govee.mjs compile \
  --score tests/fixtures/dusk-gradient.score.json \
  --capabilities tests/fixtures/segmented-device.json

针对实时能力进行预览。这仍然是只读的，因为缺少 --confirm-write：

node scripts/govee.mjs apply --score /private/path/look.score.json

对于场景外观，实时应用在编译之前，会通过 Govee 的专用场景目录解析 lightScene 和 diyScene 名称。当名称缺失时，不要使用发明的标识符进行替换。

在用户明确请求后应用，并保留证据/恢复收据：

node scripts/govee.mjs apply \
  --score /private/path/look.score.json \
  --confirm-write \
  --receipt /private/path/look.receipt.json

对于实验性的分段写入，仅在解释广告支持并非可见证据后，添加 --confirm-segments。

恢复可查询的先验状态：

node scripts/govee.mjs restore \
  --receipt /private/path/look.receipt.json \
  --confirm-write

诚实地编写渐变

为了获得最佳的空间效果，直接编写 3-5 个有序的色带、引用已验证的调色板目录条目、或编译一个受约束的 OKLCH 配方。配方使插值、色调偏移和诊断可重现；显式的十六进制色带是一等公民，并且永远不会被静默重新生成。仅当所选设备公布 devices.capabilities.segment_color_setting / segmentedColorRgb 并提供显式的分段域时，才编译任一形式。如果设备还公布 devices.capabilities.toggle / gradientToggle，则在发送分段颜色之前启用它。如果能力或域缺失，则仅使用分数声明的后备方案。

将 API 接受和可见渲染视为独立的证据。200 响应仅证明 Govee 接受了请求。它不能证明各个像素点或灯泡呈现了不同的颜色。在将设备称为分段已验证之前，记录固件上下文和可见结果。

不要将纯色后备描述为渐变。不要将场景重放描述为任意的每灯控制。公共 API 可以触发广告中的 DIY 场景，但并未记录 DIY 效果的创建或上传。在结果中记录所选的执行模式。

使用受管理的包

仓库根目录是单一事实来源。scripts/manage.mjs 预览、安装、审计并保守地移除 Codex、Claude Code 和 Hermes 的本地发现链接。在安装或打包之前，阅读 references/distribution.md。

当 Agent 应该调用类型化工具而不是 shell 命令时，使用 mcp/server.mjs。它默认为只读模式，从环境继承凭据，并对物理写入进行双重门控。在将其连接到 Agent 之前，阅读 references/mcp.md。

分离编写与实时渲染

使用 Agent 解释文本或图像并编写 LightScore。使用专用的本地运行时进行高频率的音频响应或屏幕响应控制。官方云设备限制不适合帧率流式传输；此技能可以配置、启动、停止或诊断此类运行时，但不得将云请求转变为伪渲染循环。

不要抓取 Govee Home 应用、重现私有身份验证或声称能够访问 CogniGlow 或 AI Lighting Bot 的生成。除非 Govee 发布受支持的端点，否则仅将这些产品用作交互先例。

通过 LAN 绘制每颗 LED

lan 命令无需 API 密钥即可访问本地网络上的设备，包括在具有已验证像素配置文件的灯具上进行每 LED 绘制。上述工作流程仍然适用；这些规则是附加的，每条都编码了一个硬件测量的教训：

1. 先扫描（lan scan）——它是只读的，并报告哪些已发现的灯具支持每 LED 绘制，以及它们的像素计数是否已经过硬件验证。多播发现因设备而异且不稳定，因此切勿从短时间或不完整的扫描中得出结论“不支持 LAN”。
2. 将每 LED 意图编写为普通的渐变 LightScore。色带按编写顺序编译为像素；故意不设计任意每像素数组，因为具有较少区域的灯具会在色轮上以较长的路径在色带之间插值，而色带顺序是使相邻像素在色调上保持相邻的关键。
3. 永远不要声称每 LED 写入已渲染。该通道是静默的——无确认，无可查询的分段状态。结果带有 verified: false；只有眼睛（或用户）才能确认，技能必须明确说明这一点。
4. 明确时长。每 LED 外观在数据停止后大约一分钟会恢复到设备自身的特效。使用 --hold-seconds 设置一个有限保持时间（默认为 900，最大 14400），并告知用户外观何时结束；使用 lan release 提前结束。
5. 永远不要混用写入者。当保持激活时，对该灯具的整设备颜色写入将被拒绝——整设备命令会重绘每个像素并展平每 LED 外观。如果打算将保持中的灯具更改为纯色，请传递 --hand-over（MCP 中的 handOver: true）：Suffuse 停止保活信号并退出每 LED 模式，然后写入。新的渐变以相同方式接管现有的保持。不要在两个外观之间执行 restore——这会闪烁旧颜色然后覆盖它；当用户希望回到较早状态时，才进行恢复。
6. 恢复仅限整设备。devStatus 在写入前被捕获，并由 restore 重放；先前的每 LED 外观在任何通道上都不可查询，收据必须说明这一点，而不是夸大其词。
7. 如果回复端口（UDP 4002）被另一个本地控制器占用，扫描和状态捕获将失败并发出错误。不要通过端口共享来解决此问题——两个监听器会静默地窃取彼此的回复。告知用户需要退出的进程，或使用 --ip 固定设备。
8. 对于不熟悉的 SKU，首先查阅挖掘出的资产组合（node scripts/portfolio.mjs <SKU>）——包含 371 个 SKU 的社区先验知识，每个事实都有出处。在一个规则下阅读它：挖掘出的正面结果是可信的，挖掘出的负面结果仅是“未知”——供应商标志描述的是应用支持，而不是固件接受的内容。永远不要仅凭挖掘出的标志或资产组合中的缺失，就告诉用户他们的设备“不支持”每 LED 绘制。

通过蓝牙访问仅支持 BLE 的硬件

ble 命令可以访问 LAN 结构上无法访问的灯具（H6009 类：云端列出，无 LAN 控制）——无需密钥且无需 Wi-Fi。上述工作流程仍然适用；这些规则是附加的：

1. 先扫描（ble scan）——只读。被其他中心设备（用户的 Govee Home 应用、另一个控制器）持有的灯具将停止广播并且不会出现；未出现并不等于不存在。要说明这一点，而不是得出结论灯具已消失。
2. 仅限一次性操作。连接、写入、耗尽、断开——切勿保持 BLE 会话打开：一个连接的中心设备会将用户锁定在其自己的应用程序之外。如果用户希望获得持久的照明效果，BLE 是错误的连接方式；要说明这一点。
3. 无回读。无法捕获先前的颜色和亮度，因此收据记录一个声明的暖白恢复点，restore 将灯具恢复到此状态——到一个明确说明的中性色，而不是其先前的照明效果。在写入之前将此告知用户。
4. 写入无确认（verified: false）。报告发送了哪些内容；仅眼睛确认。
5. 颜色操作码是特定于设备类别的（在 RGBWW H6009 上已验证；广泛记录的仅 RGB 编码在那里被接受且是惰性的）。灯具通电调光但忽略颜色，这是错误操作码的标志——提交兼容性报告，而不是更努力地重试。
6. 依赖项是可选的。如果缺少 @stoprocent/noble 或主机缺少蓝牙权限（macOS 会杀死未签名的进程，这些进程在无提示的情况下接触 CoreBluetooth——负责的进程，通常是终端应用程序，必须持有该权限），则传递错误中的结构化修复建议；Suffuse 的所有其他表面仍然正常工作。

处理不可用的凭据

如果缺少 GOVEE_API_KEY，则继续执行分数编写、灯具固定装置、编译测试和文档。声明实时设备能力验证和写入仍处于待处理状态。切勿要求用户将密钥粘贴到聊天中。

返回证据收据

报告：

• 选定的 SKU 和经过编辑的设备身份；
• 使用的广告能力；
• 请求和执行的模式；
• 回退方案和警告；
• 控制操作的数量和结果；
• 收据路径（如果已写入）；
• 恢复覆盖范围以及任何无法捕获的状态。
• 证据摘要陈述和剩余不确定性；切勿将 accepted 或 sent-unacknowledged 翻译成可见的成功。