cyanfish-x/dsh-live2d-pets

English | 简体中文

A Live2D desk girl for DeepSeek Harness (DSH): it tilts its head when you think, celebrates when you finish, and you can pet it!

Features

• Model loading: 5 curated presets (Hiyori / Haru / Mao / Mark / Natori) plus custom entries; any .model3.json over https / http, or an absolute local path (e.g. C:/models/foo/foo.model3.json) served by the plugin Host through a same-origin route; custom models support animation mapping to bind native motion groups to pet states / touch interactions
• State mirroring: the pet reflects agent thinking / idle / error / done / file-delivery celebration / waiting-for-approval (motion + bubbles, SSE push)
• Personas: six built-in tones (tsundere / genki / airhead / kuudere / gentle / yandere); custom personas via a plugin-owned JSONC file with hot reload
• Companionship: part-based tap reactions / mouse-follow (head, eyes and body look toward the pointer) / free drag docking / task-done celebration; when HitAreas are sparse, spatial fallback uses five AABB rectangles
• Settings panel: DSH Settings → “Pet config” — enable, size, FPS, persona, models, developer options; scalar settings are persisted to ~/.dsh/settings.yaml, while custom personas and custom models live in ~/.dsh/live2d-pet/ plugin-owned JSONC files; applies immediately
• Stay out of the way: bottom-right by default, small size, draggable, hideable, pause rendering when the tab is hidden, FPS cap, static avatar fallback on low end

Quick start

Option A: Paste a prompt for your agent (recommended)

Copy this into a DSH Web GUI chat and let the agent install and verify:

Please install the dsh-live2d-pets plugin (Live2D desk pet for DSH):
1. Run: dsh plugin --profile web add dsh-live2d-pets
2. Run: dsh plugin --profile web list and confirm dsh-live2d-pets is installed
3. Report the result; if it fails, include the error output

Option B: Manual install

dsh plugin --profile web add dsh-live2d-pets

The plugin is enabled by default after install. Start DSH:

dsh web

Open the browser — a default pet (160px) appears at the bottom-right. Default model is Hiyori (Live2D sample); first load needs network.

Interaction

• Mouse follow (enabled by default): as the pointer moves anywhere on the page, the pet’s head, eyes and body smoothly look toward it; when the pointer leaves the page it resets to face front. It pauses while dragging, hidden, or when the tab/window is not focused.
• Tap interactions: touching the head / legs / arms / body triggers its own line and motion; when a model has sparse HitAreas, spatial fallback zones are used.
• Drag: hold and drag the pet anywhere, then release to dock it; the position is persisted.

Custom models: Settings → “Pet config” → “My models”, add a name + .model3.json URL (CDN, self-hosted static, local HTTP, or an absolute local path such as C:/models/foo/foo.model3.json; local paths are served by the plugin Host via /pet-local-models/...). Expand Spatial tap override to tune the five rectangles (0–1; leave blank for defaults), or expand Animation mapping to parse the model’s native motion groups and bind them to states / touch interactions. Pair with developer option Show tap zones. Built-in Hiyori ships with a centered preset.

Configuration

Open DSH Settings → “Pet config”. Changes apply immediately — no restart.

• Show pet: on / off
• Size: 40–400px (default 160)
• Render FPS: 30 / 60 / unlimited (default 30)
• Personas: switch built-in or custom tones; “Custom personas ↗” edits $DSH_HOME/live2d-pet/personas.jsonc, then hit “↻ Reload”
• Models: pick a curated preset, or add name + .model3.json URL under “My models” (optional spatial-tap / animation mapping); custom models live in $DSH_HOME/live2d-pet/custom-models.jsonc
• Developer options: master toggle (off by default); when enabled, shows the debug panel (with native model animation list preview) and the tap-zone overlay

Uninstall

dsh plugin --profile web remove dsh-live2d-pets

Docs

Need	Doc
Chinese README	README.md
Product intent	docs/intent/live2d-pet-plugin.md (Chinese)
Behavior spec	docs/spec/live2d-pet-v01.md (Chinese)
Architecture decisions	docs/adr/ (rendering stack: ADR-003)
Research notes	docs/research/ (settings panel: settings-tab.md)

Stack

• pixi-live2d-display 0.4.0 + PixiJS 6.5.10 + Cubism Core 4 (ADR-003)
• Client renders in DSH Web GUI shell.overlay (Popover top layer, ADR-005); settings section on settings.section (ADR-002)
• State push: Host subscribes to agent/* → same-origin SSE /api/live2d-pet/events (ADR-006); pause when tab hidden / blurred
• Settings: scalar settings via Host ctx.settings (~/.dsh/settings.yaml over base); custom personas at ~/.dsh/live2d-pet/personas.jsonc, custom models at ~/.dsh/live2d-pet/custom-models.jsonc are read/written by the plugin; transport via plugin API /api/live2d-pet/settings (settingsScope wire allowlist limits — research 3.4/3.5)

License

• Plugin code: MIT
• Model list: URL-only, not shipped in the package; each entry must record license type + link; NC models marked non-commercial only (src/presets/presets.jsonc)
• Built-in Hiyori / Haru / Mao / Mark / Natori: Live2D sample models under the Sample Model Terms (free for commercial use with attribution)
• Live2D SDK: follow Live2D official terms