Suffuse

¿Qué hace Suffuse?

Usa este Skill junto con el servidor MCP local como las dos partes del control de iluminación Govee orientadas al agente. El Skill proporciona el flujo de trabajo y el juicio; MCP proporciona las herramientas tipadas y las compuertas de ejecución. Inspecciona el dispositivo instalado, traduce la intención en un pequeño LightScore, compílalo de forma determinista contra las capacidades anunciadas, previsualiza las operaciones resultantes y realiza escrituras solo cuando el usuario solicitó explícitamente un cambio en el dispositivo. La CLI es infraestructura compartida debajo de ambas superficies; la creación de paletas perceptuales es opcional.

El proveedor de ejecución actual es la Plataforma para Desarrolladores documentada de Govee. Las herramientas MCP específicas del proveedor conservan los nombres govee_ hasta que se implemente otro proveedor. Este es un proyecto comunitario no oficial y no está afiliado ni respaldado por Govee.

Sigue el flujo de trabajo de control

1. Determina si la solicitud es creación de paletas, inspección de solo lectura, una previsualización compilada o una escritura en el dispositivo.
2. Usa govee_inspect_household cuando el inventario de transporte o la identidad entre fuentes sea importante, luego inspecciona el dispositivo exacto instalado antes de prometer segmentos, escenas o restauración. Las referencias de instantáneas del hogar son de solo lectura y efímeras.
3. Lee references/color-theory.md, references/palettes.md y references/light-score.md al crear o revisar una paleta o puntuación.
4. Compila la puntuación contra el documento de capacidades devuelto. Nunca infieras la compatibilidad de capacidades a partir de un SKU o página de producto.
5. Muestra una ejecución en seco censurada a menos que el usuario ya haya dado un imperativo directo para cambiar las luces.
6. Para una escritura, usa --confirm-write y guarda el recibo en una ruta privada. Las escrituras de segmentos también requieren --confirm-segments hasta que se haya establecido independencia visible.
7. Inspecciona la evidencia del recibo al informar los resultados. Mantén separados la aceptación del protocolo, el estado de la consulta, la observación visual y la incertidumbre residual.
8. Restaura desde el recibo cuando se solicite. Explica cuando la API no pudo capturar el estado segmentado anterior exactamente; el intento de restauración se persiste de nuevo en el recibo.

Lee references/govee-platform.md para conocer los endpoints, formas de capacidad, límites de velocidad y el límite entre API pública y privada. Lee references/ecosystem.md al decidir si la API cloud documentada, LAN, MQTT, BLE o una implementación MCP existente debe poseer la ejecución. Lee references/device-evidence.md antes de interpretar una respuesta exitosa de la API como prueba visual. Lee references/safety.md antes de cambiar dispositivos, manejar identificadores o reclamar restauración. Lee references/lan-razer.md antes de hacer cualquier afirmación sobre el canal LAN por LED — no está documentado por Govee, y esa página es la cadena de procedencia de cada afirmación en la que Suffuse se basa.

Lee references/evidence-transactions.md antes de interpretar o extender la evidencia del recibo a través de transportes. Lee references/device-registry.md antes de usar observaciones del hogar para selección de transporte, persistencia o diseño de grupos.

Usa la CLI determinista

Requiere Node.js 20 o superior. GOVEE_API_KEY desbloquea el descubrimiento de los dispositivos compatibles de la cuenta, sus capacidades frescas y estado consultable, sus escenas nativas y DIY, y solicitudes de control autenticadas. La clave no autoriza una escritura de Suffuse por sí sola. La CLI la lee solo del entorno del proceso y nunca la acepta como argumento de línea de comandos.

Lista las paletas personalizadas incluidas sin credenciales:

node scripts/govee.mjs palettes

Inspecciona capacidades en vivo sin cambiar un dispositivo:

node scripts/govee.mjs inspect --sku H608B

Inspecciona un dispositivo mientras las credenciales no están disponibles:

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

Compila una puntuación contra capacidades capturadas o de fixture:

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

Previsualiza contra capacidades en vivo. Esto sigue siendo de solo lectura porque --confirm-write está ausente:

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

Para looks de escena, la aplicación en vivo resuelve los nombres lightScene y diyScene a través de los catálogos de escenas dedicados de Govee antes de compilar. No sustituyas un identificador inventado cuando falte un nombre.

Aplica después de una solicitud explícita del usuario y conserva un recibo de evidencia/restauración:

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

