andyed/suffuse

Was macht suffuse?

Verwende diesen Skill zusammen mit dem lokalen MCP-Server als die beiden agentenseitigen Komponenten der Govee-Beleuchtungssteuerung. Der Skill liefert den Workflow und die Beurteilung; MCP liefert die typisierten Werkzeuge und die Laufzeitsperren. Untersuche das installierte Gerät, übersetze die Absicht in einen kleinen LightScore, kompiliere ihn deterministisch gegen die angekündigten Fähigkeiten, zeige eine Vorschau der resultierenden Operationen und führe Schreibvorgänge nur dann durch, wenn der Benutzer explizit eine Geräteänderung angefordert hat. Die CLI ist die gemeinsame Infrastruktur unter beiden Oberflächen; die Erstellung von Wahrnehmungspaletten ist optional.

Der aktuelle Ausführungsanbieter ist die dokumentierte Entwicklerplattform von Govee. Anbieterspezifische MCP-Werkzeuge behalten die Namen govee_, bis ein anderer Anbieter implementiert wird. Dies ist ein inoffizielles Community-Projekt und steht in keiner Verbindung zu Govee und wird von Govee nicht unterstützt.

Folge dem Steuerungsworkflow

1. Stelle fest, ob die Anfrage eine Palettenerstellung, eine schreibgeschützte Inspektion, eine kompilierte Vorschau oder ein Geräteschreibvorgang ist.
2. Verwende govee_inspect_household, wenn der Transportbestand oder die geräteübergreifende Identität wichtig ist, und untersuche dann das genaue installierte Gerät, bevor du Segmente, Szenen oder Wiederherstellungen versprichst. Haushalts-Schnappschuss-Referenzen sind schreibgeschützt und flüchtig.
3. Lies references/color-theory.md, references/palettes.md und references/light-score.md, wenn du eine Palette oder einen Score erstellst oder überarbeitest.
4. Kompiliere den Score gegen das zurückgegebene Fähigkeitsdokument. Schließe niemals von einer SKU oder einer Produktseite auf die Fähigkeitsunterstützung.
5. Zeige einen geschwärzten Trockenlauf an, es sei denn, der Benutzer hat bereits einen direkten Befehl zur Änderung der Beleuchtung gegeben.
6. Verwende bei einem Schreibvorgang --confirm-write und speichere die Quittung in einem privaten Pfad. Segment-Schreibvorgänge erfordern ebenfalls --confirm-segments, bis eine sichtbare Unabhängigkeit nachgewiesen wurde.
7. Untersuche die Quittungsnachweise, wenn du Ergebnisse meldest. Halte Protokollakzeptanz, Abfragestatus, visuelle Beobachtung und Restunsicherheit getrennt.
8. Stelle auf Anfrage aus der Quittung wieder her. Erkläre, wenn die API den vorherigen Segmentzustand nicht exakt erfassen konnte; der Wiederherstellungsversuch wird zurück in die Quittung geschrieben.

Lies references/govee-platform.md für Endpunkte, Fähigkeitsformen, Ratenlimits und die Grenze zwischen öffentlicher und privater API. Lies references/ecosystem.md, wenn du entscheidest, ob die dokumentierte Cloud-API, LAN, MQTT, BLE oder eine bestehende MCP-Implementierung die Ausführung übernehmen soll. Lies references/device-evidence.md, bevor du eine erfolgreiche API-Antwort als visuellen Beweis interpretierst. Lies references/safety.md, bevor du Geräte änderst, Identifikatoren behandelst oder eine Wiederherstellung beanspruchst. Lies references/lan-razer.md, bevor du eine Behauptung über den per-LED-LAN-Kanal aufstellst – er ist von Govee nicht dokumentiert, und diese Seite ist die Herkunftskette für jede Behauptung, auf die sich Suffuse stützt. Lies references/evidence-transactions.md, bevor du Quittungsnachweise über verschiedene Transporte hinweg interpretierst oder erweiterst. Lies references/device-registry.md, bevor du Haushaltsbeobachtungen für die Transportauswahl, Persistenz oder Gruppenbildung verwendest.

Verwende die deterministische CLI

