前言¶

DSH 的理念是「一切皆插件」。当需要在 DSH Web GUI 中增加一个可交互角色时，可以把显示、交互和素材管理收敛到插件里，而不是单独维护一套静态资源。

awesome-dsh-pet 面向这个场景：它在 DSH Web GUI 内显示桌面宠物，并在页面右下角展示，同时允许继续添加自定义角色。

社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，不应把它理解为官方应用商店。

这是什么¶

awesome-dsh-pet 是 DSH Web GUI 内的可扩展多角色桌面宠物插件，由 Awesome-AI-Pedia 维护，许可证为 MIT。

它解决的是 DSH Web 页面内的轻量角色展示与交互：显示宠物、投喂、玩耍、切换角色，并支持自定义角色素材。

GitHub 仓库：

https://github.com/Awesome-AI-Pedia/Awesome-DSH-Pet

核心功能¶

• 在 DSH Web GUI 内显示桌面宠物，并在页面右下角展示。
• 提供 jingyu-zongcai（鲸鱼总裁）和 lulu-capybara（噜噜）两个角色。
• 菜单里可以投喂、玩耍、切换角色。
• 支持通过 settings.yaml 的 awesome-dsh-pet section 配置 enabled、size、opacity、walk.enabled、sleepAfterMs。
• 支持快速添加自定义宠物：放素材、改 manifest、跑门禁。
• 支持 Codex atlas 8×9 spritesheet 和单行动作 sheet 两种素材形式。
• 要求 15 个状态：idle / working / celebrate / error / disappointed / joy / eat / play / drag / walk / sleep / wake / welcome / think / wait。

安装与启用¶

插件以当前 dsh 进程权限运行，安装前应检查源码、脚本、素材和许可证。许可证为 MIT。

下面使用本地路径安装或更新插件：

dsh plugin --profile web add /Users/icourt/Desktop/DSH-plugin/Awesome-DSH-Pet

安装或更新后重启 web。

基本配置¶

在 settings.yaml 中使用 awesome-dsh-pet section：

awesome-dsh-pet:
  enabled: true
  size: 110
  opacity: 1
  walk:
    enabled: true
  sleepAfterMs: 60000

这里的配置项包括：

• enabled：是否启用。
• size：尺寸。
• opacity：透明度。
• walk.enabled：是否启用行走。
• sleepAfterMs：睡眠相关时间参数。

添加自定义角色¶

下面以角色 id my-cat 为例，整体流程是：放素材、改 manifest、跑门禁。

1、确定角色 id

角色 id 只允许 [a-z0-9-]，因为会当 URL 路径用。示例使用 my-cat。

2、放素材

将素材放到角色目录，例如：

lib/assets/characters/my-cat/spritesheet.webp

素材形式支持两种：

• Codex atlas 8×9 spritesheet
• 单行动作 sheet

3、改 manifest

在 lib/assets/manifest.json 的 characters 下增加角色 key，例如：

my-cat

如果希望新角色成为默认角色，把顶层 default 从 jingyu-zongcai 改成新角色 id。

4、跑门禁

先运行门禁和测试：

node scripts/gates/verify-assets.mjs
node --test 'tests/*.test.mjs'

如果修改了前端源码，需要重新构建：

node scripts/build-client.mjs

5、重启

安装或更新后重启 web。

素材与状态约束¶

自定义角色必须提供全部 15 个状态：

idle / working / celebrate / error / disappointed / joy / eat / play / drag / walk / sleep / wake / welcome / think / wait

一个都不能少。

常用约束如下：

• sheet 相对 lib/assets/characters/<id>/，允许 .png / .webp / .svg / .jpg / .jpeg / .gif / .json。
• frames 必须为正整数。
• PNG 多帧图必须满足宽度 = frames × 高度。
• atlas 需满足 row < rows。
• playback 可选 loop / pingpong / once / blink；pingpong 和 blink 要求至少 2 帧，其他至少 1 帧。
• motion 可选 bob / wiggle / squash / shake / sigh / hop / tilt / float / wave，且要求 frames === 1；error 是唯一例外，可以多帧并叠加运动。

开发与维护¶

lib/client.js 是构建产物。修改 lib/client/index.mjs 后，运行：

node scripts/build-client.mjs

重新生成前端产物。

适用场景与注意¶

这个插件适合希望给 DSH Web GUI 增加轻量桌面宠物、自定义角色或状态素材的开发者。

使用时需要注意：

• 插件以当前 dsh 进程权限运行。
• 安装前检查源码、脚本、素材和许可证。
• 自定义素材需要满足 15 个状态、帧数、playback 和 motion 等约束。
• 许可证为 MIT。

GitHub 仓库：

https://github.com/Awesome-AI-Pedia/Awesome-DSH-Pet