Para una escritura segmentada experimental, agrega --confirm-segments solo después de explicar que la compatibilidad anunciada no es prueba visible.

Restaura el estado anterior consultable:

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

Crea gradientes honestamente

Para el resultado espacial preferido, crea directamente de 3 a 5 bandas ordenadas, nombra una entrada de catálogo de paletas validadas o compila una receta OKLCH restringida. Las recetas hacen que la interpolación, el recorrido de tono y el diagnóstico sean reproducibles; las bandas hex explícitas siguen siendo de primera clase y nunca se regeneran silenciosamente. Compila cualquiera de las formas solo cuando el dispositivo seleccionado anuncie devices.capabilities.segment_color_setting / segmentedColorRgb y proporcione un dominio de segmentos explícito. Si el dispositivo también anuncia devices.capabilities.toggle / gradientToggle, actívalo antes de enviar los colores de los segmentos. Si la capacidad o el dominio están ausentes, usa solo los valores de respaldo declarados por la puntuación.

Trata la aceptación de la API y la representación visible como evidencia separada. Una respuesta 200 prueba solo que Govee aceptó la solicitud. No prueba que pucks o bombillas individuales hayan mostrado colores distintos. Registra el contexto del firmware y el resultado visible antes de llamar a un dispositivo verificado por segmentos.

No describas un respaldo de color sólido como un gradiente. No describas la reproducción de escenas como control arbitrario por luz. La API pública puede activar escenas DIY anunciadas pero no documenta la creación o carga de nuevos efectos DIY. Registra el modo de ejecución seleccionado en el resultado.

Usa el paquete gestionado

La raíz del repositorio es la única fuente de verdad. scripts/manage.mjs previsualiza, instala, audita y elimina de forma conservadora los enlaces de descubrimiento local para Codex, Claude Code y Hermes. Lee references/distribution.md antes de instalarlo o empaquetarlo.

Usa mcp/server.mjs cuando el agente deba llamar a herramientas tipadas en lugar de comandos de shell. Es de solo lectura de forma predeterminada, hereda las credenciales del entorno y tiene doble compuerta para escrituras físicas. Lee references/mcp.md antes de conectarlo a un agente.

Separa la creación de la representación en tiempo real

Usa el agente para interpretar texto o imágenes y crear un LightScore. Usa un runtime local dedicado para el control de alta velocidad reactivo a audio o pantalla. El límite oficial de dispositivos cloud no es adecuado para streaming de fotogramas; este Skill puede configurar, iniciar, detener o diagnosticar dicho runtime, pero no debe convertir solicitudes cloud en un bucle de representación pseudo.

No extraigas datos de la aplicación Govee Home, reproduzcas autenticación privada ni reclames acceso a la generación de CogniGlow o AI Lighting Bot. Usa esos productos solo como precedentes de interacción a menos que Govee publique un endpoint compatible.

Pinta por LED a través de la LAN

Los comandos lan alcanzan dispositivos en la red local sin clave de API, incluida la pintura por LED en dispositivos con un perfil de píxeles verificado. El flujo de trabajo anterior sigue siendo aplicable; estas reglas son adicionales y cada una codifica una lección medida en hardware:

