dsh-pet-codex

桌面宠物插件 —— 为 DeepSeek Harness 增加一个独立、透明的悬浮宠物窗口，随 DSH 会话状态（思考 / 调用工具 / 完成 / 失败 / 等待审批）切换动画与状态气泡。窗口由 Electron 独立运行，关闭浏览器也不会消失。

开源的是「能力」，不是「素材」。 本包不随附任何宠物立绘/图集（assets/pets/ 为空）。它发现并渲染你自己的宠物：来自你的 Codex CLI 目录、你的 DSH 用户目录，或你放进包内 assets/pets/ 的 v2 格式图集。

能力一览

• 多源宠物发现：启动时按「包内内置 → $DSH_HOME/dsh-pet/pets → ~/.codex/pets」三级扫描，同一 id 后源覆盖前源（Codex > DSH > 内置）。
• 从 Codex 同步：设置卡片里的「从 Codex 同步」按钮，把 ~/.codex/pets/* 下所有有效宠物复制到 $DSH_HOME/dsh-pet/pets/（持久化），立即生效、免重启。
• 会话状态驱动：宿主把 DSH 会话事件投影成动画轨（idle / running / waiting / failed / review…）+ 状态气泡，通过 SSE 推给桌面窗口。
• 独立桌面窗口：Electron 透明置顶窗口，无边框、无托盘、不进任务栏；可拖动（带奔跑动画）、点击跳跃、光标注视、问候挥手；右键菜单仅「关闭宠物」。
• 双端设置：网页设置面板与桌面窗口（双击宠物）都能改，同一份 $DSH_HOME/dsh-pet/config.json；「显示宠物」开关只存在于网页设置面板。
• 零框架负担：无亲和度、无宠物商店扫描、无 WebUI 全家桶概念——宿主只推状态，桌面管动画与交互。

宠物格式（v2 图集契约）

每个宠物是一个目录：

<petId>/
  pet.json            # 清单
  spritesheet.webp    # 1536×2288，192×208 格，8 列 × 11 行

pet.json：

{
  "id": "cartethyia",
  "displayName": "卡提西亚",
  "description": "一句话介绍（可选）",
  "spriteVersionNumber": 2,
  "spritesheetPath": "spritesheet.webp",
  "frames": [6, 8, 8, 4, 5, 8, 6, 6, 6]
}

• 行 0–8：9 个动画轨（idle / running-right / running-left / waving / jumping / failed / waiting / running / review）。
• 行 9–10：16 个注视方向。
• frames 可选，缺省用契约默认值 [6, 8, 8, 4, 5, 8, 6, 6, 6]。

把目录放进 ~/.codex/pets/、$DSH_HOME/dsh-pet/pets/ 或包内 assets/pets/，设置面板的宠物下拉框就会出现它。

安装

pnpm add dsh-pet-codex   # 或 file: 指向本地打包的 .tgz

1. Bundle 补丁：确保 dsh.profile.bundles 引入了 cordis.patch.yml（插入 id pet-codex）。
2. Electron：electron 是 peerDependency，需随包安装；profile 的 pnpm-workspace.yaml 里放行构建：allowBuilds: { electron: true }。
3. Web 设置面板白名单：DSH 的 packages/host/apiproxy/src/api-proxy.ts 中 WEB_SETTINGS_NAMESPACES 需包含 'pet-codex'（本仓库已加入）。若缺失，设置面板会返回 settings-not-exposed。
4. 重启 DSH（pnpm dsh --profile web），在设置 → 插件 里打开「桌面宠物」卡片，打开「显示宠物」。

使用

• 宠物列表：设置卡片下拉框；条目带来源后缀（· Codex / · DSH）。
• 同步 Codex 宠物：设置卡片「从 Codex 同步」，复制 ~/.codex/pets/* 到 $DSH_HOME/dsh-pet/pets/。
• 尺寸：设置面板 120–250 滑块，实时生效。
• 关闭：桌面窗口右键「关闭宠物」；重新打开只走网页设置面板「显示宠物」。

开发

依赖全部来自 npm registry（@deepseek-ai/* 均为发布版），克隆后无需 DSH 源码即可独立构建：

pnpm install
pnpm build        # tsc -b && tsdown → lib/
pnpm test

打包：

pnpm pack

package.json 的 files 已排除 assets/pets/**，tarball 不含任何内置立绘。如需随包附带宠物，把 v2 目录放进 assets/pets/<id>/ 即可（记得从 files 里去掉排除项）。

目录结构

src/
  index.ts            # 宿主：生命周期、路由、设置命名空间 pet-codex、同步端点
  service.ts          # 多源扫描、同步、SSE/资源路由
  config.ts           # 桌面配置文件读写
  state.ts            # 会话活动 → 动画轨状态机（纯）
  event-projection.ts # 会话事件 → 视觉相位投影（纯）
  client/index.ts     # 网页设置卡片（含「从 Codex 同步」）
desktop/              # Electron：主进程、preload、renderer、双击设置窗
assets/pets/          # 空——能力层不随附素材

License

Apache-2.0