---

特性

• 🏠 内嵌 3080 页面：通过官方 webServer.tapIndex 注入浮层，桌宠与 dsh 同源同页、一起出现一起消失
• 🎬 真实事件驱动：订阅根 context 的 session/event，按 turn/start、tool/call、turn/end 等切换待机 / 思考 / 执行 / 等待 / 完成 / 失败动画
• 🖼️ 精灵图即配置：网格布局与状态→行映射由配置声明（config.sprite 或同名 .json 侧车文件），渲染器运行时拉取，换图无需改源码
• ⚙️ 设置页管理：dsh 设置页「桌宠」分区可视化配置——上传/选择精灵图、网格、状态映射、缩放、动画速度、待机延迟、显隐
• ⚡ 改动实时生效：配置经 SSE config 事件热推给渲染器，缩放、动画速度、待机延迟调整即时生效，无需刷新或重启
• 💾 自动持久化：所有设置保存到 pet/user-config.json，刷新后自动恢复，优先级高于 cordis.patch.yml
• 🪟 多形态呈现：除内嵌浮层外，还提供独立弹窗页、Chrome app 无边框窗、pywebview 透明窗（可打包 .exe）、Electron 四种用法

安装

环境要求

• DeepSeek Harness（dsh CLI）已安装并运行过 Web profile
• Node.js ≥ 18

安装步骤

# 1. 把本地插件注册到 web profile（bundle 自动生效，无需手动改 dsh 文件）：
dsh plugin --profile web add <本目录路径>

# 2. 启动 dsh（会一并启动 Web GUI）：
dsh --profile web

启动后打开 dsh 的 Web 地址（终端会打印，通常 http://127.0.0.1:3080/），右下角出现桌宠；管理入口在 设置 → 桌宠。

卸载

dsh plugin --profile web remove dsh-pet
#    用户数据（pet/user-config.json 与 pet/uploads/）会保留，如需彻底清除请手动删除。

纯客户端改动（精灵图、缩放、动画速度等设置）只需强制刷新浏览器；宿主侧改动（index.js 的路由/逻辑）需要重启 dsh。

界面说明

管理面板位于 dsh 设置页的「桌宠」分区（settings.section 槽），各区域功能如下：

区域	说明
启用	桌宠显示开关，即时生效（关闭后浮层立即隐藏）
精灵图	预览当前图；「上传图片」从本地选任意精灵图（webp / png / gif / jpg / svg），自动存入 pet/uploads/；已上传图可删除；「默认（哆啦A梦）」固定切回内置图
网格	列数 / 行数。精灵图按 列 × 行 等分，每行是一种状态动画
状态 → 行映射	为 idle / thinking / working / waiting / failed / completed 各指定精灵图行号（0 起）
外观与节奏	缩放（0.5×–3×）、动画速度（0.25×–4× 全局倍速）、待机延迟（ms）
操作	保存（写入 pet/user-config.json 并经 SSE 推送）、恢复默认

数据存储

• 配置：pet/user-config.json（enabled、scale、fpsScale、idleMs、spriteFile、sprite 网格/状态映射等）
• 上传图片：pet/uploads/ 目录（上传的文件，配置只保存文件名，不把大图写进 JSON）
• 两者均为运行时用户数据，已被 .gitignore 忽略，不进版本库；如需团队共享默认，请改用 cordis.patch.yml 配置

工作原理