Erfordert Node.js 20 oder neuer. GOVEE_API_KEY schaltet die Erkennung der unterstützten Geräte des Kontos, ihrer aktuellen Fähigkeiten und abfragbaren Zustände, ihrer nativen und DIY-Szenen sowie authentifizierter Steuerungsanfragen frei. Der Schlüssel autorisiert allein keinen Suffuse-Schreibvorgang. Die CLI liest ihn nur aus der Prozessumgebung und akzeptiert ihn niemals als Befehlszeilenargument.

Liste gebündelte benutzerdefinierte Paletten ohne Anmeldeinformationen auf:

node scripts/govee.mjs palettes

Überprüfe Live-Fähigkeiten, ohne ein Gerät zu ändern:

node scripts/govee.mjs inspect --sku H608B

Überprüfe ein Gerät, wenn keine Anmeldeinformationen verfügbar sind:

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

Kompiliere einen Score gegen aufgezeichnete oder Fixture-Fähigkeiten:

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

Vorschau gegen Live-Fähigkeiten. Dies bleibt schreibgeschützt, da --confirm-write fehlt:

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

Für Szenen-Looks löst apply im Live-Modus die Namen lightScene und diyScene über die dedizierten Szenenkataloge von Govee auf, bevor es kompiliert. Ersetze keinen erfundenen Identifikator, wenn ein Name fehlt.

Wende nach einer expliziten Benutzeranforderung an und behalte eine Evidenz-/Wiederherstellungsquittung:

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

Füge für einen experimentellen segmentierten Schreibvorgang --confirm-segments nur hinzu, nachdem du erklärt hast, dass die angekündigte Unterstützung kein sichtbarer Beweis ist.

Stelle den abfragbaren vorherigen Zustand wieder her:

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

Erstelle Farbverläufe ehrlich

Erstelle für das bevorzugte räumliche Ergebnis direkt 3–5 geordnete Bänder, nenne einen validierten Palettenkatalogeintrag oder kompiliere ein eingeschränktes OKLCH-Rezept. Rezepte machen Interpolation, Farbtonwanderung und Diagnostik reproduzierbar; explizite Hex-Bänder bleiben erstklassig und werden niemals stillschweigend neu generiert. Kompiliere eine der beiden Formen nur, wenn das ausgewählte Gerät devices.capabilities.segment_color_setting / segmentedColorRgb bewirbt und eine explizite Segmentdomäne bereitstellt. Wenn das Gerät auch devices.capabilities.toggle / gradientToggle bewirbt, aktiviere es, bevor du Segmentfarben sendest. Wenn die Fähigkeit oder Domäne fehlt, verwende nur die vom Score deklarierten Fallbacks.

Behandle API-Akzeptanz und sichtbare Darstellung als getrennte Evidenz. Eine 200-Antwort beweist nur, dass Govee die Anfrage akzeptiert hat. Sie beweist nicht, dass einzelne Pucks oder Glühbirnen unterschiedliche Farben dargestellt haben. Zeichne den Firmware-Kontext und das sichtbare Ergebnis auf, bevor du ein Gerät als segmentverifiziert bezeichnest.

Beschreibe einen einfarbigen Fallback nicht als Farbverlauf. Beschreibe die Szenenwiedergabe nicht als willkürliche Steuerung pro Leuchte. Die öffentliche API kann beworbene DIY-Szenen auslösen, dokumentiert jedoch nicht die Erstellung oder das Hochladen neuer DIY-Effekte. Zeichne den gewählten Ausführungsmodus im Ergebnis auf.

Verwende das verwaltete Paket

Das Repository-Stammverzeichnis ist die alleinige Quelle der Wahrheit. scripts/manage.mjs zeigt Vorschauen an, installiert, prüft und entfernt konservativ lokale Erkennungslinks für Codex, Claude Code und Hermes. Lies references/distribution.md, bevor du es installierst oder paketierst.

Verwende mcp/server.mjs, wenn der Agent typisierte Werkzeuge anstelle von Shell-Befehlen aufrufen soll. Es ist standardmäßig schreibgeschützt, erbt Anmeldeinformationen aus der Umgebung und schützt physische Schreibvorgänge mit einer doppelten Sperre. Lies references/mcp.md, bevor du es mit einem Agenten verbindest.

Trenne die Erstellung von der Echtzeitdarstellung

