dsh-whale-girl-live2d

🐋 鲸鱼娘桌宠 · Whale Girl Live2D

DSH（DeepSeek Harness）Web 界面里的 Live2D 桌宠 —— 她真的在跟着 agent 干活。 A Live2D desktop pet for the DeepSeek Harness Web UI — she really does follow what the agent is doing.

点一下就能跟 agent 说话 · 右键就是钱包 · 表情 / 装饰 / 场景 / 动作 四页菜单 · 拖动换位置

🐋 先读这三行：只有一套插件，两种用法

1. 插件只有一个：dsh-whale-girl-live2d。装一次，网页版和桌面版共用同一份 —— 模型、动作、表情、跟 agent 的联动、菜单、钱包、设置，全部在插件里。
2. 网页版 = 插件自带的用法，装完就有（Windows / macOS / Linux 都能用）。
3. 桌面版 = 额外下载一个 1.4 MB 的 macOS 外壳 App，把同一个页面放进桌面上的独立窗口。 它不是第二个插件，也不用再装任何东西。

「网页版和桌面版是两套不同的插件吗？」→ 不是。 是一套插件 + 一个可选的 Mac 外壳。所以你不需要"两边都装插件"， 也不存在"装了桌面版会不会跟网页版冲突"。

两种用法对照

安装：两条路都行，按你现在的状态选

🅰 先装网页版，再装桌面版（推荐）

# ① 装插件
dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d

# ② 重启 DSH（宿主插件只在启动时加载），然后刷新页面
#    右下角出现她 = 网页版成功

# ③ 自检（返回 401 = 已挂载，被信任栅栏挡着，正常；404 = 没加载）
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/dsh-pet/pet.js

然后装桌面版：去 Releases 下载 DS-WhaleGirl-Pet-macOS-*.zip → 解压 → 把 DS 鲸鱼娘桌宠.app 拖进「应用程序」→ 双击。

🅱 先装桌面版，再装网页版（也可以）

1. 直接下载上面那个 zip，解压、拖进「应用程序」、双击。 → 这时窗口里会显示一张提示卡「🐋 正在找 DSH…」——这是正常的，因为插件还没装。
2. 再按 🅰 的 ①②③ 装插件并重启 DSH。
3. 她会出现，不用重启 App —— App 每 5 秒自动重试一次，插件一就位她就自己出来了。

⚠️ 顺序无所谓，但少了插件一定不行：桌面 App 本身不带模型、不带联动 （所以它只有 1.4 MB）。它只是一个窗口，内容全在插件里。

Windows / Linux 用户看这里

• 桌面外壳目前只有 macOS 版（Swift 编译出来的 .app），Release 里只有 Mac 附件。
• Windows / Linux 用网页版就行，功能完全一样（联动、菜单、钱包一个不少），只是她住在浏览器标签页里。
• 跨平台外壳（Electron）在计划中；在那之前，Windows 用户可以用 http://127.0.0.1:3080/dsh-pet/standalone 配 Chrome 的「创建快捷方式 → 在窗口中打开」， 得到一个小窗效果（但不透明、不置顶、不能点击穿透，不是真桌宠）。

装完不出现 / 连不上？按顺序查这五条

桌面版的技术说明（想知道细节再看）

见 desktop/README.md：本机通行证（为什么壳子能过信任栅栏）、 透明窗口的私有键、点击穿透怎么判定、怎么自己编译。

🚀 安装（网页版）/ Install the web version

先确认一件事：你机器上已经装好 DSH（DeepSeek Harness）。终端里敲 dsh --version 有输出就说明没问题； 没装的话先装 DSH，再回来装这个桌宠。

方式 A：命令行装（推荐，一条命令）

dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d

• --profile web 是 DSH Web 界面的 profile 名。如果你用的是别的 profile 名，把 web 换成你自己的。
• 这条命令会从 GitHub 拉取插件并注册进 profile（需要能访问 GitHub）。

方式 B：手动下载 ZIP（不想用命令行 / 公司网络限制 git）

1. 打开仓库页面 → 绿色 Code 按钮 → Download ZIP
2. 解压到一个你能记住的目录，例如：
   • macOS / Linux：~/Documents/dsh-whale-girl-live2d-main
   • Windows：C:\Users\你的用户名\Documents\dsh-whale-girl-live2d-main
3. 用 绝对路径装（link: 后面必须是绝对路径；有空格一定要加引号）：

