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. 在 profile 里登记

在 ~/.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。