dsh-pet

给 DSH (DeepSeek Harness) 用的 Windows 桌面宠物插件。

复用 Codex 兼容宠物包（pet.json + spritesheet.webp），在桌面上显示透明置顶的分层窗口；会话运行、授权等待、完成后会在宠物头顶出气泡。宠物只出现在桌面，不会注入 DSH 网页。

• 设置卡片：设置 → 插件 → 桌面宠物（开关、缩放、帧间隔、默认宠物）
• Codex 宠物零转换：默认读 ~/.codex/pets 和 $DSH_HOME/pets
• 会话气泡：多个运行中会话可叠放，悬停展开；点击定位到已打开的 DSH 标签页
• 授权 / 完成提醒：只在宠物上提示，不弹 Windows 系统通知

目录

• 前置要求
• 安装
• 配置页
• 配置项
• 宠物格式
• 桌面交互
• HTTP 路由
• 卸载
• 文件结构
• 开发注意

前置要求

1. Windows 10/11，已安装 DSH，并用 dsh web 打开 Web GUI
2. 本机有 Codex 兼容宠物，放在 %USERPROFILE%\.codex\pets\<pet-id>\
3. 桌面悬浮窗需要 Windows PowerShell 5.1（自带）。desktop/dsh-pet-desktop.ps1 必须保持 UTF-8 带 BOM，否则 param() 解析失败、开关打开也看不到窗口

安装

推荐：用 DSH 插件命令（会装依赖）

在插件目录外执行：

dsh plugin --profile web add %CD%

本地路径也可用 pnpm 的 file: 协议：

dsh plugin --profile web add file:%CD%

然后编辑 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml，追加：

- insert:
    - id: pet
      name: 'dsh-pet'
      config:
        routeBase: /dsh-pet

重启 DSH（自己启动 dsh web），浏览器硬刷新。打开 设置 → 插件，应看到「桌面宠物」卡片。

备选：复制目录

把整个 dsh-pet 文件夹复制到：

%USERPROFILE%\.dsh\profiles\node_modules\dsh-pet\

目录名必须是 dsh-pet。同样注册上面的 cordis.patch.yml 条目，并确保 profile 的 node_modules 里能解析到 sharp 与 @deepseek-ai/schemastery（用 dsh plugin add 时会自动安装）。

配置页

设置 → 插件 → 展开「桌面宠物」：

项	说明
启动桌面宠物	卡片标题栏开关，打开即拉起桌面悬浮窗，关闭即退出。开关会立刻写入设置，不必点保存
桌面缩放	0.5～4，保存后立即生效
桌面动画每帧毫秒	30～1000，越小越快
默认宠物	桌面未手动选过宠物时使用；空 = 清单第一只

配置页保存写入 DSH 的 settings.yaml（pet: 节），不必再改 cordis.patch.yml。

配置项

cordis.patch.yml 的 config: 与设置页用户层叠加后生效。

键	默认	说明
enabled	true	插件总开关
routeBase	/dsh-pet	HTTP 路由前缀
sourceDirs	[]	自定义宠物目录；空则用 ~/.codex/pets + $DSH_HOME/pets
defaultPet	yingyue	默认宠物 id
desktop	true	是否启动桌面悬浮窗
desktopScale	0.5	桌面缩放
desktopFrameMs	300	桌面每帧毫秒
columns / rows	8 / 9	图集列 / 行
cellWidth / cellHeight	192 / 208	单格尺寸
states	idle=0, working=1, …	全局状态 → 行号
petStates	{}	按宠物 id 覆盖行映射（不改宠物文件）
desktopLauncher	""	可选：自定义 .ps1 / .cmd 绝对路径；空 = 包内 desktop/dsh-pet-desktop.ps1

以下键仍可出现在旧配置里以免解码失败，但网页宠物已关闭，界面不再提供：inject、scale、position、frameMs。

宠物格式

一个宠物 = 一个文件夹：

<pet-id>/
├── pet.json
└── spritesheet.webp

pet.json 与 Codex 一致：id、displayName、description、spritesheetPath、kind。可选扩展字段 states 覆盖行映射。

图集默认 9 行 × 8 列，每格 192×208。第 0 行视为 idle。1～8 行因宠物包而异，可用 states / petStates 配置。未映射的状态回落到 idle。

桌面交互

• 拖动：向右播 running-right，向左播 running-left（与 Codex 相同）
• 鼠标移上：播一轮 thinking/happy，再回到待机/工作循环
• 左键单击：播一次 happy
• 右键：切换宠物 / 鼠标穿透 / 退出
• 托盘图标：右键同款菜单；关闭窗口即最小化到托盘
• 气泡：运行中会话、等待授权、已完成（约 60 秒，可点掉）。多会话折叠叠放，悬停展开。点击气泡会尽量激活已打开的 DSH 浏览器标签并定位会话，没有标签时才新开
• 位置 / 所选宠物：保存在 $DSH_HOME/dsh-pet-desktop.json（默认 %USERPROFILE%\.dsh\dsh-pet-desktop.json）

需要 DSH 服务在运行（默认 http://127.0.0.1:3080）。手动调试：

powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File desktop\dsh-pet-desktop.ps1 -Scale 0.5 -FrameMs 300

HTTP 路由

路由	说明
GET /dsh-pet/manifest.json	宠物清单 + 默认宠物
GET /dsh-pet/spritesheet/<id>	原图集
GET /dsh-pet/spritesheet-png/<id>	PNG 图集（桌面窗用）
GET /dsh-pet/status.json	活动状态与会话气泡数据
GET /dsh-pet/desktop.json	桌面开关 / 缩放 / 帧间隔
POST /dsh-pet/focus	请求定位会话
GET /dsh-pet/focus.json	浏览器端轮询定位

卸载

1. 设置卡片里关掉「启动桌面宠物」，或删除 cordis.patch.yml 中的 pet 条目
2. 删除 $DSH_HOME/profiles/node_modules/dsh-pet/（若用 dsh plugin 安装，也可用对应 remove）
3. 可选：清理 $DSH_HOME/settings.yaml 的 pet: 节，以及 $DSH_HOME/dsh-pet-desktop.json
4. 重启 DSH

文件结构

dsh-pet/
├── package.json              # dsh.plugin / dsh.client + exports
├── index.js                  # Host 插件：路由、设置命名空间、拉起桌面窗
├── client/
│   ├── settings-card.js      # 设置 → 插件 卡片（须 inject sessions）
│   ├── settings.html         # 旧版 /dsh-pet/settings 页
│   └── player.js             # 保留的网页播放器（默认不注入）
├── desktop/
│   ├── dsh-pet-desktop.cmd   # 手动启动器
│   └── dsh-pet-desktop.ps1   # 分层窗口实现（UTF-8 BOM）
├── README.md
└── LICENSE

开发注意

• 改 Host / 设置卡片后：重启 DSH，并硬刷新浏览器
• 只改 desktop/*.ps1：关掉桌面宠物再打开，或结束 dsh-pet-desktop 进程后重启
• 不要把 dsh-pet-desktop.ps1 存成无 BOM 的 UTF-8
• Cordis 浏览器插件必须 inject: ["slots", "settingsScope", "sessions"]，否则会 cannot get property "sessions" without inject
• 不要向 DSH 网页注入播放器（inject 固定为 false）

许可证

MIT