1. Escanea primero (lan scan) — es de solo lectura e informa qué dispositivos descubiertos son compatibles con por LED y si su recuento de píxeles está verificado por hardware. El descubrimiento multicast es intermitente por dispositivo, por lo que nunca concluyas "sin soporte LAN" a partir de un escaneo corto o parcial.
2. Crea la intención por LED como un LightScore de gradiente ordinario. Las bandas se compilan a píxeles en el orden de creación; no hay una matriz arbitraria por píxel a propósito, porque los dispositivos con menos zonas interpolan entre los puntos de parada dando la vuelta larga a la rueda de tono, y el orden de las bandas es lo que mantiene los píxeles adyacentes adyacentes en tono.
3. Nunca afirmes que una escritura por LED se haya renderizado. El canal es mudo — sin acuse de recibo, sin estado de segmento consultable. Los resultados llevan verified: false; solo los ojos (o el usuario) pueden confirmar, y el Skill debe decirlo.
4. Haz explícita la duración. Un look por LED vuelve a los efectos propios del dispositivo aproximadamente un minuto después de que los datos se detienen. Usa --hold-seconds para una retención limitada (predeterminado 900, máximo 14400) e informa al usuario cuándo terminará el look; usa lan release para finalizarlo antes.
5. Nunca mezcles escritores. Mientras una retención esté activa, las escrituras de color de todo el dispositivo en ese dispositivo son rechazadas — un comando de todo el dispositivo repinta cada píxel y aplana el look por LED. Para cambiar un dispositivo retenido a un color sólido a propósito, pasa --hand-over (MCP handOver: true): Suffuse detiene el keepalive y sale del modo por LED, luego escribe. Un nuevo gradiente toma el control de una retención existente de la misma manera. No hagas restore entre dos looks — eso parpadea el color anterior solo para pintar sobre él; restaura cuando el usuario quiera el estado anterior.
6. La restauración es solo para todo el dispositivo. devStatus se captura antes de la escritura y se reproduce mediante restore; un look por LED anterior no es consultable en ningún canal, y el recibo debe decirlo en lugar de reclamar de más.
7. Si el puerto de respuesta (UDP 4002) está ocupado por otro controlador local, el escaneo y la captura de estado fallan ruidosamente. No lo evites con uso compartido de puertos — dos oyentes roban silenciosamente las respuestas del otro. Indica al usuario qué proceso cerrar, o fija el dispositivo con --ip.
8. Para un SKU desconocido, consulta primero la cartera minada (node scripts/portfolio.mjs <SKU>) — 371 SKUs de antecedentes comunitarios con procedencia por hecho. Léelo bajo una regla: un positivo minado es confiable, un negativo minado es solo "desconocido" — las banderas del proveedor describen la compatibilidad de la aplicación, no lo que el firmware acepta. Nunca le digas al usuario que su dispositivo "no es compatible" con por LED basándote en una bandera minada o en la ausencia de la cartera.

Alcanza hardware solo BLE a través de Bluetooth

Los comandos ble alcanzan lámparas que la LAN estructuralmente no puede (la clase H6009: listada en la nube, sin Control LAN) — sin clave y sin Wi-Fi. El flujo de trabajo anterior sigue siendo aplicable; estas reglas son adicionales:

1. Escanea primero (ble scan) — de solo lectura. Una lámpara retenida por otro central (la aplicación Govee Home del usuario, otro controlador) deja de anunciarse y no aparecerá; la ausencia no es ausencia. Dilo en lugar de concluir que la lámpara se ha ido.
2. Solo una vez. Conecta, escribe, drena, desconecta — nunca mantengas una sesión BLE abierta: un central conectado bloquea al usuario fuera de su propia aplicación. Si el usuario desea un look persistente, BLE es el cable incorrecto; dilo.
3. No hay lectura de vuelta. El color y brillo anteriores no se pueden capturar, por lo que el recibo registra un punto de restauración de blanco cálido declarado y restore devuelve la lámpara allí — a un neutro declarado, no a su look anterior. Informa al usuario antes de escribir.
4. Las escrituras no se acusan recibo (verified: false). Informa lo que se envió; solo los ojos confirman.
5. El código de operación de color es por clase de dispositivo (verificado en el RGBWW H6009; la codificación RGB solo ampliamente documentada se acepta y es inerte allí). Una lámpara que se enciende y atenúa pero ignora el color es la firma de un código de operación incorrecto — presenta un informe de compatibilidad en lugar de intentarlo más fuerte.
6. La dependencia es opcional. Si falta @stoprocent/noble o el host carece del permiso de Bluetooth (macOS mata los procesos no firmados que tocan CoreBluetooth sin un aviso — el proceso responsable, normalmente la aplicación de terminal, debe tener el permiso), transmite la remediación estructurada del error; cada otra superficie de Suffuse sigue funcionando.

Maneja credenciales no disponibles

Si GOVEE_API_KEY está ausente, continúa con la creación de puntuaciones, fixtures, pruebas de compilación y documentación. Indica que la verificación de capacidades del dispositivo en vivo y las escrituras quedan pendientes. Nunca le pidas al usuario que pegue una clave en el chat.

Devuelve un recibo de evidencia

Informa:

• SKU seleccionado e identidad del dispositivo censurada;
• capacidad anunciada utilizada;
• modo solicitado y ejecutado;
• valores de respaldo y advertencias;
• número y resultado de las operaciones de control;
• ruta del recibo, cuando se escribió;
• cobertura de restauración y cualquier estado que no se pudo capturar.
• la declaración resumen de evidencia y la incertidumbre residual; nunca traduzcas accepted o sent-unacknowledged como éxito visible.