dsh-plugin-whale-mate
Verifieddsh-plugin-whale-mate · v0.6.3 · MIT · Web UI
希可儿:DeepSeek Harness 的 3D 桌宠。安装即用,坐在输入框上陪你聊天、回复时开口说话;切换到桌面模式后可坐在任意窗口顶边和任务栏上。
Install
dsh plugin add dsh-plugin-whale-mate Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
希可儿 · deepseek-mate
DeepSeek Harness 的 3D 桌宠插件。 安装后希可儿出现在 Harness 网页里,坐在聊天输入框上沿:会呼吸、眨眼、用眼睛和头跟着鼠标,DeepSeek 思考时托腮,回复时跟着流式文字开口说话;切到桌面模式后还能坐到任意窗口顶边和任务栏上。
命名说明。 项目/仓库名是 deepseek-mate,插件包名(安装标识)仍是
dsh-plugin-whale-mate,保持不变是为了不破坏已安装实例、配置键和本地存储的设置。角色名是希可儿。
![]()
目录
她会做什么
| 场景 | 表现 |
|---|---|
| 待机 | 呼吸、眨眼、晃腿,眼睛和头跟着鼠标。偶尔伸懒腰、走动、坐到边上,或做个小动作。3 分钟没有互动会打瞌睡。 |
| 你发消息 | 点头回应。 |
| DeepSeek 思考中 | 手托下巴,气泡显示「…」。 |
| DeepSeek 回复 | 嘴型跟着流式文字动;气泡先显示回复的最新片段,结束后显示回复开头。 |
| 请求失败 | 难过、摇头,气泡里说明原因(例如「没有配置 API key」)。 |
| 拖动她 | 从抓取点垂下来随你摆动;松手会掉落或被抛出,落到下方卡片的顶边或窗口底部。窗口顶部太靠上、头会被切掉的表面会被跳过。 |
| 双击 | 挥手打招呼。 |
| 点头部 / 在头上左右移动鼠标 | 摸头:眯眼微笑。 |
| 点身体 | 被吓一跳。 |
| 右键 | 圆形转盘:你收藏的动作和表情、窗口/桌面模式切换、隐藏。 |
| 设置 | 设置 → 希可儿桌宠:形象、模式、大小、右键转盘内容、诊断信息。 |
角色完全在本地运行:插件自带 Three.js / three-vrm 引擎和 VRM 形象,本身不调用任何大模型;气泡里的文字来自它所跟随的 Harness 会话。
环境要求
- DeepSeek Harness:官方桌面版(推荐)或
dsh web,版本0.2.1及以上。 - 系统:Windows 10/11、macOS、Linux(X11)。桌面模式的窗口跟踪在 Windows 上最完整,详见桌面模式。
- Node.js 22+:只有从源码构建或跑测试时需要。安装插件不需要工具链。
- 不需要 Unity、不需要 Blender、不需要单独的程序。桌面模式首次使用时会自行下载 Electron 运行时(也可以复用你已有的)。
安装
安装源
添加插件 输入框接受三种来源:
| 来源 | 示例 | 说明 |
|---|---|---|
| npm 包名 | [email protected] |
已发布到 npm:dsh-plugin-whale-mate |
| GitHub 仓库地址 | https://github.com/mymde/deepseek-mate.git#v0.6.3 或 github:mymde/deepseek-mate#v0.6.3 |
本仓库,固定到版本标签 |
| 本地绝对路径 | /绝对路径/deepseek-mate 或 .tgz |
离线安装与开发调试 |
三种都能用。建议带上版本号或标签(@0.6.3、#v0.6.3),重复安装时结果可复现。
DeepSeek Harness Web(dsh web)
# 从 npm 安装
dsh plugin --profile web add [email protected]
# 从 GitHub 安装,固定到版本标签
dsh plugin --profile web add github:mymde/deepseek-mate#v0.6.3
# 或本地目录 / 压缩包
dsh plugin --profile web add /绝对路径/deepseek-mate
dsh plugin --profile web add /绝对路径/dsh-plugin-whale-mate-0.6.3.tgz
重启 dsh web 并打开页面,希可儿会坐在输入框上沿。
DeepSeek Harness 官方桌面版
桌面版使用自己的 desktop profile,--profile web 管不到它。两种方式:
- 在应用里打开 插件 → 添加插件,填
[email protected]、仓库地址https://github.com/mymde/deepseek-mate.git#v0.6.3,或解压后插件目录的绝对路径; - 或者用应用自带的
dsh命令(应用菜单 → 管理 dsh 命令…):完全退出桌面版,执行dsh plugin --profile desktop add [email protected](或github:形式),再重新打开应用。
升级与卸载
插件管理器不允许直接覆盖已安装的包:
- 完全退出 Harness;
- 在 插件 里移除旧插件;
- 添加新版本并重启。
设置 → 希可儿桌宠 → 版本 · 诊断信息 会显示实际运行的版本(页面端和后台端),可以用来确认升级是否生效。
使用
- 侧边栏:🐋 希可儿按钮显示/隐藏她;再次显示一定会回到输入框上。
- 右键:圆形转盘,包含设置里选好的动作/表情(最多 6 个)、窗口模式 / 桌面模式切换和隐藏。
- 设置 → 希可儿桌宠:形象、模式、大小(160–640 px)、右键转盘内容、叫她回来、诊断信息。
- 大小按浏览器保存在 localStorage 里,桌面模式使用同一尺寸。
桌面模式
在页面里她永远出不了 Harness 窗口。桌面模式会打开一个透明、置顶、可点击穿透的桌面窗口,让她搬到桌面上:
- 开启桌面模式后自动坐到 Harness 窗口顶边,窗口移动时跟着走;
- 可以拖到屏幕任意位置;只有她可见的像素接收鼠标,其余部分点击穿透到下面的应用;
- Harness 最小化或隐藏到托盘时叠加层一起隐藏,恢复时回到原来的位置;
- 窗口贴着屏幕顶部(包括最大化)时,座位会向内收,保证头不被切掉;
- 回复、思考、错误和
pet_*工具在桌面上同样生效。
从右键转盘(到桌面上去)或 设置 → 希可儿桌宠 → 桌面模式 开启;从桌面上的右键菜单(回到 Harness 窗口里)或同一处设置关闭。选择会被记住。
运行时来源
叠加层是一个 Electron 窗口,运行时按以下顺序选择:
- 插件配置里的
electron(或DSH_WHALE_MATE_ELECTRON)——你已有的 Electron 可执行文件路径; - Harness 后台本身运行在 Electron 主进程时,直接复用;
- 否则首次使用时从 npmmirror 镜像(GitHub 备选)下载对应系统的 Electron 44.10.2(Windows 约 150 MB),用发布页的
SHASUMS256.txt校验,解压到~/.dsh-whale-mate/runtime/(可用DSH_WHALE_MATE_HOME改位置)。不开启桌面模式就不会下载任何东西。
桌面模式只在运行 Harness 的那台机器上有效:控制路由只接受回环请求,并且位于 Harness 的登录校验之后。远程或无显示的主机会在设置里显示原因。配置 desktop: false 会彻底关掉桌面模式。Linux 上叠加层以关闭 sandbox 的 Chromium 运行(解压出来的运行时没法带 setuid helper),并且只从带 token 的回环地址加载插件自己的文件。
配置示例
- id: whale-mate
config:
desktop: true # false:不要桌面模式
electron: C:/tools/electron/electron.exe # 可选:用这个运行时,跳过下载
模型
内置模型
| id | 模型 | 说明 |
|---|---|---|
deepseek-reset(默认) |
DeepSeek Reset | 使用本模型请注明 B站 @hihihihi202(https://space.bilibili.com/3546568969947566)。原作者允许修改,**禁止商用**。 |
设置 → 希可儿桌宠 会显示当前模型的作者和署名要求(从 VRM 元数据读取)。
早期的 VRoid 模板形象(whale-maid.vrm,18.7 MB)从 0.6.2 起不再随包发布,安装包因此从 21.6 MB 降到 9.1 MB。它的 CC0 底模说明保留在 ASSET_LICENSES.md;你仍然可以通过 model 配置使用自己拥有的任意 VRM。
使用自己的 VRM
把 model 设为 Harness 主机上一个 .vrm 文件的绝对路径(支持 VRM 0.x 和 1.0):
- id: whale-mate
config:
model: /path/to/your-avatar.vrm
modelName: 我的角色 # 设置页显示名(可选)
也可以使用环境变量 DSH_WHALE_MATE_MODEL=/path/to/x.vrm。修改后重启 dsh web 生效。模型文件只提供给本机已登录的用户,不会上传到任何地方。
修复导出的模型
从 Blender 导出的模型常有下面这些问题。scripts/repair-vrm.py 会修好并写出新文件,绝不修改原文件。
| 选项 | 修复内容 |
|---|---|
--rest-from-bind |
骨架 rest 姿态和网格对不上。按蒙皮逆绑定矩阵重建 rest 姿态。 |
--face +x |
角色朝向错误。旋转网格和骨架,让角色朝向 +Z(VRM 1.0 的要求)。 |
--unlit-emission |
颜色全在自发光里(基础色为黑),在 three.js 里发白。把这些材质转成 unlit,并用 AgX 映射保持观感。 |
--expressions map.json |
形态键没有绑到 VRM 表情(不会眨眼、做表情、对口型)。按名字绑定。 |
--patch-materials / --add-image |
补回导出丢失的贴图(脸、头发、虹膜)。 |
--nudge / --thicken |
修共面层的 z-fighting(虹膜和眼白),以及桌宠尺寸下细到看不见的嘴部线条。 |
| 始终启用 | 去掉恒定的顶点色、去掉 unlit 网格的形态法线、把形态键存成稀疏 accessor,通常能把文件缩小数倍。 |
从 .blend 重建默认模型
scripts/build-deepseek-reset.sh DeepSeek_Reset_4K_Lite.blend(Blender 5.2 + VRM Add-on 4.10)会:把角色转向镜头、把 HoYoverse/原神卡通材质烘焙成贴图并转成 MToon、绑定 13 个标准表情以及 jito / wink / tehe、写入署名元数据,并用 repair-vrm.py 瘦身。产物约 13 MB。scripts/tune-mtoon.py 可以在不重建的情况下调整 MToon 描边和明暗。
配置
插件配置写在 profile 的 cordis.patch.yml 里:
- id: whale-mate
config:
desktop: true
electron: null
model: null
modelName: null
tools: true
| 键 | 类型 | 默认 | 含义 |
|---|---|---|---|
desktop |
boolean | true |
false 完全关闭桌面模式及其路由。 |
electron |
string | — | Electron 可执行文件的绝对路径,跳过下载。 |
model |
string | — | 内置 id(deepseek-reset)或 .vrm 的绝对路径。 |
modelName |
string | — | 自定义模型在设置页的显示名。 |
tools |
boolean | true |
false 时不注册 pet_* 工具。 |
环境变量:
| 变量 | 作用 |
|---|---|
DSH_WHALE_MATE_MODEL |
等同于 model,配置为空时生效。 |
DSH_WHALE_MATE_ELECTRON |
等同于 electron。 |
DSH_WHALE_MATE_HOME |
桌面运行时下载后的解压位置。 |
智能体工具
智能体可以通过三个工具控制她(tools 不为 false 时才注册):
| 工具 | 作用 |
|---|---|
pet_say |
在气泡里说一句话(text,可选 expression),建议 60 字以内。 |
pet_expression |
设置表情并保持 seconds 秒(1–30,默认 4):neutral、happy、angry、sad、relaxed、surprised、blink。 |
pet_action |
做一个动作:wave、nod、shake、cheer、bow、stretch、shy、dance、jump、sit、stand、walk、sleep、wake、home,以及 public/motions.json 里的全部动作。 |
这些工具只做确认;浏览器端的叠加层监听会话事件流并执行动作,所以不需要额外的后台↔浏览器通道。
实现方式
- 后台(
lib/index.js)- 在
/whale-mate/下提供public/里的引擎和模型,位于 Harness 自己的登录校验之后(未登录请求返回 401); - 注册三个
pet_*工具(只做确认); - 挂载桌面模式路由,并把校验过的命令转发给叠加层。
- 在
- 桌面叠加层(
lib/desktop.js、desktop/)lib/desktop.js负责找到或下载运行时,用 Node IPC 启动desktop/app.cjs(或进程内运行叠加层),校验后通过POST /whale-mate/desktop/send把页面消息转给叠加层;desktop/main.cjs在 Harness 所在显示器的工作区上开一个透明窗口,从随机回环端口提供overlay.html、pet.js和模型;按她每个像素的命中测试切换点击穿透(Windows/macOS)或在她周围设置输入形状(Linux),并轮询系统光标;- Windows 官方桌面版上,
desktop/harness-window.cjs用 Koffi 只读取启动官方 Host 的 shell 进程的窗口(DWM 可见边框、物理像素转 Electron DIP、50 ms 轮询)。其他应用不会成为座位; - Web / 非 Windows 上由页面每 200 ms 上报
window.screenX/Y、尺寸和可见性,这个回退方案没有原生跟踪的保证。
- 浏览器端(
client/client.js):手写的 DSH 客户端模块(安装时不需要构建),加载public/pet.js,通过sessions服务跟随主视图会话,用实时文字、运行状态和tool/call事件直接驱动桌宠。 - 引擎(
src/pet/,连同 three.js 和 three-vrm 打包成public/pet.js)- 叠加层:透明的
position:fixed层,逐像素命中测试; - 姿态系统:移动状态、手势层、看向和根运动混合后平滑到每根骨骼;
- 物理:运行时为头发、裙子和尾巴添加 70 根弹簧骨;
- 面部:情绪混合、随机眨眼、按文字驱动的口型。
- 叠加层:透明的
开发
npm install
npm run build # src/pet -> public/pet.js(缺少模型时也会复制)
npm test # 后台路由、原生跟踪、座位几何、FFI(Linux 需要 C 编译器)
npm run lint # ESLint(flat config)
npm run format # Prettier 格式化
npm run format:check # 只检查格式,不写文件
node scripts/check-pet.mjs # 在模拟页面(test/harness.html)上截图
node scripts/pose-gallery.mjs # 每个姿势的正/侧面截图
node scripts/mock-llm.mjs 18790 # 端到端测试用的 OpenAI 兼容 mock 模型
node scripts/check-dsh.mjs '<带 ?token= 的 dsh 地址>' # 在真实 Harness 里做端到端检查
node scripts/check-clip.mjs # 回归:不会出现头被切掉的座位
桌面模式检查(Linux + Xvfb;软件渲染时设 WHALE_MATE_ELECTRON_FLAGS="--use-gl=angle --use-angle=swiftshader"):
xvfb-run -s "-screen 0 1600x900x24" node scripts/check-desktop.mjs <electron> [outDir]
DISPLAY=:77 node scripts/check-dsh-desktop.mjs '<带 ?token= 的 dsh 地址>' [outDir]
截图和端到端脚本需要 playwright-core 和 Chrome/Chromium。请自行安装(npm i -D playwright-core),或用 PLAYWRIGHT_CORE 指向已安装的模块、用 CHROME_PATH 指向浏览器;脚本不会自动下载。
开发验证基于 DeepSeek Harness 0.2.1-rc.5(Linux,无头 Chrome + SwiftShader)。Windows 的 Win32 跟踪仍建议在真机上做一次验收。
目录结构
client/ DSH 客户端模块(浏览器端,无需构建)
desktop/ Electron 叠加层:主进程、preload、座位几何、Win32 窗口读取、内置 koffi
lib/ 后台:路由、模型解析、智能体工具、桌面运行时管理与下载
locale/ 中英文界面文案
public/ 运行时资源:pet.js 打包产物、VRM 模型、motions.json、缩略图、素材声明
scripts/ 构建、截图、端到端检查、VRM 修复/重建脚本
src/pet/ 桌宠引擎源码(Three.js + three-vrm),打包进 public/pet.js
test/ node:test 测试与 HTML 测试页
常见问题
| 现象 | 排查 |
|---|---|
| 她一直不出现 | 插件 里是否启用?是否被隐藏(侧边栏 🐋 / 设置里的「叫她回来」)?看 版本 · 诊断信息 里页面端和后台端的版本。 |
| 设置页是空的 | 后台加载失败;在 Harness 日志里找 whale-mate: 开头的消息。 |
| 桌面模式提示运行时下载失败 | 把 electron(或 DSH_WHALE_MATE_ELECTRON)指向已有的 Electron,或使用发布包里的 Windows 离线运行时,然后重试。 |
桌面窗口一启动就退出(Cannot find module 'koffi') |
0.5.10 起已通过内置 desktop/vendor/koffi/ 修复;确认安装包里有这个目录(npm/GitHub 包都带)。 |
| 窗口跟踪不可用 | Windows 原生跟踪需要官方桌面版 Host;其他启动方式会退回页面坐标。 |
| 模型显示异常 / 有黑色细刺 | 用 scripts/repair-vrm.py 修复 VRM,并确认是 VRM 0.x/1.0、使用 MToon 材质。 |
已知限制
- 只有带独立头发/裙子/尾巴骨骼链的模型(VRoid 风格)才会自动添加弹簧骨物理。头发是单网格蒙在头上的模型(如 DeepSeek Reset)没有头发摆动。
- 长裙没有布料模拟。坐下依赖「坐姿」形态键和弹簧骨,极端姿势下会有轻微穿模。
- 她只跟随主视图会话的实时事件;后台会话里的工具调用不会传给她。
- 每个浏览器标签页一只桌宠。大小、显示/隐藏、座位位置等设置存在该浏览器的 localStorage 里。
- Windows 的 Win32 调用、混合 DPI 多显示器和焦点/点击穿透仍建议真机验收。
- 原生跟踪限定在官方 Windows 桌面版 Host 入口及其父 shell 进程。koffi 3.1.0 提供 Windows x64/ia32 预编译二进制,Windows ARM64 未验证。
许可
- 代码:MIT,见
LICENSE。 deepseek-reset.vrm:作者 B站 @hihihihi202。允许修改与再分发但必须署名,禁止商用。详见ASSET_LICENSES.md。- 第三方动作/表情数据:从 GI-Engine / Mate-Engine 转换的片段(AGIA,Clean Curve Studio;Shiny)不属于 MIT,本项目也未获得再分发授权,版权归原作者,按原条款使用;Quaternius 片段为 CC0。详见
public/animation-notices/与ASSET_LICENSES.md。 - 依赖:three.js、three-vrm、Electron、koffi 均为 MIT。
致谢
这个项目站在很多人的工作上,感谢他们。
参考的项目与库
| 项目 | 作者 / 来源 | 用途 |
|---|---|---|
| DeepSeek Harness(DSH) | DeepSeek | 宿主平台、插件 API、Web 服务、会话事件 |
| Cordis | DeepSeek / cordis | 插件与加载器运行时 |
| three.js | mrdoob 及贡献者(MIT) | 3D 渲染 |
| @pixiv/three-vrm | pixiv Inc.(MIT) | VRM 加载、MToon、表情、弹簧骨 |
| Electron | OpenJS Foundation(MIT) | 桌面叠加层窗口(按需下载,不随包分发) |
| koffi | Niels Martignène(MIT) | Windows 原生窗口查询 |
| esbuild | Evan Wallace(MIT) | 把 src/pet 打包成 public/pet.js |
| GI-Engine | Nekoluna-dot;AGIA 素材作者 Clean Curve Studio | AGIA 待机 / 行走 / 挥手 FBX 动作(本地转换) |
| Mate-Engine | Shiny | 追加动作与表情来源 |
| Quaternius Universal Animation Library | Quaternius(CC0) | 10 段完整骨骼的移动 / 待机动作 |
| VRoid Studio | pixiv Inc. | 早期鲸鱼女仆形象的 CC0 AvatarSample_4 底模 |
| Blender + VRM Add-on | Blender Foundation / SATO Yusuke | 模型导出与材质转换流程 |
使用的模型与美术
- DeepSeek Reset(
public/deepseek-reset.vrm)——角色原作者 B站 @hihihihi202。由DeepSeek_Reset_4K_Lite.blend重新导出,做了朝向修正、MToon 烘焙、表情绑定和元数据写入。原作者允许修改与署名再分发,禁止商用。 - 希可儿(鲸鱼女仆)——基于 VRoid Studio 的 CC0
AvatarSample_4(Victoria Rubin),新增深蓝女仆服、围裙、头饰、长发、鳍耳和鲸尾;角色设计依据本项目提供的参考图。0.6.x 不再随包发布。 - 动作与表情数据——AGIA(Clean Curve Studio)、GI-Engine、Mate-Engine 与 Quaternius,详见上面的许可说明和
ASSET_LICENSES.md。
特别感谢
- DeepSeek Harness 团队提供的插件系统,以及本项目沿用的
pet_*工具模式。 - 所有提 issue、帮忙测试桌面模式和参与翻译的人。