andyed/suffuse

O que suffuse faz?

Use este Skill com o servidor MCP local como as duas partes voltadas ao agente do controle de iluminação Govee. O Skill fornece o fluxo de trabalho e o julgamento; o MCP fornece as ferramentas tipadas e as portas de tempo de execução. Inspecione o dispositivo instalado, traduza a intenção em um LightScore pequeno, compile-o deterministicamente contra as capacidades anunciadas, pré-visualize as operações resultantes e realize gravações apenas quando o usuário solicitar explicitamente uma alteração no dispositivo. O CLI é uma infraestrutura compartilhada abaixo de ambas as superfícies; a criação de paletas perceptuais é opcional.

O provedor de execução atual é a Plataforma de Desenvolvedor documentada da Govee. Ferramentas MCP específicas do provedor mantêm nomes govee_ até que outro provedor seja implementado. Este é um projeto comunitário não oficial e não é afiliado ou endossado pela Govee.

Siga o fluxo de trabalho de controle

1. Estabeleça se a solicitação é criação de paleta, inspeção somente leitura, uma pré-visualização compilada ou uma gravação de dispositivo.
2. Use govee_inspect_household quando o inventário de transporte ou a identidade entre fontes importar, então inspecione o dispositivo exato instalado antes de prometer segmentos, cenas ou restauração. As referências de snapshot doméstico são somente leitura e efêmeras.
3. Leia references/color-theory.md, references/palettes.md e references/light-score.md ao criar ou revisar uma paleta ou score.
4. Compile o score contra o documento de capacidade retornado. Nunca infira suporte de capacidade a partir de um SKU ou página de produto.
5. Mostre uma simulação a seco (dry run) editada, a menos que o usuário já tenha dado um imperativo direto para alterar as luzes.
6. Para uma gravação, use --confirm-write e salve o recibo em um caminho privado. Gravações de segmento também exigem --confirm-segments até que a independência visível tenha sido estabelecida.
7. Inspecione a evidência do recibo ao relatar resultados. Mantenha separados a aceitação do protocolo, o estado da consulta, a observação visual e a incerteza residual.
8. Restaure a partir do recibo quando solicitado. Explique quando a API não pôde capturar exatamente o estado segmentado anterior; a tentativa de restauração é persistida de volta no recibo.

Leia references/govee-platform.md para endpoints, formas de capacidade, limites de taxa e o limite da API pública/privada. Leia references/ecosystem.md ao decidir se a API de nuvem documentada, LAN, MQTT, BLE ou uma implementação MCP existente deve ser a responsável pela execução. Leia references/device-evidence.md antes de interpretar uma resposta de API bem-sucedida como prova visual. Leia references/safety.md antes de alterar dispositivos, manipular identificadores ou reivindicar restauração. Leia references/lan-razer.md antes de fazer qualquer afirmação sobre o canal LAN por LED — ele não é documentado pela Govee, e essa página é a cadeia de proveniência para cada afirmação da qual o Suffuse depende. Leia references/evidence-transactions.md antes de interpretar ou estender evidências de recibos entre transportes. Leia references/device-registry.md antes de usar observações domésticas para seleção de transporte, persistência ou design de grupo.

Use o CLI determinístico

Requer Node.js 20 ou superior. GOVEE_API_KEY desbloqueia a descoberta dos dispositivos suportados da conta, suas capacidades novas e estado consultável, suas cenas nativas e DIY e solicitações de controle autenticadas. A chave não autoriza uma gravação do Suffuse por si só. O CLI a lê apenas do ambiente do processo e nunca a aceita como argumento de linha de comando.

Liste paletas personalizadas incluídas sem credenciais:

node scripts/govee.mjs palettes

Inspecione capacidades ao vivo sem alterar um dispositivo:

node scripts/govee.mjs inspect --sku H608B

Inspecione um dispositivo enquanto credenciais não estão disponíveis:

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

Compile um score contra capacidades capturadas ou de fixture:

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

Pré-visualize contra capacidades ao vivo. Isso permanece somente leitura porque --confirm-write está ausente:

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

Para looks de cena, a aplicação ao vivo resolve os nomes lightScene e diyScene através dos catálogos de cena dedicados da Govee antes de compilar. Não substitua um identificador inventado quando um nome estiver ausente.

Aplique após uma solicitação explícita do usuário e retenha um recibo de evidência/restauração:

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

