前言¶
DeepSeek Harness (DSH) 的核心設計理念是插件化。dsh-live2d-voice 插件在 DSH 的會話視圖中新增了一個 Live2D tab。它將 Live2D 角色與對話流結合，提供實時語音交互能力，解決了純文本對話缺乏動態視覺表現的問題。
安裝與配置¶
依賴與安裝¶
該插件依賴 DSH 環境版本。在 DSH 的 profile 目錄（例如 ~/.dsh/profiles/web）下執行以下命令安裝：
pnpm add dsh-live2d-voice
安裝後，需在對應 profile 的 package.json 中確認 dsh.profile.bundles 包含該插件名稱，並重啓 DSH 服務。
配置文件¶
插件使用配置文件 <DSH_HOME>/live2d-voice.json（默認爲 ~/.dsh/live2d-voice.json）。保存配置後刷新頁面即可生效。
{
// 角色模型目錄，包含 .model3.json 的文件夾
"modelPath": "/root/.dsh/live2d-voice-models/haru",
// Fish Audio 音色 ID
"voiceId": "0c7771ca5910484e8a4933068017fcee",
// Fish Audio API Key 列表（支持多 Key 輪詢）
"apiKeys": [],
// 情緒標籤映射到模型表情索引
"emotionMap": {
"neutral": 0, "joy": 1, "sadness": 2, "anger": 3,
"surprise": 4, "fear": 5, "disgust": 6, "shy": 7
},
// 語音識別語言：auto / zh / ja / en
"sttLanguage": "auto",
// 角色說話語言：ja / zh / en
"speechLanguage": "ja",
// 字幕翻譯目標語言：zh / ja / en / off
"subtitleLanguage": "zh",
// per-workspace 覆蓋配置
"workspaces": {}
}
核心功能¶
Live2D 渲染與同步¶
插件基於 Cubism 4 模型，使用 pixi.js v7 渲染。角色在說話時會根據音頻 RMS 包絡驅動 ParamMouthOpenY 實現口型同步，並根據情緒標籤自動切換表情。
流式語音與輸入¶
- 流式語音：LLM 回覆經 Fish Audio 流式合成，使用 44100Hz PCM 格式，通過 SSE 推送並在瀏覽器端隊列播放。
- 連續語音輸入：支持瀏覽器本地 VAD 分句，配合火山引擎 ASR 實時推流。支持 25 種語言，並具備說話打斷（barge-in）功能。
- 音色庫：內置 Fish Audio 公共音色庫檢索功能，支持關鍵詞搜索、試聽，選中後自動寫入配置。
字幕與翻譯¶
支持用戶與 AI 臺詞的雙語字幕顯示，字幕 14 秒淡出，並支持一鍵隱藏。角色臺詞會自動翻譯成目標語言（需配置 subtitleLanguage）。
模型管理¶
- 多模型目錄：v0.3.0 起，當
modelPath指向包含多個角色子目錄時，設置面板會出現切換器。 - Per-workspace 覆蓋：v0.3.0 起，可按工作區路徑覆蓋音色、模型、語言等配置，實現多工作區多角色。
沉浸與實驗特性¶
- 沉浸全屏：v1.1.0 起，支持一鍵全屏，並在語音監聽時啓用 Wake Lock 保持屏幕常亮。
- 視線追蹤：v1.1.0 實驗性，通過前置攝像頭追蹤視線。
- 陀螺儀視差：v1.2.0 實驗性，根據設備傾斜角度調整角色頭部與身體位置。
獨立入口¶
- 獨立會話頁：v1.3.0 起，提供無 GUI 界面的獨立入口，訪問路徑爲
/live2d-voice/app?session=<id>。 - 會話選擇頁：v1.6.0 起，提供
/live2d-voice路徑，列出全部會話並支持快速新建。
使用方法¶
基礎對話¶
- 打開任一會話，在頂部視圖 tab 切換到 Live2D。
- 使用 HUD 面板中的 ⌨️ 圖標打開輸入框直接對話，或使用 🎙️ 圖標開啓連續語音輸入。
- AI 說話時直接開口即可打斷（barge-in）。
音色庫使用¶
在 Live2D 設置面板或系統設置的「Live2D 角色與語音」中點擊音色行：
1. 瀏覽熱門榜或使用搜索框檢索全庫。
2. 點擊試聽（優先播放預渲染樣本）。
3. 點擊選用，音色 ID 會自動寫入配置文件。
配置覆蓋¶
若需要在特定工作區使用不同角色，在配置文件的 workspaces 字段中添加工作區絕對路徑，並在對象內指定對應的 voiceId、modelPath 等參數。
注意事項¶
- 提示詞注入：插件注入的提示詞（如語音輸出格式、情緒標籤）是會話級的，僅在當前會話打開 Live2D 視圖時生效。切回普通對話後，模型會恢復正常輸出。
- 網絡依賴：TTS 音色庫和 ASR 識別依賴宿主側的 Fish Audio 與火山引擎網絡環境，需確保 API Key 配置正確且網絡可達。
- 觸摸模式：觸摸模式功能目前處於待發布狀態，暫不可用。
