前言¶
用 DSH 挂长任务时，Web GUI 通常缩在后台标签页里。任务什么时候跑完，要么一直盯着状态，要么反复切回来刷新。这类「完成提示」属于纯界面层的增强，按 DSH「一切皆插件」的思路，不必改动 DSH 源码，装一个插件就能加上。下面介绍的 dsh-whale-celebration 做的就是这件事：根代理完成任务变 idle 时，页面底部跃出一只 DeepSeek 官方鲸鱼喷水，持续 3 秒后沉入屏幕。
这是什么¶
dsh-whale-celebration 是一个 DSH Web 插件，由 kob-repo 维护，代码采用 MIT 许可。它监听 agent 状态变化，只在根代理（用户直接对话的 agent）从 running 变为 idle 时播放庆祝动画，子代理完成不触发。整段动画不占用交互层，浮层设置了 pointer-events: none，不会拦截任何点击。
核心功能¶
- 官方鲸鱼图标：logo 路径取自 deepseek-harness 官方仓库（MIT）
- 喷水动画：水柱加飞溅水滴，整体 3 秒，时序为 0.4s 跃起 → 喷水 → 2.5s 沉入
- 并排庆祝：短时间内连续完成多个任务时，最多 3 只鲸鱼同时喷水
- 主题自适应：配色跟随 CSS 变量
--dsw-alias-brand-primary，亮/暗模式自动适配 - 不挡操作：浮层
pointer-events: none，不拦截任何点击 - 精准触发：仅根代理完成时庆祝，子代理（subagent）完成不触发
工作原理¶
插件由 Host / Client 两个半身组成：
1、Host 半身运行在 DSH 进程内：监听 agent/status 事件，根代理 running → idle 记为一次任务完成；对外提供 GET /api/whale-celebration/state 轮询接口，取走待播次数并清零。
2、Client 半身运行在浏览器：注册在 shell.overlay 全局浮层，每 0.9s 轮询一次 Host，拿到完成信号后播放鲸鱼喷水动画。
安装与启用¶
先从 npm 安装：
dsh plugin --profile web add dsh-whale-celebration
--profile 后面换成你自己的 profile 名。也可以直接从 GitHub 仓库安装：
dsh plugin --profile web add git+https://github.com/kob-repo/dsh-whale-celebration.git
包内声明了 dsh.bundle，安装时会自动并入 profile 的 bundle 层，不需要手工编辑任何配置文件。依赖方面，peerDependencies 要求 react ^18.2.0；client 端注入 @deepseek-ai/dsh-client-runtime，平台为 web。
安装完成后重启一次 DSH，插件即以标准 bundle 层生效。
验证与移除¶
经过上面的安装与重启步骤后，可以用两种方式确认插件已运行：
1、给 agent 发一个任务，任务完成后页面底部应出现鲸鱼喷水 3 秒；
2、直接访问 http://localhost:3080/api/whale-celebration/state，返回 {"count":0} 即表示 Host 半身已运行。
不想用了就移除：
dsh plugin --profile web remove dsh-whale-celebration
移除后重启一次 DSH 完成清理。浏览器端的动画会随移除即时消失，页面如有残留，刷新一次即可。
自定义动画¶
想调整鲸鱼大小、颜色或喷水效果：
1、打开插件目录下的 lib/client.js；
2、修改样式 .ds-whale-item 和 @keyframes ds-*；
3、重启 DSH。
行为细节¶
- 多标签页不会重复播放：待播计数被任一标签页轮询取走即清零，一次完成只播放一次。
- 浏览器关闭期间完成的任务会补播一次，待播计数最多累计 12 次。
- 子代理完成任务没有反应是设计如此：只庆祝用户直接对话的根代理，避免打扰。
适用场景与注意¶
适合长时间挂着 DSH 跑任务、不想一直盯着屏幕确认完成的用户——鲸鱼一出现，就说明当前对话的根代理已经空闲。
两点注意：
- 插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证。代码采用 MIT 许可；鲸鱼图标路径来自 deepseek-harness（MIT），仅作展示用途，DeepSeek 品牌与 logo 归其所有者所有。
- 这是一个本地外部插件，不改 DSH 源码，卸载也只需一条命令加重启。
小结¶
dsh-whale-celebration 功能很小，解决的是一个很具体的问题：不用盯着屏幕，也能一眼知道任务完成了。装上、重启，下一次任务结束时鲸鱼就会从页面底部跃出来。
- 社区插件目录（独立站点，与 DeepSeek、幻方无官方从属关系）：https://www.skillhub.cn/plugins/kob-repo/dsh-whale-celebration
- 源码仓库：https://github.com/kob-repo/dsh-whale-celebration
