dsh-codex-compatible-pet

English | 中文

桌面宠物插件：一只兼容 codex 格式的动画宠物，驻留在 Web GUI 右下角并随智能体状态变化。它是双面客户端插件——node 半边通过 HTTP 提供宠物文件服务，浏览器半边渲染精灵与设置页。

宠物模型（codex 兼容）

宠物模型移植自 codex-rs（tui/src/pets/model.rs），已有的 codex 宠物无需改动即可使用：

• 清单 — pet.json（也接受旧版 avatar.json），字段包括 id、displayName、description、spritesheetPath（默认 spritesheet.webp）、frame（默认 192×208，8 列 × 9 行）与 animations（frames 精灵序号、fps 默认 8、loop 默认 true、fallback 默认 idle）。spriteVersionNumber: 2（Codex App 精灵表格式）会把默认网格扩为 11 行；其他未知字段（如 kind）与 codex 解析器一样被忽略。
• 动画运算 — 行优先精灵网格；使用默认 frame 规格且没有自定义轨道的宠物（内置宠物，以及标准 8×9 或 v2 8×11 精灵表）播放完整的 codex 状态表（running、waiting、review、failed 等），自定义网格或自定义轨道则保持 codex 的“仅 idle”规则——这是 Codex App 的做法，让标准精灵表能动起来而不是呆站。循环轨道采用“前缀后循环”计时，一次性轨道播完后回落到 idle，缺失的状态轨道回落到 idle——与 codex 环境播放行为完全一致。

宠物来源

• 内置宠物 — codex 目录（Codex、Dewey、Fireball、Rocky、Seedy、Stacky、BSOD、Null Signal），由宿主从 Codex 官方宠物 CDN 代理，并带校验的 $DSH_HOME/cache/dsh-pets 缓存。
• 本地宠物 — $DSH_HOME/pets/<id>/（可写，导入目标）。
• Codex 家目录宠物 — ~/.codex/pets/<id>/ 与旧版 ~/.codex/avatars/<id>/（遵循 CODEX_HOME），以只读方式扫描，已为 Codex 安装的宠物会自动出现。

宿主半边（/dsh-pet 路由）

• GET /dsh-pet/list — 内置目录加目录宠物（损坏的清单仍会列出，显示为禁用行）。
• GET /dsh-pet/manifest/<source>/<id> — 宠物的原始清单 JSON。
• GET /dsh-pet/asset/<source>/<id>/<name> — 宠物精灵表；文件名必须是清单自身的 spritesheetPath，且不能越过宠物目录。
• GET /dsh-pet/builtin/<file> — 基于文件名白名单的 CDN 代理，4 MB 上限并校验 WebP。
• POST /dsh-pet/import — 导入浏览器选取的 .codex-pet 目录（清单加 base64 精灵表）；frame 网格必须精确覆盖 WebP 画布（codex 的校验），写入先暂存再改名。

所有路由都在浏览器信任栅栏之后（loopback 加配置的 trustedHosts），与 /api 栅栏同形。id 与素材名受模式限制，路径穿越在路由层即被拒绝。

浏览器半边

• 环境悬浮层 — shell.overlay 条目 pet：当前会话运行中播放 running，交互（审批、提问、计划复核）阻塞时播放 waiting，running→idle 边沿后的几秒内播放 review，否则播放 idle，并显示状态气泡（思考中 / 等待确认 / 已完成）。点击宠物会播放第一个可用的互动轨道（wave、bounce、jumping、waving）；按住鼠标可以把它拖到任意位置，拖动时播放与方向匹配的奔跑动画（running-right／running-left，依次回落到 running 与状态轨道）——4 px 阈值区分拖动与点击，位置持久化在 store 中。减少动态效果的用户看到静态首帧。
• 悬停详情卡 — 鼠标悬停在宠物上时，以 codex 风格展示它正在做什么（内容截断）：最近一次用户提示词作为更大更粗的标题，正在执行的工具调用（工具名 + 紧凑的参数开头）、最近助手输出的开头（优先流式文本）以及待处理交互的类型。长文本保留开头、以尾部省略号收尾。这些事实由对象层派生——会话列表加当前会话绑定——通过 inject 的 hooks 槽位以一个裸可观察源交付，组件不携带任何订阅机制。
• 设置页 — settings.section 条目 pet：目录浏览与静态预览、大小选项（小/中/大 = 94/117/150 px 目标精灵高度）、.codex-pet 目录导入、关闭控制。
• 持久化 — 选择、大小与拖动偏移存放在框架 store 引擎的 dsh.pet（localStorage）中。

安装

本包是一个 dsh bundle：其 dsh.bundle 清单会把 ui-pet 行插入任何列出该包的 profile，dsh.client 清单与 lib/client.js 携带 Web GUI 的浏览器半边。

最简单的安装方式是交给 agent 完成——DeepSeek Harness 本身，或任何能访问本仓库、且目标机器装有 dsh CLI 并有终端的 agent。把下面这段提示词粘贴给它：

帮我安装 GitHub 上的 dsh-codex-compatible-pet 插件（https://github.com/youzhoujiMrLiu/dsh-codex-compatible-pet）。

1. 执行 `dsh plugin add github:youzhoujiMrLiu/dsh-codex-compatible-pet`（针对特定 profile 加 `--profile <name>`）。
2. pnpm ≥10 首次会拒绝 git 依赖的构建脚本：把 pnpm 打印出的包键复制进该 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds` 块，然后重新执行 add。
3. 验证 `ui-pet` 行出现在 profile 组合里（`dsh --profile <name> --dump-config`）或 Web GUI 的插件页。
4. Web GUI 刷新页面——宠物出现在右下角，设置里出现「宠物」页；服务器重启后请再次刷新。

信任提示：git 安装会在安装机上执行本包的 `prepare` 构建；如需固定版本可锁定提交（`github:youzhoujiMrLiu/dsh-codex-compatible-pet#<sha>`）。

底层走的仍是官方 git 安装路径：prepare 在安装后从 src/ 构建 lib/，自包含、不依赖 monorepo。

Model Experience

无，因为插件只改变浏览器呈现，不注册任何 prompt、工具、schema、会话事件或 provider 请求。

#### KV Cache effect

无；本包不组装也不发送任何 provider 请求。

Known Limitations and Deferred Work

• 状态来源是会话列表 — 宠物从标准 useSessions 数据源推导状态（running 位、待处理交互与 running→idle 边沿），因此单轮错误暂时没有专门的 failed 动画；失败轮次会回落到 review 提示与 idle。详情卡的活动文本则来自当前会话的会话窗口。
• 内置宠物需要首次下载 — 首次选择内置宠物时会从 Codex CDN 拉取精灵表，下载完成前不显示。
• 导入是唯一的写入路径 — 手动把 .codex-pet 目录放进 $DSH_HOME/pets/<id>/ 也可以，但除重新打开设置页外没有应用内重新扫描按钮。
• 卸载在组合层 — dsh plugin --profile <name> remove dsh-codex-compatible-pet 会同时移除依赖与插入的挂载层；暂无运行时开关。用户安装的 bundle 插入的行目前还不会出现在「自定义插件」标签页（该分类当前只识别用户补丁层）。