Live2D 看板娘 Stella-Mira/mira_live2d

mira_live2d · DSH 看板娘插件

把 Live2D 看板娘做成 DSH 会话界面的浮层：默认隐藏，界面上有常驻开关按钮；菜单里可切换模型、表情、动作与背景图；模型能通过 TTS 说话，也能把当前画面截图落盘。

本版（3.0.0）按 重构插件/任务书.txt 与 重构插件/PLAN.md §1.7 重构：

- 入口拆成 lib/index.js（装配/路由/单实例/热加载）+ models.js + tts.js + shot.js + state.js + tools.js
- 配置与状态统一落 $DSH_HOME/mira_config/mira_live2d/，带 schemaVersion
- 所有工具返回 JSON 文本（旧版返回中文纯文本；这是破坏性变化，见「迁移」）
- 模型/表情/动作文件缺失时逐条报出文件名与修复位置，不静默留白

仅依赖 Node 内置模块；前端运行库仍捆绑在 assets/lib/，没有新增 CDN 或第三方依赖。

落盘位置（先看这个）

$DSH_HOME = 环境变量 DSH_HOME（trim 后非空）→ 否则 ~/.dsh。
例如 DSH_HOME=/home/you/.dsh 时，实际是 /home/you/.dsh/mira_config/mira_live2d/。

$DSH_HOME/mira_config/mira_live2d/
├── config.json 配置（schemaVersion=2；不存在 = 全默认） ├── state.json 状态（schemaVersion=1；默认 visible:false） ├── creds/tts.json TTS 凭据（权限 600，永不回显） ├── model/ 默认模型目录（modelsDir 默认值） ├── image/ 默认背景图目录（imageDir 默认值） └── media/ 截图落盘目录（shot.mediaDir 默认值）

看一眼就知道该放哪：三个目录在插件加载时会自动创建；model/ 与 image/ 里没有内容时，对应工具会返回 config/missing 并带上完整路径，不会静默空白。

插件仓库自带的 model/StellaMira、model/SylviaMuse 是资产示例，不是默认模型目录。想直接用它们，把 modelsDir 指向 <插件目录>/model，或把模型目录复制到上面的 model/ 下（见「迁移」）。

安装与装配

dsh plugin --profile web add github:Stella-Mira/mira_live2d

在 ~/.dsh/profiles/web/cordis.patch.yml 的 insert 列表登记：

- id: mira_live2d
name: 'mira_live2d'
config: {} # 新配置优先写 config.json；这里只作为旧位置的兼容兜底

inject: ['webServer', 'tools']：webServer 是硬依赖（前端脚本注入 /live2d/assets/...、指令轮询、截图上传都靠它）。DSH web 档自带 ctx.webServer.register / tapIndex。

配置表

配置文件：$DSH_HOME/mira_config/mira_live2d/config.json，必须带 schemaVersion: 2；不匹配会拒绝使用并给迁移提示，不会静默兼容。

优先级：内置默认值 < profile 里的旧插件 config < config.json。同名项以 config.json 为准；profile 只用于兼容老用户（搬完后建议删掉，见「迁移」）。

| 键 | 默认值 | 说明 |
| schemaVersion | 2 | 必填。旧文件先备份，按「迁移」转换 |
| enabled | true | 总开关。只在加载时判断；改它需要重载插件 |
| model | '' | 初始模型名（modelsDir 下目录名）。留空 = 不指定，不自动挑默认模型；用工具/菜单显式选 |
| modelsDir | $DSH_HOME/mira_config/mira_live2d/model | 模型根目录。留空用默认；相对路径按 mira_live2d/ 解析 |
| imageDir | $DSH_HOME/mira_config/mira_live2d/image | 背景图根目录。留空用默认 |
| canvas.w / canvas.h | 480 / 630 | 画布内部分辨率 |
| position | right | 初始位置 left / right（用户拖过之后以 localStorage 为准） |
| mobileScale | 55 | 移动端初始缩放百分比 |
| showHint | true | 首次显示时弹一条操作提示 |
| pollIntervalMs | 1500 | 前端拉指令间隔（毫秒） |
| shot.mediaDir | $DSH_HOME/mira_config/mira_live2d/media | 截图落盘目录。留空用默认 |
| shot.timeoutMs | 4000 | mira_screenshot 等前端回传的最长时间 |
| shot.maxBytes | 16777216（16 MiB） | 单张截图解码后字节上限 |
| tts.enabled | false | TTS 总开关 |
| tts.provider | openai | openai / aliyun（旧值 alibaba 视作 aliyun） |
| tts.base | 供应商默认 | OpenAI 兼容接口基地址（不含 /audio/speech） |
| tts.model | 供应商默认 | 见下方 TTS 表 |
| tts.voice | 供应商默认 | 见下方 TTS 表 |
| tts.maxChars | 600 | 单次朗读最长字符数 |
| tts.timeoutMs | 15000 | TTS HTTP 超时 |
| persona.thinking.expression / .bubble | '' | 思考时表情 / 气泡 |
| persona.awaiting.expression / .bubble | '' | 等待确认时表情 / 气泡 |
| persona.idleClearMs | 3200 | 空闲后清除表情的延迟 |

