dsh-aemeath-pet

One-Line Description

Adds a pixel-art desktop pet named "Aemeath" to the DeepSeek Harness Web GUI: stays in the corner of the screen, automatically switches between idle/work/failure animations based on agent status and speaks bilingual Chinese/English bubbles.

Core Features

• Automatically switches between idle, working, and waiting loop animations based on current session state; plays failure animation and shows error bubble when agent encounters errors
• Jumps to celebrate and says "Leave it to me!" when agent starts a new task, jumps again when a round finishes and says "All done ✨"
• When idle, randomly runs left/right diagonally, works in place, or jumps; appears in both docked and free-placement modes
• Supports mouse dragging to change position, right-click menu to switch docked/free placement, resizing (small/medium/large), hiding and resetting position
• Clicking the pet causes it to wave back and randomly says a greeting
• Preferences (enabled, scale, docked or free placement position) persist to localStorage and restore after browser refresh

Technical Implementation

• Language: TypeScript
• Key Dependencies: @deepseek-ai/cordis, @deepseek-ai/dsh-client-runtime, @deepseek-ai/dsh-client-locale, @deepseek-ai/dsh-host-webserver
• Architecture Pattern: host + client dual-end; host half injects into webServer via cordis and registers precise route /aemeath-pet/spritesheet.webp to return spritesheet, client half registers via __ModuleLoader__ and injects sessions + locale, subscribes to session snapshots to derive pet state
• Entry Files: src/index.ts (host side), src/client/index.ts (client side)
• Rendering: Canvas draws sprite sheets, DOM injects bubbles and right-click menus, no React dependency

Use Cases

DSH Web users who want a more companionable interface instead of just a cold command-line panel. After installation, this pixel pet stays in the bottom-right corner of the screen and provides feedback throughout your interactions with the agent—asking questions, waiting for responses, and debugging errors. Ideal for developers and power users who keep DSH running for extended periods. If you prefer not to be disturbed by animations, you can hide it with one click.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:culture-flask/dsh-aemeath-pet

Configuration Options

This plugin requires no pre-declared configuration options. All adjustable parameters take effect immediately via the right-click menu:

These preferences are written to the current browser's localStorage (key: dsh-aemeath-pet.prefs), not synced across devices; to restore defaults, click "Reset Position" in the menu or clear this key.

FAQ

Q: What to do if the pet doesn't appear after installation?

A: Restart dsh web and perform Cmd/Ctrl+Shift+R hard refresh in the browser. The old Service Worker may have cached the missing sprite sheet route. Note that --profile web in the command is required—the plugin only works for the web profile.

Q: Where is pet data stored? Does it sync with the account?

A: Preferences (enabled state, scale, docked or free placement position) are written only to the current browser's localStorage, key: dsh-aemeath-pet.prefs. It doesn't go online and doesn't sync across devices. Uninstalling the plugin or clearing this localStorage key restores defaults.

Q: Will the pet block other buttons on the page?

A: No. The pet's root container is fixed with pointer-events: none, re-enabling pointer events only on the canvas, menu, and "paw print" button; CSS sets the highest z-index (2147483000) but doesn't intercept interactions with underlying applications.

Q: What happens on mouse click / drag?

A: Clicking plays a wave animation and randomly says "Hi~" or "I'm here~"; dragging for more than 5 pixels enters free placement mode, and the position is written back to localStorage after release. Right-click opens the menu for size, dock/freedom, hide, reset, etc.

Q: What happens if asset loading fails?

A: The canvas remains blank, and the pet shows a "Asset loading failed..." bubble. This is usually due to unreachable /aemeath-pet/spritesheet.webp route on the host side or incorrectly installed lib resources. Please verify the plugin is added to dsh.profile.bundles and dsh web has been restarted.

Q: Is this an official plugin? Can the assets be used commercially?

A: No. The Aemeath character is from "Wuthering Waves" (Kuro Games), and the sprite sheet is sourced from the Apache-2.0 version of aemeath-codex-pet and dynamics released by Bilibili user "Neuro音乐"; the plugin code itself is Apache-2.0, but the character image and original art assets rights belong to the original author and respective rights holders. The repository grants no additional commercial usage license.

