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 | 以 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