Para uma gravação experimental de segmento, adicione --confirm-segments apenas depois de explicar que o suporte anunciado não é prova visível.

Restaure o estado anterior consultável:

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

Crie gradientes honestamente

Para o resultado espacial preferido, crie diretamente 3 a 5 faixas ordenadas, nomeie uma entrada de catálogo de paleta validada ou compile uma receita OKLCH restrita. Receitas tornam interpolação, viagem de matiz e diagnósticos reproduzíveis; faixas hexadecimais explícitas permanecem de primeira classe e nunca são regeneradas silenciosamente. Compile qualquer uma das formas apenas quando o dispositivo selecionado anunciar devices.capabilities.segment_color_setting / segmentedColorRgb e fornecer um domínio de segmento explícito. Se o dispositivo também anunciar devices.capabilities.toggle / gradientToggle, ative-o antes de enviar cores de segmento. Se a capacidade ou domínio estiver ausente, use apenas os fallbacks declarados pelo score.

Trate a aceitação da API e a renderização visível como evidências separadas. Uma resposta 200 prova apenas que a Govee aceitou a solicitação. Não prova que pucks ou lâmpadas individuais renderizaram cores distintas. Registre o contexto do firmware e o resultado visível antes de chamar um dispositivo de segmento-verificado.

Não descreva um fallback de cor sólida como um gradiente. Não descreva a reprodução de cena como controle arbitrário por luz. A API pública pode acionar cenas DIY anunciadas, mas não documenta a criação ou upload de novos efeitos DIY. Registre o modo de execução selecionado no resultado.

Use o pacote gerenciado

A raiz do repositório é a fonte única da verdade. scripts/manage.mjs pré-visualiza, instala, audita e remove conservadoramente links de descoberta local para Codex, Claude Code e Hermes. Leia references/distribution.md antes de instalar ou empacotá-lo.

Use mcp/server.mjs quando o agente deve chamar ferramentas tipadas em vez de comandos shell. Ele é predominantemente somente leitura por padrão, herda credenciais do ambiente e protege duas vezes as gravações físicas. Leia references/mcp.md antes de conectá-lo a um agente.

Separe a criação da renderização em tempo real

Use o agente para interpretar texto ou imagens e criar um LightScore. Use um runtime local dedicado para controle de alta taxa, responsivo a áudio ou tela. O limite oficial do dispositivo em nuvem é inadequado para streaming de taxa de quadros; este Skill pode configurar, iniciar, parar ou diagnosticar tal runtime, mas não deve transformar solicitações de nuvem em um pseudo-loop de renderização.

Não colete dados do aplicativo Govee Home, reproduza autenticação privada ou reivindique acesso à geração CogniGlow ou AI Lighting Bot. Use esses produtos apenas como precedentes de interação, a menos que a Govee publique um endpoint suportado.

Pinte por LED através da LAN

Os comandos lan alcançam dispositivos na rede local sem uma chave de API, incluindo pintura por LED em luminárias com um perfil de pixel verificado. O fluxo de trabalho acima ainda se aplica; estas regras são adicionais, e cada uma codifica uma lição medida em hardware:

