# DSH Pets **Cross-platform desktop pets for DeepSeek Harness.** [English](README.md) | [简体中文](README_zh.md) DSH Pets brings your running AI agent sessions onto the desktop through animated characters, event-driven voice lines, and actionable notifications. Keep an eye on parallel tasks, jump to the right session, and know when an agent needs you—without constantly checking the DSH Web interface. > **Project status: early development.** This README describes the intended product and development milestones. Features listed as planned are **not** claims that they are already implemented. The project builds on ideas and code from [zuodazuoqiang001/dsh-pet](https://github.com/zuodazuoqiang001/dsh-pet), a Windows desktop-pet plugin for DSH. ## What it does The product is organized around four focused modules: | Module | Planned capabilities | | --- | --- | | **Session Management** | Show active top-level DSH sessions, quickly switch to a selected session, and notify on task completion, failure, or approval requests. Keep missed notifications accessible. | | **Character System** | Display Spine characters or sprite-sheet pets, associate characters with model identities, and map agent states to expressions and motions. | | **Voice System** | Play **pre-recorded voice lines** for events, with character-specific voice packs, volume/mute controls, cooldowns, and optional lip sync. | | **Desktop Interaction** | Transparent floating window, drag/position persistence, system tray, click-through behavior, do-not-disturb mode, and basic performance settings. | **Two non-negotiable capabilities:** 1. **Switch between running sessions quickly** from the desktop pet's session list or bubbles. 2. **Receive reliable task-completion alerts**, including an actionable path back to the corresponding session. Character animation and voice make these workflows more expressive; they must never prevent session controls and notifications from working. ## How it should feel - **Working:** a character reacts to an active agent; session bubbles show what is still running. - **Needs attention:** the character signals an approval request and offers a direct session shortcut. - **Completed:** an animation and optional recorded line announce the result; the notification remains available until reviewed. - **Idle:** the character returns to subtle idle motions without interrupting desktop work. - **Multiple agents:** notifications are queued or coalesced instead of playing several voice lines simultaneously. Characters may be mapped to model families (for example, DeepSeek, Claude, or GPT), with manual overrides. A session remains identified by its **session ID** even if the model changes. ## Planned architecture ```text DeepSeek Harness (DSH Web / Cordis plugin) ├─ Session and agent status ├─ Task completion / failure / approval events └─ Session focus and navigation │ │ Local, restricted communication ▼ Electron desktop companion (main process) ├─ Connection / notification / session controllers ├─ Window, tray, platform integration └─ React + TypeScript UI ├─ Session bubbles and notification history ├─ Spine renderer (primary character format) ├─ Static-image fallback (no GPU / reduced mode) └─ Pre-recorded voice playback + optional lip sync ``` **Target platforms:** Windows, Linux, and macOS. Initial desktop verification is planned for **Ubuntu 24.04 Desktop with DSH Web**, with Windows and macOS compatibility tests following. Linux X11/XWayland and native Wayland have different restrictions around global window positioning, always-on-top behavior, and focus; support will be documented based on real testing rather than assumed. ### Character assets Character packs are self-contained directories with a single contract file. The bundled default pack ships inside the package; every other pack is downloaded on demand into the user's data directory, which takes precedence over the bundled copy. ```text assets/characters/ # bundled, read-only index.json # downloadable-pack index (version, sha256, url) deepseek/ # the only pack shipped with the package manifest.json LICENSE preview.webp spine/ # Spine skeleton, atlas and textures voice/ index.json # voice index: every event and line the pack can speak /.ogg # one file per line, e.g. task_completed/task_completed_01.ogg ~/.dsh/pets/characters// # downloaded, writable, overrides the bundled copy ``` `manifest.json` is the contract, so the runtime never guesses file names. It declares the Spine entry plus scale and anchor, the agent-state → animation mapping (`idle`, `working`, `attention`, `done`, `failed`), the location of the voice index (`voice.index`), and a static-image fallback for machines without GPU acceleration. **The event set is defined by the voice index, not enumerated in the manifest**: the bundled pack currently ships 48 lines across 34 events, each line addressed as `voice//.ogg`. A voice pack carries no version of its own — the pack's `version` in `manifest.json` covers art, animation and audio together. A pack may ship no voice index at all, and every event then stays silent. This layout is the **agreed target**: the bundled pack already ships its assets this way, but runtime voice playback is **not implemented yet**. Voice lines are recorded or generated **ahead of time** and shipped inside a character pack. **There is no runtime text-to-speech generation requirement**, no mandatory TTS API, and no need to send session text to a speech provider. Tools for producing illustrations, skeleton animation, or audio may be used **offline during asset creation**; they are not part of the DSH Pets runtime. ## Roadmap ### v0.1 — Usable desktop companion - [ ] DSH plugin connection and reliable per-session state tracking - [ ] Active-session bubbles/list and one-click session navigation - [ ] Completion, failure, and approval alerts with deduplication - [ ] Missed/unread notifications and safe reconnection behavior - [ ] Cross-platform desktop window and tray foundation - [ ] Spine character rendering with static-image fallback - [ ] Pre-recorded voice playback, mute, and event cooldown - [ ] Dragging, remembered position, and basic do-not-disturb controls - [ ] Ubuntu 24.04 end-to-end verification ### Later improvements - [ ] Model-to-character mapping, character-pack management UI, and on-demand pack download - [ ] Better mouth-motion synchronization and natural idle interactions - [ ] Edge docking, auto-hide, and configurable mouse pass-through - [ ] Power-saving / reduced-frame-rate mode - [ ] Wider Windows, macOS, X11, and Wayland compatibility coverage The roadmap is indicative and may change as implementation and compatibility testing progress. ## Installation **No stable cross-platform release is documented yet.** Once an installable version is available, installation steps and supported DSH versions will be published here. Please do not assume the original Windows-only `dsh-pet` installation instructions apply to this project. ### Current plugin shape (development) The repository is already installable as a Host-only Cordis bundle: `package.json` declares `dsh.bundle.patch`, `cordis.patch.yml` activates the entry, and `index.js` registers every bundled `skills//SKILL.md` as an agent skill. As a result the character-pipeline skill `three-view-parts` appears in the skill catalog without being copied into `.agents/skills`. ```bash # Link this checkout into a profile (example: the web profile) dsh plugin --profile web add /path/to/dsh-pets # Restart Harness afterwards so the bundle is activated; the skill then appears # in the session skill catalog and can be loaded by name. # Uninstall dsh plugin --profile web remove dsh-pets ``` At this stage the bundle only registers skills. The pet window, session tracking, voice playback, and tray integration remain planned work; see the roadmap above. ## Reliability, privacy, and resource usage Design priorities: - Prefer explicit task lifecycle signals; losing connectivity must **not** be mistaken for successful completion. - Deduplicate completion events, retain unread notices, and restore the visible state after reconnection when supported by DSH. - Keep controls usable when the character renderer, audio, or GPU acceleration is unavailable. - Keep communication local by default and restrict exposed control endpoints; remote-access configurations must be secured separately. - Do not read task contents aloud by default. Recorded voice lines communicate predefined **status messages**, not arbitrary code, secrets, or chat content. - Provide mute, do-not-disturb, and lower-resource options for long-running desktop use. These are **engineering goals**, not a security audit or a claim of completed functionality. ## Development and contributions The project is in an early stage. Issues, platform-specific bug reports, and reproducible test cases are welcome. Before proposing new features, please prioritize the two core workflows: **session switching** and **reliable completion notifications**. ## Attribution and licensing This project uses **split licensing**: source code is MIT, character art is CC BY-NC-SA 4.0. The authoritative text is the root [LICENSE](LICENSE). ### Project code: MIT DSH Pets is intended to evolve from [zuodazuoqiang001/dsh-pet](https://github.com/zuodazuoqiang001/dsh-pet) (MIT). Source code, scripts and docs are MIT, and reused upstream code keeps its original copyright and license notices. **The MIT grant does not extend to `assets/characters/`.** ### Character packs: CC BY-NC-SA 4.0, non-commercial The bundled `deepseek` pack is built on community fan artwork and is distributed under **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International** ([CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans)), following the original author's [copyright statement](https://www.bilibili.com/opus/1247156596114456581). Three rules apply: 1. **The attribution chain must stay complete.** The whale-girl prototype is by 上善无形 / 上善, the DeepSeek personification redesign is by ZipZipPipe ([author page](https://space.bilibili.com/4168597)), and this project contributes the derivative production and packaging. All three must be credited; omitting any link breaks the license. 2. **Free distribution is not commercial permission.** Publishing free-of-charge on GitHub Releases or npm satisfies the non-commercial requirement, but it neither grants nor transfers any commercial right. Nobody may put a pack or its derivatives into commercial products, paid services or for-profit distribution on that basis. 3. **We cannot license rights we do not hold.** Every character, texture and audio asset needs its own verified upstream authorization; anything unverified is excluded, and the reasons are listed in `ATTRIBUTION.md`. Third-party assets keep their own licenses — this project grants nothing on their behalf. - Reuse requires: keep attribution, indicate your changes, non-commercial use only, and release derivative contributions under the same CC BY-NC-SA 4.0. - Every pack ships its own `LICENSE` and `ATTRIBUTION.md` beside its assets — see [assets/characters/deepseek/LICENSE](assets/characters/deepseek/LICENSE) and [ATTRIBUTION.md](assets/characters/deepseek/ATTRIBUTION.md) for the full provenance chain and the assets deliberately **not** included. - **Takedown**: if a rights holder objects to any included asset, open an [issue](https://github.com/bloodarea/dsh-pets/issues) with the file path and a verifiable source; the asset is removed after verification. CC licenses are irrevocable, so this commits us to stopping distribution, not to amending the license. - Character packs are themed after model families but are **not** official brand material. ### Trademarks Names and marks such as DeepSeek, Claude, GPT, Kimi, and Qwen belong to their respective owners. Nothing in this project implies affiliation with or endorsement by any of them. ### Spine runtime Spine runtimes and exported animation data are subject to Esoteric Software's commercial licensing terms; confirm the applicable terms before shipping. Other third-party SDKs and assets keep their own licenses. --- **DSH Pets** — A small, always-available desktop entry point for your AI agent sessions.