workled MCP 컨트롤러은(는) 무엇을 하나요?
강제 상태 프로토콜
모든 상태 전환 시 MCP를 통해 set_agent_state를 호출하세요:
| 상태 | 시점 |
|---|---|
thinking | 모든 응답의 첫 번째 도구 호출 시; 사용자가 메시지를 제출할 때 |
idle | 턴 종료; 세션 종료 시 |
input | 에이전트가 사용자를 기다리는 모든 경우 — 입력 도구(question/ask/confirm) 호출, 클라이언트 측 모달(hermes _confirm_destructive_slash 등) 내부, 또는 일반 텍스트 선택 목록/다중 옵션 질문을 렌더링한 후 사용자의 선택을 기다리는 경우 |
error | 런타임 오류 발생 시 |
턴별 절차 (매 턴마다 순서대로 실행):
- 턴 시작/사용자 메시지 수신 →
set_agent_state("thinking")— 첫 번째 작업, 다른 도구 호출 전에 실행. - 옵션/선택 사항 렌더링, 모달 열기, 질문하기 전에 →
set_agent_state("input"). - 턴 종료, 작업 완료, 더 이상 출력이 없음 →
set_agent_state("idle"). - 런타임 오류/실패한 도구 호출 →
set_agent_state("error").
사전 응답 게이트 — 최종 표시 메시지를 보내기 전에 확인하세요:
- 이번 턴에
set_agent_state를 최소 한 번 호출했습니까? - LED 상태가 표시하려는 내용과 일치합니까? (완료 시 idle, 질문 시 input, 작업 중 thinking)
- 둘 중 하나라도 아니요라면, 올바른
set_agent_state호출을 먼저 보낸 후 응답하세요.
MCP 도구 참조
| 도구 | 속성 | 설명 | 사용법 |
|---|---|---|---|
| set_agent_state | state_name: string | LED를 에이전트 상태(thinking/idle/input/error)로 설정 | set_agent_state("thinking") |
| get_agent_state | — | 현재 에이전트 LED 상태 반환: idle/thinking/input/error (설정되지 않으면 빈 문자열) | get_agent_state() |
| set_brightness | brightness: integer | LED 밝기 0-255; 0 = 꺼짐 | set_brightness(128) |
| get_brightness | — | 현재 LED 밝기 0-255 반환 | get_brightness() |
| set_effect | effect_name: string, effect_json: string | effect_name ∈ led(수동 효과)/idle/thinking/input/error; effect_json은 JSON 문자열 {"type","hue","saturation","value","speed"}입니다. 조명이 먼저 켜져 있어야 합니다(set_brightness > 0). 자연어 색상을 HSV로 매핑(아래 표 참조). | set_effect("led", '{"type":"breathe","hue":180,"speed":50}') |
| get_effect | effect_name: string | effect_name 설정을 JSON으로 가져오기 | get_effect("thinking") |
| set_macro | macro_name: string, macro_json: string | 터치 패드 제스처에 대한 매크로 설정; macro_name ∈ single_click/double_click/long_press_start; macro_json은 세그먼트의 JSON 배열(매크로 형식 참조); 빈 macro_json은 재설정 | set_macro("single_click", '[{"combo":"ctrl+c"}]') |
| get_macro | macro_name: string | 매크로를 JSON 배열 문자열로 반환, 설정되지 않으면 빈 문자열(비밀번호 값은 마스킹) | get_macro("single_click") |
자연어 색상을 set_effect에 매핑
사용자가 애니메이션을 요청하지 않는 한 type:"solid"를 사용하세요. 색상 이름을 HSV로 매핑:
| 설명 | type | hue | saturation | value |
|---|---|---|---|---|
| 순수 흰색 | solid | 0 | 0 | 255 |
| 따뜻한 흰색 | solid | 30 | 80 | 255 |
| 빨간색 | solid | 0 | 255 | 255 |
| 주황색 | solid | 30 | 255 | 255 |
| 노란색 | solid | 60 | 255 | 255 |
| 초록색 | solid | 120 | 255 | 255 |
| 청록/틸 | solid | 180 | 255 | 255 |
| 파란색 | solid | 240 | 255 | 255 |
| 보라색 | solid | 270 | 255 | 255 |
| 분홍색 | solid | 330 | 200 | 255 |
| 어두움/야간 모드 | solid | 30 | 80 | 60 |
| 무지개 (애니메이션) | rainbow | - | - | - |
경험 법칙: hue 0-359로 색조 선택, saturation 0-255 (0 = 흰색/파스텔, 255 = 선명), value 0-255 밝기. 파스텔/흰색 톤은 낮은 채도 사용; 선명한 톤은 255 사용.
매크로 형식
전체 매크로 참조 macro_format.md
설정 및 문제 해결
장치가 응답하지 않으면 node <skill-dir>/index.js status를 실행하고 출력된 JSON hint를 따르세요. 전체 설치/배포/문제 해결 참조: device_setup.md