前言¶
用 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
