前言¶

在 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 插件（宿主端）

前言¶