deepseek-pet

v0.2.0

Published

3 months ago

Run Codex Code Pet packages inside the DeepSeek Harness Web UI.

0High
0Medium
0Low

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 官方资料：

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

deepseek-pet

能力

Code Pet 包格式

安装

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

选择和配置宠物

动画状态映射

开发

License