andyed/suffuse

suffuse은(는) 무엇을 하나요?

이 스킬을 로컬 MCP 서버와 함께 Govee 조명 제어의 두 에이전트 대면 부분으로 사용하세요. 스킬은 워크플로와 판단을 제공하고, 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. 사용자가 이미 조명을 변경하라는 직접적인 명령을 제공하지 않은 한, 수정된 드라이 런(dry run)을 보여줍니다.
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를 읽습니다. 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을 통해 LED별로 페인팅

lan 명령은 API 키 없이 로컬 네트워크의 기기에 도달하며, 확인된 픽셀 프로필이 있는 조명기구의 LED별 페인팅을 포함합니다. 위의 워크플로는 여전히 적용됩니다. 이러한 규칙은 추가적이며 각각 하드웨어 측정된 교훈을 인코딩합니다:

1. 먼저 스캔합니다 (lan scan) — 읽기 전용이며, 발견된 조명기구 중 LED별을 지원하는 것과 픽셀 수가 하드웨어 확인되었는지 보고합니다. 멀티캐스트 검색은 기기별로 간헐적이므로 짧거나 부분적인 스캔에서 "LAN 지원 없음"이라고 결론짓지 마십시오.
2. LED별 의도를 일반 그라디언트 LightScore로 작성합니다. 밴드는 작성된 순서대로 픽셀로 컴파일됩니다. 의도적으로 임의의 픽셀별 배열은 없습니다. 영역이 적은 조명기구는 색조 휠을 따라 긴 경로로 중지점 사이를 보간하기 때문이며, 밴드 순서는 인접 픽셀이 색조에서 인접하게 유지되도록 합니다.
3. LED별 쓰기가 렌더링되었다고 주장하지 마십시오. 채널은 묵음입니다 — 확인, 쿼리 가능한 세그먼트 상태가 없습니다. 결과는 verified: false를 전달합니다. 오직 눈(또는 사용자)만이 확인할 수 있으며, 스킬은 그렇게 말해야 합니다.
4. 지속 시간을 명시적으로 만듭니다. LED별 룩은 데이터가 중단된 후 약 1분 후에 기기 자체 효과로 되돌아갑니다. --hold-seconds를 사용하여 제한된 유지 시간(기본값 900, 최대 14400)을 설정하고, 룩이 종료될 시간을 사용자에게 알립니다. lan release를 사용하여 조기 종료합니다.
5. 절대 작성자를 혼합하지 마십시오. 유지가 활성화된 동안 해당 조명기구에 대한 전체 기기 색상 쓰기는 거부됩니다 — 전체 기기 명령은 모든 픽셀을 다시 칠하고 LED별 룩을 평평하게 만듭니다. 유지 중인 조명기구를 의도적으로 단색으로 전환하려면 --hand-over(MCP handOver: true)를 전달합니다: Suffuse는 킵얼라이브를 중지하고 LED별 모드를 종료한 다음 쓰기를 수행합니다. 새 그라디언트는 동일한 방식으로 기존 유지를 인계받습니다. 두 룩 사이에서 restore하지 마십시오 — 이전 색상을 깜빡인 후에야 덮어씁니다. 사용자가 이전 상태를 원할 때 복원하십시오.
6. 복원은 전체 기기에만 해당됩니다. devStatus는 쓰기 전에 캡처되어 restore에 의해 재생됩니다. 이전 LED별 룩은 어떤 채널에서도 쿼리할 수 없으며, 영수증은 과장하지 않고 이를 언급해야 합니다.
7. 회신 포트(UDP 4002)가 다른 로컬 컨트롤러에 의해 점유된 경우, 스캔 및 상태 캡처가 실패하고 큰 오류가 발생합니다. 포트 공유로 해결하지 마십시오 — 두 리스너가 서로의 회신을 조용히 훔칩니다. 종료할 프로세스를 사용자에게 알리거나 기기를 --ip로 고정합니다.
8. 익숙하지 않은 SKU의 경우, 먼저 마이닝된 포트폴리오를 참조하십시오 (node scripts/portfolio.mjs <SKU>) — 사실별 출처가 있는 371 SKU의 커뮤니티 사전 정보. 한 가지 규칙으로 읽습니다: 마이닝된 긍정은 신뢰할 수 있고, 마이닝된 부정은 단지 "알 수 없음"입니다 — 공급업체 플래그는 앱 지원을 설명하며 펌웨어가 허용하는 것을 설명하지 않습니다. 마이닝된 플래그나 포트폴리오 부재만으로 사용자에게 기기가 LED별을 "지원하지 않는다"고 말하지 마십시오.

블루투스를 통해 BLE 전용 하드웨어에 도달

ble 명령은 LAN이 구조적으로 도달할 수 없는 램프(H6009 클래스: 클라우드에 나열됨, LAN 제어 없음)에 도달합니다 — 키가 없고 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가 없으면 점수 작성, 픽스처, 컴파일 테스트 및 문서화를 계속하십시오. 라이브 기기 기능 확인 및 쓰기가 보류 중임을 명시하십시오. 사용자에게 채팅에 키를 붙여넣도록 요청하지 마십시오.

증거 영수증 반환

보고:

• 선택된 SKU 및 수정된 기기 ID;
• 사용된 광고된 능력;
• 요청 및 실행된 모드;
• 대체 및 경고;
• 제어 작업 수 및 결과;
• 작성된 경우 영수증 경로;
• 복원 범위 및 캡처할 수 없는 상태.
• 증거 요약문 및 잔여 불확실성; accepted 또는 sent-unacknowledged를 가시적 성공으로 번역하지 마십시오.