Verwende den Agenten, um Text oder Bilder zu interpretieren und einen LightScore zu erstellen. Verwende eine dedizierte lokale Laufzeit für hochfrequente, audio-reaktive oder bildschirm-reaktive Steuerung. Das offizielle Cloud-Gerätelimit ist für bildratenbezogenes Streaming ungeeignet; dieser Skill kann eine solche Laufzeit konfigurieren, starten, stoppen oder diagnostizieren, darf aber Cloud-Anfragen nicht in eine Pseudo-Render-Schleife verwandeln.

Scrape nicht die Govee Home App, reproduziere keine private Authentifizierung und beanspruche keinen Zugriff auf CogniGlow oder AI Lighting Bot Generierung. Verwende diese Produkte nur als Interaktionspräzedenzfälle, es sei denn, Govee veröffentlicht einen unterstützten Endpunkt.

Male per-LED über das LAN

Die lan-Befehle erreichen Geräte im lokalen Netzwerk ohne API-Schlüssel, einschließlich der per-LED-Malerei auf Leuchten mit einem verifizierten Pixelprofil. Der obige Workflow gilt weiterhin; diese Regeln sind zusätzlich, und jede kodiert eine hardwaregemessene Lektion:

1. Scanne zuerst (lan scan) – es ist schreibgeschützt und meldet, welche entdeckten Leuchten per-LED unterstützen und ob ihre Pixelanzahl hardware-verifiziert ist. Die Multicast-Erkennung ist pro Gerät zeitweise unzuverlässig, ziehe also niemals den Schluss „keine LAN-Unterstützung“ aus einem kurzen oder teilweisen Scan.
2. Erstelle die per-LED-Absicht als gewöhnlichen gradienten LightScore. Bänder werden in der erstellten Reihenfolge auf Pixel kompiliert; es gibt absichtlich kein willkürliches Per-Pixel-Array, da Leuchten mit weniger Zonen zwischen den Stopps auf dem langen Weg um den Farbkreis interpolieren und die Bandreihenfolge dafür sorgt, dass benachbarte Pixel im Farbton benachbart bleiben.
3. Behaupete niemals, dass ein per-LED-Schreibvorgang dargestellt wurde. Der Kanal ist stumm – keine Bestätigung, kein abfragbarer Segmentzustand. Ergebnisse tragen verified: false; nur Augen (oder der Benutzer) können bestätigen, und der Skill muss dies sagen.
4. Mache die Dauer explizit. Ein per-LED-Look kehrt ungefähr eine Minute nachdem keine Daten mehr gesendet werden zu den eigenen Effekten des Geräts zurück. Verwende --hold-seconds für eine begrenzte Haltezeit (Standard 900, maximal 14400) und teile dem Benutzer mit, wann der Look enden wird; verwende lan release, um ihn vorzeitig zu beenden.
5. Mische niemals Schreiber. Während ein Halten aktiv ist, werden geräteweite Farbschreibvorgänge auf diese Leuchte abgelehnt – ein geräteweiter Befehl malt jedes Pixel neu und macht den per-LED-Look zunichte. Um eine gehaltene Leuchte absichtlich auf eine einfarbige Farbe umzustellen, übergib --hand-over (MCP handOver: true): Suffuse stoppt den Keepalive und verlässt den per-LED-Modus, dann schreibt es. Ein neuer Gradient übernimmt einen bestehenden Halt auf die gleiche Weise. Führe restore nicht zwischen zwei Looks aus – das blitzt die alte Farbe nur auf, um sie dann zu übermalen; stelle wieder her, wenn der Benutzer den früheren Zustand zurückhaben möchte.
6. Die Wiederherstellung ist nur geräteweit. devStatus wird vor dem Schreibvorgang erfasst und von restore wiedergegeben; ein vorheriger per-LED-Look ist auf keinem Kanal abfragbar, und die Quittung muss dies sagen, anstatt etwas vorzutäuschen.
7. Wenn der Antwortport (UDP 4002) von einem anderen lokalen Controller belegt ist, schlagen das Scannen und die Zustandserfassung mit einem lauten Fehler fehl. Umgehe dies nicht mit Port-Sharing – zwei Zuhörer stehlen sich gegenseitig still die Antworten. Sage dem Benutzer, welchen Prozess er beenden soll, oder pinne das Gerät mit --ip.
8. Konsultiere für eine unbekannte SKU zuerst das abgebaute Portfolio (node scripts/portfolio.mjs <SKU>) – 371 SKUs von Community-Vorwissen mit faktenbezogener Herkunft. Lies es unter einer Regel: Ein abgebauter Positivbefund ist vertrauenswürdig, ein abgebauter Negativbefund ist nur „unbekannt“ – Verkaufsflags beschreiben die App-Unterstützung, nicht das, was die Firmware akzeptiert. Sage dem Benutzer niemals, dass sein Gerät per-LED „nicht unterstützt“, allein aufgrund eines abgebauten Flags oder des Fehlens im Portfolio.

