前言¶
用 DSH Desktop 做智能体开发时，主窗口往往被编辑器、终端和浏览器挤到后面。要回到 DSH，要么记快捷键，要么在 Dock 或任务切换里找窗口。若希望桌面上有一个始终可见、点一下就能唤起 DSH 的入口，同时又不想多占一块普通应用窗口，dsh-codex-pets 提供的是透明置顶的小宠物窗口：默认是一只 DeepSeek 小鲸鱼，也可以换成 Codex 格式的其他宠物并调节尺寸。
下面介绍这个插件的定位、能力、安装方式与配置项。事实以仓库 README 与 package.json 为准。
这是什么¶
dsh-codex-pets 由社区维护者 jusong 发布，归类为 DSH 社区目录中的「趣味换装」类插件。它面向 DSH Desktop（macOS）：在桌面上浮一只宠物，透明无边框、始终置顶、跟随所有 Space，且不抢焦点。仓库当前版本为 0.11.1，插件本体与内置 deepseek-whale 图集以 MIT 许可发布。
Codex 官方的 9 只宠物属于 OpenAI 第一方资产，不在本仓库中分发；设置里的「从 Codex 导入」只读取本机已有副本。社区目录页：https://www.skillhub.cn/plugins/jusong/dsh-codex-pets，源码：https://github.com/jusong/dsh-codex-pets。
核心功能¶
README 中列出的能力如下，安装前可按需对照。
窗口与交互
- 常驻桌面：透明无边框、置顶、跨桌面，不抢焦点。
- 点击回 DSH：点宠物将 DSH 窗口带到前面；若 DSH 未运行则打开它。
- 拖动跟手：位置按屏幕刷新率跟随光标，重启后记住上次位置。
- 闲时动画：轮流播放小动作，偶尔带粒子效果；系统开启「减少动态效果」时只显示静态帧。
设置与扩展
- 设置 → 宠物：切换宠物、调节大小（80–260 px），即时生效，无需重启 DSH。
- 可关闭显示：设置里关「显示宠物」，或在宠物上右键「隐藏宠物」；再打开时回到原位置。
- 右键「设置」：直接打开设置页并跳到「宠物」一节。
- 兼容 Codex 宠物格式：可从 codex-pets.net 安装，或从本机 Codex 一键导入。
- 最近会话球（默认开启）：宠物脚下显示会话数，点击可跳到正在等待的会话。
实现要点（与排错相关）
悬浮窗依赖原生 AppKit 助手 bin/dsh-codex-pets-macos（随包发布，含 arm64 与 x86_64）。安装过程不编译；若缺少该二进制，插件可能显示已安装但桌面无宠物，宿主日志会出现 native helper missing。
安装与启用¶
环境要求：macOS 13+、DSH Desktop 0.2.1+。
在 desktop profile 下从 GitHub 安装，依赖由 profile 的 pnpm 一并安装：
dsh plugin --profile desktop add github:jusong/dsh-codex-pets
需要固定版本时带上 tag，例如：
dsh plugin --profile desktop add github:jusong/dsh-codex-pets#v0.11.1
装完后重启 DSH。README 说明鲸鱼会出现在屏幕右下、输入框上方。
若未出现，可在 ~/.dsh/profiles/desktop/cordis.patch.yml 中手动加入 loader 配置：
- id: dsh-codex-pets
name: dsh-codex-pets
config:
pet: deepseek-whale
典型用法¶
设置入口
- 设置 → 宠物（亦可在「插件 → 内置插件配置 → 桌面宠物」下找到）。
日常操作
- 用顶部「显示宠物」开关控制是否留在桌面；宠物右键有「设置」与「隐藏宠物」。
- 在画廊卡片上点击切换宠物，预览与尺寸滑块会同步更新。
- 在输入框粘贴 codex-pets.net 的宠物 ID 或页面链接即可安装，装完后排在「已安装」末尾。
- 「从 Codex 导入」会导入
~/.codex/pets中尚未导入的条目，以及 Codex 自带（位于ChatGPT.app内）的宠物。 - 用户安装的宠物可删除、拖拽排序；内置宠物不可删。删除当前使用的宠物时会自动切换到剩余的第一只（至少保留一只）。
配置文件示例
完整 config 字段见 README：
- id: dsh-codex-pets
name: dsh-codex-pets
config:
pet: deepseek-whale # pets/<id> 的目录名
size: 220 # 80–260 px
visible: true # false 隐藏宠物（右键宠物也能隐藏）
sessions: true # 脚下的最近会话球
sessionLimit: 5 # 球里列几条（1–10）
sessionMotion: true # 有会话在忙时宠物不闲着，忙完跳一下
shortcut: Command+Option+N # 打开新会话输入框；留空关闭
用户安装的宠物目录为 ~/.dsh/dsh-codex-pets/，顺序保存在同目录的 pets.json。旧版路径 ~/.dsh/pets 在升级后首次启动会自动迁移。
内置 deepseek-whale 为 v1 图集（8 列 × 9 行）。自定义宠物可放入 ~/.dsh/dsh-codex-pets/<id>/（pet.json + 精灵图集，格式与 Codex 一致）；仓库提供 tools/install-pet.mjs 与 tools/port_custom_pet.py 等工具，细节见 GitHub README。
适用场景与注意¶
适合谁
- 长期在 macOS 上使用 DSH Desktop，希望桌面有轻量、可点的 DSH 入口。
- 已有 Codex 或 codex-pets.net 宠物资源，希望在 DSH 桌面复用同一套格式。
- 需要脚下「最近会话球」快速跳转到进行中的会话。
使用前请注意
- 插件仅支持 macOS，且依赖 DSH Desktop 与随包原生助手；Linux 或纯 CLI 环境不适用。
- DSH 生态遵循「一切皆插件」；社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。安装第三方插件前，应自行审阅源码与许可证；插件以当前 DSH 进程权限运行。
- Codex 官方 9 只宠物需通过本机导入或社区来源获取，勿假定仓库内已附带。
结尾¶
dsh-codex-pets 把 DSH Desktop 的唤起与会话跳转做成桌面上的 Codex 格式宠物：内置 DeepSeek 小鲸鱼，可换宠、调尺寸、管会话球，并与 Codex 宠物生态兼容。需要安装命令与配置字段时，以 README 为准。
