前言¶

長時間盯着 DeepSeek Harness（DSH）的 Web 界面寫代碼、跑 Agent，界面再專業也容易顯得冷清：任務在後臺推進，進度條在走，但屏幕上缺少一個能回應你操作的「在場感」。早年 QQ 寵物靠右下角的小精靈陪伴桌面，whale-girl 把類似體驗搬進了 DSH Web GUI——一隻可拖拽、可投餵、可玩耍的鯨魚娘，懸浮在頁面右下角，還會根據任務成敗、會話狀態和你是否空閒切換表情與動作。

whale-girl 由社區開發者 vlln 維護，在 SkillHub 插件庫歸類爲「趣味換裝」，GitHub 倉庫截至覈實日約有 281 stars。本文依據 SkillHub 目錄頁、deepseek-harness-plugin.com 詳情頁 與 GitHub README.zh.md 交叉覈實後整理：它是什麼、核心能力、如何安裝，以及使用時需要注意什麼。

這是什麼¶

whale-girl 是一款面向 DSH Web GUI 的桌面寵物（桌寵）插件，形態參考 QQ 寵物：角色常駐頁面右下角，可拖動位置，點擊彈出菜單進行餵食（🍗）或玩耍（🎾）。它不是換膚插件，而是帶交互與成長邏輯的「積累型夥伴」——完成任務、開啓會話、陪伴時長會累積成資歷等級、稱號與共同回憶，hover 狀態條可查看等級、任務數與近期記憶摘要。

技術上，whale-girl 採用官方 bundle 插件格式（根目錄 package.json 聲明 dsh.bundle + dsh.client，配合 cordis.patch.yml），倉庫 README 將其定位爲 bundle 機制的完整參考實現。許可證爲 MIT；角色形象來自 B 站 UP 主 ZipZipPipe 的「鯨魚娘」貼紙設計。

需要說明的是：DeepSeek Harness 的核心理念是「一切皆插件」，社區目錄（如 SkillHub、deepseek-harness-plugin.com）由社區獨立維護，與 DeepSeek / 幻方無官方從屬關係。whale-girl 是社區精選插件，安裝前仍建議自行審閱源碼。

核心功能與亮點¶

十五態狀態機，跟工作臺脈搏聯動¶

寵物內置完整狀態機，共 15 種狀態，覆蓋待機、工作、慶祝、驚嚇、投餵、玩耍、散步、睡眠等場景。部分典型映射如下：

完整優先級、轉換語義與觸發源見倉庫 docs/state-machine.md；成長體系（XP、稱號閾值）見 docs/growth-system.md。README 明確：XP / 稱號等語義層不可通過配置修改，以免破壞積累賬本一致性。

積累型陪伴：等級、稱號與回憶¶

與純裝飾 GIF 不同，whale-girl 把「一起幹活」寫進數據：任務完成、會話活躍、陪伴時長會推動資歷升級並解鎖稱號，狀態條展示等級、任務計數與最近共同回憶。長時間使用 DSH 的開發者，會明顯感知到「這隻寵物記得你做過什麼」——而不是每次刷新都回到同一張靜態圖。

可選桌面伴侶：跳出瀏覽器窗口¶

除網頁內寵物外，倉庫 desktop/ 提供獨立桌面伴侶應用（Node 引擎 + Tauri 渲染殼，體積約 12MB）。它不通過 dsh plugin 安裝，需自行執行 npm install -g whale-girl-desktop 並從 Tauri 源碼編譯殼層。桌面端通過公開端點（/state、/events、/presence 等）與 DSH 通信，運行期間網頁端寵物按 presence 契約自動隱藏，退出或崩潰（TTL 45 秒）後恢復。適合希望寵物常駐操作系統桌面、而非僅嵌在瀏覽器裏的用戶。

bundle 插件範本¶

對打算開發 DSH 插件的讀者，whale-girl 的價值不止於「好玩」：lib/（入口 / 邏輯 / client / 素材）與 docs、decisions、scripts 分層清晰，配套門禁腳本 scripts/gates/run.mjs 與素材全量契約（docs/sprites-spec.md）。vlln 的 plugin-registry 還提供 make-dsh-plugin skill 與 cookbook，可與本倉庫對照學習。

安裝與啓用¶

whale-girl 面向 web profile。社區目錄頁給出的通用安裝命令爲：

