mira_live2d · DSH 看板娘プラグイン

xhqm-live2d（WordPress プラグイン）を DSH ネイティブプラグインとして移植：看板娘が会話インターフェースのオーバーレイとして表示され、モデルは MCP ツールで発話・表情切り替え・モデル切り替え・動作切り替えができ、「思考 / 待機確認 / アイドル」に応じて表情が自動で切り替わります。

インストール（任意の DSH web profile）

本プラグインは依存関係のない純 ESM パッケージです：ホスト側は Node 組み込みモジュールのみを使用し、ブラウザ側の実行ライブラリは assets/lib/ にバンドルされています。

1. パッケージのインストール

dsh plugin --profile web add github:xhqm-xyz/mira_live2d

クローン後にローカルパスでインストールすることもできます：

git clone https://github.com/xhqm-xyz/mira_live2d.git
dsh plugin --profile web add ./mira_live2d

2. profile に登録

~/.dsh/profiles/web/cordis.patch.yml の insert リストに追記：

- id: mira_live2d
  name: 'mira_live2d'
  config:
    model: StellaMira          # 初始模型（model 目录名）
    position: right
    tts:
      enabled: false
      provider: openai         # 或 alibaba；base 可覆盖为任意 OpenAI 兼容端点
      keyEnv: 'OPENAI_API_KEY' # 建议用环境变量；或用 key 填字面量（仅本机私有配置）

キーは tts.keyEnv（環境変数名）または tts.key（ローカルのプライベート設定ファイルのみ）で指定してください。リポジトリにコミットしないでください。

3. 再起動

dsh web

ページを更新すると、看板娘が会話インターフェースの右下に表示されます。

Related MCP server: live2d-to-agent

モデル

モデルは model/ ディレクトリに配置し、各モデルはサブディレクトリに置きます。ディレクトリ内に *.model3.json が必須です（model/README.md 参照）。mira_list_models が自動スキャンします。

フロントエンド操作

• ドラッグ移動：マウス / シングルフィンガードラッグ（位置は localStorage に記憶）

• ズーム：ホイール（デスクトップ）/ ピンチ（モバイル）、0.25× ～ 3×（ズームも記憶）；モバイルはデフォルトで mobileScale に従って拡大縮小

• メニュー：右クリック（デスクトップ）/ 長押し（モバイル）で表情 / 動作メニューを表示

• 表情の重ね合わせ：メニューの表情項目は重ね合わせトグルで、クリックでオン/オフ（アクティブ項目には ✓ 表示）；「デフォルト表情」で全表情と重ね合わせをクリア

• バブル：mira_speak / mira_bubble / 思考待機中のヒントがここに表示されます

MCP ツール（モデルが呼び出し可能、接頭辞 mira_）

表情：排他と重ね合わせ

• デフォルトの mira_set_expression(name) は排他置換：新しい表情が前の表情をフェードアウトさせます。

• mira_set_expression(name, stack=true) は重ね合わせトグル：その表情を重ね合わせスタックに追加し、現在の排他表情や他の重ね合わせ表情と共存できます（exp3.json の Blend:Add 加算に依存）。

• 右クリック / 長押しメニューの表情項目は常に重ね合わせトグル（✓ はオンを示す）、1 回クリックでオン、もう 1 回でオフ。

• mira_set_expression("")（空文字）でデフォルトに戻す：排他表情 + 全重ね合わせ表情をクリア。

設定項目

すべてオプション、デフォルト値は lib/index.js の DEFAULTS を参照：

思考 / 待機表情のトリガー

• モデルが生成を開始（agent が running に移行）→ mood: thinking

• モデルが ask_user_question を呼び出した後 → mood: awaiting

• モデルがこのターンを終了（agent が idle に戻る）→ mood: idle、idleClearMs 後にデフォルト表情に戻る

• mira_set_mood で手動設定も可能

サードパーティコンポーネント

assets/lib/ には PixiJS（MIT）、pixi-live2d-display（MIT）、Live2D Cubism Core（プロプライエタリ、Live2D Software License Agreement）がバンドルされています。各コンポーネントの著作権とライセンス全文は THIRD-PARTY-NOTICES.md を参照してください。