clown139880/dsh-live2d-avatar

dsh-live2d-avatar

npm
Node.js
License: MIT

dsh-live2d-avatar 为 DeepSeek Harness（DSH）提供可切换的 Live2D 对话舞台、轨迹展示和桌宠模式。它不替代 DSH 的对话、Agent、记忆、工具或历史记录，只负责角色的视觉表现和可选的语音交互。

功能概览

- 对话、轨迹、形象三个视图；形象视图提供 Live2D 舞台
- 内置可公开使用的 Live2D Haru 示例模型，安装后即可看到效果
- 支持用户导入自己的 Cubism 2/3+ 模型，并设置模型目录、缩放和位置
- 普通 DSH Web 中提供可拖动的页面内桌宠
- TokensCowork Desktop 中可打开透明、置顶、独立的桌宠窗口
- 可选的表情控制 prompt；首次安装默认关闭，并支持按当前对话授权
- ASR/TTS 默认关闭，不影响没有语音服务的用户使用视觉功能

Haru 形象舞台

安装

可以让 DSH Agent 执行：

请帮我安装 dsh-live2d-avatar 插件，并确认安装后可以打开“形象”视图。

也可以手动安装：

dsh plugin --profile web add dsh-live2d-avatar
dsh web

打开一个非空对话后，选择“形象”即可看到内置 Haru。卸载：

dsh plugin --profile web remove dsh-live2d-avatar

桌宠模式

在普通 dsh web 中，桌宠会显示为页面内的可拖动浮层。在 TokensCowork Desktop 中，插件可以创建透明、无边框、置顶的独立窗口，因此主窗口最小化或被其他应用遮挡时，角色仍可显示在 Windows 桌面上。

Desktop 独立桌宠

独立窗口仍依赖正在运行的 TokensCowork Desktop；退出客户端后桌宠也会关闭。桌宠和舞台会使用当前形象设置，包括模型、角色名、缩放和位置。

🐣 第一次用、想一步步照做？ 完整的分步操作（怎么判断、怎么配 Electron、怎么验证、常见问题）见 桌面端桌宠模式使用说明。

独立桌宠是如何运行的

新版 DSH Desktop 把 DSH Host 整体放进了 Electron 的 utilityProcess 子进程，而 BrowserWindow 属于主进程 API，Host 里拿不到。因此本插件不再由 Host 直接建窗，而是由 Host 拉起一个独立的 Electron 伴生进程（companion），由它创建透明、无边框、置顶的桌宠窗口并加载 /avatar/pet。

Host 会按以下顺序探测可用的 Electron 二进制，找到后用它启动伴生进程；都找不到时自动退回页面内桌宠：

1. 设置中配置的“桌宠 Electron 路径”（companionElectronPath）
2. 环境变量 DSH_LIVE2D_AVATAR_ELECTRON 指向的 Electron
3. 插件 vendor/-/（或 vendor/）目录下的 Electron（不进 Git，不随包发布）
4. 未打包/开发版 DSH Desktop 的 Electron（process.execPath，仅当没有打包为 app.asar 时）
5. 系统 PATH 上的 Electron

打包安装的 TokensCowork 不携带独立的通用 Electron 二进制，因此真实用户的独立桌宠需要提供上表第 1–3 项之一（例如把 electron.exe 放到 vendor/win32-x64/、设置 DSH_LIVE2D_AVATAR_ELECTRON，或在“形象”设置里填写路径）。未提供时桌宠作为页面内浮层显示，并在界面给出文档提示。

页面内桌宠始终作为兜底保留：只有桌面引擎可用时才启用独立伴生窗口。

使用自己的 Live2D 模型

在“形象”设置中可以配置：

- 模型目录：包含模型及其纹理、表情、物理和动作文件的目录
- 模型入口：相对于模型目录的 .model.json 或 .model3.json 文件
- 缩放、X/Y 偏移：用于调整舞台和桌宠中的显示大小与位置

也可以把模型目录放在插件的 assets/models// 下。由于模型目录会由本机 DSH 服务提供给浏览器，请只选择专用模型目录，不要选择包含隐私文件的宽泛目录。

自定义模型设置

未知模型会使用通用 profile；基础渲染、口型同步和模型自带的点击动作仍可工作。更细致的表情到动作映射属于后续版本，不影响第一版使用自定义模型。

内置 Haru 使用 Live2D 的 Free Material License，具体授权请阅读 assets/models/haru/NOTICE.md。Haru 的授权不包含在本项目 MIT 许可证中。

表情控制 prompt

表情控制 prompt 会让当前对话中的 LLM 在台词前输出 Live2D 表情和动作指令。它可能改变发送给模型的 prompt，因此属于可选且具有侵入性的功能：

- 首次安装默认关闭，不会自动修改任何对话
- 启用前会在当前对话中明确提示并请求授权
- 可以在设置中配置全局默认，但单个对话仍可覆盖
- 控制标记不会显示在台词或发送到 TTS
表情控制授权

ASR 与 TTS（可选）

第一版不要求所有用户都能使用语音功能。ASR 和 TTS 默认关闭，视觉舞台、模型和桌宠不依赖语音服务。

启用后，可以填写自己部署的 ASR/TTS HTTP API 地址。当前实现优先兼容 ModelDeck 使用的接口格式；其他服务和渠道会在后续版本逐步支持，也欢迎通过 Issue 提出需求。录音只会发送到用户配置的 ASR 地址，回复文本只会发送到用户配置的 TTS 地址。

API 密钥不会填写到浏览器设置中，只支持从 DSH host 的环境变量读取。请仅配置自己信任的 http(s) 地址，并注意语音数据和文本会离开本机发送到该服务。

安全与隐私

- 默认安装不会请求 ASR/TTS 服务，也不会注入表情控制 prompt
- prompt 控制按对话授权，且可以随时关闭
- API 密钥只从 host 环境变量读取，不进入浏览器配置或日志
- 模型文件仅应放在专用目录中，避免意外暴露其他本地文件
- 语音服务为用户自部署或自行信任的服务，插件不代替用户判断其隐私策略
- Desktop 桌宠是可选增强；没有 Electron 时会自动退回页面内桌宠

开发

pnpm install
pnpm check
pnpm build
pnpm test
pnpm watch

本地安装到 DSH Web profile：

dsh plugin --profile web add link:C:\path\to\dsh-live2d-heroine
dsh --profile web

发布前检查项见 docs/release-checklist.md。

许可证与示例素材

插件代码使用 MIT 许可证，见 LICENSE。内置 Haru 示例素材由 Live2D Inc. 提供并受其单独授权条款约束；请同时阅读 NOTICE.md 以及 Live2D Free Material License。