# dsh-whale-pet 让鲸鱼娘住进 DeepSeek Harness：感知工作状态、回应互动，并在屏幕上自由漫游。 [![npm version](https://img.shields.io/npm/v/%40luweiyabo%2Fdsh-whale-pet?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/@luweiyabo/dsh-whale-pet) [![npm downloads](https://img.shields.io/npm/dm/%40luweiyabo%2Fdsh-whale-pet?style=flat-square&logo=npm&label=downloads)](https://www.npmjs.com/package/@luweiyabo/dsh-whale-pet) [![GitHub stars](https://img.shields.io/github/stars/luweiyabo/dsh-whale-pet?style=flat-square&logo=github)](https://github.com/luweiyabo/dsh-whale-pet/stargazers) [![GitHub issues](https://img.shields.io/github/issues/luweiyabo/dsh-whale-pet?style=flat-square&logo=github)](https://github.com/luweiyabo/dsh-whale-pet/issues) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/luweiyabo/dsh-whale-pet/blob/main/LICENSE) [![DeepSeek Harness](https://img.shields.io/badge/DeepSeek_Harness-Web-2f81f7?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness) [English](https://github.com/luweiyabo/dsh-whale-pet/blob/main/README_EN.md) · [预览](#功能预览) · [安装](#安装) · [使用](#如何使用) · [功能](#功能说明) · [动作](#动作展示) · [配置](#配置与数据) · [问题反馈](https://github.com/luweiyabo/dsh-whale-pet/issues)

dsh-whale-pet 是一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI 的开源鲸鱼桌宠插件。它会根据 Agent 的思考、编码、工具调用、等待和错误等状态自动切换动作，也支持点击回应、拖拽、屏幕漫游、自定义动画和触发规则。插件包含 **95 个 640×360 透明 WebM 动画**，提供中英文界面，设置修改后自动保存并热生效。 ## 功能预览 ### 设置与动作管理

集中设置	动作分类、搜索与预览
自定义动作与触发规则

### 桌面交互与状态信息

点击移动	右键快捷菜单	账户余额气泡
中英文界面

## 动作展示以下按运行时分类展示全部 **16 个分类、95 个动作**。预览为 240×135、5 FPS 的低帧率循环 GIF；将鼠标悬停在图片上可查看中文动作名。 ### 待机（1）

待机呼吸休闲

### 转向（1）

东张西望

### 移动（4）

原地漂浮踏步螃蟹走路原地左转奔跑摔跤预备姿势奔跑

### 点击回应（6）

开心跃动害羞惊讶傲娇生气挠痒咯咯笑元气挥手原地挥手打招呼

### 拖拽（2）

被鼠标拖拽悬空反馈快速甩出后变成球

### 日常（10）

女仆屈膝礼仪超大伸懒腰小幅度原地旋转展示哈欠连天原地小憩沉眠打瞌睡被惊醒晨间刷牙照镜子整体换装试色侧耳倾听

### 工作（3）

轻快记录文字写代码深度思考碎碎念

### 游戏（9）

专心玩魔方蹲下玩玩具汽车玩游戏气急败坏玩水枪骑木马踢毽子抽陀螺下五子棋荡秋千

### 音乐舞蹈（6）

悠闲哼歌小提琴演奏优雅女仆舞轻快摇摆舞可爱宅舞吹笛子

### 美食（12）

大口吃零食偷吃零食被抓住吃白饭吃早餐吃午餐吃晚餐吃冰淇淋融化吃西瓜涮火锅吃大闸蟹吃糖葫芦吃长寿面

### 节日（20）

中秋赏月吃月饼放烟花拆礼物吃粽子吃汤圆吃饺子吃青团吃腊八粥吃年糕吃重阳糕收红包舞狮头写福字穿针乞巧装点圣诞树讨糖南瓜灯插茱萸赏菊放河灯萌化小幽灵放孔明灯

### 四季（4）