# macOS / Linux
dsh plugin --profile web add "link:/Users/你的用户名/Documents/dsh-whale-girl-live2d-main"

# Windows（PowerShell / CMD 都可以）
dsh plugin --profile web add "link:C:\Users\你的用户名\Documents\dsh-whale-girl-live2d-main"

方式 C：从 DSH 插件市场装

等本插件被 DSH 插件市场 收录后， 在界面的插件中心搜 鲸鱼娘、whale-girl 或 live2d 就能一键安装（收录进度见下方「相关链接」）。 现在还没收录，先走方式 A 或 B。

装完必须做两步（少一步都不会出现）

1. 重启 DSH（宿主插件只在启动时加载）：把正在跑的 dsh web 停掉，重新起一次
2. 刷新页面（强刷 Cmd+Shift+R / Ctrl+F5）

装成功后，界面右下角会出现鲸鱼娘。

一行自检

浏览器打开：http://127.0.0.1:3080/dsh-pet/pet.js

更新 / 卸载

# 更新到最新版（更新完同样要重启 DSH + 刷新页面）
dsh plugin --profile web update dsh-whale-girl-live2d

# 卸载
dsh plugin --profile web remove dsh-whale-girl-live2d

dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d

dsh plugin --profile web add "link:/absolute/path/to/dsh-whale-girl-live2d-main"

dsh plugin --profile web update dsh-whale-girl-live2d   # then restart DSH + reload
dsh plugin --profile web remove dsh-whale-girl-live2d

🎮 一分钟上手 / Quick start

✨ 这是什么 / What is this

中文

把 Live2D 模型「鲸鱼娘」挂进 DSH 的 Web 界面。她常驻在桌面角落，不是一张静态贴图—— 她在跟着 agent 的真实状态动：思考时低头、查资料时戴上眼镜掏出手机、逐字输出时嘴巴跟着动、 报错时黑一下脸、一轮收工就伸懒腰庆祝。

和「一张 PNG 加气泡文案」的挂件不同：这是活的 Live2D —— 44 个表情、8 个动作、物理摆动、视线跟随， 而且由真实的事件流驱动（不是轮播动画）。所有小动作都照模型作者自己的按键表来 （52 条热键逐条对照，见 docs/作者按键表-对照.md），所以互不冲突、 不会互相覆盖、到点自己收回。

English

Whale Girl Live2D puts a Live2D model — the DeepSeek whale girl — inside the DSH Web UI. She lives in a corner of the screen and is not a static sticker: she follows what the agent is actually doing, tilting her head while thinking, putting on glasses and pulling out a phone when the agent reads or searches, moving her mouth as text streams in, darkening her face when a tool errors, and stretching in celebration when a turn finishes. Unlike a PNG-with-a-bubble widget this is real Live2D: 44 expressions, 8 motions, physics, gaze tracking — driven by the real event stream, not an animation loop. Every one-shot action is mapped from the original model author's own hotkey sheet (52 hotkeys, item by item — see docs/作者按键表-对照.md), so nothing overlaps and everything expires on its own.

🧠 她跟 agent 的联动 / What she reacts to

English: thinking → head down with notebook and pen; tool calls → face and motion follow the tool (reading = glasses, web search = phone, writing = scribbling, shell = rolled-up sleeves); streaming text → mouth moves, bubble fills letter by letter; tool error → she darkens for a moment; turn finished → stretch, peace sign and a stats bubble; idle for a long time → she glances around, changes expression for a few seconds, mutters to herself or complains she is hungry.

🎭 菜单：表情 / 装饰 / 场景 / 动作

点 ⋯ 打开的菜单有四页，每页守一条不同的规矩：

English: four tabs with four different lifetimes — Expressions are temporary (3–4 s, then she hands her face back to the motions); Accessories and Scenes are persistent (toggle on/off, one per category); Actions are one-shot (they play once and clean themselves up). The omurice action is the special case: it is an expression plus the ketchup-squeezing motion, and it disappears right after the sauce is squeezed.

永久移除（代码里也拦死了 BANNED_MOTIONS，菜单里找不到）：吹泡泡糖、大锤砸、呆呆眼、圈圈眼。

工作优先级高于互动：干活时点她不打断——不改脸、不放动作，最多弹一下表示「知道了」。

