dsh-live2d-voice：DeepSeek Harness 的 Live2D 语音伴侣

前言¶

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 配置正确且网络可达。
触摸模式：触摸模式功能目前处于待发布状态，暂不可用。