mira_live2d · Plugin de mascota para DSH

Porta xhqm-live2d (plugin de WordPress) como plugin nativo de DSH: la mascota aparece como capa flotante en la interfaz de conversación; el modelo puede hablar, cambiar de expresión, de modelo y de acción mediante herramientas MCP, y cambia automáticamente de expresión según «pensando / esperando confirmación / inactivo».

Instalación (cualquier perfil web de DSH)

Este plugin es un paquete ESM puro sin dependencias: el lado del host solo utiliza los módulos integrados de Node.js, y la librería de ejecución del lado del navegador ya está empaquetada en assets/lib/.

1. Instalar el paquete

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

También se puede clonar e instalar desde una ruta local:

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

2. Registrarlo en el perfil

Añade a la lista insert de ~/.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 填字面量（仅本机私有配置）

La clave se configura mediante tts.keyEnv (nombre de variable de entorno) o tts.key (solo en el archivo de configuración privado local). No la confirmes en el repositorio.

3. Reiniciar

dsh web

Tras actualizar la página, la mascota aparece en la esquina inferior derecha de la interfaz de conversación.

Related MCP server: live2d-to-agent

Modelos

Los modelos se colocan en el directorio model/, un subdirectorio por modelo; dentro del directorio debe existir *.model3.json (consulta model/README.md). mira_list_models los escanea automáticamente.

Interacción en el frontend

• Arrastrar para mover: arrastre con el ratón / con un dedo (la posición se guarda en localStorage)

• Zoom: rueda del ratón (escritorio) / pellizco con dos dedos (móvil), 0.25× ~ 3× (el zoom se recuerda); en móvil se escala por defecto según mobileScale

• Menú: clic derecho (escritorio) / pulsación larga (móvil) abre el menú de expresiones / acciones

• Superposición de expresiones: los elementos de expresión del menú son conmutadores de superposición: clic para activar/desactivar (los elementos activos se marcan con ✓); «Expresión por defecto» limpia todas las expresiones y superposiciones

• Burbuja: mira_speak / mira_bubble / los avisos de pensamiento y espera se muestran aquí

Herramientas MCP (invocables por el modelo, prefijo mira_)

Expresiones: exclusión mutua y superposición

• Por defecto, mira_set_expression(name) es un reemplazo exclusivo: la nueva expresión desvanece la anterior.

• mira_set_expression(name, stack=true) es un conmutador de superposición: añade la expresión a la pila de superposición y puede coexistir con la expresión exclusiva actual y con otras expresiones superpuestas (depende de la suma aditiva Blend:Add de exp3.json).

• Los elementos de expresión del menú de clic derecho / pulsación larga son siempre conmutadores de superposición (✓ indica activado); un clic los activa y otro clic los desactiva.

• mira_set_expression("") (cadena vacía) restaura el valor por defecto: limpia la expresión exclusiva + todas las expresiones superpuestas.

Opciones de configuración

Todas son opcionales; los valores predeterminados se encuentran en DEFAULTS de lib/index.js:

Cómo se activan las expresiones de pensamiento / espera

• Cuando el modelo empieza a generar (el agente entra en running) → mood: thinking

• Después de que el modelo llame a ask_user_question → mood: awaiting

• Cuando el modelo termina la ronda (el agente vuelve a idle) → mood: idle; tras idleClearMs se restaura la expresión por defecto

• También se puede establecer manualmente con mira_set_mood

Componentes de terceros

assets/lib/ incluye PixiJS (MIT), pixi-live2d-display (MIT) y Live2D Cubism Core (propietario, Live2D Software License Agreement). El texto completo de los derechos de autor y las licencias de cada componente se encuentra en THIRD-PARTY-NOTICES.md.