🐋 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