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:

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:

HTTP Interface¶

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.