前言¶

在 DeepSeek 智能體開發中，管理 API 餘額和可視化工作狀態是常見需求。DSH（宿主）生態強調插件化，本插件旨在將 DeepSeek 賬戶餘額連接到桌面上的藍鯨女僕桌寵，並提供兩個模型工具。

插件簡介¶

名稱：DeepSeek 桌寵 · DSH 插件（宿主端）
維護者：Yoshino-JF
許可證：MIT
核心能力：
* 查詢 DSH 餘額
* 通過 HTTP(127.0.0.1) 與桌寵通信
* 提供兩個模型工具 (pet_balance, pet_control)
* 監聽宿主事件 (work-start, work-end 等)
* 長輪詢機制 (wait=25)

架構與工作原理¶

插件在宿主進程內運行，持有 DEEPSEEK_API_KEY，負責查詢餘額並啓動狀態接口。桌寵通過 HTTP 請求獲取餘額與狀態，不持有密鑰。

DSH 宿主插件  ──HTTP(127.0.0.1:47831/state)──▶  桌寵窗口
   │ 持有 DEEPSEEK_API_KEY                         │ 只拿到餘額數字
   └─ ctx.credentials.resolve()                  └─ 每 5 秒取一次

插件會在 127.0.0.1 上開啓只讀狀態接口，桌寵通過長輪詢機制獲取數據。

安裝與配置¶

安裝命令如下：

plugin_manager install_bundle  D:\DeepSeek\deepseek-pet-plugin

首次安裝即熱生效。若修改了 index.js 後再次安裝，需重啓 DSH 纔會加載新的 JS 邏輯。

在宿主的 profile 目錄下編輯 cordis.patch.yml，在 dsh-pet 行配置參數：

字段	默認值	說明
`port`	`47831`	狀態接口端口，僅監聽 `127.0.0.1`
`petPath`	`D:\DeepSeek\deepseek-pet\build\DeepSeekPet.exe`	桌寵程序路徑
`credential`	`DEEPSEEK_API_KEY`	用於查詢餘額的 DSH 憑據
`apiBase`	`https://api.deepseek.com`	餘額接口前綴
`refreshSeconds`	`60`	緩存刷新週期（秒）
`lowBalance`	`10`	低於此值桌寵顯示“擔心”表情
`autoStart`	`true`	宿主啓動 3 秒後自動啓動桌寵
`startDelayMs`	`3000`	自動啓動延遲時間
`stopOnUnload`	`false`	卸載插件時是否關閉桌寵（默認保留）

事件與長輪詢¶

桌寵使用 GET /state?wait=25 進行長輪詢。插件將請求掛起最多 25 秒，有事件時立即返回（實測 <100ms），無事件則超時返回心跳。

插件監聽以下宿主事件：
* agent/inbox/inserted：用戶消息進入 inbox
* agent/status：10 秒內變爲 running

觸發邏輯：只有當用戶主動開始幹活（消息進入 inbox 且狀態變爲 running）時，纔會觸發桌寵的“被嚇一跳”演出。自動續跑、子代理或定時任務不會觸發。

可用事件類型：work-start、work-end、balance（餘額變化）、message（留言）、quit（軟退出）。

工具與接口¶

模型工具¶

插件提供了兩個模型工具供 DSH 調用：

工具	參數	作用
`pet_balance`	`fresh?`	讀取餘額；`fresh=true` 跳過緩存
`pet_control`	`action` (start/stop/status/refresh/say/hide/show) `text?`	控制桌寵起停、刷新、彈窗

HTTP 接口¶

路徑	說明
`GET /health`	健康檢查，返回 `{ok:true}`
`GET /state?pid=<桌寵pid>`	桌寵拉取的狀態（餘額+留言），先回緩存再補數據
`GET /say?text=...`	讓桌寵說一句話
`GET /refresh`	觸發強制刷新

開發與調試¶

修改 JS 代碼後，同包替換需要重啓 DSH。可以使用 dev-mock-server.mjs 進行本地測試，它實現了相同的協議。

node dev-mock-server.mjs 47835
DeepSeekPet.exe --url http://127.0.0.1:47835/state --screen on

測試命令示例：

curl "http://127.0.0.1:47835/dev/event?kind=work-start"
curl "http://127.0.0.1:47835/say?text=hello"

注意事項¶

安全：API Key 僅在宿主進程內使用，不進日誌、不通過 HTTP 下發。狀態接口僅監聽 127.0.0.1，是隻讀的。
依賴：需要依賴 @deepseek-ai/dsh-tools，且桌寵本體 DeepSeekPet.exe 必須存在。
版本：當前包內桌寵本體版本爲 v0.2.12，支持性能檔位、遊戲屏大小調節等功能。

DeepSeek 桌寵 · DSH 插件（宿主端）

前言¶