andyed/suffuse

suffuse 是做什麼的？

請將此技能與本地 MCP 伺服器搭配使用，作為 Govee 燈光控制的兩個代理端元件。Skill 提供工作流程與判斷；MCP 提供型別化工具與執行時期閘門。檢查已安裝的裝置，將意圖翻譯成一個小型 LightScore，根據廣告宣稱的能力進行確定性編譯，預覽結果操作，並僅在使用者明確要求裝置變更時才執行寫入。CLI 是兩個表面共用的底層基礎設施；感知色板編寫為選擇性功能。

目前的執行提供者是 Govee 官方文件的開發者平台。提供者特定的 MCP 工具保留 govee_ 前綴，直到實作其他提供者為止。這是一個非官方的社群專案，與 Govee 公司無關聯或未獲其背書。

遵循控制工作流程

1. 確認請求是色板編寫、唯讀檢查、編譯預覽或裝置寫入。
2. 當傳輸庫存或跨來源身份識別重要時，使用 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 何時無法精確捕捉先前的分段狀態；還原嘗試會持續寫回收據。

請閱讀 references/govee-platform.md 以了解端點、能力形式、速率限制以及公開/私有 API 邊界。在決定文件化的雲端 API、LAN、MQTT、BLE 或現有 MCP 實作是否應負責執行時，請閱讀 references/ecosystem.md。在將成功的 API 回應解讀為視覺證據之前，請閱讀 references/device-evidence.md。在變更裝置、處理識別碼或聲稱還原之前，請閱讀 references/safety.md。在對逐顆 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

針對擷取或 fixture 能力編譯分數：

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 配方。配方可使內插、色相移動和診斷具有可重複性；顯式的十六進制頻帶仍然是第一公民，且絕不會被默默重新產生。僅在選定裝置廣告宣稱 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。

當代理應呼叫型別化工具而非 shell 命令時，請使用 mcp/server.mjs。它預設為唯讀模式，從環境繼承憑證，並對實體寫入設置雙重閘門。在將其連接到代理之前，請閱讀 references/mcp.md。

分離編寫與即時渲染

使用代理來解讀文字或影像，並編寫一個 LightScore。使用專用的本地運行時進行高頻率的音訊反應或螢幕反應控制。官方雲端裝置限制不適合幀率串流；此技能可以配置、啟動、停止或診斷此類運行時，但不得將雲端請求變成偽渲染迴圈。

請勿爬取 Govee Home 應用程式、重現私有身份驗證，或聲稱有權存取 CogniGlow 或 AI Lighting Bot 生成。除非 Govee 發布支援的端點，否則僅將這些產品用作互動先例。

透過 LAN 進行逐顆 LED 繪製

lan 命令無需 API 金鑰即可接觸本地網路上的裝置，包括在具有經過驗證的像素配置文件的燈具上進行逐顆 LED 繪製。上述工作流程仍然適用；這些規則是附加的，且每一條都編碼了一個硬體實測的教訓：

1. 先掃描 (lan scan) — 這是唯讀操作，並報告哪些發現的燈具支援逐顆 LED，以及它們的像素計數是否經硬體驗證。多播發現對每個裝置而言是間歇性的，因此切勿從短暫或部分掃描就得出「不支援 LAN」的結論。
2. 將逐顆 LED 意圖編寫為一個普通的漸層 LightScore。頻帶按編寫順序編譯為像素；出於設計考量，沒有任意的逐像素陣列，因為具有較少區域的燈具會在色相輪上繞遠路在停靠點之間進行內插，而頻帶順序正是保持相鄰像素色相相鄰的關鍵。
3. 切勿聲稱逐顆 LED 寫入已成功渲染。該通道是靜默的 — 沒有確認，沒有可查詢的區段狀態。結果帶有 verified: false；只有肉眼（或用戶）才能確認，技能必須說明這一點。
4. 明確指定持續時間。逐顆 LED 外觀在數據停止後大約一分鐘會恢復到裝置自身的效果。使用 --hold-seconds 進行有限時間的保持（預設 900，最大 14400），並告知使用者外觀將何時結束；使用 lan release 提前結束。
5. 切勿混合寫入者。在保持活動期間，對該燈具的整體裝置顏色寫入將被拒絕 — 整體裝置命令會重新繪製每個像素並扁平化逐顆 LED 外觀。要故意將處於保持狀態的燈具切換為純色，請傳遞 --hand-over（MCP 的 handOver: true）：Suffuse 停止 keepalive 並離開逐顆 LED 模式，然後進行寫入。新的漸層會以相同方式接管現有的保持。不要在兩個外觀之間執行 restore — 這會閃過舊顏色然後再覆蓋它；當使用者想要恢復到更早的狀態時才使用 restore。
6. 還原是僅限整體裝置的。devStatus 在寫入前被捕捉，並由 restore 重播；先前的逐顆 LED 外觀在任何通道上都不可查詢，收據必須說明這一點，而不是過度聲稱。
7. 如果回覆埠（UDP 4002）被另一個本地控制器佔用，掃描和狀態捕捉會大聲失敗。不要嘗試透過埠共享來繞過此問題 — 兩個監聽者會悄悄竊取彼此的回覆。告訴使用者要退出哪個程序，或使用 --ip 固定裝置。
8. 對於不熟悉的 SKU，請先查閱已挖掘的投資組合 (node scripts/portfolio.mjs <SKU>) — 包含 371 個 SKU 的社群先驗知識，附帶每項事實的出處。在一個規則下閱讀它：挖掘到的正面結果是可信的，挖掘到的負面結果僅代表「未知」 — 供應商標誌描述的是應用程式支援，而非韌體接受的內容。切勿根據挖掘到的標誌或不在投資組合中，就告訴使用者他們的裝置「不支援」逐顆 LED。

透過藍牙連接純 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 或主機缺少藍牙權限（macOS 會殺死未簽署的進程以接觸 CoreBluetooth，除非提示 — 負責的進程，通常是終端應用程式，必須持有權限），請轉發錯誤中的結構化補救措施；所有其他 Suffuse 表面仍然可以運作。

處理無法取得的憑證

如果缺少 GOVEE_API_KEY，請繼續進行分數編寫、fixture、編譯測試和文件記錄。說明即時裝置能力驗證和寫入仍在待處理狀態。切勿要求使用者將金鑰貼到聊天中。

傳回證據收據

報告：

• 選定的 SKU 和經過編輯的裝置身份；
• 所使用的廣告宣稱能力；
• 請求和已執行的模式；
• 後備方案和警告；
• 控制操作的數量和結果；
• 收據路徑（當已寫入時）；
• 還原覆蓋範圍以及任何無法捕捉的狀態。
• 證據摘要陳述和殘餘不確定性；切勿將 accepted 或 sent-unacknowledged 翻譯為可見成功。