dsh plugin add github:vlln/whale-girl

倉庫 README 針對 web 場景的寫法更明確（git 源一行，構建產物已入庫）：

dsh plugin --profile web add "github:vlln/whale-girl#main"

也可使用 npm 源或本地目錄：

# npm 源
dsh plugin --profile web add whale-girl@0.1.0

# 本地目錄
dsh plugin --profile web add <whale-girl 本地路徑>

如需可復現安裝，可固定 commit 哈希，例如目錄頁建議的 dsh plugin add github:vlln/whale-girl#commit。

裝完後必須重啓 web（bundle 層在啓動時合成）。重啓後右下角出現寵物：點擊彈出菜單，拖拽可移動；鼠標懸停顯示狀態條。初始配置頁 / onboarding 場景下寵物會隱藏，避免干擾首次引導。

更新插件：

dsh plugin --profile web update whale-girl

或更換 git ref 後再次重啓 web。

典型用法示例¶

網頁內日常交互¶

1. 打開 DSH Web GUI，確認 whale-girl 已安裝且 web 已重啓。
2. 右下角點擊寵物，選擇 🍗 餵食或 🎾 玩耍，觀察 eat/play → joy 動畫鏈。
3. 拖拽寵物到不擋代碼的位置；空閒一分鐘後它會 sleep，再點擊即可 wake。
4. 正常跑 Agent：新會話觸發 welcome，思考期陪伴 think，任務成功 celebrate，失敗則 error → disappointed。

熱更新配置（無需重啓）¶

在 <dshHome>/settings.yaml 的 whale-girl: 段或設置 UI 中調整，修改後即時生效：

whale-girl:
  enabled: true      # 網頁端開關；與桌面伴侶並存時可設 false 避免雙寵物
  size: 110          # 尺寸 px，範圍 64–160
  opacity: 1         # 透明度 0.2–1
  walk:
    enabled: true    # 是否允許週期遊走
  sleepAfterMs: 60000

換角色（多角色 manifest 時）¶

菜單「🎭 換角色」可循環切換；也可設置 localStorage 鍵 whale-girl:character。若 manifest 僅含一個角色，按鈕會置灰並提示「暫無其他角色」。貢獻新角色需按 docs/adding-a-character.md 產出 15 張狀態 sheet 並通過 verify-assets 驗收。

適用場景與注意事項¶

適合誰：

• 長期在 DSH Web GUI 裏寫代碼、審 diff、盯 Agent 的開發者，希望界面多一點輕鬆陪伴感。
• 想學習官方 bundle 插件結構、client 注入與狀態機設計的插件作者。
• 喜歡 QQ 寵物 / 桌面寵物文化，又不願離開 DSH 工作流的用戶。

注意事項：

1. 權限與安全：插件以當前 dsh 進程權限運行，安裝過程可能執行代碼。安裝前請閱讀 GitHub 倉庫 源碼與 MIT 許可證；生產環境建議固定 commit。
2. 僅 Web GUI：核心體驗綁定 web profile；TUI 或純 CLI 場景不會自動出現這隻寵物。
3. 重啓 web：bundle 插件裝完必須重啓 web，否則看不到右下角角色。
4. 桌面伴侶是可選分支：whale-girl-desktop 需 Node ≥18 與 Rust（cargo），首次 Tauri 編譯可能耗時 5–15 分鐘，與 dsh plugin 安裝路徑無關。
5. 星標與分類：GitHub 星標會變動（覈實日約 281）；SkillHub 歸類「趣味換裝」，deepseek-harness-plugin.com 目錄頁標註「主題與外觀」——二者均爲社區目錄標籤，以功能描述爲準即可。

結尾¶

whale-girl 把 QQ 寵物式的右下角陪伴感帶進了 DeepSeek Harness Web 界面：能拖、能喂、能玩，還能跟任務與會話狀態同頻呼吸。對日常泡在前端的 DSH 用戶，它是一劑輕量但持久的「界面溫度調節器」；對插件開發者，它更是 bundle 格式與 client 狀態機的一份活教材。

• SkillHub 目錄頁：https://www.skillhub.cn/plugins/vlln/whale-girl
• 社區目錄詳情：https://deepseek-harness-plugin.com/zh-CN/plugins/whale-girl/
• GitHub 倉庫：https://github.com/vlln/whale-girl