前言¶

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