前言¶

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。