在 DSH 安装目录下（profile 名按你的实际使用，如 web）

dsh plugin --profile web add dsh-codex-pet

或手动安装：

1. 把本仓库复制到 profile 的 `node_modules`：

   ```bash
   cp -r dsh-codex-pet "$DSH_HOME/profiles/web/node_modules/"

2. 在 $DSH_HOME/profiles/web/package.json 的 dsh.profile.bundles 中加入 "dsh-codex-pet"，并在 dependencies 中加入 "dsh-codex-pet": "file:D:/path/to/dsh-codex-pet"。

3. 重启 DSH，桌宠出现在页面右下角；设置 → 桌宠 可调整。

方式二：独立桌面应用（脱离网页，桌面上动）

桌宠也可以脱离浏览器，作为独立的透明置顶窗口显示在桌面上（需要已通过方式一迁移好皮肤）：

cd desktop
npm install        # 首次需要（安装 Electron）
npm start          # 启动桌面桌宠

功能：透明无边框置顶窗口（不占任务栏）、拖拽移动（位置自动保存到 $DSH_HOME/pet.desktop.json）、右键菜单（随机散步/摸摸/置顶/点击穿透/重新扫描/退出）、随 DSH agent 状态实时变化、多会话对话框。DSH 未运行时桌宠保持待机动画。

与网页设置联动：桌面窗口以 $DSH_HOME/pet.json 的 codexPet 为主配置源，网页设置面板（设置 → 桌宠）里的皮肤、缩放、速度、动画开关、随机行为、空闲动画间隔、置顶、点击穿透、空闲隐藏实时同步生效（每 1.5s 轮询）；桌面右键菜单的置顶/穿透切换也会写回共享配置，两种模式始终一致。桌面窗口位置单独保存在 pet.desktop.json，不受网页位置影响。

方式三：动态插件（开发调试）

在 DSH 会话中通过 Cordis 工具 cordis_define / cordis_run 加载本仓库 lib/ 下的 host/client 代码（详见仓库内注释）。动态插件在 DSH 进程重启后丢失，仅用于开发调试。

前置条件

• Windows（皮肤迁移当前使用 node:fs 直接扫描，跨平台通用；Codex 皮肤目录需可读）。
• DSH 0.1.0-rc.6+（依赖 webServer、slots、timer、agents、sessionTitle 服务）。
• Codex 桌面宠物皮肤：/pets//{pet.json, spritesheet.webp}，社区皮肤可从 Codex 社区获取。

使用

操作	效果
拖动桌宠	移动位置（自动保存）
单击桌宠	随机互动（开心/挥手/跳跃）
右键桌宠	菜单：随机散步 / 隐藏桌宠 / 重新扫描皮肤 / 退出
双击桌宠	互动动画
单击对话框	折叠 / 展开
双击对话框	跳转到对应会话并移除该气泡（会话重新活动时气泡恢复）
悬停进行中的对话框	显示 ⏹ 终止按钮，点击终止对话
设置 → 桌宠	皮肤、缩放、速度、行为开关、迁移

皮肤精灵表格式

Codex 皮肤为 8 列 × N 行精灵表（192×208 单元格）：

行	动作
0	待机（idle）
1 / 2	向右跑 / 向左跑
3	挥手
4	跳跃
5	失败
6	等待
7	奔跑
8	审查
9 / 10	v2 皮肤左右注视

末尾全透明的帧会被自动跳过，地面对齐按每帧非透明像素自动计算。

事件 → 动画映射

DSH 事件	桌宠状态	动画轨
agent/session-start	启动中	挥手
agent/status running	思考中	奔跑轨
tools/pre-execute / tools/execute（ask）	等待用户批准	等待轨
approval/request	等待用户批准	等待轨
tools/execute（其他工具）	正在使用工具	奔跑轨
workflow/phase	工作中	奔跑轨
llm/stream text-delta	思考中 + 输出尾部	奔跑轨
agent/status idle	完成	跳跃 + 审查
agent/error	出错了	失败轨

多会话并行时按 失败 > 工作 > 等待 > 空闲 优先级聚合动画，对话框分别显示每个会话。

配置

所有配置保存在 $DSH_HOME/pet.json 的 codexPet 键下：

{
  "codexPet": {
    "name": "deepseek",          // 当前皮肤目录名
    "x": 640, "y": 480,          // 位置（按窗口尺寸归一化）
    "scale": 1.0,                // 缩放 0.5–4
    "alwaysOnTop": true,         // 置顶
    "clickThrough": false,       // 点击穿透
    "hideWhenIdle": false,       // 空闲隐藏
    "animationEnabled": true,    // 动画
    "animationSpeed": 1.0,       // 速度 0.25–4
    "idleFrequencySec": 15       // 空闲动画间隔（秒）
  }
}

目录结构

dsh-codex-pet/
├── package.json          # bundle 声明（dsh.bundle.patch / dsh.client）
├── cordis.patch.yml      # 插件行插入补丁
├── lib/
│   ├── index.js          # host 半：迁移 + webServer API + 事件监听
│   └── client.js         # client 半：渲染、动画、对话框、设置页
├── desktop/              # 独立桌面应用（Electron，脱离网页）
│   ├── main.js           # 透明置顶窗口 + 状态轮询 + 配置
│   ├── preload.js        # IPC 桥
│   └── renderer/         # 动画渲染（复用 client 逻辑）
└── docs/
    └── pet-demo.webp     # 示例图

开发

## 使用

| 操作 | 效果 |
| --- | --- |
| 拖动桌宠 | 移动位置（自动保存） |
| 单击桌宠 | 随机互动（开心/挥手/跳跃） |
| 右键桌宠 | 菜单：随机散步 / 隐藏桌宠 / 重新扫描皮肤 / 退出 |
| 双击桌宠 | 互动动画 |
| 单击对话框 | 折叠 / 展开 |
| 双击对话框 | 跳转到对应会话并移除该气泡（会话重新活动时气泡恢复） |
| 悬停进行中的对话框 | 显示 ⏹ 终止按钮，点击终止对话 |
| 设置 → 桌宠 | 皮肤、缩放、速度、行为开关、迁移 |

## 配置

所有配置保存在 `$DSH_HOME/pet.json` 的 `codexPet` 键下：

```jsonc
{
  "codexPet": {
    "name": "deepseek",          // 当前皮肤目录名
    "x": 640, "y": 480,          // 位置（按窗口尺寸归一化）
    "scale": 1.0,                // 缩放 0.5–4
    "alwaysOnTop": true,         // 置顶
    "clickThrough": false,       // 点击穿透
    "hideWhenIdle": false,       // 空闲隐藏
    "animationEnabled": true,    // 动画
    "animationSpeed": 1.0,       // 速度 0.25–4
    "idleFrequencySec": 15       // 空闲动画间隔（秒）
  }
}