# DSH Pet 插件 — 复刻方案

## 目标
在 DeepSeek Harness（DSH）Web GUI 中复刻 Codex 的 Pets 功能：一只漂浮的动画宠物，由当前会话的 agent 运行状态实时驱动。

## 架构

```
dshernesspet/                     # 插件包（可 install 进 DSH web profile）
├── package.json                  # dsh.client 声明（inject/platform/exports）
├── lib/
│   ├── index.js                  # host 侧 apply（空，纯 UI 插件）
│   ├── client.js                 # 浏览器侧：window.__ModuleLoader__.load({id, factory})
│   └── pet-core.js               # 纯逻辑（可 Node 测试）：pet.json 解析 + 帧切片 + 状态机
├── assets/
│   └── (默认宠物 spritesheet 由运行时 canvas 生成，无需二进制资产)
├── test/
│   └── pet-core.test.mjs         # Node 单测：帧索引/状态机/校验
└── docs/ , research/             # 调研文档
```

## 核心模块

### 1. pet-core.js（纯函数，无 DOM）
- `parsePetJson(json)`：解析 4 基础字段 + frame + animations，做与官方一致的回退与校验（fps 范围、frames 索引 < 总帧数、网格铺满）。
- `spriteGrid(pet)`：由 frame/尺寸推出 cols/rows/frameW/frameH。
- `frameRect(index, grid)`：`(col×W, row×H, W, H)`，`index = row×cols + col`。
- `stateFrames(state)`：9 状态 → 该行帧索引列表（V1 默认表）。
- `derivePetState({running, waiting, error, completed, prevRunning, celebrateUntil})`：纯状态机。

### 2. client.js（浏览器侧，shell.overlay）
- `inject: ['slots']`；`apply(ctx)` 注册 `shell.overlay`（id=dsh-pet, order 高位）。
- 组件 `PetOverlay({ useSessions })`：
  - `useSessions()` 读 `current` + `byId[current]`（`running` / `pendingInteraction` / `completed`）。
  - 状态机驱动：running→working、pendingInteraction→waiting、completed→review、错误→failed、running 由 true→false 触发短暂庆祝(jumping)后回 idle。
  - 渲染：CSS background-position 步进帧动画，缩放至 ~96px，右下角悬浮，可点透（宠物本体接收 pointer 事件，支持点击喂食/交互）。
- 内置默认精灵：`buildDefaultSprite()` 用离屏 `<canvas>` 程序化画一只像素小宠物（8×9 格、每格 192×208），产出 dataURL + 内联 pet.json，完整走 Codex 格式路径。

### 3. 状态映射表
| DSH 信号 | 宠物状态（行） |
| --- | --- |
| `summary.running === true` | running（7，工作；超 3min 未刷新回退 idle） |
| `summary.pendingInteraction` | waiting（6，等待输入；24h 存活期） |
| `snapshot.lastAgentError` | failed（5，报错；1h 存活期） |
| running true→false 边沿 | jumping（4，庆祝）约 2.6s |
| `summary.completed === true` | review（8，就绪；7d 存活期） |
| 切换/打开会话 | waving（3，打招呼）约 1.7s |
| 拖拽移动中 | running-left/right（1/2，按拖动方向） |
| 无活动 | idle（0） |

## 落地步骤
1. 写 `lib/pet-core.js` + Node 单测。（已完成）
2. 写 `lib/client.js`（模块加载器包装 + PetOverlay + canvas 精灵生成）。（已完成）
3. 写 `package.json` 契约 + `lib/index.js`。（已完成）
4. 验证：Node 跑 pet-core 单测；比对 client.js 结构与 `dsh-client-ui-goal` 契约一致。（已完成）
5. 安装进 DSH web profile（`dsh plugin`）并重启验证。（已完成，见 INSTALL.md）
6. 扩展项：拖拽交互、设置项、多宠物（3 内置配色 + Codex 宠物包导入）、状态存活期、减少动态、会话切换 waving、双副本一致性测试。（已完成；对照见 `差距分析.md`）