dsh-web-ui/packages/dsh-pet

Name: dsh-web-ui/packages/dsh-pet
Availability: InStock
Rating: 5 (5125 reviews)
Author: zhu1090093659

一句话定位

为 dsh web GUI 增加一只常驻右下角的桌面宠物伴侣：模型会话活动驱动它切换动画，你可以摸头喂食攒亲密度，并能通过投放 pet.json 目录的方式无改代码接入任何自定义精灵或 Live2D 宠物。

核心能力

在右下角挂一个浮窗精灵，模型处于等待 / 思考 / 调工具 / 整理 / 完成 / 失败六个相位时切换为不同动画；完成会跳一下，失败静一静后回到待机
摸头（10 秒冷却，+1 好感）和喂小鱼干（30 秒冷却，+5 好感，-1 库存）两种互动；亲密度从「幼鲸」到「鲸生共渡」共 9 级，攒到顶也不会卡住
小鱼干是稀缺经济：每完成 30 轮会话 +1 条，每过 5 小时 +1 条，库存上限 20，比原版 Codex 节奏慢 10 倍
内置两只鲸鱼娘（原版 + 精致版），并通过「注册表」扫描 $DSH_HOME/pets/ 用户目录、~/.codex/pets/ legacy 目录、以及嵌入应用传入的额外条目，同 id 自动覆盖
支持 sprite2d 精灵图集（9 行 × 8 列默认契约）与 Live2D 模型（v2 manifest）；Live2D 走 PixiJS 按需加载的 MIT vendor bundle
悬浮面板提供改名、投喂、隐藏+召唤、按住拖动改位置；状态气泡按场景轮换词库，支持 voice.json 替换全部文案与按钮文字

技术实现