堆雪人摇扇纳凉被落叶淹没放风筝

### 魔术（3）

变鸽子魔术凭空生花魔术扑克魔术

### 趣味（9）

吹气球动物环绕三球抛接蝴蝶蜜蜂环绕头顶开花原地跳跃抓碎头顶物品敲击桌面互动重力下蹲压缩被吓一跳

### 鲸鱼特色（3）

鲸鱼吐泡泡特效蓝鲸现世用鲸鱼尾巴拍打地面

### 梗图（2）

吃 Token 是啊，吃什么？

## 安装 ### 环境要求 | 项目 | 要求 | |---|---| | DeepSeek Harness | `>= 0.1.0-rc.6`（开发者预览版；Web profile） | | Node.js | `^22.19.0 \|\| >=24.0.0`（跟随 DSH 官方要求，见 DSH `package.json` 的 `engines.node`） | | pnpm | 可在命令行中使用；`dsh plugin` 会把插件管理命令转发给 pnpm | ### 从 npm 安装 ```sh dsh plugin --profile web add @luweiyabo/dsh-whale-pet ``` 安装完成后重启 Web profile： ```sh dsh web ``` 宠物默认显示在页面右下角。 > 或者直接从 GitHub 安装： > > ```sh > dsh plugin --profile web add github:luweiyabo/dsh-whale-pet > ``` 同一 Web profile 只能保留一种安装来源。切换 npm、GitHub 或本地源码版本前，请先卸载当前版本；否则多个包会同时声明 `whale-pet` loader entry，导致 DSH 启动失败。 ### 从本地源码安装在仓库根目录执行： ```sh dsh plugin --profile web add . ``` ### 更新 ```sh dsh plugin --profile web update @luweiyabo/dsh-whale-pet ``` ### 卸载 ```sh dsh plugin --profile web remove @luweiyabo/dsh-whale-pet ``` 卸载后重新启动 `dsh web`。用户上传的动作保存在 `$DSH_HOME/whale-pet/actions/`，卸载插件不会自动删除这些文件。 ## 开发 ```sh git clone https://github.com/luweiyabo/dsh-whale-pet.git cd dsh-whale-pet dsh plugin --profile web add . dsh web ``` 运行测试与发布内容预检： ```sh npm run check npm test npm pack --dry-run ``` 项目采用 DSH 双半侧插件结构： - [`lib/index.js`](https://github.com/luweiyabo/dsh-whale-pet/blob/main/lib/index.js)：宿主侧设置、静态动画、自定义动作和余额 API - [`lib/client.js`](https://github.com/luweiyabo/dsh-whale-pet/blob/main/lib/client.js)：浏览器侧播放、交互、意图仲裁和设置界面 - [`cordis.patch.yml`](https://github.com/luweiyabo/dsh-whale-pet/blob/main/cordis.patch.yml)：DSH bundle 挂载声明 - [`assets/plugin-logo.png`](https://github.com/luweiyabo/dsh-whale-pet/blob/main/assets/plugin-logo.png)：插件 Logo - [`assets/thumb/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/assets/thumb)：内置透明动画 - [`docs/images/screenshots/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/docs/images/screenshots)：README 功能预览截图 - [`docs/images/actions/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/docs/images/actions)：95 个动作的低帧率循环 GIF - [`materials/references/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/materials/references)：角色首帧与视觉参考图 - [`materials/videos/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/materials/videos)：AI 生成的源 MP4（仅用于溯源和再处理，不参与运行时播放） - [`materials/prompts/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/materials/prompts)：动画生成提示词欢迎提交 [Issue](https://github.com/luweiyabo/dsh-whale-pet/issues) 或 [Pull Request](https://github.com/luweiyabo/dsh-whale-pet/pulls)。提交前请确认测试通过，并避免把 API Key、私有配置或大体积源视频提交到仓库。 ## 如何使用 ### 基础交互 | 操作 | 效果 | |---|---| | 悬停 | 宠物朝向光标所在一侧，移开后恢复原朝向；拖拽或惯性滑行期间不生效 | | 悬停（动效） | 光标靠近时宠物轻微倾向光标，可在设置中关闭 | | 单击宠物 | 根据头部、身体或尾部区域播放不同回应，并切换选中状态；开启交互动效时会同时触发一次 Q 弹压缩回弹；选中后点击页面可让宠物前往目标位置 | | 双击宠物 | 播放“蓝鲸现世”特殊动画并取消选中状态 | | 拖拽与反弹 | 移动并放置宠物；拖动时按速度产生挤压拉伸形变，快速甩动后会从球形帧开始播放“变成球”动画并惯性滑行；人物边界触碰屏幕时反弹，开启交互动效时碰撞会产生 Q 弹挤压；系统启用“减少动态效果”时不滑行 | | 完全拖出屏幕 | 宠物进入边缘隐藏状态；将指针移到对应屏幕边缘可露出召回区域 | | 右键宠物 | 打开快捷菜单：回家、打开设置或隐藏 | ### 打开设置进入 **设置 → 插件 → 鲸鱼桌宠**，可以调整： - 显示、文字气泡和账户余额气泡 - 交互动效（光标倾斜跟随、点击弹跳、拖拽挤压） - 宠物尺寸、默认角落和会话感知范围 - 安静、均衡、活泼三档自主活跃程度 - 工作、编码、阅读、搜索、思考、等待、倾听和错误等意图对应的动作 - 自主动作、移动动作和点击回应动作池 - 自定义动作上传、预览和删除 - 自定义事件触发规则所有设置会自动保存并即时生效，无需重启。 ## 功能说明 ### 事件感知动作宠物会读取 Harness 会话活动，并通过 9 类意图仲裁器选择合适动作（可配置）： | Harness 状态 | 默认表现示例 | |---|---| | Agent 编码或操作文件 | 坐在电脑前编码 | | 思考与推理 | 深度思考 | | 阅读与检索 | 记笔记 | | 等待审批或用户回答 | 左右张望 | | 用户发送消息 | 侧耳倾听 | | 工具或 Agent 出错 | 惊吓回应 | | 没有活动 | 待机、转向、随机动作或屏幕漫游 | 高频状态变化带有去抖和消退延迟，避免连续工具调用时频繁闪切。用户交互和错误等高优先级事件可以抢占当前动画。 ### 自主行为与屏幕漫游 - 无会话事件时持续运行自主动画链 - 默认概率为待机 30%、转向 10%、动作 40%、移动 20% - 行走方向与动画朝向同步，并自动检测可用空间 - 位置按窗口比例保存，窗口缩放后仍保持相对位置 - 双缓冲视频交叉淡入，减少动作切换时的空白帧 - 交互动效层：光标倾斜跟随（rAF 弹簧）、点击弹跳、拖拽挤压拉伸与滑行/反弹 Q 弹形变，可整体关闭 - 支持系统 `prefers-reduced-motion` 设置 ### 自定义触发规则可以用事件条件驱动任意内置或自定义动画： - 内置工具名匹配、工具失败、Agent 出错、回合结束和等待审批等模板 - 多条件自由组合 - 可配置优先级、冷却时间和动作保持时间 - 支持“试触发”和最近触发状态 - 与内置意图使用同一优先级仲裁机制 ### 账户余额气泡开启 `meter` 后，宠物会根据当前会话实际调用的模型识别服务商，并显示服务商官方接口返回的账户余额。该功能不进行 Token 费用估算。 - 自动读取 Harness 当前模型配置、凭据库及服务商默认环境变量 - 支持 `DEEPSEEK_API_KEY`、`MOONSHOT_API_KEY`、`STEPFUN_API_KEY` 等现有凭据来源；也可在对应服务商设置里指定自定义 `apiKeyEnv` 凭据环境变量 - 仅请求代码中配置的官方白名单端点；余额查询会把对应服务商的 API Key 发送到其官方接口（请求在本机服务端发起，仅用于余额查询） - 默认关闭 - 服务商没有可用余额 API 时显示“当前服务商暂不支持” ## 动作配置完整内置动作见[动作展示](#动作展示)。动作选择器会跟随 Harness 语言显示中文或英文名称，并支持按分类、英文 ID 或中英文名称搜索；内置动作与用户上传动作都可以加入自主动作池、绑定事件意图或用于触发规则。 ## 自定义动作可以直接在设置卡片上传 `.webm` 或 `.mp4` 文件，也可以复制到： ```text $DSH_HOME/whale-pet/actions/ ``` 推荐规格： | 项目 | 要求 | |---|---| | 画布 | 640×360 | | 背景 | 透明 | | 脚底线 | y=330 | | 格式 | WebM 或 MP4 | | 单文件上传限制 | 64 MiB | | 自定义动作总容量 | 512 MiB | | 动作 ID | 使用文件名，支持中文；同名文件不会被覆盖 | 上传后的动作会进入“自定义”分类，可以加入自主动作池、绑定事件意图或用于触发规则。 ## 配置与数据插件设置保存在 DSH 的 `whale-pet` 设置命名空间，自定义动画保存在 `$DSH_HOME/whale-pet/actions/`。插件不会把动画、设置或 API Key 上传到本项目维护者的服务器。常用环境变量： | 环境变量 | 用途 | |---|---| | `DSH_HOME` | 指定 DSH 数据目录；未设置时使用 DSH 默认目录 | | `DEEPSEEK_API_KEY` | DeepSeek 余额查询凭据来源之一 | | `MOONSHOT_API_KEY` | Moonshot 余额查询凭据来源之一 | | `STEPFUN_API_KEY` | StepFun 余额查询凭据来源之一 | ## 常见问题

