🖥️ macOS 使用 mov（Safari 透明播放）

macOS 的 Safari/WKWebView 下透明动画需用 .mov 素材，三步：

下载 mov 素材：（保持最新，zip 解压后文件名与 webm 一一对应）
放入素材目录：把 .mov 文件放进 $DSH_HOME/dsh-pet/main-animation/mov/（pet pack 宠物则是 pet/-animation/mov/）
改变量：搜 ANIMATION_EXT，把 .webm 改为 .mov：
- npm 包用户改产物 lib/client.js（桌面端如需再改 runtime/electron-helper/shared-core.js）
- 自构建用户改源码 src/shared/constants.ts 后重新构建

改完重启 dsh web（或重新加载页面）即生效，其余平台不受影响。

⚙️ 配置

配置项	说明
设置页「桌宠配置」	DSH 设置 → 桌宠配置：图形化编辑大小 / 位置 / 边距，支持多开（添加/删除宠物，每只独立配置）；全局开关也在设置页——系统通知（点保存才写入）、碎碎念配图 / 对话配图 / 抛掷锁定（随「保存」一起写入）；保存即时生效，「同步」把项目内置的 `config.jsonc`（原文，含注释与全部高级字段）整份写入用户配置，既是恢复默认又留下一份可直接编辑的完整配置
`pets`（config.jsonc）	默认宠物列表：`[{ "id", "name", "size", "balanceEnabled", "whisperEnabled", "workStatusEnabled", "display", "position": { "corner", "marginX", "marginY" } }]`；`display` 为 web/desktop/both/none（必填，缺失即配置错误）；`whisperEnabled` / `workStatusEnabled` = 碎碎念 / 工作状态气泡开关（默认：true）；多只即多开，`display` 含 desktop 的宠物出现在桌面窗口（与浏览器同屏渲染），首只为「添加宠物」的默认模板
`whisperPrompt`	碎碎念与对话共用的人设系统提示词（条目级：每个种类一份，种类文件顶层可覆盖）：默认「你是主人桌面上的Q版蓝发小女仆……20 字以内」；实际发出的 system = 它 + 一句「你的名字是“”。」
`chatMemoryRounds`	每次对话请求携带的最近历史轮数（默认 5；1 轮 = 1 问 1 答；0 = 不带历史）：`memory.json` 全存不删，此值只决定截取多少进上下文。全局默认（设置页「AI 模型与对话上下文」区一个数字输入框，改一次对所有宠物生效，含 pet pack；种类文件顶层可覆盖）
`whisperModel` / `chatModel`	碎碎念 / 对话各自用哪个服务商 + 模型（全局默认：设置页改一次对所有宠物生效，含 pet pack；种类文件顶层可覆盖。设置页「AI 模型」每项一个下拉框，与 DSH 对话框右下角的模型选择器同款：搜索 + 按服务商分组的清单，选项同源）。`provider` 与 `model` 都留空 = 跟随当前对话的模型（默认）；只填一半即配置错误。填了但调用失败（凭据被删 / 模型下架）会自动回落到当前对话的模型重试一次
`whisperImageEnabled`（0.2.9）	碎碎念配图开关（布尔，默认开；全局默认，pet pack 可在种类文件里覆盖）：开启后每次碎碎念从 `memes` 池随机抽 1 张，连同那句话一起显示。token：碎碎念本来就每次生成都要调一次模型，配图只多约 100 字符（≈60 token），增量可忽略
`chatImageEnabled`（0.2.9）	对话配图开关（布尔，默认开；全局默认，pet pack 可在种类文件里覆盖）：开启后把整张 `memes` 清单交给模型按语境选 1 张（可不选；选了池外名称视为没选，标记会原样留在正文里）。token：每条消息约 1.1k 字符（≈650 token），随图片数量线性增长
`chatImageLimit`	对话配图张数上限（非负整数，默认 10，0 = 不限制；全局默认，pet pack 可在种类文件里覆盖）：对话时只把 `memes` 清单的前 N 张（= 配置里写在前面的那 N 条，想优先发哪几张就往前写）交给模型选图。原因：整张清单是每条消息都要附的，token 随张数线性增长（27 张约 1.1k 字符 ≈ 650 token），限制成前 N 张即可给配图开销封顶。设置页「AI 模型与对话上下文」区可改。只影响对话选图——碎碎念只带抽中的那一张
`memes`（0.2.9）	表情包映射：键 = 表情包目录里的 `.png` 文件名（不含扩展名），值 = 该图内容的简要描述（模型据此选图/配文）。图片按素材归属查找（种类独占 `pet/-memes/` → 用户目录 `memes/` → 包内 `assets/memes/`，与动画同规矩）；配置里写了但哪个目录都没有该文件的条目自动失效（删图不必同步改配置）；删掉某个键即停用该图
`notificationsEnabled`	系统通知总开关（布尔，默认开）：对话完成 / 生成失败 / 输出截断 / 权限申请 / 用户选择，在窗口失焦时弹系统级通知（桌面右下角）
`physics`（0.2.5）	拖拽抛掷物理参数（全局默认，所有宠物共用；种类文件顶层可覆盖）：`gravity` 重力 / `restitution` 碰壁恢复系数（0~1）/ `groundFriction` 地面摩擦 / `ceilingBounce` 顶部反弹 / `throwPower` 总力度 / `petCollision` 多宠物碰撞开关；缺省取内置默认（1400 / 0.78 / 2.5 / true / 1.0 / false）；`gravity=0` 为无重力，`petCollision=true` 开启多宠物碰撞

