前言¶
在 DeepSeek Harness（DSH）裏做智能體開發時，主界面往往是會話列表、工具調用和文件樹；長時間盯着同一套 UI，缺少一個「常駐、可對話、又能複用同一套 DSH 能力」的入口。社區裏已有以看板娘形態掛在 Web UI 角上的做法；dariodemh/dsh-whale-maid-mascot 在 yefeng7531/dsh-whale-maid-mascot（MIT）基礎上擴展，把頁面內角色、共享 Agent 會話、本地長期記憶，以及可選的 Telegram 長輪詢橋接接到同一條會話上。下面按定位、能力、安裝與配置說明如何使用，並交代權限與安全注意點。
這是什麼¶
Whale-chan（DeepSeek 娘）是面向 DSH Web UI 的頁面內伴侶插件，維護者爲 dariodemh，在 SkillHub 目錄中歸類爲「趣味換裝」。它不是 DeepSeek 或幻方官方組件；DSH 生態採用「一切皆插件」，社區目錄站點與上游無從屬關係。插件自述爲研究友好的 MIT 開源衍生項目（詳見倉庫 NOTICE 與 LICENSE），模型供應商與 Telegram Bot 均由使用者自行配置，不會經由此倉庫共享。
瀏覽器角標與 Telegram（若配置）共用同一角色、同一 Agent 會話與同一記憶：手機發的一條消息會進入瀏覽器裏同一段對話，角色在任意一端均可調用 DSH 真實工具（文件、Shell、搜索、Skills 等）。
核心功能¶
頁面內（Web UI）¶
- 看板娘：可拖拽、點擊互動，四套服裝與情緒姿勢、 speech bubble。
- 對話：雙向可帶圖片，支持本地生成的卡片與塗鴉類內容。
- Mis trabajos：工作區面板，展示近期文件與預覽。
- 長期記憶：偏好稱呼、穩定偏好與項目相關事實，默認寫入
~/.dsh/whale-maid-mascot/memory.json。 - 其它：主動 check-in、歸檔聊天、「解釋這個術語」等 README 列出的頁面能力。
Telegram（可選）¶
- 與頁面爲同一 DSH Agent 會話（默認 session id 爲
whale-maid），可讀寫文件、執行命令、使用 Skills；回覆以單條消息流式編輯方式呈現（streamReplies默認爲true）。 - 命令包括：
/new、/status、/memory、/models、/model <provider>/<model>、/stop、/help。 - 配對：Bot 默認忽略所有人；首次需在 Telegram 向 Bot 發送
/pair <code>，配對碼由插件寫入~/.dsh/whale-maid.pairing.txt。 - 無需公網 IP 或 Webhook：橋接通過 long polling 拉取 Telegram 更新。
- 在你先向 Bot 發過消息後，可收到主動消息（例如長任務結束），符合 Telegram 側規則。
共享會話與記憶¶
- 打開頁面聊天面板時會重載共享 transcript，Telegram 側消息會出現在頁面側。
- 通過
whale_remember等機制在任一端寫入的持久記憶會在另一端可見。
環境與依賴¶
- DeepSeek Harness Desktop 0.2.1-rc.5 或兼容構建（插件爲 DSH bundle：宿主側 + 可選 Web 客戶端）。
- DSH 中已配置可用的模型 Provider（與 Profile 現有一致即可）。
- Node：包聲明
engines.node爲>=20。 - 可選 Telegram：向 @BotFather 申請 Bot Token；當前 package 版本爲 2.3.0（以
package.json爲準）。
安裝與啓用¶
推薦從 npm 安裝。在 DeepSeek Harness 中打開 Settings → Plugins，安裝：
dsh-whale-maid-mascot
重啓 DSH 後，Web UI 右下角出現看板娘；Telegram 相關行處於未配置 Token 的空載狀態。
本地開發可從 checkout 複製到 ~/.dsh/plugins/dsh-whale-maid-mascot 並在 Profile 的 package.json 中以 file: 依賴與 bundles 引用；README 給出 Windows robocopy 示例，完成後同樣需要重啓 DSH。本文不展開 clone 流程，以倉庫 README 爲準。
配置 Telegram¶
- 在 Telegram 與 @BotFather 對話，執行
/newbot，創建 Bot 並複製 Token。 - 將 Token 交給插件，任選其一：
- 寫入~/.dsh/whale-maid.token（單行，無其它內容），或
- 啓動 DSH 前設置環境變量TELEGRAM_BOT_TOKEN，或
- 在 Profile 的whale-maid-telegram行配置中設置token。 - 重啓 DSH；插件生成
~/.dsh/whale-maid.pairing.txt中的配對碼。 - 在 Telegram 打開你的 Bot，發送：
/pair <code>
授權完成後可刪除配對文件。橋接狀態（允許列表、配對碼、Telegram offset、共享 session 等）保存在 ~/.dsh/whale-maid.state.json。
可選配置文件¶
可選文件 ~/.dsh/whale-maid.json，或與 Profile cordis.patch.yml 中 whale-maid-telegram 行使用相同鍵。常用項如下（默認值以 README 表格爲準）：
| 鍵 | 默認 | 含義 |
|---|---|---|
cwd |
~/Documents/deepseek-harness/default-workspace |
共享 Agent 會話的工作目錄 |
personaName |
Whale-chan |
角色自稱與提示中的名稱 |
persona |
— | 完整替換 system prompt |
permissionPreset |
danger-full-access |
會話權限預設 |
sessionId |
whale-maid |
共享會話 id；修改可另開對話 |
model |
profile 默認 | 可爲會話固定 { provider, model, reasoningEffort } |
turnTimeoutMs |
900000 |
單輪 Agent 最長等待 |
streamReplies |
true |
Telegram 回覆是否流式編輯同一條消息 |
完整鍵列表見 GitHub README。
典型用法¶
僅頁面伴侶：完成 npm 安裝並重啓後，在右下角與 Whale-chan 對話、換裝互動；需要時打開工作區面板查看近期文件。記憶與偏好會落在本地 memory.json，不依賴 Telegram。
頁面 + 手機同一腦：配置 Token 並完成 /pair 後，在 Telegram 發送文字或照片；會話與工具調用走真實 DSH session。長任務可在手機端用 /stop；換模型可用 /model <provider>/<model> 或 /models 查看。頁面側再次打開聊天面板即可看到 Telegram 側消息。
收緊權限：若不希望會話具備完整 Shell 與系統用戶級寫權限，可在 ~/.dsh/whale-maid.json 將 permissionPreset 設爲 workspace-write；部分操作可能等待 DSH 審批，而 Telegram 聊天無法代爲點選批准。
架構簡述¶
README 中的結構可概括爲：瀏覽器 client.js 經 HTTP 訪問宿主 dsh/index.js（看板娘與 /whale-maid-mascot/* 路由）；Telegram 用戶經 long poll 與 dsh/telegram.js 通信；二者匯入 dsh/session.js 管理的同一個 DSH Agent 會話（工具、記憶、人設、歷史一致）。
適用場景與注意¶
適合：希望在 DSH Web UI 角上保留輕量、可換裝的角色伴侶，又希望（可選）用手機延續同一會話並調用真實 Agent 工具的用戶；接受 MIT 衍生項目、自行審閱源碼的開發者。
務必注意：
- 默認
permissionPreset爲danger-full-access：會話內可在你當前 OS 用戶權限下執行命令與寫文件，這是 Telegram 遠程協助能力的基礎，也是真實風險。安裝前請閱讀倉庫源碼與許可證；更嚴格隔離可考慮專用 OS 用戶、虛擬機，並將cwd指向唯一允許的項目目錄。 - Bot Token 爲憑證，只應放在本地文件或環境變量，不應寫入日誌或公開倉庫。
- 未授權 Telegram 用戶只會收到有限回覆；除
/pair與未授權時的/start外，Bot 默認忽略他人。 - 插件以當前 DSH 進程權限運行；趣味換裝分類不改變其 Agent 與工具鏈本質。
結尾¶
dsh-whale-maid-mascot 把頁面看板娘、共享 DSH 會話與可選 Telegram 橋接綁在一起：一套記憶、一套工具、兩處界面。若要在目錄頁查看元信息或安裝入口，可打開 SkillHub 插件頁；實現細節、安全說明與開發命令以 GitHub 倉庫 README 爲準。
