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_live2d2. 在 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 |
provider 默认 | 模型 / 音色 |
思考 / 等待表情如何触发
- 模型开始生成（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。