beyondgjc/dsh-agentic-pet

---

description: "The dsh desktop pet: an agentic pet plugin that serves the pet renderer over the web composition, drives it from in-process dsh events, and answers approvals and questions from the desktop." kind: "package-bundle"

dsh-agentic-pet

English | 中文

Summary

dsh-agentic-pet is a desktop-pet plugin for the DeepSeek Harness ecosystem: the pet lives on your desktop as a transparent always-on-top window, follows your agent sessions (idle / thinking / working / error), races the web GUI to answer approvals and user questions (first answer wins), collects a per-pet touch-affection ledger, and exposes expressive tools (pet_say, pet_do, pet_digest, pet_interactions, pet_state) so the model can speak and act through the pet. Spoken lines can be read aloud through BreezeBlue TTS — the carrier synthesizes each /say text and delivers bubble and voice as one event; synthesis failure or timeout degrades to visual-only (configure it in the desktop settings page). Multiple pet implementations can run side by side — a directory registry (~/.dsh/pet-http.d/) discovers every live pet and routes state, interactions, and ledgers per pet.

The pet itself is a dumb display with zero dsh knowledge. Everything that understands the runtime — event convergence, interaction waterfalls, multi-pet routing, the model tools — lives in the plugin's driver, and the pet only implements a small local HTTP control interface. Any pet implementation that speaks the same HTTP contract can be adopted without changing this plugin.

What's in this repo

Path	What it is
src/	The plugin (Cordis bundle): /pet route, event driver, registry, PetService seam, model tools, settings-page routes
client/	The desktop sidebar settings page (client half)
carrier/	The Electron carrier build artifacts shipped with the package (lib/, dist-renderer/)
carrier-src/	The carrier sources (mirrored from the dev upstream; media assets live in dsh-pet-assets)
vendor/typert-plugin/	Vendored typert decorator plugin used by the packaging config
tests/	Vitest specs (pure-function coverage of the registry routing and the /status field-matrix normalization)

Install

From the DeepSeek Harness desktop app's plugin page, or:

dsh plugin --profile <name> add dsh-agentic-pet

The animation media ship as a separate package, dsh-agentic-pet-assets, and are pulled in automatically as a dependency.

Development

The TypeScript build still runs inside the dsh monorepo workspace (the bundled @deepseek-ai/dsh-* deps are not published to npm). The flow:

1. In the monorepo: pnpm run build (plugin lib/) and pnpm --filter @deepseek-ai/dsh-pet run build (carrier lib/ + dist-renderer/).
2. Here: scripts\sync-from-monorepo.cmd — mirrors sources and build outputs into this repo.
3. Commit here, then publish from here (see Releasing; the assets package goes first, manual in dsh-pet-assets/PUBLISH.md).

Tests: npx vitest run tests/registry-service.spec.ts runs self-contained (needs only cordis and vitest); the full suite including tests/pet-app.spec.ts runs in the monorepo workspace.

Releasing

package.json's version is owned by this repo: scripts\sync-from-monorepo.cmd mirrors every other manifest field and keeps it. The monorepo copy carries the workspace version (0.2.1-rc.3), so a plain mirror copy used to rewrite the published number — which is why npm 0.4.0 had no commit and no tag carrying it.

node scripts\release.mjs 0.4.1 --dry-run   # preflight and pack listing, nothing published
node scripts\release.mjs 0.4.1             # publish, commit "chore(release): 0.4.1", tag v0.4.1
git push --follow-tags

The script refuses to publish unless the working tree is clean, the version exceeds the current one, tag v<version> is absent, the build artifacts are present, and lib/ carries exactly one bundle chunk (tsdown runs with clean:false, so a stale service-*.js would ship). A failed publish restores package.json, so the tree never claims a version that did not ship. A prerelease version (x.y.z-rc.N) publishes under --tag rc.

Every published version is reachable as tag v<version> — the tag, not the manifest, is what answers "what is on npm". Version in the tree therefore always equals the last published version.

Documentation

• Control-plane contract (the frozen consumer API every pet implementation speaks): see the multi-pet guide in the project documentation.
• Say-side TTS (BreezeBlue voice-over) design notes: docs/tts.md in the monorepo workspace (packages/bundle/pet-app).
• Known limitations and design notes live in the repo wiki and the project's engineering docs.

Credits & Licensing

• This project is a derivative of PC2005-cloud/dsh-pet — the upstream dsh-pet plugin by PC2005-cloud. Plugin code is licensed MIT.
• The character artwork (the "大肥鱼" whale-girl character under carrier/assets and dsh-agentic-pet-assets) is licensed CC BY-NC-SA 4.0 (attribution · non-commercial · share-alike) by its original author — original statement. Non-commercial use only; artwork derivatives must be shared under the same license.