dsh-pet

English | 中文

A community DeepSeek Pet plugin for DeepSeek Harness. It keeps a DeepSeek whale visible in the Web viewport, swims in place, follows the current session lifecycle, and opens a compact API statistics panel.

What it provides

• A fixed viewport overlay with an in-place swimming whale; a frame-sized atlas viewport advances through discrete frames with a one-pixel vertical bob, without horizontal travel or rotation.
• Current-session states for idle, running, waiting, failed, and completed turns, with English and Simplified Chinese dictionaries.
• A click-to-open panel for the current chat title, latest provider/model identity, and API statistics from sessionStats, tokenUsage, and contextPressure projections.
• Primary-pointer dragging with grab-point tracking, an 8px viewport margin, persistent browser-local position, and viewport clamping.
• An expanded panel that chooses the side with more room, collides with every viewport edge, and scrolls internally when the viewport is shorter than the card.
• A root-scoped overlay that remains visible when no session is selected; session data is bridged into it without duplicating the pet per session.
• Host commands /pet and /pet-game: toggle the global pet or reveal/hide the mini-game from the normal DSH command input.
• A pet-themed Snake mini-game in the UI panel. The whale is the snake head, colorful score blocks supply the food, and arrow keys/WASD, Space, double Space, Escape, and restart are supported. Each new game shows a three-second countdown and starts automatically; a browser-local personal best survives reloads and is committed only when a game settles. Through score 10, food favors the central 8×8 area; later placement samples the board broadly with a reduced outer-edge bias. The game is a non-modal floating glass card anchored to the pet, starts at a 240ms move interval, accelerates gently with score, and stays inside the viewport.
• Codex v2 8×11 sprite atlas packaging with the WebP asset embedded in the client bundle.

Integration status

This repository is a source release of the Web client package @deepseek-ai/dsh-client-ui-pet. The package contributes a browser entry to the DSH Web composition; it is not a standalone dsh.bundle yet.

The current build and test path uses the matching DeepSeek Harness checkout because the package uses DSH workspace dependencies and TypeScript project references. In that checkout, place this directory at packages/client/ui-pet, keep the Web patch row below, and run the focused checks from the monorepo root:

- id: ui-pet
  name: '@deepseek-ai/dsh-client-ui-pet'

rsync -a --exclude .git --exclude lib --exclude node_modules /path/to/dsh-pet/ packages/client/ui-pet/
pnpm install
pnpm exec vitest run packages/client/ui-pet/tests
pnpm exec tsc -p packages/client/ui-pet/tsconfig.json --noEmit
pnpm --filter @deepseek-ai/dsh-client-ui-pet bundle

Direct dsh plugin --profile <name> add github:Vulcan626/dsh-pet activation is intentionally deferred. The package does not declare dsh.bundle, and its current workspace:^ references are not self-contained for a Git install. The official DSH plugin publishing guide explains why a public Git package needs a self-contained prepare build or prebuilt artifacts before it can be installed this way.

Runtime and statistics

The pet reads the selected session through the runtime standard hooks and keeps the visual overlay at root scope. Durable whole-log counts and provider billing buckets are preferred when their projections are installed; a projection-free fixture or deployment folds the visible conversation window as a display fallback without issuing an RPC or creating a second usage ledger.

Cache hit is cacheReadTokens / (uncachedInputTokens + cacheReadTokens + cacheWriteTokens). Context occupancy uses projectedTokens with pressureTokens as its fallback numerator. The plugin sends no model request and adds no model-visible content.

Commands and mini-game

/pet toggles the browser-wide overlay. /pet-game toggles the floating Snake card and reveals the pet when opening it. The same mini-game is available from the statistics panel's Open mini-game button. Each game opens with a three-second countdown and starts automatically; Space pauses or resumes, while double Space restarts. The game starts at a 240ms move interval and applies a gentle exponential speed increase as the score grows. Food placement favors the central 8×8 area through score 10, then samples broadly while reducing concentration on the outer edge. Its colorful glass score blocks and glass card follow the pet and collide with the viewport edges instead of covering the workspace. The active board is local to the browser and pauses when the document is hidden; the personal best survives reloads, is written only at final settlement, is not synchronized between tabs, and does not enter the model context.

Development notes

The source is organized as a host plugin plus a browser entry under src/client/. Focused React and pure-rule tests cover status derivation, statistics folding, usage calculations, sprite selection, dragging, viewport clamping, panel edge collision, command control, countdown, double-Space restart, personal-best storage, colorful food rendering, score-banded food placement, terminal settlement, and Snake movement. Generated lib/, node_modules/, temporary files, environment files, and macOS metadata are excluded from this repository.

Official ecosystem guidance

The upstream contribution guide currently directs community contributions toward shared plugins, guides, blog posts, and answers while the official repository is not accepting external pull requests. Add the dsh-plugin topic when publishing related packages so other DSH users can discover them.

Release notes and TODO

• CHANGELOG.md records the current public source release.
• TODO.md lists the next packaging, installation, accessibility, and statistics milestones.

License

MIT. See LICENSE.