dsh-whale-celebration

Readme

# dsh-whale-celebration

[![npm version](https://img.shields.io/npm/v/dsh-whale-celebration.svg)](https://www.npmjs.com/package/dsh-whale-celebration)
[![npm downloads](https://img.shields.io/npm/dm/dsh-whale-celebration.svg)](https://www.npmjs.com/package/dsh-whale-celebration)
[![license](https://img.shields.io/npm/l/dsh-whale-celebration.svg)](LICENSE)

任务完成庆祝插件：每次**根代理**（用户直接对话的 agent）完成任务变 idle 时，DSH Web GUI 页面底部会跃出一只 **DeepSeek 官方鲸鱼**喷水，效果持续 3 秒后沉入屏幕。

## 特性

- 🐳 **官方鲸鱼图标**：logo 路径取自 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 官方仓库（MIT）
- 💦 **喷水动画**：水柱 + 飞溅水滴，整体恰好 3 秒（0.4s 跃起 → 喷水 → 2.5s 沉入）
- 🎉 **多次完成并排庆祝**：短时间连续完成时，最多 3 只鲸鱼同时喷水
- 🌗 **主题自适应**：配色跟随 `--dsw-alias-brand-primary`，亮/暗模式自动适配
- 🚫 **不挡操作**：浮层 `pointer-events: none`，不拦截任何点击
- 🎯 **精准触发**：仅根代理完成时庆祝，子代理（subagent）完成不触发

## 工作原理

插件由 Host / Client 两个半身组成：

- **Host 半身**（DSH 进程内）：监听 `agent/status` 事件，根代理 `running → idle` 记为一次任务完成；对外提供 `GET /api/whale-celebration/state` 轮询接口（取走待播次数并清零）。
- **Client 半身**（浏览器）：注册在 `shell.overlay` 全局浮层，每 0.9s 轮询一次 Host，拿到完成信号后播放鲸鱼喷水动画。

## 安装

从 npm 安装：

```bash
dsh plugin --profile web add dsh-whale-celebration
```

也可以直接从 GitHub 仓库安装：

```bash
dsh plugin --profile web add git+https://github.com/kob-repo/dsh-whale-celebration.git
```

> `--profile` 换成你自己的 profile 名。包内声明了 `dsh.bundle`，安装时自动并入 profile 的 bundle 层，**无需手工编辑任何配置文件**。

## 生效

安装完成后**重启一次 DSH**，插件即以标准 bundle 层生效。

如何确认已经生效：

- 给 agent 发一个任务，任务完成后页面底部应出现鲸鱼喷水 3 秒；
- 或直接访问 `http://localhost:3080/api/whale-celebration/state`，返回 `{"count":0}` 即表示 Host 半身已运行。

## 移除

```bash
dsh plugin --profile web remove dsh-whale-celebration
```

移除后**重启一次 DSH** 完成清理。浏览器端的动画会随移除即时消失，如页面有残留刷新一次即可。

## 常见问题

**Q：为什么子代理完成任务没有反应？**
A：设计上只庆祝用户直接对话的根代理，子代理完成不算，避免打扰。

**Q：打开多个标签页会重复播放吗？**
A：不会。计数被任一标签页轮询取走即清零，只播放一次。

**Q：任务在浏览器关闭期间完成，回来会补播吗？**
A：会。Host 侧的待播计数会保留，下次打开页面轮询到后播放一次（最多累计 12 次）。

**Q：想调整鲸鱼大小 / 颜色 / 喷水效果？**
A：修改 `lib/client.js` 中的样式（`.ds-whale-item`、`@keyframes ds-*`）即可，改完重启 DSH。

## 许可与出处

- 代码：MIT（见 [LICENSE](LICENSE)）
- 鲸鱼图标路径来自 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（MIT），仅作展示用途；DeepSeek 品牌与 logo 归其所有者所有
- 源码仓库：https://github.com/kob-repo/dsh-whale-celebration