配置热加载：每次工具调用//live2d/api/config 都会比较 config.json 的 mtime + size，变了就重读。目录、model、TTS、背景目录改动无需重启；enabled 除外。

「必备项为空」的纪律：模型/背景目录为空、TTS 未配置、指定模型不存在等，一律返回 {ok:false,error:{code,message,hint}}，不做自动探测。

模型与资源缺失诊断

模型目录结构（每个模型一个子目录，子目录里必须有 .model3.json）：

model/
└── StellaMira/
├── StellaMira.model3.json ← 入口（必须） ├── StellaMira.moc3 ├── StellaMira.4096/... ├── 待机.motion3.json └── 思考.exp3.json

mira_list_assets / mira_get_model_capabilities 会解析 FileReferences，逐项检查 Moc、Textures、Physics、Pose、Expressions[].File、Motions[].File 是否存在：

{
"ok": true,
"models": [{
"name": "TestModel",
"missing": [{
"kind": "expression",
"file": "缺失.exp3.json", "path": "/home/you/.dsh/mira_config/mira_live2d/model/TestModel/缺失.exp3.json", "exists": false, "name": "缺失", "hint": "把 缺失.exp3.json 放到 …/TestModel，或从 …/TestModel.model3.json 的 FileReferences.Expressions 里删掉 \"缺失\"" }] }] }

- 只缺表情/动作文件：mira_switch_model 仍可切换，但返回 missing 与 warning；mira_set_expression / mira_play_motion 对该项返回 resource/missing（带文件路径与修复 hint）。
- 缺 Moc / Textures：mira_switch_model 直接返回 resource/missing，拒绝切换。
- 模型目录本身不存在/为空：config/missing，message 指出缺 .model3.json（配置了 model 时具体到 <model>.model3.json），hint 指出 modelsDir 与 config.json 路径。

TTS（openai / aliyun）

两个服务商都走 OpenAI 兼容的 POST {base}/audio/speech（不引 SDK，不直连阿里云原生 WebSocket）：

| provider | 默认 base | 默认 model | 默认 voice |
| openai | https://api.openai.com/v1 | tts-1 | alloy |
| aliyun | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-tts | Chelsie |

凭据文件（600，永不回显）

mkdir -p ~/.dsh/mira_config/mira_live2d/creds
cat > ~/.dsh/mira_config/mira_live2d/creds/tts.json <<'JSON'
{
"schemaVersion": 1,
"provider": "openai",
"apiKey": "sk-..."
}
JSON
chmod 600 ~/.dsh/mira_config/mira_live2d/creds/tts.json

- 文件里 provider 可省略；写了则优先于 config.json 的 tts.provider。
- apiKey 只从 creds/tts.json 读；mira_tts_status 只报 configured / provider / keySource / credsMode / credsModeOk，绝不回传 key。
- 权限不是 600 会写一条 warn（只打印路径与权限位），但仍可读；建议立刻 chmod 600。
- 超过 tts.maxChars（默认 600，按 code point 计，不会劈开 emoji 的代理对）只朗读前 N 个字符，并在 mira_speak / POST /api/tts 的返回值里带 truncated:true、chars、requestedChars——不静默截断。
- 旧的 tts.key / tts.keyEnv 已废弃并被忽略：会打 warn，mira_tts_status.legacyKeyIgnored / legacyKeyEnvIgnored=true，提示迁移到 creds/tts.json。

启用

{
"schemaVersion": 2,
"tts": { "enabled": true, "provider": "openai" }
}

