andyed/suffuse

suffuse は何をしますか？

このスキルは、Govee照明制御のエージェント向け2つの部分として、ローカルMCPサーバーと共に使用します。スキルはワークフローと判断を提供し、MCPは型付きツールとランタイムゲートを提供します。インストールされたデバイスを検査し、意図を小さなLightScoreに変換し、アドバタイズされた機能に対して決定論的にコンパイルし、結果の操作をプレビューし、ユーザーが明示的にデバイスの変更を要求した場合にのみ書き込みを実行します。CLIは両方のインターフェースの下にある共有インフラストラクチャであり、知覚パレットの作成はオプションです。

現在の実行プロバイダーは、Goveeの文書化されたDeveloper Platformです。プロバイダー固有のMCPツールは、別のプロバイダーが実装されるまでgovee_という名前を保持します。これは非公式のコミュニティプロジェクトであり、Goveeとの提携や推奨はありません。

制御ワークフローに従う

1. リクエストがパレット作成、読み取り専用検査、コンパイルされたプレビュー、またはデバイス書き込みのいずれであるかを判断します。
2. トランスポートの在庫やクロスソースのIDが重要な場合はgovee_inspect_householdを使用し、セグメント、シーン、復元を約束する前に、正確にインストールされたデバイスを検査します。家のスナップショット参照は読み取り専用で一時的です。
3. パレットやスコアを作成または修正する際は、references/color-theory.md、references/palettes.md、references/light-score.mdを参照してください。
4. 返されたケイパビリティドキュメントに対してスコアをコンパイルします。SKUや製品ページからケイパビリティのサポートを推測しないでください。
5. ユーザーがすでに照明を変更する直接的な命令を与えていない限り、編集されたドライランを表示します。
6. 書き込みの場合は、--confirm-writeを使用し、レシートをプライベートパスに保存します。セグメント書き込みでは、可視的な独立性が確立されるまで--confirm-segmentsも必要です。
7. 結果を報告する際は、レシートの証拠を検査します。プロトコルの受け入れ、クエリ状態、視覚的観察、および残存する不確実性を分離します。
8. 要求された場合は、レシートから復元します。APIが以前のセグメント化された状態を正確にキャプチャできなかった場合を説明します。復元の試行はレシートに保存されます。

エンドポイント、ケイパビリティ形式、レート制限、パブリック/プライベートAPIの境界については、references/govee-platform.mdを参照してください。文書化されたクラウドAPI、LAN、MQTT、BLE、または既存のMCP実装のどれが実行を担当すべきかを判断する際は、references/ecosystem.mdを参照してください。成功したAPI応答を視覚的な証明として解釈する前に、references/device-evidence.mdを参照してください。デバイスを変更したり、識別子を処理したり、復元を主張したりする前に、references/safety.mdを参照してください。per-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レシピをコンパイルします。レシピにより、補間、色相の移動、診断が再現可能になります。明示的な16進バンドは引き続き第一級であり、静かに再生成されることはありません。選択したデバイスが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を参照してください。

エージェントがシェルコマンドの代わりに型付きツールを呼び出す必要がある場合は、mcp/server.mjsを使用します。デフォルトで読み取り専用であり、環境から認証情報を継承し、物理的な書き込みを二重にゲートします。エージェントに接続する前に、references/mcp.mdを参照してください。

作成とリアルタイムレンダリングを分離する

エージェントを使用してテキストまたは画像を解釈し、LightScoreを作成します。高速なオーディオリアクティブまたはスクリーンリアクティブ制御には、専用のローカルランタイムを使用します。公式のクラウドデバイス制限はフレームレートストリーミングには適していません。このスキルはそのようなランタイムを設定、開始、停止、または診断する場合がありますが、クラウドリクエストを疑似レンダリングループに変えてはなりません。

Govee Homeアプリをスクレイピングしたり、プライベート認証を再現したり、CogniGlowやAI Lighting Botの生成へのアクセスを主張したりしないでください。Goveeがサポートされているエンドポイントを公開しない限り、それらの製品をインタラクションの先行例としてのみ使用してください。

LAN経由でピクセル単位でペイントする

lanコマンドは、APIキーなしでローカルネットワーク上のデバイスに到達します。これには、検証済みのピクセルプロファイルを持つフィクスチャへのピクセル単位のペイントも含まれます。上記のワークフローは引き続き適用されます。これらのルールは追加であり、それぞれがハードウェアで測定された教訓をエンコードしています:

1. 最初にスキャンします（lan scan）— 読み取り専用であり、発見されたどのフィクスチャがピクセル単位をサポートし、ピクセル数がハードウェア検証済みかを報告します。マルチキャスト検出はデバイスごとに断続的であるため、短いまたは部分的なスキャンから「LANサポートなし」と結論付けないでください。
2. ピクセル単位の意図を通常のグラデーションLightScoreとして作成します。バンドは作成された順序でピクセルにコンパイルされます。任意のピクセル単位の配列は意図的にありません。ゾーンの少ないフィクスチャは、色相ホイールの長い方のルートでストップ間を補間し、バンドの順序によって隣接するピクセルが色相で隣接し続けるためです。
3. ピクセル単位の書き込みがレンダリングされたと主張しないでください。チャネルはミュートされています—確認応答もクエリ可能なセグメント状態もありません。結果はverified: falseを保持します。目（またはユーザー）だけが確認でき、スキルはそう言わなければなりません。
4. 期間を明示的にします。ピクセル単位のルックは、データが停止してから約1分後にデバイス自身のエフェクトに戻ります。--hold-secondsを使用してバインドされたホールド（デフォルト900、最大14400）を指定し、ルックがいつ終了するかをユーザーに伝えます。lan releaseを使用して早期に終了します。
5. ライターを混在させないでください。ホールドがアクティブな間、そのフィクスチャへのデバイス全体のカラー書き込みは拒否されます。デバイス全体のコマンドはすべてのピクセルを再ペイントし、ピクセル単位のルックをフラット化します。ホールドされたフィクスチャを意図的に無地の色に切り替えるには、--hand-over（MCPのhandOver: true）を渡します。Suffuseはキープアライブを停止してピクセル単位モードを終了し、その後書き込みます。新しいグラデーションも同じ方法で既存のホールドを引き継ぎます。2つのルック間でrestoreを実行しないでください。古い色をフラッシュして上書きするだけです。ユーザーが以前の状態に戻したい場合に復元します。
6. 復元はデバイス全体のみです。devStatusは書き込み前にキャプチャされ、restoreによって再生されます。以前のピクセル単位のルックはどのチャネルでもクエリ可能ではなく、レシートは過大宣伝するのではなく、そう言わなければなりません。
7. 応答ポート（UDP 4002）が別のローカルコントローラーによって保持されている場合、スキャンと状態キャプチャはエラーで失敗します。ポート共有で回避しないでください。2つのリスナーが互いの応答を静かに盗みます。ユーザーに終了するプロセスを伝えるか、--ipでデバイスを固定します。
8. 見慣れないSKUの場合は、最初にマイニングされたポートフォリオを参照してください（node scripts/portfolio.mjs <SKU>）— 371のSKUのコミュニティ事前情報と、事実ごとの来歴。1つのルールで読み取ります。マイニングされた肯定は信頼でき、マイニングされた否定は「不明」のみです。ベンダーフラグはアプリのサポートを説明しており、ファームウェアが受け入れるものを説明していません。マイニングされたフラグまたはポートフォリオからの欠如に基づいて、ユーザーのデバイスがピクセル単位を「サポートしていない」とユーザーに伝えないでください。

Bluetooth経由でBLE専用ハードウェアに到達する

bleコマンドは、LANが構造的に到達できないランプ（H6009クラス：クラウドにリストされているが、LAN Controlなし）に到達します。キーがなく、Wi-Fiもありません。上記のワークフローは引き続き適用されます。これらのルールは追加です:

1. 最初にスキャンします（ble scan）— 読み取り専用。別のセントラル（ユーザーのGovee Homeアプリ、別のコントローラー）によって保持されているランプはアドバタイズを停止し、表示されません。不在は不在ではありません。ランプがなくなったと結論付ける代わりに、そう言ってください。
2. ワンショットのみ。接続、書き込み、ドレイン、切断—BLEセッションを開いたままにしないでください。接続されたセントラルは、ユーザーを自分のアプリからロックアウトします。ユーザーが永続的なルックを望む場合、BLEは間違ったワイヤーです。そう言ってください。
3. 読み返しはありません。以前の色と明るさをキャプチャできないため、レシートは宣言された暖かみのある白の復元ポイントを記録し、restoreはランプをそこに戻します。指定されたニュートラルに、以前のルックではありません。書き込む前にこれをユーザーに伝えてください。
4. 書き込みは確認応答されません（verified: false）。送信されたものを報告します。目だけが確認します。
5. カラーオペコードはデバイスクラスごとです（RGBWW H6009で検証済み。広く文書化されたRGB専用エンコーディングはそこで受け入れられ、不活性です）。電源は入り調光はできるが色を無視するランプは、間違ったオペコードの兆候です—より強くリトライするのではなく、互換性レポートを提出してください。
6. 依存関係はオプションです。@stoprocent/nobleがない場合、またはホストにBluetooth権限がない場合（macOSは、権限を保持する責任のあるプロセス、通常はターミナルアプリが必要とするCoreBluetoothに触れる未署名のプロセスをプロンプトなしで強制終了します）、エラーから構造化された修復を中継します。Suffuseの他のすべてのインターフェースは引き続き機能します。

利用できない認証情報を処理する

GOVEE_API_KEYがない場合は、スコア作成、フィクスチャ、コンパイルテスト、ドキュメントを続行します。ライブデバイスのケイパビリティ検証と書き込みは保留中であると述べてください。ユーザーにチャットにキーを貼り付けるように要求しないでください。

証拠レシートを返す

報告:

• 選択されたSKUと編集されたデバイスID
• 使用されたアドバタイズされたケイパビリティ
• 要求および実行されたモード
• フォールバックと警告
• 制御操作の数と結果
• 書き込まれた場合のレシートパス
• 復元のカバレッジとキャプチャできなかった状態
• 証拠の要約ステートメントと残存する不確実性。acceptedまたはsent-unacknowledgedを可視的な成功に翻訳しないでください。