• 注入：插件拿到 dsh 自带的 webServer 服务，用 tapIndex 把 <script type="module" src="/dsh-pet/overlay.js"> 写入 3080 页面；精灵图、状态、SSE 全部挂在同源 /dsh-pet/* 路由下
• 状态机：订阅根 context 的 session/event，按 event.type 映射桌宠状态并播放对应动画行（见下表）
• 布局下发：/dsh-pet/sprite-config 返回网格与状态映射；单元格像素由渲染器按图片实际尺寸 ÷ cols ÷ rows 自动计算，不同分辨率的精灵图都能正确切片
• 热更新：设置面板的改动经 POST /config 持久化并广播到 SSE 流，渲染器收到 config 事件后即时应用（精灵图文件变化才重载图片，避免动画闪烁）

状态映射

dsh 事件（event.type）	桌宠状态	动画行	说明
turn/start	thinking	第 8 行	一个回合开始，模型在思考
step/start	working	第 1 行	进入执行步骤
assistant/message、assistant/chunk	thinking	第 8 行	模型生成中
tool/call	working	第 1 行	调用工具（气泡显示工具名）
tool/result	working	第 1 行	处理工具结果
turn/end（reason.kind 为 completed）	completed	第 4 行	任务完成，停留 idleMs 后回到待机
turn/end（reason.kind 为 error/aborted/interrupted/blocked）	failed	第 5 行	执行中断

dsh 的 agent 状态经会话事件日志（session.append(...)）记录，并统一以根 context 的 session/event 暴露给 host 插件；agent/error、agent/status 发在 agent 私有 dispatch 上，不在 session/event 中，因此本插件以 turn/end 的 reason.kind 作为失败判据。waiting 状态目前仅由演示模式手动触发。

配置

在 profile 的 cordis.patch.yml 中覆盖默认配置（cordis.patch.yml 必须是顶层 YAML 数组，每个元素是一个 patch entry）：

- insert:
  - id: dsh-pet
    name: dsh-pet
    config:
      idleMs: 3000
      scale: 1
      fpsScale: 1
      injectOverlay: true
      overlayRoute: /dsh-pet

配置项	类型	默认值	说明
idleMs	number	3000	完成/出错后多久恢复待机（ms，500–600000）
scale	number	1	浮层尺寸倍数（0.5–3）
fpsScale	number	1	动画播放速度倍速（0.25–4，作用于全部状态的全局乘数，不覆盖各行 rowFps 的相对节奏）
injectOverlay	boolean	true	是否把浮层注入 3080 页面；设为 false 则只提供 /dsh-pet/ 弹窗页
overlayRoute	string	/dsh-pet	同源路由前缀，所有资源挂在其下
enabled	boolean	true	是否显示桌宠；也可在设置面板里开关（最终写入 pet/user-config.json）
spriteFile	string	doraemonsprite.webp	精灵图文件名（相对于 pet/ 目录）
sprite	object	见下方	精灵图网格与状态映射配置（支持部分覆盖，深合并默认值）

sprite 配置结构：

sprite:
  cols: 8          # 网格列数（每行帧数上限）
  rows: 9          # 网格行数（动画状态数）
  fps: 8           # 默认帧率（可被 rowFps 逐行覆盖）
  rowFrames: { 0: 6, 1: 8 }   # 可选：逐行帧数（缺省用 cols）
  rowFps:    { 8: 12 }        # 可选：逐行帧率（缺省用 fps）
  stateRows:                  # dsh 状态 -> 网格行号
    idle: 0
    thinking: 8
    working: 1
    waiting: 3
    failed: 5
    completed: 4

默认精灵图（doraemonsprite.webp，9 行 × 8 列）的动画布局：

行号	dsh 状态	默认帧数	默认帧率	含义
0	idle	6	6	待机
1	working	8	12	向右奔跑
2	（未映射）	8	12	向左奔跑
3	waiting	4	5	挥手
4	completed	5	8	开心
5	failed	9	10	晕倒/失败
6	（未映射）	6	10	跳跃
7	（未映射）	7	9	大笑
8	thinking	6	8	思考

独立窗口模式

除内嵌浮层外，桌宠渲染器也提供全屏透明页，适合做成"桌面宠物"独立窗口：

http://127.0.0.1:3080/dsh-pet/

# Chrome 应用模式（无边框窗口）
chrome --app="http://127.0.0.1:3080/dsh-pet/" --window-size=256x320

# pywebview + pyinstaller 打包成单文件 .exe（推荐离线）
cd dsh-pet/pet
pip install pywebview
python launch.py                       # 本地预览
pyinstaller --onefile --windowed --add-data "doraemonsprite.webp;." --add-data "pet.html;." launch.py

未连接 dsh 时，独立页会自动循环播放各状态动画（演示模式），按 D 键可手动切换。

文件结构

dsh-pet/
├── index.js              # Cordis 插件入口（接入 webServer：注入浮层 + 同源路由 + SSE）
├── cordis.patch.yml      # dsh bundle 声明（顶层 YAML 数组）
├── package.json          # npm 包与 dsh client/bundle 配置（exports 需导出 ./package.json）
├── LICENSE               # MIT 许可证
├── README.md             # 本文件（中文）
├── README.en.md          # 英文版 README
├── lib/
│   └── client.js         # 客户端束：把管理面板挂入 dsh 设置页 settings.section 槽
└── pet/
    ├── doraemonsprite.webp   # 默认精灵图源文件（9 行 × 8 列）
    ├── pet.html              # 全页桌宠封装（thin wrapper，独立窗口模式）
    ├── pet-render.js         # 共享渲染逻辑（浮层与全页复用，含 SSE config 热更新）
    ├── overlay.js            # 浮层入口（被 3080 页面注入加载，仅精灵本体）
    ├── settings-panel.js     # 管理面板（原生 JS，设置页挂载）
    ├── launch.py             # pywebview 透明窗体启动器（可选）
    ├── uploads/              # 用户上传的精灵图（运行时生成，已 gitignore）
    └── user-config.json      # 管理面板的持久化配置（运行时生成，已 gitignore）

开发

node --check index.js pet/pet-render.js pet/settings-panel.js pet/overlay.js   # 语法检查
dsh --profile web                                                              # 重启后生效

宿主侧改动（index.js）需要重启 dsh；设置页 client 条目依赖 package.json 的 dsh.client.inject（真实模块 ID）与 exports["./package.json"]——缺少任一都会导致 client 条目被启动清单静默丢弃、设置页无「桌宠」区块。

安全说明

• 所有数据仅存储在本机（pet/ 目录与 dsh profile），不上传任何内容
• 精灵图上传接口只接受图片格式，文件名白名单校验防路径穿越
• 不采集任何密钥或凭据；所有资源监听在 dsh 自身服务上，仅本地可访问

🤖 AI 声明

本项目使用 DeepSeek Harness 开发。

许可证

MIT © Levi5