说明：插件安装即用，配置均为可选；设置页保存的用户覆盖写入 $DSH_HOME/dsh-pet/main-config.jsonc（用户层，优先于包内默认）。

📄 高级自定义（直接编辑配置文件）

用户数据统一收敛在 $DSH_HOME/dsh-pet/：

层	路径	作用
默认配置（只读）	包内 `assets/config.jsonc`	完整结构参考：宠物列表 / 动画池（idle/turn/drag/clicks/moves/categories）/ 播放权重
用户配置	`$DSH_HOME/dsh-pet/main-config.jsonc`	覆盖片段：可整体覆盖 `pets` / `animations` / `animationWeights`，缺省字段回落默认
对话记忆（自动生成）	`$DSH_HOME/dsh-pet/memory.json`	对话历史（user/assistant 正文，全存不删；每次请求只取最近 `chatMemoryRounds` 轮）。删掉即清空记忆
用户动画（可选）	`$DSH_HOME/dsh-pet/main-animation/`	放入 `.webm`（VP9-Alpha）即可作为动画播放，优先于包内素材（放 `main-animation/webm/` 子目录）
用户表情包（可选）	`$DSH_HOME/dsh-pet/memes/`	放入 `.png` 即可作为配图，优先于包内素材；键（文件名去扩展名）与描述仍需写进配置的 `memes`

设置页底部「高级配置」显示这些路径；「卸载与存储」列出插件的全部存储位置与卸载命令
自定义动画：把 xxx.webm 放进 main-animation/webm/，在动画池/分类里写 "xxx"，刷新页面即可（无需重启 DSH）
格式：.webm 需 VP9 Alpha 编码（Chrome/Edge/Firefox），与包内素材同规范，普通编码会有黑底
修改用户配置后同样刷新页面生效
动画名请对照默认配置填写，避免引用不存在的动画
表情包图片按素材归属查找（与动画同一套）：pet/-memes/（种类独占，见下节）→ 用户目录 $DSH_HOME/dsh-pet/memes/ → 包内 assets/memes/。往用户目录放 xxx.png，再在 config 的 memes 里写 "xxx": "这张图的描述"，刷新页面即可用（加图/换图不必再改包内目录，也就不会被 add/更新覆盖）；只想去掉某张图，删 config 里对应的键即可（不用动图片文件）

🐾 额外宠物（pet pack）——添加新「种类」

默认只能调整主宠物（config.jsonc / main-config.jsonc 的 pets）。要添加全新种类的宠物（独立动画池 + 自己的素材），在用户数据根下建 pet/ 目录：

$DSH_HOME/dsh-pet/pet/
├─ pig-config.json        ← 额外宠物 pig 的配置（命名词干 = 种类名，实例 id 任意）
├─ pig-animation/         ← pig 自己的动画素材（直接平铺 .webm，仿 main-animation）
│  ├─ 待机.webm
│  └─ 打滚.webm
└─ pig-memes/             ← 可选：pig 自己的表情包（直接平铺 .png，仿用户 memes/）
   └─ 吃白饭的大肥鱼.png

每只额外宠物 = 一个 -config.json（配置）+ 一个 -animation/ 目录（素材），同前缀配对，扫描 pet/ 自动发现（浏览器与桌面同时生效，无需重启）；-memes/ 目录可选，有则独占该种类的配图（见下节）。

