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. Регистрация в профиле

Добавьте в список insert в ~/.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 填字面量（仅本机私有配置）

Для ключей используйте 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) — это переключатель наложения: добавляет выражение в стек наложения, может сосуществовать с текущим взаимоисключающим выражением и другими наложенными выражениями (зависит от аддитивного смешивания Blend:Add в exp3.json).

• Пункты выражений в меню правого клика / долгого нажатия всегда являются переключателями наложения (✓ означает включено): нажмите один раз, чтобы включить, ещё раз — чтобы выключить.

• mira_set_expression("") (пустая строка) восстанавливает значение по умолчанию: очищает взаимоисключающее выражение и все наложенные выражения.

Параметры конфигурации

Все параметры необязательны, значения по умолчанию см. в DEFAULTS в lib/index.js:

Как запускаются выражения размышления / ожидания

• Модель начинает генерацию (агент переходит в running) → mood: thinking

• Модель вызывает ask_user_question → mood: awaiting

• Модель завершает текущий цикл (агент возвращается в 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.