前言¶
用 DSH 做智能體開發時，會話進度本身是看不見的：回合數、工具調用次數、連續使用記錄，都埋在 Host 側的事件流裏。想給這些數據加一層可視反饋，常見做法要麼把狀態塞回模型上下文，要麼把數據送到遠端服務，前者浪費 token，後者有隱私代價。
dsh-whale-companion 走了另一條路：插件只在 Host 側觀察已提交的會話事件元數據，不讀內容、不連網絡，把「潮汐、遠征、收藏」這套進度體系渲染成一隻可拖動的桌面鯨魚。下面介紹它的定位、功能、安裝方式和實現邊界。
這是什麼¶
dsh-whale-companion 是一個 local-first 的 DSH 鯨魚世界插件，由 LeemanCheung 維護，許可證爲 MIT。在目錄裏它被歸入「趣味換裝」類。一句話定位：隱私安全的會話元數據，變成一隻可拖動的桌面鯨魚伴侶，附帶 20 個可解鎖鯨魚精靈、可見潮汐、個人海灣（cove）、非懲罰性遠征，以及 opt-in、僅本地的鯨魚圈卡片。
版本 2.6.0 針對 DSH 0.1.2-rc.1，保留了既有的名稱、外觀、位置、進度、收藏、房間預設與 ImageGen 物種圖鑑。
對模型側，它不添加任何 prompt、工具、消息、token 用量或 KV-cache 內容；只在 Host 觀察已提交的會話事件元數據，並暴露瀏覽器 UI。
核心功能¶
可拖動的桌面鯨魚¶
插件提供一隻運行在 shell.overlay 上的鯨魚，支持指針拖拽、鍵盤移動、邊緣吸附，位置持久化時會做視口安全校正。整份 UI 共享一個 5 秒本地刷新週期。新的潮汐時刻出現在有界的可見氣泡裏，只有里程碑會通知讀屏器。
20 個鯨魚精靈與 XP 體系¶
20 個可解鎖鯨魚精靈隨 Ocean Levels 1–100 逐步解鎖，每個精靈把自身故事和可見潮汐響應映射到一類安全事件，不改變模型行爲。
XP 規則是明確的：
- 每回合 10 XP（只有
user/message計爲回合） - 每個工具結果 5 XP
- 每次會話開始 20 XP
等級由 XP 推導，連續記錄使用 UTC 會話開始日期，缺勤不扣減進度或收藏。
潮汐、收藏與遠征¶
潮汐時刻由 live-only 的 session/created、user/message、tool/result 元數據驅動，且是有界的。重複的工具結果仍計入既有 XP，但無法刷潮汐時刻、收藏品或遠征進度。
Whale Home 頁面提供七天海洋日誌、當前鯨魚故事節點、cove 可視化預覽，以及一份基於真實字段的 Privacy Ledger。另有潮汐時間線、本地 PNG 明信片導出、24 項收藏品目錄、8 個固定房間槽位、3 套房間預設，以及一套非懲罰性遠征。6 套 cove 主題調整背景、界面強調色和環境光，鯨魚美術保留自身配色；12 個成就全部包含。
分享：漂流瓶與鯨魚圈卡片¶
訪客漂流瓶是隔離的只讀房間預覽，不會合並或覆蓋接收者的進度。
鯨魚圈卡片是 opt-in 的、僅基於本地文件的交換：只包含預設別名、物種、皮膚、粗粒度活躍分桶和共鳴星，沒有賬號、網絡、排行、自由文本、提示詞摘錄、任務名或工具數據。
呈現模式與動畫¶
安靜、標準、活潑三種呈現模式存於瀏覽器本地偏好，系統 reduced-motion 始終優先，存儲被拒絕時安全回退且不影響進度。
2.6.0 帶來一段 2.4 秒的墨鯨躍出動畫：96 幀、40 fps，原生 WebP 採用 25ms 均勻幀間隔。系統或產品內 reduced-motion 開啓時切換爲對應 PNG 靜幀，且不替換原有的 Dive/Classic 狀態動畫。
安裝與啓用¶
安裝到 DSH Web profile：
dsh plugin --profile web add github:LeemanCheung/dsh-whale-companion
安裝後重啓現有 DSH Web 進程並刷新頁面即可看到鯨魚。
開發驗證與美術管線¶
如果要自己構建或驗證，在倉庫根目錄執行：
corepack pnpm typecheck
corepack pnpm verify:minke
corepack pnpm test
corepack pnpm build
corepack pnpm pack:check
美術管線需要先裝依賴：
python -m pip install -r requirements-art.txt
管線固定於 Python 3.12、NumPy 2.3.3、Pillow 12.3.0。corepack pnpm art:minke 重建透明 sprite，corepack pnpm art:species 規範化倉庫內置的 20 物種 ImageGen 圖鑑。視覺快照基線在 Ubuntu CI 維護，其他平臺仍運行交互、動效、reduced-motion 和窄佈局斷言，但不生成 RC 截圖基線。生產客戶端內嵌這些柵格資產，不含運行時矢量鯨魚繪製。
隱私與實現邊界¶
這是這個插件最值得寫清楚的部分：
- Host 只讀取 session id、事件序號、事件類型和時間戳，從不讀取、存儲、導出或渲染提示詞、助手輸出、代碼、路徑、工具參數或工具結果。
- 內存回執摘要使用不離開 Host 進程的 HMAC 密鑰；持久化回執窗口上限 4,096 條，只防近期重複投遞，不防跨 Host 重啓的永久重放。備份刻意不含回執摘要、session id 或事件數據。
- 後臺寫入失敗不會中斷 DSH 會話，可能只丟失該次進度更新，後續更新仍被接受；顯式的用戶保存仍會報告失敗。
- 文本導入在 JSON 解析前統一限制 512 KiB；持久化寫入全部做 schema 校驗。
- 進度存於單一 DSH 存儲後端，不跨設備同步。
- overlay 每 5 秒輪詢一次，原因是當前 host Remote 事件允許列表沒有包內鯨魚狀態推送路由。
- 鯨魚圈卡片刻意只支持本地導入/導出；要做託管社區，需要另行擁有、鑑權並審覈的傳輸提供方。
適用場景與注意¶
適合的讀者：在 DSH Web 環境里長期工作、想要一份本地優先的進度可視化，同時不希望插件觸碰提示詞內容、不給模型增加任何開銷的人。它也適合作爲「Host 側只觀察元數據」這類插件形態的參考實現。
注意以下幾點：
1、該插件以當前 dsh 進程的權限運行，安裝前建議先閱讀倉庫源碼與 LICENSE（MIT）確認可接受。
2、進度不做跨設備同步，換機器不會帶走進度。
3、回執機制防的是近期重複投遞，不是跨重啓的永久重放，這一點 README 寫得很明確。
結尾¶
dsh-whale-companion 展示了一種剋制的插件形態：只用事件元數據、全部計算和存儲留在本地、對模型零開銷，把日常會話變成一個可積累的鯨魚世界。如果你在做 DSH 插件或想給工作環境加點趣味，值得一試。
- 目錄頁：https://www.skillhub.cn/plugins/LeemanCheung/dsh-whale-companion
- GitHub：https://github.com/LeemanCheung/dsh-whale-companion
