Introduction

In DeepSeek agent development, managing API balance and visualizing work status are common requirements. The DSH (host) ecosystem emphasizes a plugin-based approach. This plugin aims to connect DeepSeek account balance to a Blue Whale Maid desktop pet and provide two model tools.

Plugin Overview

Name: DeepSeek Desktop Pet · DSH Plugin (Host Side)
Maintainer: Yoshino-JF
License: MIT
Core capabilities:
* Query DSH balance
* Communicate with the desktop pet over HTTP (127.0.0.1)
* Provide two model tools (pet_balance, pet_control)
* Listen to host events (work-start, work-end, etc.)
* Long polling mechanism (wait=25)

Architecture and Working Principles

The plugin runs inside the host process, holds DEEPSEEK_API_KEY, and is responsible for querying the balance and starting the status endpoint. The desktop pet fetches the balance and status through HTTP requests and does not hold the key.

DSH Host Plugin  ──HTTP(127.0.0.1:47831/state)──▶  Desktop Pet Window
   │ Holds DEEPSEEK_API_KEY                         │ Receives balance number only
   └─ ctx.credentials.resolve()                  └─ Fetches once every 5 seconds

The plugin opens a read-only status endpoint on 127.0.0.1, and the desktop pet fetches data using long polling.

Installation and Configuration

The installation command is as follows:

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

The first installation takes effect immediately. If you reinstall after modifying index.js, you must restart DSH for the new JS logic to load.

In the host’s profile directory, edit cordis.patch.yml and configure parameters on the dsh-pet line:

Field Default Description
port 47831 Status endpoint port; listens only on 127.0.0.1
petPath D:\DeepSeek\deepseek-pet\build\DeepSeekPet.exe Desktop pet executable path
credential DEEPSEEK_API_KEY DSH credential used to query the balance
apiBase https://api.deepseek.com Balance API prefix
refreshSeconds 60 Cache refresh interval (seconds)
lowBalance 10 If the balance falls below this value, the desktop pet shows a “worried” expression
autoStart true Automatically start the desktop pet 3 seconds after the host starts
startDelayMs 3000 Auto-start delay
stopOnUnload false Whether to close the desktop pet when the plugin is unloaded (default: keep it running)

Events and Long Polling

The desktop pet uses GET /state?wait=25 for long polling. The plugin holds the request for up to 25 seconds, returns immediately when an event occurs (measured <100 ms), and returns a heartbeat on timeout if no event occurs.

The plugin listens to the following host events:
* agent/inbox/inserted: A user message enters the inbox
* agent/status: The status changes to running within 10 seconds

Trigger logic: The desktop pet’s “startled” animation is triggered only when the user actively starts work (a message enters the inbox and the status changes to running). Automatic resumptions, subagents, or scheduled tasks do not trigger it.

Available event types: work-start, work-end, balance (balance change), message (note), quit (soft exit).

Tools and Interfaces

Model Tools

The plugin provides two model tools for DSH to call:

Tool Parameters Purpose
pet_balance fresh? Read the balance; fresh=true skips the cache
pet_control action (start/stop/status/refresh/say/hide/show)
text?		 Control the desktop pet: start/stop, refresh, and show pop-up messages

HTTP Interface

Path Description
GET /health Health check, returns {ok:true}
GET /state?pid=<pet pid> The state pulled by the desktop pet (balance + note); responds with cached data first and then supplements it
GET /say?text=... Make the desktop pet say something
GET /refresh Trigger a forced refresh

Development and Debugging

After modifying the JS code, replacing the plugin package requires restarting DSH. You can use dev-mock-server.mjs for local testing; it implements the same protocol.

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

Example testing commands:

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

Notes

  1. Security: The API Key is used only inside the host process and is not written to logs or delivered over HTTP. The status endpoint listens only on 127.0.0.1 and is read-only.
  2. Dependencies: It requires @deepseek-ai/dsh-tools, and the desktop pet executable DeepSeekPet.exe must exist.
  3. Version: The desktop pet executable included in the current package is v0.2.12 and supports features such as performance levels and game screen size adjustment.