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 格式取得 effect_name 的設定 | 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