看板娘浮层 xhqm-xyz/mira_live2d

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

刷新页面后看板娘出现在对话界面右下角。

模型

模型放 model/ 目录，每个模型一个子目录，目录内必须含 *.model3.json（见 model/README.md）。mira_list_models 自动扫描。

前端交互

- 拖拽移动：鼠标 / 单指拖动（位置记忆到 localStorage）
- 缩放：滚轮（桌面）/ 双指捏合（移动端），0.25× ~ 3×（缩放记忆）；移动端默认按 mobileScale 缩放
- 菜单：右键（桌面）/ 长按（移动端）呼出表情 / 动作菜单
- 表情叠加：菜单里的表情项是叠加开关，点击开/关（活跃项标 ✓）；「默认表情」清空全部表情与叠加
- 气泡：mira_speak / mira_bubble / 思考等待提示在此显示

MCP 工具（模型可调用，前缀 mira_）

| 工具 | 说明 |
| mira_get_state | 在线与否、显隐、当前模型/表情/动作/语句、表情/动作列表、开关、思考等待配置、可切换模型 |
| mira_list_models | 列出 model 文件夹所有模型 |
| mira_get_model_capabilities | 解析 model3.json 返回表情/动作清单 |
| mira_switch_model | 切换展出模型 |
| mira_set_expression | 切换/叠加表情（空串恢复默认；stack=true 叠加并存） |
| mira_play_motion | 播放动作组 |
| mira_speak | TTS 合成语音 + 气泡（让模型说话） |
| mira_bubble | 只显示气泡不朗读 |
| mira_show / mira_hide | 显示 / 隐藏 |
| mira_set_expressions_enabled | 开/关表情系统 |
| mira_set_animations_enabled | 开/关动作播放 |
| mira_set_mood | 手动设置 thinking / awaiting / idle |
| mira_set_persona | 设置思考/等待表情、气泡与空闲清除延迟 |
| mira_get_config | 读取当前配置（TTS key 不回传明文） |

表情：互斥与叠加

- 默认 mira_set_expression(name) 为互斥替换：新表情会淡出上一个表情。
- mira_set_expression(name, stack=true) 为叠加开关：把该表情加入叠加栈，可与当前互斥表情、其它叠加表情并存（依赖 exp3.json 的 Blend:Add 加算）。
- 右键 / 长按菜单里的表情项一律是叠加开关（✓ 表示已开启），点一次开、再点一次关。
- mira_set_expression("")（空串）恢复默认：清空互斥表情 + 全部叠加表情。

配置项

全部可选，默认值见 lib/index.js 的 DEFAULTS：

| 键 | 默认 | 说明 |
| enabled | true | 总开关 |
| model | '' | 初始模型（model 目录名） |
| modelsDir | 插件 model/ | 模型目录覆盖 |
| canvas.w/h | 480/630 | 画布内部分辨率 |
| position | right | 初始 left / right |
| mobileScale | 55 | 移动端缩放百分比 |
| showHint | true | 首次显示操作提示 |
| pollIntervalMs | 1500 | 指令轮询间隔 |
| persona.thinking.{expression,bubble} | '' | 思考时表情/气泡（默认空） |
| persona.awaiting.{expression,bubble} | '' | 等待确认时表情/气泡（默认空） |
| persona.idleClearMs | 3200 | 空闲后清除表情的延迟 |
| tts.enabled | false | TTS 开关 |
| tts.provider | openai | openai / alibaba |
| tts.base | provider 默认 | 接口基地址 |
| tts.key | '' | API Key（字面量） |
| tts.keyEnv | '' | 存 API Key 的环境变量名 |
| tts.model / tts.voice | 服务商默认 | 模型 / 音色 |

思考 / 等待表情如何触发

- 模型开始生成（智能体进入 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。