mira_live2d · DSH 마스코트 플러그인

xhqm-live2d(WordPress 플러그인)를 DSH 네이티브 플러그인으로 포팅했습니다: 마스코트가 대화 인터페이스의 오버레이로 나타나며, 모델은 MCP 도구를 통해 말하고, 표정을 바꾸고, 모델을 전환하고, 동작을 전환할 수 있으며, '생각 중 / 확인 대기 / 유휴' 상태에 따라 표정이 자동으로 전환됩니다.

설치(모든 DSH 웹 프로필)

이 플러그인은 의존성이 없는 순수 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. 프로필에 등록

~/.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 가산에 의존).

• 오른쪽 클릭 / 길게 누르기 메뉴의 표정 항목은 항상 오버레이 토글입니다(✓는 켜짐을 의미). 한 번 클릭하면 켜지고, 다시 클릭하면 꺼집니다.

• 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를 참조하세요.