anded/suffuse

Que fait suffuse ?

Utilisez cette Skill avec le serveur MCP local en tant que deux parties orientées agent du contrôle d'éclairage Govee. La Skill fournit le workflow et le jugement ; MCP fournit les outils typés et les portes d'exécution. Inspectez l'appareil installé, traduisez l'intention en un petit LightScore, compilez-le de manière déterministe par rapport aux capacités annoncées, prévisualisez les opérations résultantes, et effectuez des écritures uniquement lorsque l'utilisateur a explicitement demandé un changement d'appareil. La CLI est une infrastructure partagée sous les deux surfaces ; la création de palettes perceptuelles est facultative.

Le fournisseur d'exécution actuel est la plateforme de développement documentée de Govee. Les outils MCP spécifiques au fournisseur conservent les noms govee_ jusqu'à ce qu'un autre fournisseur soit implémenté. Ceci est un projet communautaire non officiel et n'est ni affilié ni approuvé par Govee.

Suivre le workflow de contrôle

1. Déterminez si la demande concerne la création d'une palette, une inspection en lecture seule, une prévisualisation compilée ou une écriture sur l'appareil.
2. Utilisez govee_inspect_household lorsque le transport d'inventaire ou l'identité multi-source est important, puis inspectez l'appareil exact installé avant de promettre des segments, des scènes ou une restauration. Les références d'instantané du foyer sont en lecture seule et éphémères.
3. Lisez references/color-theory.md, references/palettes.md et references/light-score.md lors de la création ou de la révision d'une palette ou d'un score.
4. Compilez le score par rapport au document de capacités retourné. Ne déduisez jamais la prise en charge d'une capacité à partir d'un SKU ou d'une page produit.
5. Affichez un aperçu à sec expurgé, sauf si l'utilisateur a déjà donné un ordre impératif direct de changer les lumières.
6. Pour une écriture, utilisez --confirm-write et sauvegardez le reçu dans un chemin privé. Les écritures segmentées nécessitent également --confirm-segments jusqu'à ce que l'indépendance visible ait été établie.
7. Inspectez les preuves du reçu lors du rapport des résultats. Séparez l'acceptation du protocole, l'état de la requête, l'observation visuelle et l'incertitude résiduelle.
8. Restaurez à partir du reçu lorsque demandé. Expliquez quand l'API n'a pas pu capturer exactement l'état segmenté antérieur ; la tentative de restauration est persistée dans le reçu.

Lisez references/govee-platform.md pour les points de terminaison, les formes de capacités, les limites de débit et la frontière API publique/privée. Lisez references/ecosystem.md pour décider si l'API cloud documentée, le LAN, MQTT, BLE ou une implémentation MCP existante doit prendre en charge l'exécution. Lisez references/device-evidence.md avant d'interpréter une réponse API réussie comme une preuve visuelle. Lisez references/safety.md avant de modifier des appareils, de manipuler des identifiants ou de revendiquer une restauration. Lisez references/lan-razer.md avant de faire une quelconque affirmation sur le canal LAN par LED — il n'est pas documenté par Govee, et cette page est la chaîne de provenance pour chaque affirmation sur laquelle Suffuse s'appuie. Lisez references/evidence-transactions.md avant d'interpréter ou d'étendre les preuves de reçu entre les transports. Lisez references/device-registry.md avant d'utiliser des observations du foyer pour la sélection du transport, la persistance ou la conception de groupes.

Utiliser la CLI déterministe

Nécessite Node.js 20 ou plus récent. GOVEE_API_KEY permet de découvrir les appareils pris en charge du compte, leurs capacités récentes et leur état interrogeable, leurs scènes natives et DIY, ainsi que les requêtes de contrôle authentifiées. La clé n'autorise pas une écriture Suffuse par elle-même. La CLI la lit uniquement depuis l'environnement du processus et ne l'accepte jamais comme argument de ligne de commande.

Listez les palettes personnalisées fournies sans identifiants :

node scripts/govee.mjs palettes

Inspectez les capacités en direct sans modifier un appareil :

node scripts/govee.mjs inspect --sku H608B

Inspectez un appareil lorsque les identifiants ne sont pas disponibles :

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

Compilez un score par rapport à des capacités capturées ou de fixture :

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

Prévisualisez par rapport aux capacités en direct. Cela reste en lecture seule car --confirm-write est absent :

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

Pour les looks de scène, l'application en direct résout les noms lightScene et diyScene via les catalogues de scènes dédiés de Govee avant la compilation. Ne substituez pas un identifiant inventé lorsqu'un nom est absent.

Appliquez après une demande explicite de l'utilisateur et conservez un reçu de preuve/restauration :

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