💰 右键 = 钱包（余额 / 本轮消耗 / 峰谷计价）

• 计价用 Flash 价目（命中 0.02 / 未命中 1 / 输出 4 元每百万 token，高峰 = 空闲 ×2）；换 Pro 模型自动按 3 倍算。
• 不跟对话抢屏幕：开菜单时 HUD 自动收起；鼠标停在 HUD 上时不会被自动收起；自动弹出的那次 9 秒后自己收。
• 不依赖别的插件：余额 / 峰谷 / 记账都是这个插件宿主自己算的；两个数据源都没有时显示「读不到余额接口」，不假装有数。

English: right-click her for a wallet HUD: remaining balance (DeepSeek's official user/balance endpoint, key read from DSH's credential service), this turn's cost (auto-popped when a turn ends, with hit / miss / output token tiers), today's total, and peak / off-peak pricing (peak = red, off-peak = green; peak hours are Mon–Fri 09:00–12:00 and 14:00–18:00 Beijing time, holidays excluded). It never fights the chat for screen space, and it works without any other plugin installed.

🤖 让 agent 主动指挥她 / Agent control

装好之后，agent（或者你自己）可以用命令行指挥她：

cd <你放插件的目录>/dsh-whale-girl-live2d

node tools/pet-ctl.mjs status          # 她在不在、当前会话、连接数
node tools/pet-ctl.mjs mood happy      # 换情绪
node tools/pet-ctl.mjs expr 星星眼      # 直接指定表情
node tools/pet-ctl.mjs motion selfie   # 播动作
node tools/pet-ctl.mjs say "搞定了！"   # 弹一句话
node tools/pet-ctl.mjs prop 猫猫贴纸 on # 戴道具
node tools/pet-ctl.mjs ask "要继续吗？" # 弹话 + 打开面板提醒你

底层就是一个本地 HTTP 接口，也可以直接打：

curl -X POST http://127.0.0.1:3080/dsh-pet/control \
  -H 'Content-Type: application/json' \
  -d '{"mood":"happy","motion":"selfie","say":"你好呀"}'

浏览器控制台里还有 DSHPet 对象可以直接玩：

DSHPet.state              // 当前状态
DSHPet.setMood('angry')   // 换脸
DSHPet.playMotion('selfie')
DSHPet.setProp('glassesSun', true)
DSHPet.hitTest(x, y)      // 这个坐标算不算点在它身上

🩺 排错 / Troubleshooting

先做这一步：打开 http://127.0.0.1:3080/dsh-pet/diag —— 一条 URL 把启动过程、模型尺寸、 取景结果、可用表情 / 动作、被过滤的参数全列出来。出问题截图这一页就够定位了。

⚙️ 配置 / Config

默认值写在 lib/index.js 的 DEFAULT_CONFIG；用户覆盖写在 ~/.dsh/dsh-live2d-pet.json （文件名沿用旧名，改它会读不到，别改）：

{
  "enabled": true,
  "height": 340,
  "corner": "br",
  "lookAtCursor": true,
  "talkMouth": true,
  "sleepAfterMs": 180000,
  "showReasoning": false
}

enabled: false 会连注入脚本一起去掉（改完要重启 DSH）。

English: defaults live in DEFAULT_CONFIG in lib/index.js; override them in ~/.dsh/dsh-live2d-pet.json (the filename intentionally keeps the old name). Changing enabled requires a DSH restart.

🔧 它内部是怎么动的 / How it works

模型这套资产原本是给 VTube Studio 用的：44 个「表情」其实是 44 组参数开关（全是 Add 混合）， model3.json 里连 Motions 段都没有。所以做了三件事：

1. 补 model3.json：把 8 个动作按独立 group 注册进去，标准 Live2D 运行时才播得动 （tools/build-model.mjs 生成，可重跑）。
2. 自己写 rig，不用框架的 expressionManager：挂在 InternalModel 的 beforeModelUpdate 上—— 那是 model.update() 之前的最后一站，动作 / 眨眼 / 视线 / 物理都已经算完，我们加的参数一定生效； 而每帧结尾 loadParameters() 会把参数还原，所以写入不跨帧累积。情绪（互斥）和道具（粘性）分开管； 权重降到 0 的表达式不再写参数，把脸交还给动作，这样「伸展」「自拍」这些自带表情的一次性动作 才不会被抹平成面瘫。
3. 命中判定用 alpha 掩码，不是包围盒：这个模型是一整张书桌场景，包围盒里大半是空气， 点空气要让事件穿透到下面的 DSH 界面。