未启用/未配 key 时：

- mira_speak 返回 config/missing，message 说明是没启用还是缺 key，hint 指到 creds/tts.json 与 config.json；
- 前端菜单里的 TTS 项仍然可见，点击后在气泡/按钮旁显示同一段提示（功能点10），不会静默 false；
- 不会发起任何网络请求。

mira_tts_status 是只读诊断工具，不会因为没配置而失败。

背景图

- 图片放 imageDir（默认 .../mira_live2d/image）顶层，支持 png / jpg / jpeg / webp / gif。
- mira_set_background(image="bg1.png") 设置，image="" 或 clear:true 清除；设置后落 state.json，刷新页面保持。
- 菜单里也列出背景图；文件经 /live2d/backgrounds/<文件名> 输出。
- 目录不存在/没有图片：config/missing，message 带目录绝对路径，hint 指到 imageDir 与 config.json。
- 实现同时写 body 的背景图（cover / fixed）与一个固定在 z-index:-1、pointer-events:none 的全屏层；如果宿主主题里还有更高的不透明容器，背景仍可能被盖住（见「已知取舍」）。

截图（功能点7）——已确认的后端路径

模型是浏览器 canvas，宿主进程没有渲染器。本插件采用 PLAN §3.11 的 (a)：

前端 canvas.toDataURL('image/png') → POST /live2d/api/shot { requestId, dataUrl, model } → 插件校验（PNG/JPEG/WebP 签名、maxBytes） → 原子写入 shot.mediaDir（默认 .../mira_live2d/media） → 返回 { ok:true, path, url, bytes, mime, ... }

依据：lib/index.js 本来就用 ctx.webServer.register({ kind:'prefix', path:'/live2d', handler }) 提供 /live2d/api/（旧版 readBody 就在这个 handler 里读 JSON），DSH 的 dsh-host-webserver 约定 WebRoute.handler 拥有完整请求/响应生命周期。因此不需要、也没有引入 Playwright。

mira_screenshot 的语义：

1. 模型必须处于显示状态（visible:true），否则 shot/unavailable，hint 让你先 mira_show / mira_set_visible；
2. 下发带 requestId 的 screenshot 指令，等前端回传（默认 4s，可用参数 timeoutMs 覆盖，500–30000ms）；
3. 成功返回绝对路径与 /live2d/media/<file> URL；失败返回 shot/unavailable（页面没开/模型没显示/超时）、shot/invalid（空白 canvas/坏 dataUrl）、shot/too-large、shot/write-failed；
4. 前端 PIXI 已开 preserveDrawingBuffer: true，否则部分浏览器 toDataURL 会得到空白图。

限制：

- 只截 canvas 内容（透明背景不会带页面背景），不是整页截图；
- 需要浏览器里看板娘页面已打开且模型已加载；
- 若宿主没有可用的上传端点（webServer.register 缺失），工具返回 platform/unsupported，不落盘，也不引渲染依赖；
- shot.maxBytes 限制解码后大小；请求体读取上限是它的 1.5 倍 + 8 KiB。

工具清单（20 个，全部返回 JSON 文本）

| 工具 | 说明 |
| mira_get_state | 显示与否、当前模型、开启的表情/动作、背景、TTS 是否配置、可切换模型、资源缺失诊断、浏览器是否连上。默认 visible:false |
| mira_list_models | 列出模型（目录名 + model3.json 相对入口）；目录为空返回 config/missing |
| mira_list_assets | 模型/表情/动作/背景图 + 逐文件缺失诊断（missing[].hint） |
| mira_get_model_capabilities | 解析指定/当前模型的 model3.json，返回表情、动作组、缺失文件 |
| mira_switch_model | 切换模型；核心文件缺失拒绝，非核心缺失带回 warning |
| mira_set_expression | 设置表情（空串恢复默认；stack=true 叠加开关） |
| mira_play_motion | 播放动作组 |
| mira_speak | TTS 合成 + 气泡；未配置返回 config/missing 并给提示 |
| mira_bubble | 只显示气泡 |
| mira_set_visible | 显式开关：{"visible":true|false}，状态落盘 |
| mira_show / mira_hide | 旧工具保留（等价于 set_visible） |
| mira_set_expressions_enabled | 开关表情系统 |
| mira_set_animations_enabled | 开关动作播放 |
| mira_set_mood | thinking / awaiting / idle |
| mira_set_persona | 思考/等待表情气泡与 idleClearMs（运行期，不落盘） |
| mira_get_config | 当前生效配置（目录绝对路径；TTS key 只报是否配置） |
| mira_set_background | 设置/清除背景图，落 state.json |
| mira_screenshot | 前端 canvas 截图 → POST 上传 → 落盘并返回路径 |
| mira_tts_status | 只读：是否启用、供应商、key 是否配置、key 来源、creds 文件权限（不含 key） |