Pour une écriture segmentée expérimentale, ajoutez --confirm-segments uniquement après avoir expliqué que la prise en charge annoncée n'est pas une preuve visible.

Restaurez l'état antérieur interrogeable :

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

Créer des dégradés honnêtement

Pour le résultat spatial préféré, créez directement 3 à 5 bandes ordonnées, nommez une entrée de catalogue de palettes validée, ou compilez une recette OKLCH contrainte. Les recettes rendent l'interpolation, le voyage de teinte et les diagnostics reproductibles ; les bandes hexadécimales explicites restent de première classe et ne sont jamais régénérées silencieusement. Compilez l'une ou l'autre forme uniquement lorsque l'appareil sélectionné annonce devices.capabilities.segment_color_setting / segmentedColorRgb et fournit un domaine de segment explicite. Si l'appareil annonce également devices.capabilities.toggle / gradientToggle, activez-le avant d'envoyer les couleurs des segments. Si la capacité ou le domaine est absent, utilisez uniquement les solutions de repli déclarées par le score.

Considérez l'acceptation de l'API et le rendu visuel comme des preuves séparées. Une réponse 200 prouve uniquement que Govee a accepté la demande. Elle ne prouve pas que des pucks ou ampoules individuelles ont rendu des couleurs distinctes. Enregistrez le contexte du firmware et le résultat visible avant de qualifier un appareil de segment-vérifié.

Ne décrivez pas une solution de repli de couleur unie comme un dégradé. Ne décrivez pas la relecture de scène comme un contrôle arbitraire par lumière. L'API publique peut déclencher des scènes DIY annoncées mais ne documente pas la création ou le téléchargement de nouveaux effets DIY. Enregistrez le mode d'exécution sélectionné dans le résultat.

Utiliser le package géré

La racine du dépôt est la source unique de vérité. scripts/manage.mjs prévisualise, installe, audite et supprime de manière conservative les liens de découverte locaux pour Codex, Claude Code et Hermes. Lisez references/distribution.md avant de l'installer ou de le packager.

Utilisez mcp/server.mjs lorsque l'agent doit appeler des outils typés au lieu de commandes shell. Il est principalement en lecture seule par défaut, hérite des identifiants de l'environnement et double-barrière les écritures physiques. Lisez references/mcp.md avant de le connecter à un agent.

Séparer la création du rendu en temps réel

Utilisez l'agent pour interpréter du texte ou des images et créer un LightScore. Utilisez un runtime local dédié pour le contrôle audio-réactif ou écran-réactif à haute fréquence. La limite officielle des appareils cloud est inadaptée au streaming à la fréquence d'image ; cette Skill peut configurer, démarrer, arrêter ou diagnostiquer un tel runtime, mais ne doit pas transformer les requêtes cloud en une boucle de rendu pseudo.

Ne scrapez pas l'application Govee Home, ne reproduisez pas l'authentification privée, et ne revendiquez pas l'accès à CogniGlow ou AI Lighting Bot. Utilisez ces produits uniquement comme précédents d'interaction, sauf si Govee publie un point de terminaison pris en charge.

Peindre par LED sur le LAN

Les commandes lan atteignent les appareils sur le réseau local sans clé API, y compris la peinture par LED sur des appareils avec un profil de pixels vérifié. Le workflow ci-dessus s'applique toujours ; ces règles sont supplémentaires, et chacune encode une leçon mesurée sur le matériel :

