Skip to content
Back to search

dsh-whale-girl-live2d

🐋 鲸鱼娘桌宠 · Whale Girl Live2D —— DSH(DeepSeek Harness)Web 界面里的 Live2D 桌宠:跟着 agent 的真实状态换表情与动作,点一下就能直接跟 agent 说话,右键是钱包。A Live2D desktop pet for the DSH Web UI. 安装 Install: dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/andersen216--dsh-whale-girl-live2d/badge.svg)](/listings/andersen216--dsh-whale-girl-live2d)

HTML

<a href="/listings/andersen216--dsh-whale-girl-live2d"><img src="/api/listings/andersen216--dsh-whale-girl-live2d/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

🅰 先装网页版,再装桌面版(推荐)

# ① 装插件
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](https://github.com/Andersen216/dsh-whale-girl-live2d/releases/latest) 下载 **`DS-WhaleGirl-Pet-macOS-*.zip`** → 解压 → 把 **`DS 鲸鱼娘桌宠.app`** 拖进「应用程序」→ 双击。

🅱 先装桌面版,再装网页版(也可以)

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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 584 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. ## 🚀 网页版一键部署(不用懂命令行)
  3. DSH 网页版原来要自己装 Node、装 CLI、起服务、再装插件 —— 现在一条命令搞定:
  4. ```bash
  5. # macOS / Linux / WSL:起网页版(自动挑空闲端口、自动打开浏览器)
  6. curl -fsSL https://raw.githubusercontent.com/Andersen216/dsh-whale-girl-live2d/main/tools/dsh-web-deploy.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 10 on GitHub
  7. # 想连桌宠插件一起装好
  8. curl -fsSL https://raw.githubusercontent.com/Andersen216/dsh-whale-girl-live2d/main/tools/dsh-web-deploy.sh | bash -s -- --with-pet
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 13 on GitHub
  9. ```
  10. Windows:下载仓库里的 `tools/dsh-web-deploy.cmd` **双击运行**(内部走 PowerShell,
  11. 已绕开执行策略;⚠️ 作者没有 Windows 机器,这版**尚未真机验证**)。
  12. **它做了什么**:检查 Node(≥20)→ 复用已装的 dsh(没有就用 `npm exec` 免安装跑)→
  13. 用官方支持的 `--port 0` 让系统挑空闲端口 → 抓出带登录 token 的地址 → 自动开浏览器 →
  14. (可选)装桌宠插件。
  15. **子命令**:`--doctor` 只体检不起服务 · `stop` 停止 · `status` 看状态。
  16. 状态记在 `~/.dsh/.web-deploy.json`(**只存 pid/端口/时间,不存 token**)。
  17. > 为什么不用现成的?调研了一圈(2026-10-03),社区 6 个「一键部署」项目**全是 Windows 专用**
  18. > (.cmd / PowerShell / WinForms),macOS/Linux 的 `curl | bash` 是空白;而且多数选择
  19. > 「下便携 Node + 拉源码 + 完整构建」这条 2–4GB 的重路径 —— 其实 `npm exec` 直接跑官方包即可。
  20. ## 兼容性(重要)
  21. | 宿主 | 状态 |
  22. | --- | --- |
  23. | DSH **0.2.0-rc.1 / 0.2.0-rc.2**(官方桌面版当前版本) | ✅ **对齐的目标版本**,开发与验证都在这个版本上 |
  24. | DSH 0.2.x(后续版本) | 🔄 会持续跟进 |
  25. | DSH **0.1.x**(例如桌面版 0.1.7-rc.2) | ❌ **不支持** —— 会报 `failed to import` / `did not activate` |
  26. 为什么老版本不行:宿主插件 API 在 0.1.x → 0.2.x 之间有过变动
  27. (举例:`connection.requestRejection` 在 0.1.0-rc.3 上不存在、0.1.5-rc.2 上才有)。
  28. 本插件本身**只依赖 Node 内置模块**、没有任何第三方依赖,所以加载失败不是缺依赖,
  29. 而是与老宿主的 API 不匹配。
  30. **遇到 `failed to import` 怎么办**:把官方桌面版 / DSH 升级到 **0.2.0-rc.x 或更新**,重装插件即可。
  31. # 🐋 鲸鱼娘桌宠 · Whale Girl Live2D
  32. **DSH(DeepSeek Harness)Web 界面里的 Live2D 桌宠 —— 她真的在跟着 agent 干活。**
  33. **A Live2D desktop pet for the DeepSeek Harness Web UI — she really does follow what the agent is doing.**
  34. [![Release](https://img.shields.io/github/v/release/Andersen216/dsh-whale-girl-live2d?label=release&color=2f81f7)](https://github.com/Andersen216/dsh-whale-girl-live2d/releases)
  35. [![Code: MIT](https://img.shields.io/badge/code-MIT-3fb950)](LICENSE)
  36. [![Artwork: CC BY-NC-SA 4.0](https://img.shields.io/badge/artwork-CC%20BY--NC--SA%204.0-d29922)](NOTICE.md)
  37. [![Non-commercial](https://img.shields.io/badge/use-non--commercial-e5534b)](NOTICE.md)
  38. [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-8957e5)](#-安装--install)
  39. <img src="docs/screenshots/01-待机.jpg" alt="鲸鱼娘待在 DSH 界面右下角,左手笔右手本子" width="820">
  40. 点一下就能跟 agent 说话 · 右键就是钱包 · 表情 / 装饰 / 场景 / 动作 四页菜单 · 拖动换位置
  41. </div>
  42. ---
  43. ## 🐋 先读这三行:只有**一套插件**,两种用法
  44. 1. **插件只有一个**:`dsh-whale-girl-live2d`。装一次,网页版和桌面版**共用同一份** ——
  45. 模型、动作、表情、跟 agent 的联动、菜单、钱包、设置,全部在插件里。
  46. 2. **网页版** = 插件自带的用法,装完就有(Windows / macOS / Linux 都能用)。
  47. 3. **桌面版** = 额外下载一个 **1.4 MB 的 macOS 外壳 App**,把同一个页面放进桌面上的独立窗口。
  48. **它不是第二个插件**,也不用再装任何东西。
  49. > **「网页版和桌面版是两套不同的插件吗?」→ 不是。**
  50. > 是一套插件 + 一个可选的 Mac 外壳。所以你不需要"两边都装插件",
  51. > 也不存在"装了桌面版会不会跟网页版冲突"。
  52. ### 两种用法对照
  53. | | 🖥 **网页版** | 🐋 **桌面版**(macOS 外壳) |
  54. | --- | --- | --- |
  55. | 是什么 | 插件本体(**必装**) | 一个 1.4 MB 的 App,加载插件提供的那一页 |
  56. | 她住在哪 | DSH Web 界面右下角(浏览器标签页里) | **你的桌面上**:透明、无边框、永远置顶 |
  57. | 支持平台 | **Windows / macOS / Linux** | **只有 macOS 13+**(跨平台外壳在计划中) |
  58. | 需要装什么 | 插件 | 插件 **+** 这个 App |
  59. | 浏览器要开着吗 | 要(她在那张标签页里) | **不用**,DSH 在跑就行 |
  60. | 额外能力 | — | 点击穿透(不挡干活)· 拖她=拖窗口 · **贴边悬浮球** · 菜单栏 🐋 · 低性能模式 · 设置里「彻底关闭 App」 |
  61. ### 安装:两条路都行,按你现在的状态选
  62. #### 🅰 先装网页版,再装桌面版(推荐)
  63. ```bash
  64. # ① 装插件
  65. dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d
  66. # ② 重启 DSH(宿主插件只在启动时加载),然后刷新页面
  67. # 右下角出现她 = 网页版成功
  68. # ③ 自检(返回 401 = 已挂载,被信任栅栏挡着,正常;404 = 没加载)
  69. curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/dsh-pet/pet.js
  70. ```
  71. 然后装桌面版:去 [Releases](https://github.com/Andersen216/dsh-whale-girl-live2d/releases/latest)
  72. 下载 **`DS-WhaleGirl-Pet-macOS-*.zip`** → 解压 → 把 **`DS 鲸鱼娘桌宠.app`** 拖进「应用程序」→ 双击。
  73. #### 🅱 先装桌面版,再装网页版(也可以)
  74. 1. 直接下载上面那个 zip,解压、拖进「应用程序」、双击。
  75. → 这时窗口里会显示一张提示卡「**🐋 正在找 DSH…**」——**这是正常的**,因为插件还没装。
  76. 2. 再按 🅰 的 ①②③ 装插件并重启 DSH。
  77. 3. **她会出现,不用重启 App** —— App 每 5 秒自动重试一次,插件一就位她就自己出来了。
  78. > ⚠️ 顺序无所谓,但**少了插件一定不行**:桌面 App 本身不带模型、不带联动
  79. > (所以它只有 1.4 MB)。它只是一个窗口,内容全在插件里。
  80. ### Windows / Linux 用户看这里
  81. - **桌面外壳目前只有 macOS 版**(Swift 编译出来的 `.app`),Release 里只有 Mac 附件。
  82. - Windows / Linux **用网页版就行**,功能完全一样(联动、菜单、钱包一个不少),只是她住在浏览器标签页里。
  83. - 跨平台外壳(Electron)在计划中;在那之前,Windows 用户可以用
  84. `http://127.0.0.1:3080/dsh-pet/standalone` 配 Chrome 的「创建快捷方式 → 在窗口中打开」,
  85. 得到一个小窗效果(但**不透明、不置顶、不能点击穿透**,不是真桌宠)。
  86. ### 装完不出现 / 连不上?按顺序查这五条
  87. | 现象 | 原因 | 怎么办 |
  88. | --- | --- | --- |
  89. | 桌面 App 里显示「正在找 DSH…」 | 插件没装 / DSH 没跑 / 插件被停用了 | 先确认 `curl …/dsh-pet/pet.js` 是 **401**;是 404 就往下看 |
  90. | `/dsh-pet/pet.js` 返回 **404** | 插件没被注册,或**在插件设置里被停用** | ① 看 `~/.dsh/profiles/web/package.json` 的 `dependencies` 与 `dsh.profile.bundles` 里有没有 `dsh-whale-girl-live2d`;② 看 `~/.dsh/profiles/web/cordis.patch.yml` 里**有没有 `- id: dsh-live2d-pet` + `disabled: true`**(有就删掉这两行)——**踩过一次**:插件被误停用,表现为「App 突然连不上、她也消失」 |
  91. | 网页版刷新后什么都没有 | **宿主插件要重启 DSH 才加载** | 重启 DSH,再强刷页面(`Cmd+Shift+R` / `Ctrl+F5`) |
  92. | 双击 App 好像没反应 | 它是**无 Dock 图标**的后台型 App,可能已经在跑了 | 看**菜单栏右上角的 🐋**;再双击一次会把窗口叫到最前面;`~/Applications/` 里只该有**一份** App |
  93. | 更新了但没变化 | pnpm 按 lockfile 记住了旧 commit | `dsh plugin --profile web update dsh-whale-girl-live2d`;不行就 remove 再 add |
  94. ### 桌面版的技术说明(想知道细节再看)
  95. 见 [`desktop/README.md`](desktop/README.md):本机通行证(为什么壳子能过信任栅栏)、
  96. 透明窗口的私有键、点击穿透怎么判定、怎么自己编译。
  97. ## 🚀 安装(网页版)/ Install the web version
  98. > **先确认一件事**:你机器上已经装好 DSH(DeepSeek Harness)。终端里敲 `dsh --version` 有输出就说明没问题;
  99. > 没装的话先装 DSH,再回来装这个桌宠。
  100. ### 方式 A:命令行装(推荐,一条命令)
  101. ```bash
  102. dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d
  103. ```
  104. - `--profile web` 是 DSH Web 界面的 profile 名。如果你用的是别的 profile 名,把 `web` 换成你自己的。
  105. - 这条命令会从 GitHub 拉取插件并注册进 profile(需要能访问 GitHub)。
  106. ### 方式 B:手动下载 ZIP(不想用命令行 / 公司网络限制 git)
  107. 1. 打开仓库页面 → 绿色 **Code** 按钮 → **Download ZIP**
  108. 2. 解压到一个**你能记住的目录**,例如:
  109. - macOS / Linux:`~/Documents/dsh-whale-girl-live2d-main`
  110. - Windows:`C:\Users\你的用户名\Documents\dsh-whale-girl-live2d-main`
  111. 3. 用 **绝对路径**装(`link:` 后面必须是绝对路径;**有空格一定要加引号**):
  112. ```bash
  113. # macOS / Linux
  114. dsh plugin --profile web add "link:/Users/你的用户名/Documents/dsh-whale-girl-live2d-main"
  115. ```
  116. ```powershell
  117. # Windows(PowerShell / CMD 都可以)
  118. dsh plugin --profile web add "link:C:\Users\你的用户名\Documents\dsh-whale-girl-live2d-main"
  119. ```
  120. ### 方式 C:从 DSH 插件市场装
  121. 等本插件被 [DSH 插件市场](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 收录后,
  122. 在界面的插件中心搜 **`鲸鱼娘`**、**`whale-girl`** 或 **`live2d`** 就能一键安装(收录进度见下方「相关链接」)。
  123. **现在还没收录**,先走方式 A 或 B。
  124. ### 装完必须做两步(少一步都不会出现)
  125. 1. **重启 DSH**(宿主插件只在启动时加载):把正在跑的 `dsh web` 停掉,重新起一次
  126. 2. **刷新页面**(强刷 `Cmd+Shift+R` / `Ctrl+F5`)
  127. 装成功后,界面右下角会出现鲸鱼娘。
  128. ### 一行自检
  129. 浏览器打开:**`http://127.0.0.1:3080/dsh-pet/pet.js`**
  130. | 看到 | 意思 |
  131. | --- | --- |
  132. | **401** | ✅ 插件已挂载(被 DSH 的信任栅栏挡着,这是正常的) |
  133. | **404** | ❌ 插件没被加载 —— 看下面的「排错」 |
  134. | 满屏 JS 代码 | ✅ 也已经挂载了(你的 DSH 没开信任栅栏) |
  135. ### 更新 / 卸载
  136. ```bash
  137. # 更新到最新版(更新完同样要重启 DSH + 刷新页面)
  138. dsh plugin --profile web update dsh-whale-girl-live2d
  139. # 卸载
  140. dsh plugin --profile web remove dsh-whale-girl-live2d
  141. ```
  142. <details>
  143. <summary><b>🇬🇧 English — Install</b>(点开)</summary>
  144. **Requirements**: DSH (DeepSeek Harness) already installed — `dsh --version` should print something.
  145. **Option A — one command (recommended)**
  146. ```bash
  147. dsh plugin --profile web add github:Andersen216/dsh-whale-girl-live2d
  148. ```
  149. `web` is the profile name used by the DSH Web UI; replace it if your profile is named differently.
  150. This pulls the plugin from GitHub and registers it in that profile (needs GitHub access).
  151. **Option B — download the ZIP** (no command line / git blocked): click **Code → Download ZIP**, unzip it
  152. anywhere, then install it by **absolute path** (quote it — especially on Windows or with spaces):
  153. ```bash
  154. dsh plugin --profile web add "link:/absolute/path/to/dsh-whale-girl-live2d-main"
  155. ```
  156. **Option C — from the DSH plugin market**: once the plugin is listed, search for `whale-girl` or `live2d`
  157. in the plugin center and install with one click. *It is not listed yet* — use A or B for now.
  158. **After installing, two steps are mandatory**: ① **restart DSH** (host plugins load at startup), ② **reload
  159. the page** (hard reload: `Cmd+Shift+R` / `Ctrl+F5`). She appears in the bottom-right corner.
  160. **One-line check**: open `http://127.0.0.1:3080/dsh-pet/pet.js` — **401** means loaded (the trust gate is
  161. doing its job), **404** means not loaded (see Troubleshooting).
  162. **Update / remove**
  163. ```bash
  164. dsh plugin --profile web update dsh-whale-girl-live2d # then restart DSH + reload
  165. dsh plugin --profile web remove dsh-whale-girl-live2d
  166. ```
  167. </details>
  168. ---
  169. ## 🎮 一分钟上手 / Quick start
  170. | 你想干嘛 | 怎么做 |
  171. | --- | --- |
  172. | **跟她说话 / 给 agent 发消息** | 点工具栏的 **「说话」** 打开输入框(**再点一次就关**),`Enter` 发送、`Shift+Enter` 换行;回复会逐字冒进气泡里。旁边「打断」可以中止当前这一轮 |
  173. | **摸摸她** | 直接点她(上半身和下半身反应不一样;连着猛点会炸毛,这是设计) |
  174. | **换表情 / 换装 / 摆场景 / 演小动作** | 点工具栏的 **`⋯`**,菜单分四页(见下方「菜单」) |
  175. | **看余额 / 本轮花了多少** | **右键点她**,弹出钱包(再按一次右键、点 ×、点别处或按 `Esc` 都能收) |
  176. | **挪位置** | 直接拖。松手时:靠左/右墙就吸过去,**竖直位置保持你放的高度**;离两侧都远就停在原地 |
  177. | **藏起来** | 点工具栏的 **`–`**,右下角留个小把手,点一下就叫回来 |
  178. | **一键重置** | 菜单 →「设置」→「一键重置所有状态」:表情、道具、场景、动作全部回到最初的「本子 + 笔 + 平常脸」 |
  179. <details>
  180. <summary><b>🇬🇧 English — Quick start</b></summary>
  181. - **Talk to the agent**: click **「说话」/ Speak** in the toolbar to open the input box (click it again to
  182. close it). `Enter` sends, `Shift+Enter` is a newline; the reply streams into a speech bubble. The
  183. **「打断」/ Interrupt** button cancels the current turn.
  184. - **Pet her**: just click her (upper and lower body react differently; clicking fast repeatedly makes her
  185. snap — that is intentional).
  186. - **Expressions / dress-up / desk scenes / one-shot animations**: click **`⋯`** in the toolbar.
  187. - **Balance & turn cost**: **right-click her** — a wallet HUD appears (right-click again, click ×, click
  188. elsewhere, or press `Esc` to close).
  189. - **Move her**: drag. On release she snaps to the left/right wall if close enough; the vertical position
  190. stays exactly where you put her.
  191. - **Hide**: click **`–`**; a small handle stays in the bottom-right corner to bring her back.
  192. - **Reset everything**: menu → Settings → "Reset all state".
  193. </details>
  194. ---
  195. ## ✨ 这是什么 / What is this
  196. **中文**
  197. 把 Live2D 模型「鲸鱼娘」挂进 DSH 的 Web 界面。她常驻在桌面角落,**不是一张静态贴图**——
  198. 她在跟着 **agent 的真实状态**动:思考时低头、查资料时戴上眼镜掏出手机、逐字输出时嘴巴跟着动、
  199. 报错时黑一下脸、一轮收工就伸懒腰庆祝。
  200. 和「一张 PNG 加气泡文案」的挂件不同:这是活的 Live2D —— **44 个表情、8 个动作**、物理摆动、视线跟随,
  201. 而且由**真实的事件流**驱动(不是轮播动画)。所有小动作都照**模型作者自己的按键表**来
  202. (52 条热键逐条对照,见 [`docs/作者按键表-对照.md`](docs/作者按键表-对照.md)),所以互不冲突、
  203. 不会互相覆盖、到点自己收回。
  204. **English**
  205. Whale Girl Live2D puts a Live2D model — the DeepSeek whale girl — inside the DSH Web UI. She lives in a
  206. corner of the screen and is **not a static sticker**: she follows **what the agent is actually doing**,
  207. tilting her head while thinking, putting on glasses and pulling out a phone when the agent reads or
  208. searches, moving her mouth as text streams in, darkening her face when a tool errors, and stretching in
  209. celebration when a turn finishes. Unlike a PNG-with-a-bubble widget this is real Live2D: **44 expressions,
  210. 8 motions**, physics, gaze tracking — driven by the **real event stream**, not an animation loop. Every
  211. one-shot action is mapped from the **original model author's own hotkey sheet** (52 hotkeys, item by item —
  212. see [`docs/作者按键表-对照.md`](docs/作者按键表-对照.md)), so nothing overlaps and everything expires on its own.
  213. ### 🧠 她跟 agent 的联动 / What she reacts to
  214. | agent 在干什么 | 她的反应 |
  215. | --- | --- |
  216. | 主人在说话 / 正在思考 | 星星眼听着 / 低头想事,手里是本子 + 笔 |
  217. | 调用工具 | 按工具换脸换动作:读文件 = 戴眼镜凑近看,上网 = 掏出手机,写文件 = 奋笔疾书,跑命令 = 挽袖子 |
  218. | 逐字输出回复 | 气泡逐字冒字 + 走路般的小幅度摆动 |
  219. | 工具报错 / 整轮失败 | 黑一下脸(很短,不砸东西);成功收工 = 伸懒腰 + 比耶 + 用时 / 花费统计 |
  220. | 长时间没动静 | 她自己会动:换视线、换个表情几秒、自言自语、喊饿 |
  221. > **English**: thinking → head down with notebook and pen; tool calls → face and motion follow the tool
  222. > (reading = glasses, web search = phone, writing = scribbling, shell = rolled-up sleeves); streaming text
  223. > → mouth moves, bubble fills letter by letter; tool error → she darkens for a moment; turn finished →
  224. > stretch, peace sign and a stats bubble; idle for a long time → she glances around, changes expression for
  225. > a few seconds, mutters to herself or complains she is hungry.
  226. ---
  227. ## 🎭 菜单:表情 / 装饰 / 场景 / 动作
  228. 点 `⋯` 打开的菜单有四页,**每页守一条不同的规矩**:
  229. | 页 | 内容 | 生命周期 |
  230. | --- | --- | --- |
  231. | **表情** | 按表情去重的一张脸(16 个按钮) | **临时**:点了演 3~4 秒,自己让位;平常状态永远是**平常脸**;期间她自己的表情 / agent 事件 / 你再点一个都会把它顶掉 |
  232. | **装饰** | 眼镜、贴纸、花花、发箍、单边马尾、头顶鲸 | **常驻**:戴上就留着,再点一下摘掉(同类互斥:眼镜只戴一副、贴纸只贴一张) |
  233. | **场景** | 深色桌布、鲸鱼放桌上、巴菲、粉 / 白魔爪、掏出手机、手机换色 | **常驻**:摆着不走,再点一下收 |
  234. | **动作** | 猫爪摆手、喵喵手、比耶、冒爱心、心跳、MoeMoeQ~、橡皮、撤回、蛋包饭、自拍、快速自拍、喷水 | **一次性**:演一遍就消失,绝不写进常驻层 |
  235. > **English**: four tabs with four different lifetimes — **Expressions** are temporary (3–4 s, then she
  236. > hands her face back to the motions); **Accessories** and **Scenes** are persistent (toggle on/off, one
  237. > per category); **Actions** are one-shot (they play once and clean themselves up). The omurice action is
  238. > the special case: it is an expression plus the ketchup-squeezing motion, and it disappears right after
  239. > the sauce is squeezed.
  240. **永久移除**(代码里也拦死了 `BANNED_MOTIONS`,菜单里找不到):吹泡泡糖、大锤砸、呆呆眼、圈圈眼。
  241. **工作优先级高于互动**:干活时点她**不打断**——不改脸、不放动作,最多弹一下表示「知道了」。
  242. ---
  243. ## 💰 右键 = 钱包(余额 / 本轮消耗 / 峰谷计价)
  244. | 显示 | 说明 |
  245. | --- | --- |
  246. | **剩余余额** | DeepSeek 官方 `user/balance` 接口。key 从 DSH 的凭据服务读(`DEEPSEEK_API_KEY`),读不到就显示「未配置」 |
  247. | **本轮消耗** | 每轮结束**自动弹出来**:金额 + tokens(按命中 / 未命中 / 输出三个口径分别计价) |
  248. | **今日已用** | 当天累计(按北京时间分日) |
  249. | **峰 / 谷** | **峰 = 红,谷 = 绿**。高峰 = 北京时间周一至周五(不含法定节假日)9:00–12:00、14:00–18:00;其余(含周末、法定节假日)都是谷价 |
  250. | **距切换** | 距离下一次峰谷切换还有多久(每秒刷新,跨过切换点自动重拉余额) |
  251. - 计价用 Flash 价目(命中 0.02 / 未命中 1 / 输出 4 元每百万 token,高峰 = 空闲 ×2);换 Pro 模型自动按 3 倍算。
  252. - **不跟对话抢屏幕**:开菜单时 HUD 自动收起;鼠标停在 HUD 上时不会被自动收起;自动弹出的那次 9 秒后自己收。
  253. - **不依赖别的插件**:余额 / 峰谷 / 记账都是这个插件宿主自己算的;两个数据源都没有时显示「读不到余额接口」,不假装有数。
  254. > **English**: right-click her for a wallet HUD: remaining balance (DeepSeek's official `user/balance`
  255. > endpoint, key read from DSH's credential service), this turn's cost (auto-popped when a turn ends, with
  256. > hit / miss / output token tiers), today's total, and peak / off-peak pricing (**peak = red, off-peak =
  257. > green**; peak hours are Mon–Fri 09:00–12:00 and 14:00–18:00 Beijing time, holidays excluded). It never
  258. > fights the chat for screen space, and it works without any other plugin installed.
  259. ---
  260. ## 🤖 让 agent 主动指挥她 / Agent control
  261. 装好之后,agent(或者你自己)可以用命令行指挥她:
  262. ```bash
  263. cd <你放插件的目录>/dsh-whale-girl-live2d
  264. node tools/pet-ctl.mjs status # 她在不在、当前会话、连接数
  265. node tools/pet-ctl.mjs mood happy # 换情绪
  266. node tools/pet-ctl.mjs expr 星星眼 # 直接指定表情
  267. node tools/pet-ctl.mjs motion selfie # 播动作
  268. node tools/pet-ctl.mjs say "搞定了!" # 弹一句话
  269. node tools/pet-ctl.mjs prop 猫猫贴纸 on # 戴道具
  270. node tools/pet-ctl.mjs ask "要继续吗?" # 弹话 + 打开面板提醒你
  271. ```
  272. 底层就是一个本地 HTTP 接口,也可以直接打:
  273. ```bash
  274. curl -X POST http://127.0.0.1:3080/dsh-pet/control \
  275. -H 'Content-Type: application/json' \
  276. -d '{"mood":"happy","motion":"selfie","say":"你好呀"}'
  277. ```
  278. 浏览器控制台里还有 `DSHPet` 对象可以直接玩:
  279. ```js
  280. DSHPet.state // 当前状态
  281. DSHPet.setMood('angry') // 换脸
  282. DSHPet.playMotion('selfie')
  283. DSHPet.setProp('glassesSun', true)
  284. DSHPet.hitTest(x, y) // 这个坐标算不算点在它身上
  285. ```
  286. <details>
  287. <summary><b>🇬🇧 English — Agent control</b></summary>
  288. The host exposes a small local HTTP API, so an agent (or you) can drive her directly:
  289. `GET /dsh-pet/state`, `GET /dsh-pet/events` (SSE), `POST /dsh-pet/say` `{text}`,
  290. `POST /dsh-pet/cancel`, `POST /dsh-pet/control` `{mood, expr, motion, prop, say}`,
  291. `GET /dsh-pet/standalone` (pet-only page). `tools/pet-ctl.mjs` is a thin CLI over the same endpoints.
  292. A `DSHPet` object is also exposed in the browser console (see the code block above).
  293. </details>
  294. ---
  295. ## 🩺 排错 / Troubleshooting
  296. **先做这一步**:打开 **`http://127.0.0.1:3080/dsh-pet/diag`** —— 一条 URL 把启动过程、模型尺寸、
  297. 取景结果、可用表情 / 动作、被过滤的参数全列出来。出问题截图这一页就够定位了。
  298. | 现象 | 原因 | 怎么办 |
  299. | --- | --- | --- |
  300. | `dsh: command not found` | DSH 没装或没进 PATH | 先装好 DSH;临时可用 `npx @deepseek-ai/dsh plugin --profile web add ...` |
  301. | **照着旧教程 `link:` 装,报路径不存在** | 教程里写的是**别人的**(作者的)本机路径 | `link:` 后面必须是**你自己机器上的绝对路径**,指向你解压出来的目录;路径有空格要加引号 |
  302. | 装完刷新页面什么都没有 | **宿主插件要重启 DSH 才加载** | 重启 DSH(`dsh web` 那个进程),再刷新页面 |
  303. | 重启后还是没有 | 启动日志里有 `dsh-whale-girl-live2d` 的报错 | 多半是 `cordis.patch.yml` 的 `name:` 与包名不一致(本仓库已一致,改过就别动) |
  304. | 连 `/dsh-pet/pet.js` 都 404 | 插件没被注册进 profile | 检查 profile 的 `package.json`:`dependencies` 和 `dsh.profile.bundles` 里都要有 `dsh-whale-girl-live2d` |
  305. | **更新了但版本号没变** | pnpm 按 lockfile 记住了上次解析的 commit | `dsh plugin --profile web remove dsh-whale-girl-live2d` 再 `add` 一次;或 `dsh plugin --profile web install --force` |
  306. | 桌宠挡住按钮 / 想换个大小 | — | 拖动挪开、点 `–` 藏起来;大小和取景在菜单 →「设置」里 |
  307. | 她一直不动 | 没有会话在干活(她本来就是「平时不动」的设计) | 打开一个对话发一句话,或者 `node tools/pet-ctl.mjs motion selfie` 试一下 |
  308. <details>
  309. <summary><b>🇬🇧 English — Troubleshooting</b></summary>
  310. | Symptom | Cause | Fix |
  311. | --- | --- | --- |
  312. | `dsh: command not found` | DSH not installed / not on PATH | Install DSH first; or use `npx @deepseek-ai/dsh plugin --profile web add ...` |
  313. | `link:` install fails with "path does not exist" | the path in a tutorial was **someone else's machine** | `link:` needs **your own absolute path** to the folder you unzipped; quote it if it has spaces |
  314. | Nothing appears after install | **host plugins only load when DSH restarts** | restart DSH, then reload the page |
  315. | Still nothing after restart | an error in the DSH startup log | usually a `name:` mismatch in `cordis.patch.yml` |
  316. | `/dsh-pet/pet.js` returns 404 | plugin not registered in the profile | the name must appear in both `dependencies` and `dsh.profile.bundles` of the profile's `package.json` |
  317. | Updated but the version did not change | pnpm resolved the old commit from the lockfile | remove and re-add the plugin, or run `dsh plugin --profile web install --force` |
  318. | She never moves | no session is working (that *is* the idle design) | send a message in a chat, or try `node tools/pet-ctl.mjs motion selfie` |
  319. Diagnostics page: `http://127.0.0.1:3080/dsh-pet/diag`.
  320. </details>
  321. ---
  322. ## ⚙️ 配置 / Config
  323. 默认值写在 `lib/index.js` 的 `DEFAULT_CONFIG`;用户覆盖写在 **`~/.dsh/dsh-live2d-pet.json`**
  324. (文件名沿用旧名,改它会读不到,别改):
  325. ```json
  326. {
  327. "enabled": true,
  328. "height": 340,
  329. "corner": "br",
  330. "lookAtCursor": true,
  331. "talkMouth": true,
  332. "sleepAfterMs": 180000,
  333. "showReasoning": false
  334. }
  335. ```
  336. `enabled: false` 会连注入脚本一起去掉(改完要重启 DSH)。
  337. > **English**: defaults live in `DEFAULT_CONFIG` in `lib/index.js`; override them in
  338. > `~/.dsh/dsh-live2d-pet.json` (the filename intentionally keeps the old name). Changing `enabled` requires
  339. > a DSH restart.
  340. ---
  341. ## 🔧 它内部是怎么动的 / How it works
  342. 模型这套资产原本是给 VTube Studio 用的:44 个「表情」其实是 44 组参数开关(全是 Add 混合),
  343. `model3.json` 里连 `Motions` 段都没有。所以做了三件事:
  344. 1. **补 `model3.json`**:把 8 个动作按独立 group 注册进去,标准 Live2D 运行时才播得动
  345. (`tools/build-model.mjs` 生成,可重跑)。
  346. 2. **自己写 rig,不用框架的 expressionManager**:挂在 `InternalModel` 的 `beforeModelUpdate` 上——
  347. 那是 `model.update()` 之前的最后一站,动作 / 眨眼 / 视线 / 物理都已经算完,我们加的参数一定生效;
  348. 而每帧结尾 `loadParameters()` 会把参数还原,所以写入不跨帧累积。情绪(互斥)和道具(粘性)分开管;
  349. 权重降到 0 的表达式不再写参数,把脸交还给动作,这样「伸展」「自拍」这些自带表情的一次性动作
  350. 才不会被抹平成面瘫。
  351. 3. **命中判定用 alpha 掩码**,不是包围盒:这个模型是一整张书桌场景,包围盒里大半是空气,
  352. 点空气要让事件穿透到下面的 DSH 界面。
  353. 事件侧:宿主监听 `ctx.on('session/event')`(轮次 / 步骤 / 工具 / 最终消息)和
  354. `ctx.on('agent/assistant-stream')`(**真正的逐字流**),过滤出「人正在用的那个会话」后用 SSE 推给前端;
  355. 反向用官方的 `sessionController.prompt()`,跟你在界面上打字是同一条路。
  356. > **English**: the artwork was authored for VTube Studio, so the repo adds a `model3.json` with the eight
  357. > motions registered as proper groups, drives parameters from a hand-written rig hooked onto
  358. > `InternalModel`'s `beforeModelUpdate` (mood = exclusive, props = sticky; expressions at weight 0 stop
  359. > writing so one-shot motions keep their own faces), and hit-tests against an alpha mask instead of a
  360. > bounding box so clicks on empty air fall through to the UI. The host bridges real agent events
  361. > (`session/event`, `agent/assistant-stream`) over SSE, and sends messages back through the official
  362. > `sessionController.prompt()`.
  363. ---
  364. ## ⚠️ 已知限制 / Known limitations
  365. - **模型里有两处参数引用是坏的**(原作者的遗留):`喵喵手~喵~动画` 引用了模型里不存在的
  366. `ParamCheek51` / `ParamCheek61`;`番茄酱` 动作引用了 `keyboard` / `xbox`。
  367. 前端启动时会自动过滤掉并在控制台说明。
  368. - 桌宠显示在 DSH Web 页面里;**关掉页面它就没了**。想要常驻桌面可以用
  369. `/dsh-pet/standalone` + `open -na "Google Chrome" --args --app=http://127.0.0.1:3080/dsh-pet/standalone`。
  370. - 模型没有音频资源,所以 `config.sound` 目前是占位,没有实现。
  371. ---
  372. ## 📁 目录结构 / Layout
  373. ```
  374. dsh-whale-girl-live2d/
  375. ├── package.json DSH bundle 插件元数据(dsh.bundle.patch)
  376. ├── cordis.patch.yml 挂载声明
  377. ├── screenshots.json 插件市场详情页用的截图清单
  378. ├── lib/index.js 宿主侧:静态资源 + SSE 事件桥 + prompt 反向通道 + 自检页
  379. ├── assets/
  380. │ ├── pet.js 前端本体:Live2D 渲染 / 情绪 rig / 状态机 / 气泡 / 输入框
  381. │ ├── vendor/ Live2D Cubism Core · PIXI 6.5.10 · pixi-live2d-display 0.4.0
  382. │ └── model/ 模型本体 + 由 tools/build-model.mjs 生成的清单
  383. ├── tools/
  384. │ ├── build-model.mjs 把 VTube Studio 原始素材整理成可消费的形态
  385. │ ├── preview-server.mjs 脱离 DSH 的预览 + 假 agent 事件发生器
  386. │ ├── pet-ctl.mjs agent / 命令行驱动桌宠
  387. │ ├── smoke.mjs 浏览器内功能自检
  388. │ └── shot.mjs CDP 截图
  389. ├── docs/ 截图、作者按键表对照、发布说明
  390. └── skill/SKILL.md 给 agent 看的用法说明,装到 ~/.dsh/skills/ 后自动生效
  391. ```
  392. > 开发用:`node tools/preview-server.mjs` 打开 `http://127.0.0.1:5199` 可以不启动 DSH 就预览
  393. > (左上角三个按钮可以假装 agent 在干活)。
  394. ---
  395. ## 📜 许可与署名 / License & credits
  396. **代码 MIT,美术素材非商业 —— 这两句都要看。**
  397. | | 覆盖范围 | 许可 |
  398. | --- | --- | --- |
  399. | **代码** | `lib/`、`tools/`、`cordis.patch.yml`、`assets/pet.js` | **MIT**,Copyright © 2026 **Andersen216**([`LICENSE`](LICENSE)) |
  400. | **美术素材** | `assets/model/**`(moc3 / 贴图 / 表情 / 动作)、字体等 | **CC BY-NC-SA 4.0**(署名 — **非商业性使用** — 相同方式共享),版权归下面三位([`NOTICE.md`](NOTICE.md)) |
  401. | **运行时** | Live2D Cubism Core(Live2D Inc.)· PIXI.js(MIT)· pixi-live2d-display(MIT) | 各自的许可条款 |
  402. 模型与角色形象是**三重版权链**,都要署名(详见 [`AUTHORS.md`](AUTHORS.md)):
  403. | 版权所有人 | 贡献 | 主页 |
  404. | --- | --- | --- |
  405. | 上善无形(上善) | 鲸鱼娘角色形象原作,原创 OC「溟月」 | [B 站](https://space.bilibili.com/4456176) |
  406. | ZipZipPipe | 加入 DeepSeek 元素的「女仆鲸鱼娘」二次设计 | [B 站](https://space.bilibili.com/4168597) |
  407. | 氵六青 | 本仓库所用 Live2D 模型(绑定、动作、表情) | [B 站](https://space.bilibili.com/11272072) |
  408. **本项目是非商业的**:完全免费,不收费、不带货、不接广告变现、不卖周边、不作为任何付费产品或服务的卖点。
  409. 模型作者的无偿分享与转载授权,不解除角色形象本身的 NC / SA 条件。模型包原《使用须知》原文、
  410. 逐文件来源、以及权利主张方式见 [`PROVENANCE.md`](PROVENANCE.md)。
  411. > **English**: the **code** is MIT (© 2026 Andersen216, see [`LICENSE`](LICENSE)); the bundled **artwork is
  412. > not** — it is used under **CC BY-NC-SA 4.0** and must be credited to **上善无形 / ZipZipPipe / 氵六青**
  413. > (see [`NOTICE.md`](NOTICE.md) and [`AUTHORS.md`](AUTHORS.md)). This project is **free and
  414. > non-commercial**: no fees, no ads, no merchandise, not a selling point of any paid product.
  415. > Live2D Cubism Core belongs to Live2D Inc.; PIXI.js and pixi-live2d-display are MIT.
  416. ---
  417. ## 🔗 相关链接 / Links
  418. - **更新日志**:[`CHANGELOG.md`](CHANGELOG.md) · [Releases](https://github.com/Andersen216/dsh-whale-girl-live2d/releases)
  419. - **按键表对照**(52 条热键逐条对照):[`docs/作者按键表-对照.md`](docs/作者按键表-对照.md)
  420. - **插件市场收录进度**:[awesome-dsh-plugin PR #5882](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/5882)
  421. - **发布 / 装机问题排查**:[`docs/发布到插件市场.md`](docs/发布到插件市场.md)
  422. <div align="center">
  423. **如果她让你开心了一下,给个 ⭐ 吧 —— 也欢迎把问题提到 [Issues](https://github.com/Andersen216/dsh-whale-girl-live2d/issues)。**
  424. *Made with 🐋 by [Andersen216](https://github.com/Andersen216) · 非商业项目,模型素材版权归原作者所有*
  425. </div>
  426. - **Windows 版双击没反应 / 一闪就退?** 先把解压目录换成**纯英文、不含空格**的路径
  427. (例如 `D:\whalepet\`)。含空格或中文的路径在部分机器上会触发 Electron 启动崩溃
  428. ([Issue #6](https://github.com/Andersen216/dsh-whale-girl-live2d/issues/6)),换路径即可。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.