一句话定位

在 DSH 桌面/网页边缘放一只蓝发鲸鱼娘同人桌宠，根据会话状态自动切换表情、动画和语音，并顺带在会话头部显示 DeepSeek 账户余额和一键充值入口。

核心能力

• 在 DSH 桌面（Electron 透明置顶小窗）与 Web（右下角 iframe 悬浮层）显示鲸鱼娘桌宠，跟随 DSH 会话事件（turn/start、turn/end、tool/call、todo/write、goal/change、approval/*、command/*）切换 idle/running/happy/coquetry/sad 五种状态
• 任务完成播放跳跃+纸屑+琶音+语音庆祝；工具调用失败给"出错安慰"语音；等待审批给出气泡提示
• 戳一戳（65% 撒娇 / 20% 蹦跳 / 15% 委屈三态随机）、长按帽子 0.7 秒触发摸头、双击帽子静音、右键菜单、键盘 Esc 关菜单
• 在 Web 会话头部常驻余额徽章，每分钟自动刷新，可点击立即刷新，旁边带"充值"链接跳到 DeepSeek 开放平台充值页
• 余额走服务端 /api/balance 反向代理官方接口（https://api.deepseek.com/user/balance），服务端 30 秒缓存，浏览器不会拿到 API Key
• 网络失败保留上次余额并标注 stale，避免界面闪烁；主音量 + 语音/音效/庆祝独立音量通过 localStorage 持久化

技术实现

• 语言: JavaScript (ESM) + 少量 Python（构建/合成工具）
• 关键依赖: @deepseek-ai/dsh-credentials（credentialRef）、React（浏览器端通过 window.__ModuleLoader__ 注入）、node:fs（读 pet.html）、@deepseek-ai/dsh-client-runtime（manifest 声明注入）
• 架构模式: Cordis 双端插件，服务端 plugin/dsh-balance-widget/lib/index.js 通过 ctx.on("session/event") 监听 firehose、ctx.webServer.register 注册 /api/balance / /api/status / /pet.html 三条路由；客户端 lib/client.js 用 window.__ModuleLoader__.load 装入 React 组件并通过 ctx.slots.inject 把余额徽章注入 conversation.session.header.actions、把 Web 桌宠注入 shell.overlay；桌宠本体是 1.5 MB 的单文件 pet.html（动画 webp + 49 条预合成 mp3 全部 base64 内联）
• 入口文件: plugin/dsh-balance-widget/lib/index.js（服务端）+ plugin/dsh-balance-widget/lib/client.js（浏览器端）+ plugin/dsh-balance-widget/lib/pet.html（桌宠页面）

适用场景

想在使用 DSH 时有个会跟任务联动的可爱陪伴、并希望顺手在会话里看一眼 DeepSeek 账户余额和一键充值的用户。桌宠在任务完成时欢呼庆祝、出错时安慰、等待审批时提醒，让等待对话的间隙不再沉闷。该项目为非商业性同人作品，请勿用于商业场景。

前置依赖与兼容性

安装方式

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

配置项

本插件无需额外配置。所有可调参数（主音量、是否静音、语音/音效/庆祝独立音量）通过桌宠右键菜单中的滑块在运行时调整，状态保存在浏览器 localStorage，不涉及任何外部文件、环境变量或 DSH 配置项。

常见问题

Q: 安装后桌宠没出现怎么办？

A: 确认 install.ps1 各步骤输出为 [OK]，然后重启 DSH 桌面应用或 dsh web 服务（桌宠只在插件加载时才创建窗口）；同时检查 profile 的 cordis.patch.yml 是否包含 balance-widget 行（官方 dsh plugin add 一键安装会自动写入）。

Q: 余额徽章显示"余额不可用"或一直转圈？

A: 需要在本地配置 DEEPSEEK_API_KEY，服务端通过 @deepseek-ai/dsh-credentials 读取后代理官方接口，浏览器不会收到 API Key。点击徽章可强制刷新；网络短暂失败时徽章会保留上次余额并标 stale，不会闪断。

Q: 桌宠没有声音怎么办？

A: 浏览器自动播放策略要求首次必须点击一次桌宠（帽子热区）解锁 AudioContext；右键帽子打开的菜单里有总音量滑块和语音/音效/庆祝分项音量，确认非零。Web 版还需要确认广告拦截器没有屏蔽桌宠 iframe。

Q: 关闭 DSH Desktop 主窗口后桌宠还留在屏幕上？

A: 这是 DSH 原版 main.js 的已知行为。可选运行 apply-main-patch.ps1 给主进程打补丁（会自动备份原文件，需要的话可用 -Revert 还原），让桌宠随主窗口一起关闭。如桌面装在 C:\Program Files，需以管理员身份运行。

Q: 这是官方授权的项目吗？能商用吗？

A: 不是。这是一个非官方同人项目，与 DeepSeek 官方无隶属或背书关系，采用"非商业性使用许可"（禁止商用）。角色素材版权归原作者所有（见 README 致谢）。

Q: Web 版桌宠不显示怎么办？

A: 确认访问的是重启后的 dsh web 服务，而不是浏览器里残留的旧连接；浏览器强制刷新（Ctrl+F5）一下；同时检查广告拦截器是否屏蔽了 /pet.html iframe。

Q: 怎么卸载？

A: 直接运行 install.ps1 -Uninstall，脚本会自动还原 cordis.patch.yml 和 profile 配置；如果是手动安装，也可以从 cordis.patch.yml 删除 balance-widget 行，然后重启 dsh web。

上手难度

入门 — 一行命令安装即可使用；可调参数都在桌宠右键菜单里，不需要改任何配置文件。

已知问题与限制

• 关闭 DSH Desktop 主窗口后桌宠窗口不会同步关闭，需手动运行 apply-main-patch.ps1 修补 main.js（CHANGELOG.md:14）
• 浏览器（Web 版）的自动播放策略要求用户首次必须点击一次桌宠才能播放声音（pet.html:531-549）
• 仅在 DSH Web 客户端注册（dsh-client-runtime + client.platform = "web"），纯命令行 / IDE 形态的 DSH client 不会挂载桌宠
• pet.html 是 1.5 MB 构建产物（动画 + 音频 base64 内联），初次加载需要数秒；右键菜单"刷新"项会带 ?timestamp 强制重新加载
• 长按摸头在鼠标松手瞬间若 click 事件触发会把摸头覆盖成戳一戳，已在 pet.html 加 longPressFired 标志跳过；移动超过 5 px 也会取消长按（pet.html:968-1000）
• pnpm 安装时偶发 exists and is not a symlink 错误，提供了 fix-fallback-layer.ps1 移出回退层（CHANGELOG.md:27-30）
• 桌面端 install.ps1 / apply-main-patch.ps1 是 PowerShell 脚本，仅支持 Windows；macOS / Linux 桌面用户需手动编辑 cordis.patch.yml 添加 balance-widget 行

🐋 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