One-Line Description

Place a blue-haired whale girl (fan-made desktop companion) on the edge of DSH desktop/web, automatically switching expressions, animations, and voice based on session state, while also displaying DeepSeek account balance and one-click recharge entry at the session header.

Core Features

• Display the whale girl companion on DSH desktop (Electron transparent always-on-top window) and Web (bottom-right floating iframe), switching between idle/running/happy/coquetry/sad states following DSH session events (turn/start, turn/end, tool/call, todo/write, goal/change, approval/*, command/*)
• Play jump + confetti + arpeggio + voice celebration on task completion; play "error comfort" voice on tool call failure; show bubble notification when waiting for approval
• Poke (65% coquettry / 20% bouncing / 15% grievance random), long-press hat for 0.7s to trigger head pat, double-click hat to mute, right-click menu, Esc to close menu
• Persist balance badge in Web session header, auto-refresh every minute, click to refresh immediately, with "Recharge" link next to it pointing to DeepSeek Open Platform recharge page
• Balance goes through server-side /api/balance reverse proxying official interface (https://api.deepseek.com/user/balance), server caches for 30 seconds, browser will NOT get API Key
• Network failure preserves last balance and marks it as stale to avoid UI flickering; main volume + separate voice/effects/celebration volume persisted via localStorage

Technical Implementation

• Language: JavaScript (ESM) + minimal Python (build/composition tools)
• Key Dependencies: @deepseek-ai/dsh-credentials (credentialRef), React (injected via window.__ModuleLoader__ in browser), node:fs (reading pet.html), @deepseek-ai/dsh-client-runtime (manifest declared injection)
• Architecture: Cordis dual-end plugin, server-side plugin/dsh-balance-widget/lib/index.js listens to firehose via ctx.on("session/event"), registers three routes /api/balance / /api/status / /pet.html via ctx.webServer.register; client-side lib/client.js loads React component via window.__ModuleLoader__.load and injects balance badge into conversation.session.header.actions via ctx.slots.inject, injects Web companion into shell.overlay; companion body is a 1.5 MB single-file pet.html (animated webp + 49 pre-composed mp3 all base64 inlined)
• Entry Files: plugin/dsh-balance-widget/lib/index.js (server-side) + plugin/dsh-balance-widget/lib/client.js (browser-side) + plugin/dsh-balance-widget/lib/pet.html (companion page)

Use Cases

Users who want a cute companion that interacts with tasks while using DSH, and also want to glance at DeepSeek account balance and one-click recharge in the session. The companion cheers on task completion, comforts on errors, and reminds when waiting for approval, making the wait between dialogues less dull. This project is a non-commercial fan work, please do not use for commercial purposes.

Prerequisites and Compatibility

Installation

dsh plugin --profile web add dsh-whale-pet

Configuration

No additional configuration required. All adjustable parameters (main volume, mute state, separate voice/effects/celebration volumes) are adjusted via sliders in the companion's right-click menu at runtime, with state saved in browser localStorage. No external files, environment variables, or DSH configuration items involved.

FAQ

Q: Companion doesn't appear after installation?

A: Confirm all install.ps1 steps output [OK], then restart DSH desktop app or dsh web service (companion window is only created when plugin loads); also check if profile's cordis.patch.yml contains balance-widget line (official dsh plugin add one-click install writes this automatically).

Q: Balance badge shows "Balance Unavailable" or keeps spinning?

A: Need to configure DEEPSEEK_API_KEY locally. Server reads it via @deepseek-ai/dsh-credentials and proxies official interface, browser will NOT receive API Key. Click badge to force refresh; on network failure, badge preserves last balance and marks it stale, no flickering.

Q: Companion has no sound?

A: Browser autoplay policy requires clicking the companion once first (hat hotspot) to unlock AudioContext; right-click hat to open menu with master volume slider and separate voice/effects/celebration volumes, confirm they are non-zero. Web version also needs to confirm ad blocker isn't blocking the companion iframe.

Q: Companion stays on screen after closing DSH Desktop main window?

A: This is known behavior of DSH original main.js. Optional to run apply-main-patch.ps1 to patch main process (automatically backs up original file, can restore with -Revert if needed), which closes companion with main window. If desktop is installed at C:\Program Files, run as administrator.

Q: Is this an officially licensed project? Can it be used commercially?

A: No. This is a non-official fan project, not affiliated with or endorsed by DeepSeek official, using "Non-Commercial Use License" (commercial use prohibited). Character materials copyright belongs to original author (see README acknowledgments).

Q: Web version companion doesn't display?

A: Confirm visiting restarted dsh web service, not old connection lingering in browser; force refresh browser (Ctrl+F5); also check if ad blocker is blocking /pet.html iframe.

Q: How to uninstall?

A: Simply run install.ps1 -Uninstall, script automatically restores cordis.patch.yml and profile config; if manually installed, can also delete balance-widget line from cordis.patch.yml, then restart dsh web.

Difficulty

Beginner — install with one command; all adjustable parameters are in companion's right-click menu, no config file changes needed.

Known Issues and Limitations

• Closing DSH Desktop main window doesn't close companion window synchronously, need to manually run apply-main-patch.ps1 to patch main.js (CHANGELOG.md:14)
• Browser (Web version) autoplay policy requires user to click companion once first before playing sound (pet.html:531-549)
• Only registered in DSH Web client (dsh-client-runtime + client.platform = "web"), pure CLI/IDE形态 DSH client won't mount companion
• pet.html is 1.5 MB build artifact (animation + audio base64 inlined), takes several seconds to load first time; right-click menu "Refresh" item carries ?timestamp to force reload
• Long-press head pat may be overwritten by poke if click event fires at moment of mouse release, longPressFired flag added in pet.html to skip; moving more than 5 px also cancels long press (pet.html:968-1000)
• Occasional exists and is not a symlink error during pnpm install, fix-fallback-layer.ps1 provided to move out fallback layer (CHANGELOG.md:27-30)
• Desktop install.ps1 / apply-main-patch.ps1 are PowerShell scripts, Windows only; macOS / Linux desktop users need to manually edit cordis.patch.yml to add balance-widget line

🐋 DeepSeek 鲸鱼娘桌宠

DeepSeek Harness 桌面宠物 — 蓝发女仆 + 鲸鱼尾动画 · 晓伊神经网络语音 · 撒娇互动 · 任务完成提醒

⚠️ 免责声明

这是一个非官方同人项目，与 DeepSeek 官方（深度求索）无隶属或背书关系。 本项目不用于商业用途。角色素材版权归原作者所有（见文末致谢）， 使用 DeepSeek 品牌名称仅为指明所适配的工具，不构成任何官方授权或关联。

---

✨ 功能

支持 两种形态：

• 🖥️ 桌面版：DSH Desktop（Electron）右下角独立透明置顶小窗
• 🌐 Web 版：浏览器访问 dsh --profile web 时，页面右下角悬浮层

💰 附带功能：余额徽章 + 充值入口

插件还包含一个会话头部余额徽章（/api/balance 代理官方接口）：

余额徽章默认随插件一起启用；不需要的话可在 cordis.patch.yml 中移除 client.js 的注入，或保持插件但忽略徽章（不影响桌宠功能）。

📦 安装

要求

• Windows
• 已安装 DeepSeek Harness 桌面客户端 和/或 npx 版 dsh

方式一：DSH 插件命令（推荐，自动激活）

dsh plugin --profile web add github:aceice01/dsh-whale-pet

无 dsh 命令时用：npx @deepseek-ai/dsh plugin --profile web add github:aceice01/dsh-whale-pet

插件自带 dsh.bundle 声明，安装后自动挂载（余额徽章 + Web 悬浮桌宠），无需手动编辑 cordis.patch.yml。 安装后重启 DSH 桌面应用 / dsh web 服务生效。

方式二：一键安装脚本

powershell -ExecutionPolicy Bypass -File install.ps1

脚本自动安装到两个 profile 并启用插件（自动备份原文件）：

安装后重启 DSH 桌面应用 / dsh web 服务生效。

其他选项

install.ps1 -Target desktop   # 只装桌面版
install.ps1 -Target web       # 只装 Web 版
install.ps1 -Uninstall        # 卸载
install.ps1 -DryRun           # 预览，不实际改动

（可选）应用 main.js 补丁 —— 修复"关闭客户端桌宠不消失"

DSH Desktop 原版 main.js 有一个小问题：关闭主窗口时桌宠窗口不会同步关闭， 桌宠会残留在屏幕上。apply-main-patch.ps1 提供修复（让桌宠随主窗口一起关闭）：

powershell -ExecutionPolicy Bypass -File apply-main-patch.ps1          # 应用补丁
powershell -ExecutionPolicy Bypass -File apply-main-patch.ps1 -Revert # 还原
powershell -ExecutionPolicy Bypass -File apply-main-patch.ps1 -DryRun # 预览

如果 DSH Desktop 装在 C:\Program Files，需要以管理员身份运行 PowerShell。 补丁会备份原 main.js（patch/main.js.original），可随时还原。 应用后重启 DSH Desktop 生效。

🎮 使用

桌面版

Web 版

🏗️ 架构

dsh-balance-widget/          # Cordis 插件（服务端 + 客户端）
└── lib/
    ├── index.js             # 服务端：/pet.html /api/status /api/balance
    │                        #   - 从 session firehose 监听 turn/tool/todo/goal/approval
    │                        #   - /api/status 输出工作状态供桌宠轮询
    ├── client.js            # 客户端：会话头部余额徽章 + Web 版悬浮桌宠
    └── pet.html             # 桌宠页面（动画 + 语音 + 交互，1.5MB 内嵌资源）

工作流：

DSH server (session/event firehose)
        │  turn/start · turn/end · tool/call · todo/write ...
        ▼
index.js  ── /api/status ──►  pet.html (轮询 1.5s)
                                ├─ 状态机：idle/running/happy/coquetry/sad
                                ├─ 动画：webp 内嵌（帧延迟×3，节奏舒缓）
                                ├─ 语音：AudioContext 播放预合成晓伊 mp3
                                └─ 交互：拖动/戳/摸头/右键菜单/音量

桌面版：Electron 主进程创建透明置顶小窗 → 加载 /pet.html Web 版：client.js 注入 shell.overlay 悬浮层 → iframe 加载 /pet.html（postMessage 桥接拖动）

🔧 自定义

换语音 / 加台词

需要 Python 3.9+：

pip install edge-tts pillow
# 1. 编辑 tools/synth_all.py 里的 LINES 台词表
# 2. 重新合成语音（晓伊音色，可换 PET_VOICE 环境变量）
python tools/synth_all.py
# 3. 构建 pet.html（注入动画 + 语音）
node tools/build-pet.mjs
# 4. 安装
powershell -ExecutionPolicy Bypass -File install.ps1

修图工具（仅当替换素材时需要）

python tools/despill.py    # 去绿幕残留（素材是绿幕抠图时）
python tools/defringe.py   # 去品红残留（白背景下边缘干净）

📁 目录结构

dsh-whale-pet/
├── install.ps1              # 一键安装/卸载（支持 -Target / -DryRun）
├── apply-main-patch.ps1     # （可选）main.js 补丁：修复关闭客户端桌宠不消失
├── docs/preview.png         # 项目预览图
├── patch/
│   ├── main.js              # 补丁后的 main.js
│   └── main.js.original     # 原版 main.js（用于还原）
├── plugin/
│   └── dsh-balance-widget/  # 桌宠插件
│       ├── package.json
│       └── lib/
│           ├── index.js     # 服务端路由 + 事件监听
│           ├── client.js    # 客户端（余额徽章 + Web 桌宠）
│           └── pet.html     # 桌宠页面
└── tools/
    ├── synth_all.py       # 语音合成（edge-tts → lib/audio.json）
    ├── build-pet.mjs      # 构建 pet.html（动画+语音注入）
    ├── despill.py         # 去绿幕残留
    └── defringe.py        # 去品红残留

📄 License

非商业性使用许可（Non-Commercial Use License）

• ✅ 允许：个人使用、学习、非商业性分享
• ❌ 禁止：商业用途、未经原作者许可的二次分发
• 角色素材版权归原作者所有（见致谢）；DeepSeek 名称仅用于指明所适配的工具， 与 DeepSeek 官方无隶属或背书关系

❓ FAQ

桌宠没出现？

1. 确认安装脚本输出均为 [OK]
2. 重启 DSH 桌面应用 / dsh web 服务（插件在启动时加载）
3. 检查 cordis.patch.yml 是否包含 balance-widget

Web 版桌宠不显示？

• 确认访问的是重启后的 dsh web 服务，浏览器强制刷新（Ctrl+F5）

语音没声音？

• 确认已在首次使用时点击过桌宠（解锁 AudioContext，浏览器自动播放策略）
• 检查右键菜单里的音量滑块 > 0
• Web 版需确认 iframe 未被广告拦截器屏蔽

如何参与贡献？ 见 CONTRIBUTING.md

🙏 致谢

• 角色动画素材：codex-pet-DeepSeek-girl
• 行为系统参考：DeskPet
• 语音合成：edge-tts