事件侧：宿主监听 ctx.on('session/event')（轮次 / 步骤 / 工具 / 最终消息）和 ctx.on('agent/assistant-stream')（真正的逐字流），过滤出「人正在用的那个会话」后用 SSE 推给前端； 反向用官方的 sessionController.prompt()，跟你在界面上打字是同一条路。

English: the artwork was authored for VTube Studio, so the repo adds a model3.json with the eight motions registered as proper groups, drives parameters from a hand-written rig hooked onto InternalModel's beforeModelUpdate (mood = exclusive, props = sticky; expressions at weight 0 stop writing so one-shot motions keep their own faces), and hit-tests against an alpha mask instead of a bounding box so clicks on empty air fall through to the UI. The host bridges real agent events (session/event, agent/assistant-stream) over SSE, and sends messages back through the official sessionController.prompt().

⚠️ 已知限制 / Known limitations

• 模型里有两处参数引用是坏的（原作者的遗留）：喵喵手~喵~动画 引用了模型里不存在的 ParamCheek51 / ParamCheek61；番茄酱 动作引用了 keyboard / xbox。 前端启动时会自动过滤掉并在控制台说明。
• 桌宠显示在 DSH Web 页面里；关掉页面它就没了。想要常驻桌面可以用 /dsh-pet/standalone + open -na "Google Chrome" --args --app=http://127.0.0.1:3080/dsh-pet/standalone。
• 模型没有音频资源，所以 config.sound 目前是占位，没有实现。

📁 目录结构 / Layout

dsh-whale-girl-live2d/
├── package.json             DSH bundle 插件元数据（dsh.bundle.patch）
├── cordis.patch.yml         挂载声明
├── screenshots.json         插件市场详情页用的截图清单
├── lib/index.js             宿主侧：静态资源 + SSE 事件桥 + prompt 反向通道 + 自检页
├── assets/
│   ├── pet.js               前端本体：Live2D 渲染 / 情绪 rig / 状态机 / 气泡 / 输入框
│   ├── vendor/              Live2D Cubism Core · PIXI 6.5.10 · pixi-live2d-display 0.4.0
│   └── model/               模型本体 + 由 tools/build-model.mjs 生成的清单
├── tools/
│   ├── build-model.mjs      把 VTube Studio 原始素材整理成可消费的形态
│   ├── preview-server.mjs   脱离 DSH 的预览 + 假 agent 事件发生器
│   ├── pet-ctl.mjs          agent / 命令行驱动桌宠
│   ├── smoke.mjs            浏览器内功能自检
│   └── shot.mjs             CDP 截图
├── docs/                    截图、作者按键表对照、发布说明
└── skill/SKILL.md           给 agent 看的用法说明，装到 ~/.dsh/skills/ 后自动生效

开发用：node tools/preview-server.mjs 打开 http://127.0.0.1:5199 可以不启动 DSH 就预览 （左上角三个按钮可以假装 agent 在干活）。

📜 许可与署名 / License & credits

代码 MIT，美术素材非商业 —— 这两句都要看。

模型与角色形象是三重版权链，都要署名（详见 AUTHORS.md）：

本项目是非商业的：完全免费，不收费、不带货、不接广告变现、不卖周边、不作为任何付费产品或服务的卖点。 模型作者的无偿分享与转载授权，不解除角色形象本身的 NC / SA 条件。模型包原《使用须知》原文、 逐文件来源、以及权利主张方式见 PROVENANCE.md。

English: the code is MIT (© 2026 Andersen216, see LICENSE); the bundled artwork is not — it is used under CC BY-NC-SA 4.0 and must be credited to 上善无形 / ZipZipPipe / 氵六青 (see NOTICE.md and AUTHORS.md). This project is free and non-commercial: no fees, no ads, no merchandise, not a selling point of any paid product. Live2D Cubism Core belongs to Live2D Inc.; PIXI.js and pixi-live2d-display are MIT.

🔗 相关链接 / Links

• 更新日志：CHANGELOG.md · Releases
• 按键表对照（52 条热键逐条对照）：docs/作者按键表-对照.md
• 插件市场收录进度：awesome-dsh-plugin PR #5882
• 发布 / 装机问题排查：docs/发布到插件市场.md