mira_live2d · DSH-Maskottchen-Plugin

Portierung von xhqm-live2d (WordPress-Plugin) als natives DSH-Plugin: Das Maskottchen erscheint als schwebende Ebene im Chat-Interface. Das Modell kann über MCP-Tools sprechen, Ausdrücke wechseln, Modelle wechseln und Aktionen ausführen und wechselt automatisch den Ausdruck je nach „Denken / Warten auf Bestätigung / Leerlauf".

Installation (beliebiges DSH-Webprofil)

Dieses Plugin ist ein dependencies-freies reines ESM-Paket: Der Host verwendet nur Node-eingebaute Module, die Browser-Laufzeitbibliothek ist in assets/lib/ gebündelt.

1. Paket installieren

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

Alternativ kann das Repository geklont und über den lokalen Pfad installiert werden:

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

2. Im Profil registrieren

In der insert-Liste von ~/.dsh/profiles/web/cordis.patch.yml ergänzen:

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

Der Schlüssel sollte über tts.keyEnv (Umgebungsvariablenname) oder tts.key (nur in lokaler privater Konfigurationsdatei) bezogen werden – niemals ins Repository committen.

3. Neustart

dsh web

Nach dem Aktualisieren der Seite erscheint das Maskottchen unten rechts im Chat-Interface.

Related MCP server: live2d-to-agent

Modelle

Modelle liegen im Verzeichnis model/, jedes Modell in einem eigenen Unterverzeichnis, das zwingend eine *.model3.json enthalten muss (siehe model/README.md). mira_list_models scannt automatisch.

Frontend-Interaktion

• Ziehen & Verschieben: Mit Maus / einem Finger ziehen (Position wird in localStorage gespeichert)

• Skalierung: Mausrad (Desktop) / Zwei-Finger-Zoom (Mobil), 0,25× ~ 3× (Skalierung wird gespeichert); auf Mobilgeräten standardmäßig nach mobileScale skaliert

• Menü: Rechtsklick (Desktop) / langes Drücken (Mobil) öffnet Ausdrucks-/Aktionsmenü

• Ausdrucks-Overlay: Die Ausdruckspunkte im Menü sind Overlay-Schalter, Klicken zum Ein-/Ausschalten (aktive Punkte sind mit ✓ markiert); „Standardausdruck" löscht alle Ausdrücke und Overlays

• Sprechblase: mira_speak / mira_bubble / Denk-Warte-Hinweise werden hier angezeigt

MCP-Tools (vom Modell aufrufbar, Präfix mira_)

Ausdrücke: Gegenseitige Ausschließung und Überlagerung

• Standardmäßig ist mira_set_expression(name) eine gegenseitig ausschließende Ersetzung: Der neue Ausdruck blendet den vorherigen aus.

• mira_set_expression(name, stack=true) ist ein Overlay-Schalter: Der Ausdruck wird zum Overlay-Stack hinzugefügt und kann parallel zum aktuellen exklusiven Ausdruck und anderen Overlay-Ausdrücken existieren (abhängig von der Blend:Add-Addition in exp3.json).

• Die Ausdruckspunkte im Rechtsklick-/Langdruck-Menü sind immer Overlay-Schalter (✓ bedeutet aktiviert), einmal antippen zum Aktivieren, erneut antippen zum Deaktivieren.

• mira_set_expression("") (leerer String) stellt den Standard wieder her: löscht den exklusiven Ausdruck + alle Overlay-Ausdrücke.

Konfigurationsoptionen

Alle optional, Standardwerte siehe DEFAULTS in lib/index.js:

Wie Denk-/Warte-Ausdrücke ausgelöst werden

• Modell beginnt mit der Generierung (Agent wechselt in running) → mood: thinking

• Modell ruft ask_user_question auf → mood: awaiting

• Modell beendet die Runde (Agent zurück in idle) → mood: idle, nach idleClearMs wird der Standardausdruck wiederhergestellt

• Alternativ manuell über mira_set_mood setzen

Drittanbieter-Komponenten

assets/lib/ bündelt PixiJS (MIT), pixi-live2d-display (MIT) und Live2D Cubism Core (proprietär, Live2D Software License Agreement). Urheberrechte und Lizenztexte der jeweiligen Komponenten finden sich in THIRD-PARTY-NOTICES.md.