¿Qué hace workled MCP Controller?
Protocolo de Estado Obligatorio
Llama a set_agent_state vía MCP en cada transición de estado:
| Estado | Cuándo |
|---|---|
thinking | Primera llamada de herramienta de cada respuesta; el usuario envía un mensaje |
idle | Turno finalizado; sesión terminada |
input | Cualquier momento en que el agente esté esperando al usuario — llamando a una herramienta de entrada (question/ask/confirm), dentro de un modal del lado del cliente (hermes _confirm_destructive_slash, etc.), o después de renderizar una lista de opciones en texto plano / pregunta de opción múltiple y esperando la selección del usuario |
error | Ocurrió un error en tiempo de ejecución |
Procedimiento por turno (ejecutar cada turno, en orden):
- Turno iniciando / mensaje del usuario recibido →
set_agent_state("thinking")— primera acción, antes de cualquier otra llamada de herramienta. - Antes de renderizar opciones / elecciones / abrir cualquier modal / hacer una pregunta →
set_agent_state("input"). - Fin del turno, trabajo completado, sin salida pendiente →
set_agent_state("idle"). - Error en tiempo de ejecución / llamada de herramienta fallida →
set_agent_state("error").
Verificación Pre-Respuesta — comprueba ANTES de emitir tu mensaje visible final:
- ¿Llamé a
set_agent_stateal menos una vez en este turno? - ¿El estado del LED coincide con lo que voy a mostrar (idle si terminé, input si estoy preguntando, thinking si aún estoy trabajando)?
- Si alguna es NO, emite la llamada correcta de
set_agent_stateprimero, luego la respuesta.
Referencia de Herramientas MCP
| Herramienta | Propiedad | Descripción | Uso |
|---|---|---|---|
| set_agent_state | state_name: string | Establece el LED para reflejar el estado del agente (thinking/idle/input/error) | set_agent_state("thinking") |
| get_agent_state | — | Devuelve el estado actual del LED del agente: idle/thinking/input/error (cadena vacía si no está establecido) | get_agent_state() |
| set_brightness | brightness: integer | Brillo del LED 0-255; 0 = apagado | set_brightness(128) |
| get_brightness | — | Devuelve el brillo actual del LED (0-255) | get_brightness() |
| set_effect | effect_name: string, effect_json: string | effect_name ∈ led(efecto manual)/idle/thinking/input/error; effect_json es una cadena JSON {"type","hue","saturation","value","speed"}. La luz debe estar encendida primero (set_brightness > 0). Mapea colores en lenguaje natural a HSV (ver tabla a continuación). | set_effect("led", '{"type":"breathe","hue":180,"speed":50}') |
| get_effect | effect_name: string | Obtiene la configuración de effect_name como JSON | get_effect("thinking") |
| set_macro | macro_name: string, macro_json: string | Establece la macro para un gesto del panel táctil; macro_name ∈ single_click/double_click/long_press_start; macro_json es un arreglo JSON de segmentos (ver Formato de Macro); macro_json vacío lo reinicia | set_macro("single_click", '[{"combo":"ctrl+c"}]') |
| get_macro | macro_name: string | Devuelve la macro como una cadena de arreglo JSON, o cadena vacía si no está establecida (los valores de contraseña se ocultan) | get_macro("single_click") |
Mapeo de colores en lenguaje natural a set_effect
Usa type:"solid" a menos que el usuario solicite una animación. Mapea un nombre de color a HSV:
| Descripción | type | hue | saturation | value |
|---|---|---|---|---|
| blanco puro | solid | 0 | 0 | 255 |
| blanco cálido | solid | 30 | 80 | 255 |
| rojo | solid | 0 | 255 | 255 |
| naranja | solid | 30 | 255 | 255 |
| amarillo | solid | 60 | 255 | 255 |
| verde | solid | 120 | 255 | 255 |
| cian/verde azulado | solid | 180 | 255 | 255 |
| azul | solid | 240 | 255 | 255 |
| púrpura/violeta | solid | 270 | 255 | 255 |
| rosa | solid | 330 | 200 | 255 |
| tenue/modo nocturno | solid | 30 | 80 | 60 |
| arcoíris (animado) | rainbow | - | - | - |
Regla general: hue 0-359 selecciona el tono, saturation 0-255 (0 = blanco/pastel, 255 = vívido), value 0-255 brillo. Los tonos pastel/blanco usan saturación baja; los tonos vívidos usan 255.
Formato de Macro
Referencia completa de macros: macro_format.md
Configuración y Solución de Problemas
Si el dispositivo no responde, ejecuta node <skill-dir>/index.js status
y sigue la pista hint JSON que imprime. Referencia completa de instalación/implementación/solución de problemas: device_setup.md
Contribuciones
- Repositorio: https://github.com/git-hub-cloud/workled
- Incidencias: https://github.com/git-hub-cloud/workled/issues