1. Scannez d'abord (lan scan) — c'est en lecture seule et signale quels appareils découverts prennent en charge le par-LED et si leur nombre de pixels est vérifié par le matériel. La découverte multicast est intermittente par appareil, ne concluez donc jamais à une "absence de support LAN" à partir d'un scan court ou partiel.
2. Créez l'intention par-LED comme un LightScore de dégradé ordinaire. Les bandes sont compilées en pixels dans l'ordre de création ; il n'y a pas délibérément de tableau arbitraire pixel par pixel, car les appareils avec moins de zones interpolent entre les arrêts par le long chemin de la roue des teintes, et l'ordre des bandes est ce qui maintient les pixels adjacents adjacents en teinte.
3. Ne revendiquez jamais qu'une écriture par-LED a été rendue. Le canal est muet — aucun accusé de réception, aucun état de segment interrogeable. Les résultats portent verified: false ; seuls les yeux (ou l'utilisateur) peuvent confirmer, et la Skill doit le dire.
4. Rendez la durée explicite. Un look par-LED revient aux effets propres de l'appareil environ une minute après l'arrêt des données. Utilisez --hold-seconds pour une durée limitée (par défaut 900, max 14400) et informez l'utilisateur du moment où le look se terminera ; utilisez lan release pour y mettre fin prématurément.
5. Ne mélangez jamais les rédacteurs. Pendant qu'un maintien est actif, les écritures de couleur sur l'ensemble de l'appareil sont refusées — une commande sur l'ensemble de l'appareil repeint chaque pixel et aplatit le look par-LED. Pour passer intentionnellement un appareil maintenu à une couleur unie, passez --hand-over (MCP handOver: true) : Suffuse arrête le keepalive et quitte le mode par-LED, puis écrit. Un nouveau dégradé prend le relais d'un maintien existant de la même manière. Ne faites pas de restore entre deux looks — cela ferait clignoter l'ancienne couleur uniquement pour la peindre ; restaurez lorsque l'utilisateur souhaite revenir à l'état antérieur.
6. La restauration est uniquement sur l'ensemble de l'appareil. devStatus est capturé avant l'écriture et rejoué par restore ; un look par-LED antérieur n'est pas interrogeable sur quelque canal que ce soit, et le reçu doit le dire plutôt que de sur-réclamer.
7. Si le port de réponse (UDP 4002) est détenu par un autre contrôleur local, le scan et la capture d'état échouent bruyamment. Ne contournez pas avec le partage de port — deux écouteurs volent silencieusement les réponses de l'autre. Dites à l'utilisateur quel processus quitter, ou épinglez l'appareil avec --ip.
8. Pour un SKU inconnu, consultez d'abord le portfolio miné (node scripts/portfolio.mjs <SKU>) — 371 SKU de priors communautaires avec provenance par fait. Lisez-le sous une seule règle : un positif miné est fiable, un négatif miné est seulement "inconnu" — les indicateurs du fournisseur décrivent le support de l'application, pas ce que le firmware accepte. Ne dites jamais à l'utilisateur que son appareil "ne prend pas en charge" le par-LED sur la base d'un indicateur miné ou d'une absence du portfolio.

Atteindre le matériel BLE uniquement via Bluetooth

Les commandes ble atteignent les lampes que le LAN ne peut structurellement pas atteindre (la classe H6009 : listée dans le cloud, pas de contrôle LAN) — sans clé et sans Wi-Fi. Le workflow ci-dessus s'applique toujours ; ces règles sont supplémentaires :

1. Scannez d'abord (ble scan) — en lecture seule. Une lampe détenue par un autre central (l'application Govee Home de l'utilisateur, un autre contrôleur) cesse de diffuser et n'apparaîtra pas ; l'absence n'est pas l'absence. Dites cela au lieu de conclure que la lampe a disparu.
2. Un seul coup. Connectez, écrivez, videz, déconnectez — ne maintenez jamais une session BLE ouverte : un central connecté verrouille l'utilisateur hors de sa propre application. Si l'utilisateur souhaite un look persistant, BLE est le mauvais fil ; dites-le.
3. Il n'y a pas de lecture en retour. La couleur et la luminosité antérieures ne peuvent pas être capturées, donc le reçu enregistre un point de restauration déclaré blanc chaud et restore y ramène la lampe — vers un neutre déclaré, pas vers son look précédent. Informez l'utilisateur avant d'écrire.
4. Les écritures ne sont pas acquittées (verified: false). Rapportez ce qui a été envoyé ; seuls les yeux confirment.
5. L'opcode de couleur est propre à la classe d'appareil (vérifié sur le RGBWW H6009 ; l'encodage RGB uniquement largement documenté est accepté et inerte là-bas). Une lampe qui s'allume et diminue mais ignore la couleur est la signature d'un mauvais opcode — soumettez un rapport de compatibilité plutôt que de réessayer plus fort.
6. La dépendance est facultative. Si @stoprocent/noble est manquant ou si l'hôte n'a pas la permission Bluetooth (macOS tue les processus non signés touchant CoreBluetooth sans invite — le processus responsable, généralement l'application de terminal, doit détenir la permission), relayez la remédiation structurée de l'erreur ; toutes les autres surfaces de Suffuse fonctionnent toujours.

Gérer les identifiants indisponibles

Si GOVEE_API_KEY est absent, continuez avec la création de score, les fixtures, les tests de compilation et la documentation. Indiquez que la vérification des capacités de l'appareil en direct et les écritures restent en attente. Ne demandez jamais à l'utilisateur de coller une clé dans le chat.

Retourner un reçu de preuve

Rapportez :

• SKU sélectionné et identité de l'appareil expurgée ;
• capacité annoncée utilisée ;
• mode demandé et exécuté ;
• solutions de repli et avertissements ;
• nombre et résultat des opérations de contrôle ;
• chemin du reçu, lorsqu'il est écrit ;
• couverture de la restauration et tout état qui n'a pas pu être capturé.
• l'énoncé du résumé des preuves et l'incertitude résiduelle ; ne traduisez jamais accepted ou sent-unacknowledged en succès visible.