1. Escaneie primeiro (lan scan) — é somente leitura e relata quais luminárias descobertas suportam por LED e se a contagem de pixels é verificada por hardware. A descoberta multicast é intermitente por dispositivo, então nunca conclua "sem suporte LAN" a partir de uma varredura curta ou parcial.
2. Crie a intenção por LED como um LightScore de gradiente comum. As faixas compilam para pixels na ordem criada; não há um array de pixel arbitrário por LED de propósito, porque luminárias com menos zonas interpolam entre os pontos de parada pelo caminho mais longo ao redor da roda de matiz, e a ordem das faixas é o que mantém pixels adjacentes adjacentes em matiz.
3. Nunca reivindique que uma gravação por LED foi renderizada. O canal é mudo — sem confirmação, sem estado de segmento consultável. Os resultados carregam verified: false; apenas olhos (ou o usuário) podem confirmar, e o Skill deve dizer isso.
4. Torne a duração explícita. Um look por LED reverte para os próprios efeitos do dispositivo aproximadamente um minuto após os dados pararem. Use --hold-seconds para uma retenção limitada (padrão 900, máximo 14400) e informe ao usuário quando o look terminará; use lan release para encerrá-lo antes.
5. Nunca misture escritores. Enquanto uma retenção estiver ativa, gravações de cor de dispositivo inteiro para essa luminária são recusadas — um comando de dispositivo inteiro repinta cada pixel e achata o look por LED. Para mudar intencionalmente uma luminária retida para uma cor sólida, passe --hand-over (MCP handOver: true): Suffuse interrompe o keepalive e sai do modo por LED, depois grava. Um novo gradiente assume uma retenção existente da mesma forma. Não faça restore entre dois looks — isso pisca a cor antiga apenas para pintá-la por cima; restaure quando o usuário quiser o estado anterior de volta.
6. Restauração é apenas para dispositivo inteiro. devStatus é capturado antes da gravação e reproduzido por restore; um look anterior por LED não é consultável em nenhum canal, e o recibo deve dizer isso em vez de reivindicar demais.
7. Se a porta de resposta (UDP 4002) estiver ocupada por outro controlador local, a varredura e a captura de estado falham ruidosamente. Não contorne com compartilhamento de porta — dois ouvintes roubam silenciosamente as respostas um do outro. Informe ao usuário qual processo encerrar, ou fixe o dispositivo com --ip.
8. Para um SKU desconhecido, consulte primeiro o portfólio minerado (node scripts/portfolio.mjs <SKU>) — 371 SKUs de conhecimento prévio da comunidade com proveniência por fato. Leia-o sob uma regra: um positivo minerado é confiável, um negativo minerado é apenas "desconhecido" — flags do fornecedor descrevem suporte do aplicativo, não o que o firmware aceita. Nunca informe ao usuário que seu dispositivo "não suporta" por LED com base em uma flag minerada ou ausência do portfólio.

Alcance hardware apenas BLE via Bluetooth

Os comandos ble alcançam lâmpadas que a LAN estruturalmente não consegue (a classe H6009: listadas em nuvem, sem Controle LAN) — sem chave e sem Wi-Fi. O fluxo de trabalho acima ainda se aplica; estas regras são adicionais:

1. Escaneie primeiro (ble scan) — somente leitura. Uma lâmpada mantida por outro central (o aplicativo Govee Home do usuário, outro controlador) para de anunciar e não aparecerá; ausência não é ausência. Diga isso em vez de concluir que a lâmpada se foi.
2. Apenas uma vez. Conecte, escreva, drene, desconecte — nunca mantenha uma sessão BLE aberta: um central conectado bloqueia o usuário de seu próprio aplicativo. Se o usuário quiser um look persistente, BLE é o fio errado; diga isso.
3. Não há leitura de volta. A cor e o brilho anteriores não podem ser capturados, então o recibo registra um ponto de restauração declarado de branco quente e restore retorna a lâmpada para lá — para um neutro declarado, não para seu look anterior. Informe o usuário disso antes de escrever.
4. Gravações são não confirmadas (verified: false). Relate o que foi enviado; apenas olhos confirmam.
5. O opcode de cor é por classe de dispositivo (verificado no RGBWW H6009; a codificação RGB-only amplamente documentada é aceita e inerte lá). Uma lâmpada que liga e escurece, mas ignora a cor, é a assinatura de um opcode errado — registre um relatório de compatibilidade em vez de tentar com mais força.
6. A dependência é opcional. Se @stoprocent/noble estiver ausente ou o host não tiver permissão Bluetooth (macOS mata processos não assinados que tocam CoreBluetooth sem um prompt — o processo responsável, geralmente o aplicativo terminal, deve ter a permissão), repasse a correção estruturada do erro; toda outra superfície do Suffuse ainda funciona.

Lide com credenciais indisponíveis

Se GOVEE_API_KEY estiver ausente, continue com criação de scores, fixtures, testes de compilação e documentação. Informe que a verificação de capacidade do dispositivo ao vivo e as gravações permanecem pendentes. Nunca peça ao usuário para colar uma chave no chat.

Retorne um recibo de evidência

Relate:

• SKU selecionado e identidade do dispositivo editada;
• capacidade anunciada usada;
• modo solicitado e executado;
• fallbacks e avisos;
• número e resultado das operações de controle;
• caminho do recibo, quando escrito;
• cobertura de restauração e qualquer estado que não pôde ser capturado.
• a declaração de resumo de evidência e incerteza residual; nunca traduza accepted ou sent-unacknowledged como sucesso visível.