旧版返回中文纯文本（如 '已下发切换模型指令：X'），3.0.0 起统一为 JSON；按 ok / error.code 判断，不要正则解析文案。

前端交互

- 默认隐藏：页面加载后模型不出现，左下角常驻「显示看板娘 / 隐藏看板娘」「说话」「菜单」三个按钮。
- 菜单（菜单按钮 / 右键 canvas / 移动端长按）：
- 模型：列出 modelsDir 下所有模型（当前项标 ✓）；
- 表情：默认表情 + 当前模型表情；有文件缺失的项标 ⚠，点击显示缺失文件名与修复位置；
- 动作：当前模型动作组；
- 背景：无背景 + imageDir 里的图片；
- 截图：当前画面落盘后提示路径；
- TTS：已配置为「试听 TTS」，未配置为「TTS 未配置（点击查看）」，点击给明确提示；左下角「说话」按钮同样常驻，未配好时点击给出同一段提示。
- 拖拽移动 / 滚轮缩放 / 双指捏合 / 位置与缩放记忆（localStorage）保持旧版行为。
- 气泡、语音、RMS 口型、思考/等待表情联动保持旧版行为。
- 前端每 5 秒 POST /live2d/api/state 上报状态；服务端只持久化显隐/模型/背景/表情/动作，气泡与在线时间只留在内存。

内部 HTTP API（前端用；非模型工具）

| 方法/路径 | 用途 |
| GET /live2d/api/config | 前端启动配置：可见性、模型/入口、模型清单、能力、背景、TTS 状态、截图端点 |
| GET /live2d/api/commands?since= | 拉取指令（ID 单调递增，带时钟回拨防护） |
| POST /live2d/api/command-result | 前端指令执行结果（仅日志） |
| POST /live2d/api/state | 前端状态上报 + 持久化 |
| GET /live2d/api/audio/<id> | 取 TTS 音频（base64） |
| POST /live2d/api/tts | 前端试听 TTS（与工具同一套配置/校验） |
| POST /live2d/api/shot | 截图上传（dataUrl） |
| POST /live2d/api/background | 前端菜单设置背景 |
| GET /live2d/api/capabilities?model= | 隐藏状态下也要列表情/动作菜单 |
| GET /live2d/{assets,models,backgrounds,media}/... | 静态资源（路径越界一律 403） |

- 只接受同源请求：/live2d/api/ 全部同一口径——带 Origin 且 host 与 Host 不一致、Origin: null、或 Sec-Fetch-Site: cross-site 一律 403 http/forbidden（这些接口能改状态、落盘截图、消耗 TTS 额度，不能让任意网页盲写）。没有 Origin 的本地客户端（curl / Node）不受影响。
- GET /commands?since= 只采信安全的非负整数且最多领先当前时钟一天；异常游标会被忽略（仍返回 200），不会把指令 ID 推到浮点精度边界而破坏「ID 单调递增」。

错误码

| code | 场景 |
| config/missing | 必备配置/目录为空、模型目录没有模型、背景目录没有图、TTS 未配置 |
| config/schema | config.json / state.json / creds/tts.json 的 schemaVersion 不匹配 |
| config/invalid | 配置值非法（如 provider 拼错）或工具参数类型不对 |
| model/not-found | 指定模型/表情/动作名不在清单里（message 列出可选项） |
| model/broken | model3.json 读不了或不是 JSON |
| resource/missing | model3.json 引用的文件缺失（moc/贴图/表情/动作） |
| tts/failed | TTS 网络/接口/空音频失败（错误里已抹掉 key） |
| creds/missing | TTS 凭据文件坏或读不了 |
| shot/unavailable | 模型隐藏、前端没回传/超时、前端回报错误 |
| shot/invalid / shot/too-large / shot/write-failed | 空白 canvas/格式错 / 超上限 / 落盘失败 |
| platform/unsupported | 宿主没有 webServer.register（没有上传端点） |
| plugin/instance | 同 id 第二个实例（单实例保护） |
| plugin/disabled | config.enabled=false |
| state/write-failed | 状态文件写盘失败 |

