mira_live2d · DSH Mascot Plugin

Ports xhqm-live2d (WordPress plugin) to a native DSH plugin: the mascot appears as a floating overlay in the conversation interface, and the model can speak, switch expressions, switch models, and play motions via MCP tools, with expressions automatically switching based on "thinking / awaiting confirmation / idle" states.

Installation (any DSH web profile)

This plugin is a dependency-free pure ESM package: the host side only uses Node built-in modules, and the browser-side runtime library is bundled in assets/lib/.

1. Install the package

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

You can also clone it and install from a local path:

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

2. Register it in the profile

Append to the insert list in ~/.dsh/profiles/web/cordis.patch.yml:

- 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 填字面量（仅本机私有配置）

For the API key, use tts.keyEnv (environment variable name) or tts.key (private config file on this machine only). Never commit it to the repository.

3. Restart

dsh web

After refreshing the page, the mascot appears in the bottom-right corner of the conversation interface.

Related MCP server: live2d-to-agent

Models

Models go in the model/ directory, one subdirectory per model, and each directory must contain a *.model3.json file (see model/README.md). mira_list_models scans automatically.

Frontend Interaction

• Drag to move: mouse / single-finger drag (position remembered in localStorage)

• Zoom: mouse wheel (desktop) / pinch (mobile), 0.25× ~ 3× (zoom remembered); on mobile, scales by mobileScale by default

• Menu: right-click (desktop) / long-press (mobile) to bring up the expression / motion menu

• Expression stacking: expression items in the menu are stacking toggles; click to turn on/off (active items are marked with ✓); "Default expression" clears all expressions and stacks

• Bubble: mira_speak / mira_bubble / thinking-waiting prompts are displayed here

MCP Tools (callable by the model, prefixed with mira_)

Expressions: Mutually Exclusive and Stacking

• By default, mira_set_expression(name) is a mutually exclusive replacement: the new expression fades out the previous one.

• mira_set_expression(name, stack=true) is a stacking toggle: adds the expression to the stack, where it can coexist with the current exclusive expression and other stacked expressions (relies on Blend:Add in exp3.json).

• Expression items in the right-click / long-press menu are always stacking toggles (✓ means enabled); click once to turn on, click again to turn off.

• mira_set_expression("") (empty string) restores the default: clears the exclusive expression + all stacked expressions.

Configuration Options

All optional; defaults are in DEFAULTS in lib/index.js:

How Thinking / Awaiting Expressions Are Triggered

• Model starts generating (agent enters running) → mood: thinking

• Model calls ask_user_question → mood: awaiting

• Model finishes the turn (agent returns to idle) → mood: idle, and the default expression is restored after idleClearMs

• You can also set it manually with mira_set_mood

Third-Party Components

assets/lib/ bundles PixiJS (MIT), pixi-live2d-display (MIT), and Live2D Cubism Core (proprietary, Live2D Software License Agreement). The full copyright and license texts for each component are in THIRD-PARTY-NOTICES.md.