deepseek-pet

deepseek-pet

在 DeepSeek Harness Web UI 中运行 Code Pet 格式的宠物。插件既能直接复用 $CODEX_HOME/pets 中已安装的 Codex Pet，也支持从自定义目录加载相同格式的 Pet 包； 它会读取 pet.json + spritesheet.webp/png，把资源安全地交给浏览器，并将 dsh 会话状态映射到宠物动画。

能力

• 兼容 Code Pet v1（8×9，1536×1872）与 v2（8×11，1536×2288）。
• 自动读取 $CODEX_HOME/pets，未设置时读取 ~/.codex/pets。
• 支持通过 petsDir 从任意自定义目录加载 Code Pet 兼容包，不依赖 Codex 运行。
• running、waiting、failed、review 等动画跟随当前 dsh 会话。
• 拖动时使用左右移动动画；点击触发跳跃；右键恢复默认位置。
• v2 宠物空闲时会使用 16 个 look-direction 帧跟随鼠标。
• 尊重 prefers-reduced-motion，减少动画时停在每行第一帧。

当前只扩展 dsh web。终端 TUI 无法原样显示透明位图 atlas，因此不在支持范围内。

同时提供实验性的 macOS 原生悬浮窗。它仍由本机 dsh web profile 提供经过校验的 Pet 资源和会话状态，但宠物本身显示在独立的透明置顶窗口里，不依赖浏览器页面保持打开。

Code Pet 包格式

默认从下面的目录选取第一个有效包：

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

v2 manifest：

{
  "id": "my-pet",
  "displayName": "My Pet",
  "description": "A tiny coding companion.",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp"
}

v2 atlas 固定为 8 列 × 11 行、每格 192×208；最终尺寸 1536×2288。 省略 spriteVersionNumber 时按 v1 处理，要求 9 行、尺寸 1536×1872。

安装

开发和构建要求 Bun 1.3.14 或更高版本。dsh 要求 0.1.0-rc.6 或更高的 0.1.x 版本。注意：dsh 自己的 plugin 子命令目前仍在内部调用 pnpm；这是 dsh 的安装器实现，与本项目的依赖和构建已经全部由 Bun 管理是两回事。

在本仓库中：

bun install
bun run verify
dsh plugin --profile web add .
dsh web

插件只从本机读取 pet 文件，并通过 dsh 自己的 loopback Web 服务提供同源资源；不会上传 pet。

macOS 原生悬浮宠物（实验性）

要求 macOS 13 或更高版本，以及 Xcode Command Line Tools。先启动带插件的本机 dsh：

bunx @deepseek-ai/dsh web --no-open

另开一个终端启动原生窗口：

bun run mac

默认连接 http://127.0.0.1:3080。自定义本机端口时使用：

bun run mac -- --server http://127.0.0.1:3097

也可以生成一个可双击运行的本地 .app（临时 ad-hoc 签名，尚未公证）：

bun run mac:bundle
open "dist/DeepSeek Pet.app"

原生版本支持透明置顶、跨 Space、拖动位置、点击跳跃、右键恢复默认位置，以及菜单栏 状态预览。插件在宿主端监听 turn/* 与 approval/* 事件，并通过仅绑定本机的 /dsh-code-pet/state.json 同步 running、waiting、failed 和 review 动画。

选择和配置宠物

默认自动选择 pets 目录中按名称排序的第一个有效包。要固定宠物，在 $DSH_HOME/profiles/web/cordis.patch.yml（默认 ~/.dsh/profiles/web/cordis.patch.yml）加入：

- id: code-pet
  config:
    pet: my-pet
    petsDir: ''
    size: 112
    position: bottom-right
    offsetX: 28
    offsetY: 20
    enableLook: true
    draggable: true

petsDir: '' 表示 $CODEX_HOME/pets 或 ~/.codex/pets。也可以指向自定义的绝对路径：

- id: code-pet
  config:
    pet: my-pet
    petsDir: /absolute/path/to/my-pets

自定义目录仍采用 <petsDir>/<pet-id>/pet.json 和对应 spritesheet 的 Code Pet 包结构。 配置 patch 会替换这一行的完整 config，不过缺失字段仍会由插件 schema 填入默认值。

也可以先用临时 patch 验证：

dsh web --patch /absolute/path/to/code-pet.patch.yml

动画状态映射

dsh / 交互状态	Code Pet 行
空闲	idle
有模型输出或工具调用	running
等待批准、问题或输入	waiting
Agent 报错	failed
一轮工作完成	review
切换到会话	waving
点击宠物	jumping
向左右拖动	running-left / running-right
v2 空闲鼠标跟随	rows 9–10 的 16 个方向

开发

bun run check
bun test
bun run build
bun pm pack --dry-run

插件是一个双端 dsh bundle：Node 端校验并提供 pet 资源，浏览器端通过 shell.overlay 插槽渲染宠物。资源路由固定在 /dsh-code-pet，避免暴露任意本机路径。

实现所依据的 dsh 官方资料：

• 插件开发基础
• 插件发布与 bundle patch
• 客户端模块与 UI 扩展
• Web Server 子系统

License

MIT