安装后没有看到宠物

重新启动 `dsh web`，然后进入 **设置 → 插件 → 鲸鱼桌宠**，确认“显示宠物”已开启。也可以运行 `dsh --profile web --dump-config`，检查插件是否出现在组合配置中。

宠物被拖出屏幕后找不到了

把指针移动到宠物消失的屏幕边缘，宠物会露出召回区域。也可以通过插件设置重新显示，或在右键菜单选择“回家”。

余额气泡显示“不支持”或“查询失败”

确认当前模型服务商提供公开余额 API，并检查 Harness 模型凭据或相应环境变量。部分服务商目前没有公开余额接口，这种情况属于正常降级。

## 资源来源与许可 - 本项目原创代码使用 [MIT License](https://github.com/luweiyabo/dsh-whale-pet/blob/main/LICENSE) - [`assets/thumb/`](https://github.com/luweiyabo/dsh-whale-pet/tree/main/assets/thumb) 中的大部分动画资源来自 [PC2005-cloud/dsh-pet](https://github.com/PC2005-cloud/dsh-pet)，不属于本项目的 MIT 代码授权 - 上游目前允许这些动画资源用于开源项目，但禁止商业使用；使用、再分发或改编前请阅读 [第三方资源许可说明](https://github.com/luweiyabo/dsh-whale-pet/blob/main/THIRD_PARTY_ASSETS.md) 并核对上游最新条款 - 因 npm 包同时包含 MIT 代码和受单独条款约束的媒体资源，包的许可字段为 `SEE LICENSE IN LICENSE` 而非单纯的 `MIT`；根目录 [LICENSE](https://github.com/luweiyabo/dsh-whale-pet/blob/main/LICENSE)（标准 MIT）仅覆盖原创代码，媒体资源条款见随包分发的 [第三方资源许可说明](https://github.com/luweiyabo/dsh-whale-pet/blob/main/THIRD_PARTY_ASSETS.md)，不能把整个 npm 包视为纯 MIT 授权本项目与 DeepSeek 官方无隶属关系，是面向 DeepSeek Harness 的社区开源插件。