配置文件与 main-config.jsonc / config.jsonc 完全同构——直接复制一份 main 配置、换成自己的动画池，就是一只新宠物。一个 -config.json 定义一个「种类」（动画池 + 素材目录），pets 数组可放该种类的任意多只实例（每只独立 size/位置，共享动画池与素材）：

// pet/pig-config.json —— 与 main-config.jsonc 同构的完整配置；animations / animationWeights 必填（不回落全局）
{
  "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 或包内素材。配图同理：pet/-memes/ 存在时只查它（/pic/memes//.png 查不到即 404），绝不回落到用户 memes/ 或包内 assets/memes/
动画池不回落全局：animations / animationWeights 是该种类的（结构校验与主配置同一套规则）
pets 数组非空、每只字段（id/size/balanceEnabled/display/position）完整合法、数组内 id 唯一——id 随意写、数量随意，与主配置完全一致
用户层的「全局默认」会生效：physics / confineToScreen / whisperImageEnabled / chatImageEnabled / chatImageLimit / chatMemoryRounds / whisperModel / chatModel / eventsRefreshSec 这 9 个是用户级成本 / 偏好 / 环境 / 节奏参数——用户在设置页（写进 main-config.jsonc）改一次就对该种类生效；种类文件顶层写了则用自己那份
所有顶层字段都是整段替换：写了就整段用自己的，缺的子键不会从内置默认补回来（消费端各自兜底：余额周期读不到按 1800、碎碎念按 300）
notificationsEnabled 是全局（只读 main 条目那份）：种类文件里写了不生效（不报错）
eventsRefreshSec 内部两个键的消费端不同：.whisper 按宠物所属条目读（种类文件顶层可覆盖）；.balance 只读 main 条目（余额是一个账号一份数据，host 只有一个刷新定时器）
配置非法 / 缺少 -animation/ 目录 / 实例 id 与主宠物冲突 → 加载时显式报错并跳过该宠物（不影响其他宠物）
设置页不列出文件宠物（改文件即生效，刷新可见）；设置页保存/同步不会把它们写进 main-config.jsonc
添加/修改/删除 → 刷新页面（浏览器）或重启 Helper（桌面）生效

📄 高级自定义（直接编辑配置文件）

用户数据统一收敛在 $DSH_HOME/dsh-pet/：

层	路径	作用
默认配置（只读）	包内 `assets/config.jsonc`	完整结构参考：宠物列表 / 动画池（idle/turn/drag/clicks/moves/categories）/ 播放权重
用户配置	`$DSH_HOME/dsh-pet/main-config.jsonc`	覆盖片段：可整体覆盖 `pets` / `animations` / `animationWeights`，缺省字段回落默认
对话记忆（自动生成）	`$DSH_HOME/dsh-pet/memory.json`	对话历史（user/assistant 正文，全存不删；每次请求只取最近 `chatMemoryRounds` 轮）。删掉即清空记忆
用户动画（可选）	`$DSH_HOME/dsh-pet/main-animation/`	放入 `.webm`（VP9-Alpha）即可作为动画播放，优先于包内素材（放 `main-animation/webm/` 子目录）
用户表情包（可选）	`$DSH_HOME/dsh-pet/memes/`	放入 `.png` 即可作为配图，优先于包内素材；键（文件名去扩展名）与描述仍需写进配置的 `memes`

设置页底部「高级配置」显示这些路径；「卸载与存储」列出插件的全部存储位置与卸载命令
自定义动画：把 xxx.webm 放进 main-animation/webm/，在动画池/分类里写 "xxx"，刷新页面即可（无需重启 DSH）
格式：.webm 需 VP9 Alpha 编码（Chrome/Edge/Firefox），与包内素材同规范，普通编码会有黑底
修改用户配置后同样刷新页面生效
动画名请对照默认配置填写，避免引用不存在的动画
表情包图片按素材归属查找（与动画同一套）：pet/-memes/（种类独占，见下节）→ 用户目录 $DSH_HOME/dsh-pet/memes/ → 包内 assets/memes/。往用户目录放 xxx.png，再在 config 的 memes 里写 "xxx": "这张图的描述"，刷新页面即可用（加图/换图不必再改包内目录，也就不会被 add/更新覆盖）；只想去掉某张图，删 config 里对应的键即可（不用动图片文件）

dsh-pet-mobile

Install

README

🖥️ macOS 使用 mov（Safari 透明播放）

⚙️ 配置

📄 高级自定义（直接编辑配置文件）

🐾 额外宠物（pet pack）——添加新「种类」

📄 高级自定义（直接编辑配置文件）