Erreiche BLE-only-Hardware über Bluetooth

Die ble-Befehle erreichen Lampen, die das LAN strukturell nicht kann (die H6009-Klasse: in der Cloud gelistet, keine LAN-Steuerung) – schlüssellos und ohne Wi-Fi. Der obige Workflow gilt weiterhin; diese Regeln sind zusätzlich:

1. Scanne zuerst (ble scan) – schreibgeschützt. Eine Lampe, die von einem anderen Zentralgerät gehalten wird (die Govee Home App des Benutzers, ein anderer Controller), hört auf zu werben und wird nicht erscheinen; Abwesenheit ist nicht Abwesenheit. Sage das, anstatt zu schlussfolgern, die Lampe sei verschwunden.
2. Nur einmalig. Verbinde, schreibe, entleere, trenne – halte niemals eine BLE-Sitzung offen: Ein verbundenes Zentralgerät sperrt den Benutzer aus seiner eigenen App aus. Wenn der Benutzer einen dauerhaften Look wünscht, ist BLE der falsche Draht; sage das.
3. Es gibt kein Rücklesen. Vorherige Farbe und Helligkeit können nicht erfasst werden, daher zeichnet die Quittung einen deklarierten warmweißen Wiederherstellungspunkt auf, und restore bringt die Lampe dorthin zurück – zu einem angegebenen Neutralton, nicht zu ihrem vorherigen Look. Sage dem Benutzer dies, bevor du schreibst.
4. Schreibvorgänge werden nicht quittiert (verified: false). Berichte, was gesendet wurde; nur die Augen bestätigen.
5. Der Farbopcode ist geräteklassenspezifisch (verifiziert auf der RGBWW H6009; die weitgehend dokumentierte reine RGB-Kodierung wird dort akzeptiert und ist inert). Eine Lampe, die leuchtet und dimmt, aber Farbe ignoriert, ist das Kennzeichen eines falschen Opcodes – melde einen Kompatibilitätsbericht, anstatt es härter zu versuchen.
6. Die Abhängigkeit ist optional. Wenn @stoprocent/noble fehlt oder der Host keine Bluetooth-Berechtigung hat (macOS tötet nicht signierte Prozesse, die CoreBluetooth berühren, ohne eine Eingabeaufforderung – der verantwortliche Prozess, normalerweise die Terminal-App, muss die Berechtigung halten), gib die strukturierte Abhilfe aus der Fehlermeldung weiter; jede andere Suffuse-Oberfläche funktioniert trotzdem.

Behandle nicht verfügbare Anmeldeinformationen

Wenn GOVEE_API_KEY fehlt, fahre mit der Score-Erstellung, Fixtures, Kompilierungstests und Dokumentation fort. Gib an, dass die Live-Gerätefähigkeitsüberprüfung und Schreibvorgänge ausstehen. Bitte den Benutzer niemals, einen Schlüssel in den Chat einzufügen.

Gib eine Evidenzquittung zurück

Berichte:

• ausgewählte SKU und geschwärzte Geräteidentität;
• verwendete beworbene Fähigkeit;
• angeforderter und ausgeführter Modus;
• Fallbacks und Warnungen;
• Anzahl und Ergebnis der Steuerungsoperationen;
• Quittungspfad, wenn geschrieben;
• Wiederherstellungsabdeckung und alle Zustände, die nicht erfasst werden konnten;
• die Evidenzzusammenfassung und die Restunsicherheit; übersetze niemals accepted oder sent-unacknowledged in sichtbaren Erfolg.