dsh-pet 🐾
一只住在 DeepSeek Harness 里的桌面宠物：待机呼吸、随机动作（打瞌睡、玩魔方、写代码、吃火锅……97 个手绘风透明动画随时无缝衔接）、左右转向、屏幕漫游、点击 Q 弹、拖拽甩抛反弹、右键菜单点播动作、余额动画 + 头顶联想气泡——可多开同屏，能脱离浏览器住上桌面（透明置顶小窗），也能自己添加全新宠物种类（pet pack）。
这不是一个普通插件，而是完整的三件套项目：
① 提示词（配方） → ② 素材生成链（引擎） → ③ 插件（成品）
AI 生成动画的配方 源视频 → 透明动画的管线 运行在 DSH 里的宠物
任何人 clone 本仓库，都可以从零生成自己的桌面宠物——换角色、换动作、换风格，全流程可复现。
快速开始（安装插件）
以下命令都在你的命令行终端（PowerShell / CMD 等）中运行。前提是 DSH 环境已就绪：
# ① 前置要求：确认 Node.js 已安装
node -v
# ② 安装 DSH 启动器与 pnpm（已装可跳过；装完请重新打开终端）
npm install -g @deepseek-ai/dsh pnpm
dsh --version # 验证 dsh 命令可用
# ③ 安装本插件
dsh plugin --profile web add dsh-pet
重启 dsh web，宠物出现在界面右上角（默认配置角落，可在设置页修改）。
兼容性：本插件在 dsh 0.1.1-rc.2 下开发并测试（dsh --version 可查看你的版本）。建议使用相同版本；其他版本如遇问题欢迎反馈。
从源码安装（clone 本仓库后）
lib/ 构建产物不入库，clone 后需要先构建再安装：
# ① clone 本仓库，进入插件目录
git clone https://github.com/PC2005-cloud/dsh-pet.git
cd dsh-pet/dsh-pet
# ② 安装依赖
npm install
# ③ 构建（tsdown → lib）
npm run prepare # 构建完整 lib（npm install / npm publish 时会自动执行）
# ④ 安装到 DSH（file: 指向本目录，用构建好的 lib）
dsh plugin --profile web add file:D:/path/to/dsh-pet
注：prepare（npm install / npm publish 时自动执行，也可手动 npm run prepare）才产出完整可安装的 lib——除 tsdown 构建外还构建桌面共享核心（shared-core.js）、生成类型声明并收敛发布 files 清单；裸 tsdown 构建会缺桌面运行时与类型。
插件功能
- 纯粹的桌宠：核心就是陪你——没有天气查询、系统监控、Agent 状态感知等花活；除了可选的余额展示（见下节）与系统通知（对话完成 / 生成失败 / 输出截断 / 权限申请 / 用户选择，窗口失焦时弹系统级通知）外没有其他业务功能。零核心改动（不碰 DSH 内核）
- 余额展示：实时显示当前 LLM 服务商的余额/额度——DeepSeek 官方显示账户余额（¥），OpenCode Zen Go 显示 5h/周/月 三个额度窗口中最紧张的一个；每次刷新按档位播放余额动画，头顶弹出联想气泡（随宠物大小等比缩放，10 秒后自动消失）；每只宠物可独立开关（
balanceEnabled）
- 动画链：每个动画（含待机）播完立即按权重选下一个（权重配置于
config.jsonc，默认 idle 10 / turn 5 / move 5 + 动作分类权重），首尾相接永不停止
- 多开：可配置同时显示多个宠物，每只宠物独立的大小与位置（设置页「桌宠配置」添加/删除）
- 屏幕漫游：朝 facing 方向行走，先检查空间、不走出屏幕
- 点击/拖拽（弹簧跟手 + 甩抛反弹 + Q 弹）：点击有回应动画并「Q 弹」挤压回弹（贴地锚定，reduce-motion 跳过）；拖拽为过阻尼弹簧跟手，用力甩出会沿抛物线飞行、屏幕边缘反弹、落地摩擦停稳且每次落地 Q 弹一下（温柔放下 = 原地停住），两端同一套纯函数物理与挤压曲线（
dsh-pet/src/shared/physics.ts）
- 右键菜单：右键宠物弹出级联菜单——桌面端根项为「打开网站 / 查看余额 / 回到初始位置 + 动作」、浏览器端为「回到初始位置 + 动作」；「打开网站」用系统默认浏览器打开 DSH 网站（等效网页里 Ctrl+点击链接）；「查看余额」立即弹余额气泡播档位动画（桌面端；浏览器端用对话框
/balance 命令）；动作 → 分类 → 具体动画，可任意点播（移动分类动画点播会真实行走一段——边界检查/随机距离/起停时段与随机移动同一套）；同一份组件两端共用、外观行为一致
- 左右朝向：所有动画可镜像，人物可朝左/朝右
- 落地对齐：动画统一脚底线，宠物始终站在地面上
- 流畅切换：双缓冲交叉淡入，切换无空白帧
- 桌面模式（可选）：可脱离浏览器，为每只桌面宠物开一个独立透明置顶局部小窗，与浏览器严格同行为、共用同一份素材与纯逻辑（见下节）
- 额外宠物种类（pet pack）：在
$DSH_HOME/dsh-pet/pet/ 下建 种类名-config.json + 种类名-animation/，即可添加拥有独立动画池与素材的全新种类，多实例共享素材（见「配置 → 方式四」）
- 自定义动画：往
main-animation/webm/ 放入 VP9-Alpha 的 .webm 即可作为新动画，优先于包内素材
- 无障碍：支持
prefers-reduced-motion（减少动效时跳过 Q 弹挤压与淡入切换）
🪟 桌面模式（可选，脱离浏览器）
插件内建双模式：安装后默认会拉起独立透明置顶窗口——为每只桌面宠物各开一个局部小窗口（尺寸 = 宠物包围盒 + 四周外扩余量，为气泡/弹窗预留空间，跟随宠物移动；永不铺满屏幕：全屏透明分层窗会触发 Windows DWM 视频合成黑屏）。与浏览器 overlay 严格同行为——同一份纯逻辑源码（dsh-pet/src/shared/），两端的功能/动画/文案/配置完全对齐，不会出现"一个有另一个没有"：
- 依赖：首次启动自动探测 Electron（
DSH_PET_ELECTRON_PATH 环境变量 → 全局 npm → 常见安装位置），找不到时自动下载到 ~/.dsh/electron/（可 cd dsh-pet && npm run ensure:electron 手动触发）；缺失时仅日志告警，不影响浏览器形态
- 开关 = 每只宠物的必填字段
display（四个值）：web = 仅浏览器 / desktop = 仅桌面 / both = 两者 / none = 都不显示；桌面模式渲染 display 含 desktop 的全部宠物（多开同屏，与浏览器一致）。在 DSH 设置页「桌宠配置」编辑，保存即时生效；缺失即配置错误，代码不做兜底
- 实现：浏览器 bundle 与桌面
shared-core.js（src/shared 的 iife 构建产物，window.PetShared）共用同一份纯逻辑；桌面端 dsh-pet/runtime/electron-helper/ 只是薄壳（Electron 窗口 + 纯 DOM 渲染），行为差异为零
- 数据通道（bridge）：桌面 Helper 是插件自拉的独立 Electron 进程，宿主与它之间走进程管道 + 本地回调（
dsh-pet-bridge:// 自定义 scheme → Electron 主进程 → stdout JSON 行 → 宿主 handlePetRoute 应答，素材只传文件路径由 Helper 读盘）——桌面端不依赖 DSH 的 HTTP 路由，因此不受 DSH Desktop 2.0.3+ 浏览器访问闸门影响（该闸门只放行带内部令牌的请求，插件子进程的裸 HTTP 会被 403）。start:desktop 本地调试/无宿主场景自动回落旧 HTTP 路径
- 本地调试：
cd dsh-pet && npm run start:desktop -- http://127.0.0.1:3080/dsh-pet-7340/config（无 DSH_PET_BRIDGE，走 HTTP）
⚙️ 余额展示（Balance）
余额是"事件动画"的一种：运行时按 eventsRefreshSec.balance（秒）周期拉取当前服务商（跟随 agent-default-model 的 provider）的余额/用量数据，每次刷新按档位触发一次余额动画，并在宠物头顶弹出联想气泡（气泡为角色"思考"式白泡，随宠物大小等比缩放，10 秒后自动消失）：
- DeepSeek 官方（
deepseek-official）：气泡显示账户余额（如 余额 ¥8.79）；余额按 ¥20 满额折算成已用百分比，分 6 档播放动画（钱袋满溢 → 金袋叮当 → 钱袋如常 → 数金皱眉 → 袋空如洗 → 分文不剩）
- OpenCode Zen Go（
opencode-go）：气泡显示 5h/周/月 三个额度窗口中最先告急的一个（如 周额度已用 88% / 2.5 天重置），同样按已用百分比分档
- 按宠物开关：
pets[i].balanceEnabled（必填布尔）控制该宠物是否触发余额动画/显示气泡；全部宠物关闭时自动跳过余额轮询
- 所需凭据：对应 provider 的 API key（
deepseek-official → DEEPSEEK_API_KEY；opencode-go → OPENCODE_GO_API_KEY），在 DSH 凭据中配置后启用；未匹配的服务商按设计不触发动画、不显示气泡
⚙️ 配置（大小 / 位置 / 多开）
桌宠的大小、位置、多开均可配置，两条途径：
💡 两条途径只是编辑入口不同，最终都是同一份用户配置——配置能力远不止设置页那几个选项：设置页可改大小/位置/边距/显示位置/余额开关/多开，但手动编写配置文件可以任意自由配置（动画池、播放权重、事件动画、刷新周期……），只要格式与包内默认配置 config.jsonc 一致即可，用户配置会整体覆盖对应字段的默认值。
方式一：设置页（推荐）
DSH 设置 → 「桌宠配置」：
- 大小：宽度 px（高度自动 = 宽度 × 9/16）
- 位置：四角（corner）＋ 水平/垂直边距（marginX / marginY）
- 显示位置（display）：web=仅浏览器 / desktop=仅桌面 / both=两者都显示 / none=都不显示
- 余额功能：勾选后该宠物才会触发余额动画并显示余额气泡
- 多开：添加/删除宠物，每只宠物独立 id、大小、位置
- 点「保存」即时生效（无需刷新）；「恢复默认」回到 config.jsonc 默认
方式二：config.jsonc（单一来源）
插件包内 dsh-pet/assets/config.jsonc 的 pets 数组定义默认宠物：
"pets": [
{ "id": "main", "size": 462, "balanceEnabled": true, "display": "both", "position": { "corner": "top-right", "marginX": 24, "marginY": 100 } }
]
- 每只宠物：
id（标识）／ size（宽度 px）／ balanceEnabled（是否启用余额功能，必填布尔）／ display（web/desktop/both/none，必填，见上）／ position（corner 四角之一 + marginX/marginY 边距）
- 余额刷新周期：
eventsRefreshSec.balance（秒）——余额数据刷新与余额动画触发的间隔，启动时立即触发一次，之后按此周期循环（默认 1800）
- 设置页的修改保存到用户层
$DSH_HOME/dsh-pet/main-config.json（完整宠物列表，覆盖包内默认）；「恢复默认」即清除用户层、回落 config.jsonc
方式三：手动编辑配置文件（高级，任意自由配置）
用户层配置文件位于 $DSH_HOME/dsh-pet/main-config.json。它和包内默认配置是同一套格式——想改什么直接照着 assets/config.jsonc 的结构写即可，写错的字段/缺失的字段回落默认，无需（也无法）写完整份：
| 字段 |
作用 |
格式与默认一致即可 |
pets |
宠物列表（大小/位置/多开/余额开关） |
数组，每项同 pets[] 结构 |
animations |
动画池：idle / turn / drag / clicks / moves / categories / events（余额等事件动画） |
同 animations 结构 |
animationWeights |
动画链播放权重（idle / turn / move） |
同 animationWeights 结构 |
eventsRefreshSec |
事件刷新周期（秒） |
同 eventsRefreshSec 结构 |
notificationsEnabled |
系统通知总开关（布尔） |
同 notificationsEnabled |
覆盖语义：用户层给出即整体替换该字段（如写了 animations 就用你的整份动画池，替代默认），没写的字段回落包内默认。校验在插件加载时执行——格式错误会在 DSH 控制台显式报错，不会静默运行残缺配置。
方式四：额外宠物（pet pack）——添加新「种类」
方式一~三都只调整默认宠物的实例（数量/大小/位置），动画池始终是全局一份。要添加全新种类的宠物（独立动画池 + 自己的素材），在用户数据根下建 pet/ 目录：
$DSH_HOME/dsh-pet/
├─ main-config.json ← 主宠物配置（现有，不动）
├─ main-animation/webm/*.webm ← 主宠物素材（现有，只属于 main）
└─ pet/
├─ pig-config.json ← 额外宠物 pig 的配置（命名词干 = 种类名，实例 id 任意）
└─ pig-animation/*.webm ← pig 自己的动画素材（直接平铺，仿 main-animation）
每只额外宠物 = 一个 -config.json + 一个 -animation/ 目录，同前缀配对；扫描 pet/ 自动发现，浏览器与桌面同时生效。一个 -config.json 定义一个「种类」（动画池 + 素材目录），pets 数组可放该种类的任意多只实例（共享动画池与素材）：
// pet/pig-config.json —— 与 main-config.json 同构的完整配置
{
"notificationsEnabled": true,
"pets": [
{
"id": "pig1", // 实例 id（可多只；不必等于文件名前缀）
"size": 420,
"balanceEnabled": true,
"display": "both", // web / desktop / both / none
"position": { "corner": "top-right", "marginX": 24, "marginY": 100 }
},
{ "id": "pig2", "size": 360, "balanceEnabled": false, "display": "web", "position": { "corner": "top-left", "marginX": 24, "marginY": 100 } }
],
"animations": {
"idle": ["待机"], "turn": [], "drag": [], "clicks": ["打滚"],
"moves": { "default": { "minDist": 80, "maxDist": 360, "margin": 20, "leadSec": 2, "tailSec": 2 }, "actions": [] },
"categories": [],
"events": { "balance": ["余额-钱袋满溢", "余额-金袋叮当", "余额-钱袋如常", "余额-数金皱眉", "余额-袋空如洗", "余额-分文不剩"] }
},
"animationWeights": { "idle": 80, "turn": 0, "move": 0 },
"eventsRefreshSec": { "balance": 1800 }
}
规则（与主宠物严格隔离，绝不混用）：
- 素材只查自己的：素材目录名 = 文件名前缀（
pet/pig-config.json → pet/pig-animation/），该种类所有实例共用；动画 URL /thumb/<前缀>/<名>.webm，查不到即 404——绝不落到 main-animation 或包内素材
- 动画池不回落全局：
animations / animationWeights 必须写全（缺失即配置错误）
- 与主配置同构的约束：
pets 每只字段完整合法、数组内 id 唯一、animations / animationWeights 结构校验同一套规则；notificationsEnabled / eventsRefreshSec 是全局属性，不归宠物文件管（写了忽略、不写不报错）
- 配置非法 / 缺少
-animation/ 目录 / 实例 id 与主宠物冲突 → 加载时显式报错并跳过（不影响其他宠物）
- 设置页不列出文件宠物（改文件即生效，刷新可见；保存/恢复默认不会把它们写进
main-config.json）
- 余额档位动画按各宠物自己的
events.balance
运行效果
宠物实际运行在 DSH Web 界面中的样子：
效果预览
全部动画（640×360，插件实际播放用的资源）——GIF 预览存放于仓库 dsh-pet/assets/preview/（raw 直链渲染，文件名采用拼音便于跨平台）；完整透明视频见插件包 dsh-pet/assets/webm/（VP9-alpha，唯一发布格式）：
待机 / 转向
移动
小动作
dsh-pet 是 DeepSeek Harness（DSH）的一个透明动画桌面宠物插件：它通过 97 段手绘动画呈现发呆、打盹、还原魔方、写代码、吃火锅等动作，带有点击/拖拽物理效果和可选的余额显示气泡。