← 返回条目

dsh-pet#dsh-pet · 使用说明

中文版：依据官方 README 翻译整理，保留原有结构与命令

dsh-pet 🐾

一只住在 DeepSeek Harness 里的桌面宠物：待机呼吸、随机动作（打瞌睡、玩魔方、吃火锅……）、左右转向、屏幕漫游、点击 Q 弹、拖拽甩抛反弹、右键菜单点播——一百余个透明动画随时无缝衔接；还能跟随 DSH 会话事件切换工作状态动画、按档位播放余额动画 + 头顶气泡、碎碎念与对话聊天、窗口失焦时弹系统通知。可多开同屏，能脱离浏览器住上桌面（透明置顶小窗），也能自己添加全新宠物种类（pet pack）。

这不是一个普通插件，而是完整的三件套项目：

① 提示词（配方）    →  ② 素材生成链（引擎）  →  ③ 插件（成品）
AI 生成动画的配方     源视频 → 透明动画的管线    运行在 DSH 里的宠物

任何人 clone 本仓库，都可以从零生成自己的桌面宠物——换角色、换动作、换风格，全流程可复现。

快速开始（安装插件）

装法取决于你在用哪个 DSH：

🪟 桌面应用（Electron 版）

直接在应用内「插件管理」页的安装框里填 dsh-pet，不用开终端；需要在终端里操作插件时，用桌面应用自带的那份 CLI。

🌐 dsh web

以下命令都在你的命令行终端（PowerShell / CMD 等）中运行。前提是 DSH 环境已就绪：
# ① 前置要求：确认 Node.js 已安装
node -v

# ② 安装 DSH 启动器与 pnpm（已装可跳过；装完请重新打开终端）
npm install -g @deepseek-ai/dsh pnpm
dsh --version   # 验证 dsh 命令可用

# ③ 安装本插件（web 模式用 --profile web）
dsh plugin --profile web add dsh-pet

装完重开桌面应用（dsh web 用户则重启 dsh web）才生效——运行中的进程持有内存里的旧插件。宠物出现在界面右上角（默认配置角落，可在设置页修改）。

兼容性：本插件当前在 dsh 0.2.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

# ③ 构建（完整 lib：tsdown → lib + 桌面共享核心 + 类型声明）
npm run build       # 必须手动跑一次（克隆后 npm install 不再自动构建）

# ④ 安装到 DSH（file: 指向**插件目录**——上面 cd 进去的那一层，用构建好的 lib）
#    --profile 填实际在用的那个：dsh web → web；
#    桌面应用（Electron 版）改用应用内「插件管理」安装，见上方快速开始
dsh plugin --profile web add file:D:/path/to/dsh-pet/dsh-pet
注：npm run build（即 scripts/prepare.js）才产出完整可安装的 lib——除 tsdown 构建外还构建桌面共享核心（shared-core.js）、生成类型声明并收敛发布 files 清单；裸 tsdown 构建会缺桌面运行时与类型。发布与打包（npm publish / npm pack）时由 prepack 自动调用它，克隆仓库后需手动跑一次。

安装后你会看到什么

默认配置是 display: "both"（浏览器与桌面都显示），所以重开 DSH 之后会依次出现两处，不必手动开：

  1. 浏览器端先出现。 宠物落在界面右上角（默认角落，设置页可改），此时桌面上还是空的。
  2. 宿主自动补桌面运行时。 本机没有 Electron 时，插件会自己下载一份（落在 ~/.dsh/electron，同一版本只下一次；默认走 npmmirror 镜像）。进度直接打在 DSH 的控制台里，形如：
   [dsh-pet] Electron not found, downloading to /.dsh/electron/electron.exe ...
   [dsh-pet] Electron not found, downloading v43.3.0 (win32-x64) ...
   [dsh-pet] downloading 42.3MB / 104.1MB
   [dsh-pet] download complete (37.5s), extracting to /.dsh/electron ...

这一步在后台进行，浏览器里的宠物照常可用；要等多久取决于网速（几十秒到几分钟），期间不用管它。

  1. 桌面端随后出现。 解压完自动拉起桌面 Helper，同一只宠物以透明窗形式落到桌面上——此时屏幕上一共两只：浏览器里一只、桌面上那只，共用同一份配置与同一套动画。
  2. 想只留一只。 两条路都行，改完即时生效：
已经装过 Electron（或设了 DSH_PET_ELECTRON_PATH 指向现成可执行文件）时，第 2 步会跳过，桌面端几乎立刻出现。下载失败只影响桌面模式：控制台会给出提示，浏览器里的宠物不受影响；网络受限时可以设 DSH_PET_ELECTRON_MIRROR 换镜像、DSH_PET_ELECTRON_VERSION 指定版本，重启后再试。

💬 反馈与发版节奏

