Overview
@luweiyabo/dsh-whale-pet
README / EN
Package documentation
dsh-whale-pet
让鲸鱼娘住进 DeepSeek Harness：感知工作状态、回应互动，并在屏幕上自由漫游。
dsh-whale-pet 是一个面向 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）
安装
环境要求
| 项目 | 要求 |
|---|---|
| DeepSeek Harness | ^0.1.0-rc.6 || ^0.1.2-rc.1（开发者预览版；Web profile） |
| Node.js | ^22.19.0 || >=24.0.0（跟随 DSH 官方要求，见 DSH package.json 的 engines.node） |
| pnpm | 可在命令行中使用；dsh plugin 会把插件管理命令转发给 pnpm |
已适配 DSH 0.1.2-rc.1 的配置 RPC、会话事件订阅、模型选择、审批与问答等待状态，并保留旧版 connection.api。新版从会话服务读取当前会话；断线后重建状态时不会把历史消息当作新事件触发规则。余额仍仅查询服务商官方接口，未配置凭据时会显示查询失败。
从 npm 安装
dsh plugin --profile web add @luweiyabo/dsh-whale-pet
安装完成后重启 Web profile：
dsh web
宠物默认显示在页面右下角。
或者直接从 GitHub 安装：
dsh plugin --profile web add github:luweiyabo/dsh-whale-pet
同一 Web profile 只能保留一种安装来源。切换 npm、GitHub 或本地源码版本前，请先卸载当前版本；否则多个包会同时声明 whale-pet loader entry，导致 DSH 启动失败。
从本地源码安装
在仓库根目录执行：
dsh plugin --profile web add .
更新
dsh plugin --profile web update @luweiyabo/dsh-whale-pet
卸载
dsh plugin --profile web remove @luweiyabo/dsh-whale-pet
卸载后重新启动 dsh web。用户上传的动作保存在 $DSH_HOME/whale-pet/actions/，卸载插件不会自动删除这些文件。
开发
git clone https://github.com/luweiyabo/dsh-whale-pet.git
cd dsh-whale-pet
npm ci
npm run build
dsh plugin --profile web add .
dsh web
运行测试与发布内容预检：
npm run check
npm run format:check
npm test
npm pack --dry-run
项目采用 DSH 双半侧插件结构：
lib/index.js：宿主侧设置、静态动画、自定义动作和余额 APIlib/client.js：浏览器侧播放、交互、意图仲裁和设置界面cordis.patch.yml：DSH bundle 挂载声明assets/plugin-logo.png：插件 Logoassets/thumb/：内置透明动画docs/images/screenshots/：README 功能预览截图docs/images/actions/：95 个动作的低帧率循环 GIFmaterials/references/：角色首帧与视觉参考图materials/videos/：AI 生成的源 MP4（仅用于溯源和再处理，不参与运行时播放）materials/prompts/：动画生成提示词
欢迎提交 Issue 或 Pull Request。提交前请确认测试通过，并避免把 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 文件，也可以复制到：
$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
assets/thumb/中的大部分动画资源来自 PC2005-cloud/dsh-pet，不属于本项目的 MIT 代码授权- 上游目前允许这些动画资源用于开源项目，但禁止商业使用；使用、再分发或改编前请阅读 第三方资源许可说明 并核对上游最新条款
- 因 npm 包同时包含 MIT 代码和受单独条款约束的媒体资源，包的许可字段为
SEE LICENSE IN LICENSE而非单纯的MIT；根目录 LICENSE（标准 MIT）仅覆盖原创代码，媒体资源条款见随包分发的 第三方资源许可说明，不能把整个 npm 包视为纯 MIT 授权
本项目与 DeepSeek 官方无隶属关系，是面向 DeepSeek Harness 的社区开源插件。