语言: TypeScript（带 JSX）+ Node.js（host 半区）+ React 18（browser 半区）
关键依赖: react / react-dom ^18.2.0（peer，宿主运行时注入）、clsx（类名合并）、schemastery（DSH 配置 schema 校验）、Live2D 路径按需加载的 pixi.js + untitled-pixi-live2d-engine MIT vendor bundle
架构模式: 双半区 cordis bundle：src/index.ts 是 host 半区（export const name='pet'、cordis Service pet.*、注册设置分区、挂载 /api/pet/* 与 /pet/<id>/* 路由），src/client/index.ts 是 browser 半区（createRoot → document.body 全局挂载、每 2 秒轮询 host、visibilitychange 唤醒后立即拉取、ctx.locale.register 注册中英字典、ctx.slots.inject('settings.section', …) 注册顶级设置卡）
入口文件: packages/dsh-pet/src/index.ts（host 入口）、packages/dsh-pet/src/client/index.ts（browser 入口）；cordis bundle 声明在 packages/dsh-pet/cordis.patch.yml:1-10（插入 id pet），浏览器依赖在 packages/dsh-pet/package.json:45-58（注入 4 个官方 @deepseek-ai/dsh-client-* 模块 + platform: web）

适用场景

想要让 DSH Web GUI 在长时间跑模型任务时不那么单调、同时还有「养一只小宠物」陪伴感的用户：模型思考时它在脚下游动，完成时它跳一下庆祝；
想为自己作品或社区主题做一只「招牌精灵 / 看板娘」放进 DSH 的用户：把 pet.json + 图集丢进 $DSH_HOME/pets/ 就能上线，免改插件代码；
想给宠物换一套「人设台词」（比如让某只猫喊别的口号）的用户：在宠物目录里放一份 voice.json 即可逐槽覆盖。

前置依赖与兼容性

依赖	最低版本	说明
DSH 宿主	`0.1.0-rc.6+` 推荐	包未在 dsh.engines 声明最低版本；devDependencies 统一锁到 `@deepseek-ai/dsh-* ^0.1.0-rc.8`，已知宿主 CLI 为 0.1.0-rc.7/rc.8
Node.js	`^22.19.0` 或 `>=24.0.0`	package.json `engines.node`
平台	跨平台	host 半区是 Node.js，client 半区是浏览器，无 OS 限制
原生模块	无	运行时依赖只有 clsx / schemastery；Live2D 用的 PixiJS 与 Live2D 引擎是 MIT vendor bundle，Cubism Core 由用户自备
React	`^18.2.0`	peerDependency，由宿主注入

安装方式

dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-pet

配置项

配置	类型	说明	默认值
visible	开关	是否在屏幕上显示宠物	true
size	数字（32–512，px）	宠物显示尺寸（精灵单格高度）	160
right	数字（0–10000，px）	距视口右边界的水平偏移	24
bottom	数字（0–10000，px）	距视口底边的垂直偏移	120
petId	字符串	当前选中的宠物 id（在注册表里选）	内置默认鲸鱼娘
enabled	开关	插件总开关：关闭时宠物和 API 一起停用	true
decorationEnabled	开关	是否在状态气泡前显示小鲸鱼装饰	true
互动冷却（摸头）	内部常量（affinity.petCooldownMs）	两次摸头之间的最小间隔，源码可调	10000 ms
互动冷却（喂食）	内部常量（affinity.feedCooldownMs）	两次喂食之间的最小间隔，源码可调	30000 ms
小鱼干上限（treats.maxTreats）	数字	库存上限	20
好感上限（affinity.AFFINITY_MAX）	数字	好感点累计上限	999999999

说明：「互动冷却 / 小鱼干上限 / 好感上限」默认在源码 affinity.ts / treats.ts 内，如要调整需通过 host 配置传入 affinity / treats 参数；普通用户用默认即可。

常见问题

Q: 安装之后宠物不显示怎么办？

A: 安装后必须重启 dsh web，注册表只在 host 启动时构建一次；浏览器半区会通过 /api/pet/pets 拿列表，确认你看到两个内置选项。如果只是空白，先看浏览器控制台是否有 pet.state transport error，多出现于浏览器半区被禁用时——到设置 → 宠物把「enabled」打开即可。packages/dsh-pet/src/client/index.ts:114-119、165-184 / packages/dsh-pet/README.zh.md:271-272。

Q: 我换了一台电脑，好感度和小鱼干会带过去吗？

A: 数据写在 $DSH_HOME/pet.json（默认 ~/.dsh/pet.json），不在云端。手动复制这个文件到新机器的相同路径即可恢复所有进度（亲密度、命名、库存、位置、自选宠物 id）。packages/dsh-pet/src/persist.ts:77-167。

Q: 自定义的 Live2D 模型为什么不显示？

A: 大概率是缺 Cubism Core。Live2D 专有许可禁止再分发，本插件无法替你下载它；从 Live2D 官方拿到 live2dcubismcore.min.js 放到 $DSH_HOME/pets/.runtime/ 下，然后重启 dsh web 即可。如果路径正确仍然空白，再看图集路径与 live2d.model 是否一致，以及模型目录是否在 $DSH_HOME/pets/ 下。packages/dsh-pet/README.zh.md:127-134。

Q: 多会话同时跑，宠物会不会卡或者气泡一长串？

A: 不会。精灵动画跟最近一次有意义的活动走；多个顶层会话每个各自一个气泡，最多同屏 12 个，多出的合并到主气泡右上角的 +N 角标，悬停展开；子代理不占独立气泡，避免 N 个对话叠出 N+ 子代理数的气泡堆。packages/dsh-pet/src/service.ts:439-458、559-571。

Q: 我不喜欢它说话的语气，怎么改？

A: 两种粒度。最简的是把鼠标停到悬浮面板按「改名」，只是给当前宠物换个称呼；想要整套「换话术」，在宠物目录下放一份 voice.json（或在 $DSH_HOME/pets/.voice.json 写全局覆盖），按 voicePackVersion: 1 的格式覆盖 status / tools / whispers / panel 四个区段；合并优先级宠物自带 > 全局 > 内置，坏包只警告不拒载。packages/dsh-pet/README.zh.md:91-123。

Q: 怎么彻底关掉它，不卸载插件？

A: 进设置 → 宠物，关闭「enabled」即可，host 端 API 与浏览器端都会同步卸载（隐藏后右下角会出现一个「召唤名字」按钮再次启用）。想从设置中彻底拿掉，包括插件自身，使用 dsh plugin --profile web remove github:zhu1090093659/dsh-web-ui/packages/dsh-pet，$DSH_HOME/pets/ 与 pet.json 不会被删，下次重装可接上。packages/dsh-pet/src/index.ts:177-191 / packages/dsh-pet/src/client/index.ts:312-315。

Q: 局域网里别人能拿到我的宠物图集或状态吗？

A: 默认不能。所有 /api/pet/* 与 /pet/<id>/* 都套 loopback 围栏（127.0.0.1 + Host 头 + sec-fetch-site），LAN 邻居直接 403。同时安装了 dsh-remote-web-ui 的情况下，已配对设备的 cookie 才可作为额外放行。资产路由还做 realpath 越界检测（symlink 逃跑 403）与大小上限（图片 20 MB、Live2D 模型 32 MB、manifest 64 KB，超限 413）。packages/dsh-pet/README.zh.md:289-295 / packages/dsh-pet/src/routes.ts:42-49、72-82。

上手难度

入门 — 一行命令安装、零额外配置即可见到内置鲸鱼娘；想自带的玩家只需按 README 给的 pet.json 模板在 $DSH_HOME/pets/ 下放图集与描述文件，不涉及任何 TS/JS 代码。

已知问题与限制

Live2D Cubism Core 由 Live2D 专有许可限制，本插件不内置也不下载；缺文件时 Live2D 宠物位置显示安装指引卡，sprite2d 宠物不受影响（packages/dsh-pet/README.zh.md:127-134 / packages/dsh-pet/src/routes.ts:328-345）
资产路由硬上限：图集与 PNG/WebP/GIF 图像 20 MB、Live2D 模型闭包文件 32 MB、manifest 64 KB；超出返回 413（packages/dsh-pet/src/routes.ts:42-49）
用户编写的 voice.json / decoration.json / .voice.json 扫描时按 64 KB 限额与「必须是普通文件」过滤；超限或设备/FIFO 静默跳过（packages/dsh-pet/src/registry.ts:629-661）
pet.json 损坏或不存在时静默回退到默认值，不会报错（packages/dsh-pet/src/persist.ts:156-158）
注册表完全扫描不到任何可用条目时插件启动直接抛错 [dsh-pet] no valid pet manifests found（packages/dsh-pet/src/service.ts:246-248）
Live2D 模型必须放在宠物目录下且其引用闭包（moc、贴图、动作、物理、姿态、表情）需齐全；模型 .model3.json 引用了穿越/绝对/URL 形态的文件会直接拒载并给诊断（packages/dsh-pet/src/registry.ts:500-535）
仅依赖旧 ${CODEX_HOME:-~/.codex}/pets/ 的 hatch-pet legacy 来源仍可识别但已是历史兼容，新宠物请直接进 $DSH_HOME/pets/（packages/dsh-pet/src/registry.ts:813-820）
第三方装饰（喷水鲸鱼）素材派生自 DeepSeek wordmark（MIT），详见 packages/dsh-pet/THIRD_PARTY_NOTICES.md

Install