欢迎提 issue 与 PR——bug、体验问题随时反馈。新功能请先开 issue 说明使用场景，由维护者判断是否实现、以及放在插件本体还是作为第三方扩展，不要在确认前直接提交实现 PR。与桌宠本身关系不大、或实现特别复杂的功能，通常不会进本体，而是通过现有接口由第三方扩展实现。动手前也请先翻一眼 提交记录，确认不是已经修掉的同款问题（有些问题可能已经在 main 上修好了，只是还没发版）。

插件功能

🔌 对外接口（供其他插件调用）

桌宠不只自己玩，也对外开放两条调用通道，让别的插件或脚本能驱动它、读它的状态。

相关文件（HTTP 与 Cordis 各一套）：

兼容性

🪟 桌面模式（可选，脱离浏览器）

插件内建双模式：安装后默认会拉起独立透明置顶小窗——为每只桌面宠物各开一个局部窗口（跟随宠物移动，不铺满屏幕），与浏览器 overlay 严格同行为、功能完全对齐：

🧍 独立运行（完全不打开 DSH）

连 DSH 都不用开：插件的宿主半边跑在伪 ctx 上，由一个本机 HTTP 服务接管路由（路由表仍是插件那一份）。

npm install -g dsh-pet        # 必须 npm 装；dsh plugin add 装进 profile，bin 不在 PATH 上
dsh-pet-standalone            # http://127.0.0.1:3080/dsh-pet-7340/（占用则顺延）
dsh-pet-standalone --check    # 只体检
dsh-pet-standalone --port 3100

npm run build && npm run standalone   # 仓库里（先构建）

⚙️ 余额展示（Balance）

按 eventsRefreshSec.balance（秒）周期拉取当前服务商的余额/用量数据，每次刷新按档位触发一次余额动画，并在宠物头顶弹出联想气泡（随宠物大小等比缩放，10 秒自动消失）：

⚙️ 碎碎念与对话

⚙️ 工作状态联动（Work Status）

pets[i].workStatusEnabled 开启后，宠物跟随 DSH 会话活动切「思考 / 工作 / 整理 / 等待 / 成功 / 出错」六档动画 + 头顶气泡：非终态动画循环播、气泡常驻；成功 / 出错播一遍、气泡 10 秒自动收起。

⚙️ 配置（大小 / 位置 / 多开）

桌宠的大小、位置、多开均可配置，两条途径：

💡 两条途径只是编辑入口不同，最终都是同一份用户配置——配置能力远不止设置页那几个选项：设置页可改大小/位置/边距/显示位置/余额开关/多开，但手动编写配置文件可以任意自由配置（动画池、播放权重、事件动画、刷新周期……），只要格式与包内默认配置 config.jsonc 一致即可，用户配置会整体覆盖对应字段的默认值。

方式一：设置页（推荐）

DSH 设置 → 「桌宠配置」：

方式二：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 } }
]

方式三：手动编辑配置文件（高级，任意自由配置）

用户层配置文件位于 $DSH_HOME/dsh-pet/main-config.jsonc。它和包内默认配置是同一套格式——想改什么直接照着 assets/config.jsonc 的结构写即可，写错的字段/缺失的字段回落默认，无需（也无法）写完整份。设置页「同步」可直接生成这份完整文件（原文复制包内 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.jsonc           ← 主宠物配置（现有，不动）
├─ 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.jsonc 同构的完整配置
{
  "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 }
}

规则（与主宠物严格隔离，绝不混用）：

运行效果

宠物实际运行在 DSH Web 界面中的样子：

效果预览

全部动画（640×360，插件实际播放用的资源）——GIF 预览存放于仓库 dsh-pet/assets/preview/（raw 直链渲染，文件名采用拼音便于跨平台）；完整透明视频见插件包 dsh-pet/assets/webm/（VP9-alpha，唯一发布格式）：

待机 / 转向

移动

小动作

玩耍

吃什么

时节

文字

点击回应

拖拽

余额事件（按余额已用百分比分档，满格 → 告急 → 耗尽）

碎碎念说话动画（碎碎念 / 对话回复触发，随机抽 1 段）

工作状态动画（跟随 DSH 会话事件，六档：思考 / 工作 / 整理 / 等待 / 成功 / 出错）

注：动画为透明背景；GIF 预览中透明部分显示为页面底色，实际 webm 播放为透明。

从零生成你自己的宠物（完整流程）

① 提示词 → 源视频

用 AI 视频生成工具（如可灵、Runway、豆包等，本项目素材即由豆包生成），按 prompts/桌面宠物 10 秒动作提示词.md 的配方，一个动作生成一段 10 秒绿幕视频：

生成结果按动作各存一个 mp4，放入 video/。

源视频获取：为控制仓库体积，video/ 源视频不入 git。Releases 提供打包压缩包，浏览器直接下载即可：
- assets-videos.zip —— 全部源视频压缩包（中文名 mp4，解压后放入 video/）
解压：Expand-Archive assets-videos.zip（Windows）或 unzip assets-videos.zip，把 mp4 放回 video/ 即可运行素材链。