Difficulty Level

Beginner — Install with one command to see the pet; all interactions completed via right-click menu and dragging, no documentation reading or config file editing required.

Known Issues & Limitations

• When localStorage is unavailable (privacy mode, quota exhausted), preferences are retained only for the current session and lost after refresh; the plugin won't throw errors
• First random action appears 4–8 seconds after initial launch, subsequent intervals are 6–15 seconds; actions are paused when browser tab is backgrounded and won't be backfilled
• During dragging or when playing one-shot animations, new random actions and state transitions are postponed, not interrupted
• Pet only works for web profile; CLI profile won't load it; also don't install to desktop profile—it won't start due to missing webServer injection
• Character image is fan-made material for personal use only; redistribution or commercial use is not recommended

爱弥斯 · DeepSeek Harness 桌宠 — DeepSeek Harness Web GUI 的像素风宠物插件。

爱弥斯会停在页面角落，陪 agent 一起工作：

功能

• 🎬 全部 11 种动画（待机 / 左右移动 / 挥手 / 跳跃 / 失败 / 等待 / 工作 / 检查 / 两向注视），帧布局与 Codex Pet V2 图集一致（1536×2288，8×11 格，每格 192×208）
• 🐾 右击菜单：停靠角落 / 自由摆放、大小（小·中·大）、隐藏、重置位置；拖拽可随意移动
• 💬 跟随 DSH 语言的中/英气泡文案（locale 命名空间 dsh-aemeath-pet）
• 🏃 随时随机表演：向左/右斜向奔跑（running-left / running-right，含垂直分量）、原地工作（running）、跳跃（jumping）— 停靠和自由摆放模式下都会出现
• 💾 偏好（启用 / 缩放 / 位置）持久化在 localStorage
• 🔌 纯客户端渲染（canvas + DOM，无 React 依赖）；Host 半只负责服务精灵图素材

安装

dsh plugin --profile web add https://github.com/culture-flask/dsh-aemeath-pet/archive/refs/tags/v0.1.0.tar.gz

重启 dsh web 并硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到爱弥斯。

目录结构

dsh-aemeath-pet/
├─ src/
│  ├─ index.ts          # host 半：webServer 素材路由（/aemeath-pet/spritesheet.webp）
│  └─ client/           # 浏览器半（无 React，canvas + DOM）
│     ├─ index.ts       # 会话接线：snapshot → 情绪/动作 + 气泡
│     ├─ pet.ts         # 宠物引擎：动画循环、随机动作、拖拽/菜单/偏好
│     ├─ state.ts       # 纯函数状态派生（单测覆盖）
│     ├─ atlas.ts       # Codex Pet V2 图集布局（每动画的行/帧/帧率）
│     ├─ locales.ts     # 中英文案
│     └─ styles.ts      # 注入样式
├─ assets/              # spritesheet-v2-r2.webp（素材见下）
├─ lib/                 # 构建产物（提交）
├─ tests/               # state 纯逻辑 + pet jsdom 引擎测试
├─ cordis.patch.yml     # bundle 补丁（挂载行）
└─ dsh.plugin.json      # 插件元数据

素材与版权

素材来源：

• 精灵图与图集布局：源自 aemeath-codex-pet（Apache-2.0，R2）——本插件使用的 assets/spritesheet-v2-r2.webp 是该仓库的原始文件
• 角色形象：爱弥斯出自游戏 《鸣潮》（Wuthering Waves），角色及美术素材权利归 Kuro Games / 相应权利方所有
• 原始表情包素材：出自 B 站 up 主 「Neuro音乐」 的动态：哔哩哔哩 · 爱弥斯表情包

本项目是非官方、非商业的同人桌宠适配项目；本仓库不对这些素材授予额外的商业使用许可。角色形象与原始美术素材权利归原作者与相应权利方所有，仅供个人使用；二次分发或商业使用请先取得授权。

License

Apache-2.0，见 LICENSE。