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を少なくとも1回呼び出しましたか？ - LED の状態はこれから表示しようとしている内容と一致していますか？(完了なら idle、質問中なら input、作業中なら thinking)
- いずれかが NO の場合、正しい
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 | - | - | - |
経験則: 色相 0-359 で色を選び、彩度 0-255 (0 = 白/パステル、255 = 鮮やか)、明度 0-255 で明るさを調整します。パステル/白系の色調は低彩度、鮮やかな色調は 255 を使用します。
マクロ形式
完全なマクロリファレンス: macro_format.md
セットアップとトラブルシューティング
デバイスが応答しない場合は、node <skill-dir>/index.js status を実行し、出力される JSON の hint に従ってください。完全なインストール / デプロイ / トラブルシューティングリファレンス: device_setup.md