迁移（从 2.0.2 到 3.0.0）

先备份：cp -a ~/.dsh/mira_config/mira_live2d ~/mira_live2d.bak（如果没有该目录就备份 profile 配置）。

1. 建配置文件：新建 $DSH_HOME/mira_config/mira_live2d/config.json，至少写：

{ "schemaVersion": 2, "model": "StellaMira" }

把旧 cordis.patch.yml 里 mira_live2d.config 的字段搬进来（model / modelsDir / canvas / position / mobileScale / showHint / pollIntervalMs / persona / tts.）。搬完建议把 profile 里那一节删成 config: {}；同名项以 config.json 为准。

2. 模型目录：旧默认是插件包内 model/，新默认是 $DSH_HOME/mira_config/mira_live2d/model。二选一：
- cp -a <插件目录>/model/ ~/.dsh/mira_config/mira_live2d/model/；或
- 在 config.json 里写 "modelsDir": "<插件目录>/model"。
3. TTS 凭据：把旧 tts.key（字面量）或 tts.keyEnv 指向的环境变量值搬进 creds/tts.json 的 apiKey，再 chmod 600；这两个旧字段会被忽略并打 warn。旧 provider: "alibaba" 自动当作 aliyun。

4. 默认显隐：旧版默认显示，新版默认隐藏（任务书功能点1）。用户点过「显示看板娘」后状态落 state.json，刷新保持；要强制默认隐藏，删 state.json。

5. 工具返回值：从中文文本改为 JSON；调用方按 ok / error.code 处理。mira_list_models 从数组变为 {ok,modelsDir,models}。

6. schemaVersion 不匹配：插件会拒绝使用对应文件并在日志/mira_get_state 报 config/schema，不会静默兼容；先备份再按上表重写。旧版没有 config.json 时不算不匹配。

已知取舍 / 未做项

- 前端行为没有浏览器自动化测试：test/smoke.mjs 只测 Node 侧 + widget.js/CSS 的静态存在性（常驻按钮、preserveDrawingBuffer、toDataURL、上传路径）。真实拖拽/菜单/背景视觉需人工验证。
- 背景层可能被宿主主题盖住：同时设置 body 背景与 z-index:-1 固定层，但不保证在所有布局下可见；没有改宿主 CSS/结构，避免污染全局样式。
- TTS 只支持 OpenAI 兼容 /audio/speech：阿里云走 DashScope 兼容模式，不实现原生 WebSocket 流式；流式/字幕等未做。
- tts.key / tts.keyEnv 不再支持：凭据必须 600 落 creds/tts.json；这是任务书约定8的直接结果。
- enabled 不是热加载项：改它要重载插件；其余目录/模型/TTS 配置热生效。
- 状态是单进程内存 + 文件：没有多实例/多进程合并；单实例保护会拒绝第二个实例。
- 截图只截 canvas：透明背景、分辨率随 canvas.w/h 与 PIXI resolution；不做整页/多显示器截图。media/ 下的历史截图不会自动清理，需要时手工删。
- 不自动探测：不自动挑模型、不自动找 key、不扫描插件自带模型当默认。
- set_persona 是运行期覆盖：不写盘；未用工具覆写前 config.json 的 persona 会热加载，覆写后保持到重载插件。要持久请写 config.json。
- 背景图只列 imageDir 顶层：子目录里的图不自动列，但 mira_set_background 可传相对子路径（仍限制在 imageDir 内）。

自检

cd mira_live2d
node test/smoke.mjs # 末行 ==== ALL PASS（N 项断言）====，退出 0
cd ..
node 重构插件/tools/check-zero-dep.mjs mira_live2d
node 重构插件/tools/check-kit.mjs

自检把 DSH_HOME 指到临时目录，不碰真实 ~/.dsh；TTS 用假 fetch，不发真实网络请求；截图用合成 PNG 走真实 HTTP handler 落盘到临时目录。

lib/kit.mjs 是 重构插件/kit/kit.mjs 的逐字节副本；改 kit 请改规范源后重新复制，并跑 check-kit.mjs。