AI 連携
デスクトップキャラクターが AI の会話に反応します。イベントへのリアクション、調査結果のナレーション、他のキャラクターとのディベート、フローティングパネルでの情報表示など、さまざまなことが可能です。AI 連携は、お気に入りの AI ツールを Desktop Homunculus に接続します。
必要なもの
- Desktop Homunculus がインストールされて起動中であること
- AI クライアント — 以下のいずれか：
- （オプション） 音声・ナレーション用に VoiceVox MOD がインストールされていること
キャラクターにできること
| 機能 | 説明 |
|---|---|
| リアクション＆表情 | 表情（expression）、アニメーション、プリセットリアクション（嬉しい、考え中、驚き、困惑など） |
| 話す | VoiceVox を利用した音声合成ナレーション |
| 移動 | 画面上の任意の位置へテレポートまたはスムーズなアニメーション移動 |
| 情報の表示 | キャラクター付近に固定されたフローティング WebView パネル — HTML コンテンツ、ダッシュボード、プレゼンテーション |
| MOD コマンドの実行 | インストール済み MOD の機能をトリガー |
| 個性を持つ | ペルソナ（persona）によって各キャラクターにディベートやレビューでの独自の視点を付与 |
仕組み
このセクションは技術的なアーキテクチャの説明です。すぐに始めたい場合は、次のステップに進んでください。
Desktop Homunculus は Model Context Protocol（MCP） を通じてキャラクター制御を公開しています。MCP サーバー（@hmcs/mcp-server）が AI エージェントとアプリケーションの橋渡しをします：
[AI エージェント] <— MCP (stdio) —> [@hmcs/mcp-server] <— HTTP —> [Desktop Homunculus :3100]
- MCP サーバーは AI クライアントが起動する Node.js サブプロセスです
localhost:3100の HTTP 経由で Desktop Homunculus と通信します（ローカルのみ）- ツールが動作するには Desktop Homunculus が起動している必要があります
- デフォルト以外のホストやポートを使用する場合は
HOMUNCULUS_HOST環境変数を設定してください
MCP プリミティブ
| プリミティブ | 数 | 目的 |
|---|---|---|
| Tools | 20 | アトミックなアクション — キャラクターの移動、発話、WebView を開く、表情の設定など |
| Resources | 4 | 読み取り専用の状態 — homunculus://characters、homunculus://mods、homunculus://assets、homunculus://info |
| Prompts | 3 | 定義済みのインタラクションパターン（下記参照） |
プロンプト
プロンプトは一般的なワークフローへの最も簡単なエントリポイントです：
developer-assistant— 開発イベント（ビルド成功、テスト失敗、デプロイなど）に自動で反応。キャラクターがイベントに合わせた表情、アニメーション、効果音を再生します。character-interaction— キャラクターとの自然な会話。ムードパラメータ（happy、playful、serious、encouraging）をサポートします。mod-command-helper— 利用可能な MOD コマンドの発見と説明。homunculus://modsリソースを読み取って、インストール済みの内容を確認します。
自己発見パターン
AI エージェントはツールを呼び出す前に homunculus://characters と homunculus://mods リソースを読み取るべきです。これにより、どのキャラクターがロードされているか、どの MOD コマンドが利用可能かをエージェントが把握できます。mod-command-helper プロンプトがこのパターンのモデルとなっています。
ステートフルセッション
MCP サーバーはセッション内でアクティブなキャラクターを追跡します。select_character の呼び出しは以降のすべてのツール呼び出しに影響します。set_persona で設定されたペルソナもセッション内で保持されます。
ツールの完全なリファレンスは MCP リファレンスをご覧ください。
ユースケース
- 開発イベントリアクション —
developer-assistantプロンプトを使用します。ビルドの成功/失敗、テストの合否、コードのデプロイ時に、キャラクターが表情、アニメーション、効果音で自動的に反応します。 - 調査＆プレゼンテーション — 音声ナレーションと WebView パネルを組み合わせます。キャラクターが調査結果を説明しながら、キャラクター付近のフローティングパネルに補足資料を表示します。
- マルチキャラクターディベート — 異なるペルソナを持つ複数のキャラクターを生成します。各キャラクターがディスカッションに異なる視点で参加します。AI エージェントチームとの連携に適しています。
- コードレビューコンパニオン — キャラクターがコード変更に反応し、WebView パネルにレビューフィードバックを表示します。異なるペルソナでセキュリティ、パフォーマンス、可読性など、異なる観点に焦点を当てることができます。
既知の制限事項
AI 連携は現在動作していますが、一部のワークフローにはパフォーマンス上の制約があります：
- WebView 生成のレイテンシ — AI が推論中にフル HTML コンテンツをインラインで生成する場合、コンテンツの表示が遅くなります。これはリアルタイムのコンテンツ生成に固有のものです。
- TTS 音声レイテンシ — VoiceVox を通じた音声生成は、特に長いテキストで顕著な遅延があります。
今後の方向性：テンプレート MOD
解決策は、ビルド済みの WebView アセットを同梱する専用のテンプレート MOD です。AI がゼロから HTML を生成する代わりに、MOD コマンドを通じてデータを埋め込みます。これは open_webview がビルド済みのローカルアセットをロードする既存の MOD アセットシステムを活用します。
テンプレート MOD の作成や MCP ツールの改善に貢献したい場合は、コントリビューティングガイドをご覧ください。
次のステップ
- AI クライアントのセットアップ — 数分で接続
- MCP 機能の確認 — 20 のツール、4 つのリソース、3 つのプロンプトの完全なリファレンス
- MOD を作成する — より豊かな AI ワークフローのためのテンプレート MOD を作成