前言¶

DeepSeek Harness（DSH）的 Web 会话界面默认是工具与对话为主，没有现成的角色浮层。若希望在同一界面里切换 Live2D 模型、表情与动作，并让模型通过 TTS 朗读或把 canvas 截图落盘，通常要自己写前端注入、静态资源路由和一组工具接口。mira_live2d 由社区维护者 Stella-Mira 发布，归类为「趣味换装」，把上述能力做成 DSH 插件：默认隐藏看板娘，界面上保留常驻开关，配置与模型资产落在 $DSH_HOME 下，不随仓库入库。

下面按定位、能力、安装与典型用法说明；事实以 GitHub 仓库 README 与 SkillHub 目录页 为准。DSH 社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系。

这是什么¶

mira_live2d 是面向 DSH Web profile 的 Live2D 看板娘插件（当前版本 3.0.0，MIT 许可证）。它依赖 DSH 的 webServer 注入前端脚本与 /live2d 路由，并向智能体暴露 20 个工具（3.0.0 起统一返回 JSON 文本，与旧版中文纯文本为破坏性变更）。模型、背景图、截图目录与 TTS 凭据由用户在 $DSH_HOME/mira_config/mira_live2d/ 自行放置；仓库内的 model/StellaMira、model/SylviaMuse 仅为资产示例，不是默认模型目录。

核心功能¶

显隐与界面¶

• 默认 visible:false，页面有常驻开关；用户拖拽位置后由浏览器 localStorage 记住。
• 菜单可切换模型、表情、动作与背景图；画布默认内部分辨率 480×630，初始位置可配置为 left / right。

配置与落盘¶

$DSH_HOME 取环境变量 DSH_HOME（trim 后非空），否则为 ~/.dsh。插件相关路径示例：

$DSH_HOME/mira_config/mira_live2d/
├── config.json             # schemaVersion=2
├── state.json              # schemaVersion=1，默认 visible:false
├── creds/tts.json          # TTS 凭据，建议 chmod 600
├── model/                  # modelsDir 默认
├── image/                  # imageDir 默认
└── media/                  # shot.mediaDir 默认

config.json 变更（除 enabled 需重载插件外）可在工具调用或 /live2d/api/config 时热加载。模型或背景目录为空、指定资源缺失时，工具返回 {ok:false,error:{code,message,hint}}，不会静默留白。

模型与资源诊断¶

每个模型为 modelsDir 下独立子目录，须含 *.model3.json。mira_list_assets 等工具会按 FileReferences 检查 Moc、贴图、物理、Pose、表情与动作文件，逐条给出缺失文件名与修复 hint；缺核心 Moc/贴图时拒绝切换模型。

TTS（OpenAI / 阿里云）¶

通过 OpenAI 兼容的 POST {base}/audio/speech 实现，支持 openai 与 aliyun（旧值 alibaba 视作 aliyun）。API Key 仅从 creds/tts.json 读取；须在 config.json 中设置 tts.enabled: true。未启用或未配 key 时 mira_speak 返回 config/missing，前端菜单仍会提示，不会静默失败。

背景与截图¶

背景图放在 imageDir 顶层，支持 png/jpg/jpeg/webp/gif；设置写入 state.json，刷新后保持。

截图走前端 canvas.toDataURL → POST /live2d/api/shot，后端校验后原子写入 shot.mediaDir（不引入 Playwright）。模型须处于显示状态；仅截 canvas 内容，不是整页截图。

工具（节选）¶

README 列出 20 个工具，均为 JSON 文本，例如：

其余工具覆盖显隐、切模型、表情/动作、背景、截图、TTS 状态与朗读等，详见仓库 README「工具清单」一节。

实现上仅依赖 Node 内置模块；Live2D 运行库仍捆绑在插件 assets/lib/，无新增 CDN 依赖。要求 Node >= 18。

安装与启用¶

先在 Web profile 安装插件（命令来自官方 README）：

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 为硬依赖。新建 config.json 时须带 schemaVersion: 2，例如最小可用配置：

{
  "schemaVersion": 2,
  "enabled": true
}

将 Live2D 模型目录放入默认 model/，或把 modelsDir 指到插件目录下的示例模型路径；用 mira_list_models / 菜单显式选择模型（留空 model 不会自动挑选默认模型）。

启用 TTS 时，创建凭据文件并限制权限：

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

并在 config.json 中开启 tts.enabled。

典型用法¶

1. 安装并登记 cordis 后重载 DSH Web，确认 $DSH_HOME/mira_config/mira_live2d/model/ 下已有合法模型目录。
2. 调用 mira_get_state 或 mira_list_assets，根据返回的 missing 与 hint 补全缺失文件。
3. 通过 mira_show 或界面开关显示看板娘，再用工具或菜单切换模型、表情、动作与背景。
4. 需要语音时配置 creds/tts.json 与 tts.enabled，使用 mira_speak（超长文本会按 tts.maxChars 截断并在返回值中标注 truncated）。
5. 需要留图时在模型可见状态下调用 mira_screenshot，成功返回落盘绝对路径与 /live2d/media/ URL。

从旧版迁移时须备份配置，按 README「迁移」处理 schemaVersion、工具返回格式及 TTS 凭据位置（废弃的 tts.key / tts.keyEnv 会被忽略并打 warn）。

适用场景与注意¶

适合在 DSH Web 会话里做轻量角色展示、换装式交互，或让智能体通过工具控制看板娘状态与截图/TTS 的场景。不适合期望「开箱即有默认模型」且不愿自备 Live2D 资产的用户；也不适合需要整页截图的后端渲染方案（本插件刻意不引 Playwright）。

插件以当前 DSH 进程权限运行，TTS 会发起对外 HTTP 请求；安装前应阅读源码与 MIT 许可证，自行评估凭据与模型版权。背景图实现可能与部分宿主主题的全屏不透明层叠放，存在被遮挡的已知取舍。

结尾¶

mira_live2d 把 Live2D 看板娘收敛为 DSH Web 上的可开关浮层，并用 20 个 JSON 工具、统一配置目录与明确的缺失诊断，方便智能体侧编排。目录与详情见 SkillHub：mira_live2d，源码与完整配置表见 GitHub：Stella-Mira/mira_live2d。