DSH 通用宠物插件

August 20, 2026 · View on GitHub

在 DSH Web 中运行兼容 Codex pet.json 协议的动画宠物。插件默认扫描 ~/.codex/pets/*/pet.json，并内置嘉然作为兜底资源。

安装

cd /path/to/deepseek-harness-desktop
pnpm dsh plugin --profile web add ./plugins/codex-pets
pnpm dsh web

点击宠物会挥手，悬停会跳跃，左右拖动时会朝对应方向奔跑，双击会跳跃并回到右下角。右键宠物可循环切换已发现的宠物。

添加宠物

一个宠物目录至少包含：

my-pet/
├── pet.json
└── spritesheet.webp

pet.json 使用 Codex 格式：

{
  "id": "my-pet",
  "displayName": "My pet",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp"
}

将完整目录放入 `~/.codex/pets//$ 后重启 \text{DSH}，无需修改 \text{Desktop} 或插件源码。这与 \text{Codex} 的安装目录和 \text{manifest} 格式相同。支持 \text{v1}（8 \times 9）和 \text{v2}（8 \times 11）图集；标准动作行依次为 \text{idle}、\text{running}-\text{right}、\text{running}-\text{left}、\text{waving}、\text{jumping}、\text{failed}、\text{waiting}、\text{running}、\text{review}。

配置

打开“设置 → 插件 → 插件配置”即可管理本插件。配置卡可以显示或隐藏桌面宠物、选择任意已发现的 \text{Codex} 宠物，并将大小调整为 50% 到 200%。这些值属于 $codex-pets`，会以该 namespace 保存在 profile 设置文档中。

在 profile 的 cordis.patch.yml 中覆盖插件配置：

- id: codex-pets
  config:
    activePet: my-pet
    codexPetsRoot: /path/to/codex/pets
    petDirectories:
      - /path/to/another-pet

activePet：启动时默认显示的宠物 ID。
codexPetsRoot：自动扫描的宠物根目录，默认 ~/.codex/pets。
petDirectories：额外的独立宠物目录。

卸载插件时配置卡会一并移除；codex-pets 设置分节也会被清理，其他插件和产品设置保持不变。

会话活动

宠物旁的数字 badge 显示活动会话数量。点击 badge 展开活动列表，包含当前或后台运行、等待输入、等待计划评审和未读完成的会话；点击一行会在 DSH 中打开对应会话。

状态映射

活动列表第一项正在运行：running。
活动列表第一项需要审批、提问或计划评审：waiting。
活动列表第一项是未读完成结果：review。
当前会话无活动但存在 Agent 错误：failed。
没有活动：idle。

动画帧数、逐帧时长、三轮动作后回到慢速 idle、活动优先级和拖动阈值均按 Codex 状态机实现。

卸载

cd /path/to/deepseek-harness-desktop
pnpm dsh plugin --profile web remove codex-pets

卸载后，Desktop 会销毁插件声明的透明窗口；主界面、设置与宠物目录均不会留下插件注入的状态。~/.codex/pets 中由用户安装的资源不会被删除。