② 源视频 → 透明动画（素材链）

step02（透明视频）有两条路线，按需二选一（默认自动、人人可复现；效果不佳可用 PR 手工抠像覆盖）：

cd scripts
# 路线 A（默认）：自动绿幕抠像（HSV 色相，无需人工）
python watermark_step01.py   # 水印遮罩填充 → step01/
python chroma_step02.py      # 绿幕抠像转透明 → step02/

# 路线 B（可选）：PR 手工抠像覆盖（针对含第三方物品/自动抠像效果不佳的动作）
#   1. 在 PR 里手工抠像，导出带 alpha 的透明 .mov（如 ProRes 4444 with Alpha）
#   2. 放入 pr/，文件名与动作名一致（如 吃白饭.mov）
python pr_import_step02.py   # pr/*.mov → step02/（透明 webm，覆盖该动作自动抠像结果）

# 后续步骤两条路线共用：
python normalize_step03.py   # 归一化 2160×1215 统一站立居中 → step03/
python encode_thumbs.py      # 转码 640×360 播放变体 → step04/

依赖：Python 3 + ffmpeg + numpy + scipy（素材链脚本自动用工作区 .tools/ 下的 ffmpeg）。

本项目全部采用路线 B（全部动作均为 PR 手工抠像）：对"含第三方物品/透明边缘复杂"的动作，自动 HSV 抠像易残边或误抠，PR 手动遮罩更精细。两条路线产出同一级 step02/，后续步骤完全一致；chroma_step02.py 保留为自动化兜底，任何动作仍可一键自动生成。

②.5 🍎 Safari/HEVC 兼容素材（macOS 专用 mov）

插件默认只发布 .webm（VP9-alpha），Safari/WKWebView 不认 webm alpha（黑底），macOS 需要在 GitHub Release 下载官方转码的 HEVC-with-Alpha .mov 素材使用，两步：

  1. 下载：（固定 tag，保持最新；zip 解压后文件名与 webm 一一对应）
  2. 放入：.mov 文件放进 $DSH_HOME/dsh-pet/main-animation/mov/（pet pack 宠物则是 pet/-animation/mov/）

③ 动画 → 插件

# 把 step04 的播放变体同步进插件包（webm 直接 cp）
cp step04/*.webm dsh-pet/assets/webm/   # 播放格式（VP9-alpha）

# 本地安装插件（--profile 填实际在用的那个：dsh web → web；
# 桌面应用（Electron 版）改用应用内「插件管理」，见「快速开始（安装插件）」；
# file: 指向插件目录 dsh-pet/dsh-pet）
dsh plugin --profile web add file:D:/path/to/dsh-pet/dsh-pet
中间产物（step01-04）由脚本生成、不入仓库；video/ 源视频和脚本是成果、入库维护。

🎯 发布（单一 webm 格式）

插件只发布一个 npm 包、一个素材格式（webm）；files 收敛为固定清单（lib / src / assets/webm / runtime/electron-helper / assets/fonts / assets/pic / assets/config.jsonc / scripts/ensure-electron.mjs / cordis.patch.yml，见 prepare.js；浏览器与桌面模式共用，包体最小）：

cd dsh-pet
npm publish --tag latest   # prepack 自动执行构建（完整产物 + 收敛 files），无需手动构建

项目结构

只列代码与发布相关目录；素材链的 video / scripts / step / pr 见 ② 章节（gitignore 的本地目录不列）：

├── README.md  API.md  CORDIS.md  openapi.yaml   # 说明 / HTTP 接口 / Cordis 服务 / OpenAPI 规范
├── prompts/           # ① 动画生成提示词配方（绿幕规范 + 按秒分解）
├── assets/            # 仓库展示用截图
├── tools/             # 开发工具：API 调试页、cordis-probe mock 服务商、DPI 探针
├── .github/workflows/ # CI：Safari/HEVC 转码流水线（macOS runner，手动触发 → 发布 assets-mov Release）
├── dsh-pet/           # ③ 插件（可独立 npm 发布）
│   ├── src/
│   │   ├── host/       # 宿主半侧：配置 / 路由 / 余额 / 工作状态
│   │   ├── client/     # 浏览器半侧：宠物渲染 / 动画链 / 设置页
│   │   ├── shared/     # 双端共用纯逻辑（物理 / 菜单 / 取数）
│   │   └── standalone/ # 独立模式 CLI（不依赖 DSH 直接跑桌宠）
│   ├── lib/            # 构建产物（npm run build 生成，不入库）
│   ├── runtime/        # 桌面模式运行壳（Electron 透明窗）
│   ├── assets/         # webm 动画 / preview GIF / 字体 / 图标 / config.jsonc 默认配置
│   └── scripts/        # 构建、发布与开发脚本
└── LICENSE             # MIT

许可

内容取自仓库 README，未做删改性总结。命令与参数以原文为准。