@linxin666/dsh-pet 0.1.14 → 0.1.16

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   node scripts/verify-docs.mjs --write <dir>
-README.md: 437e1068038cb013e2880441e69cf1c259f51e79
-README.zh.md: 46511480ae653cc8d6c9b164e9e84ff5645f5945
+README.md: ea1c6ac0d9ff57a9072ac6872a8147e5dc389435
+README.zh.md: 5146dc5a8fbe4861c1e2367546a5a592dd916476

package/README.md

@@ -1,10 +1,10 @@
-# dsh-pet — Whale-girl pet plugin
+# dsh-pet — Multi-pet companion plugin
 
 English | [中文](README.zh.md)
 
-> A soft, healing whale-girl who works alongside you in DeepSeek Harness.
+> A registry-driven desktop companion for DeepSeek Harness — the built-in whale girl plus any pet you drop in.
 
-While the model thinks, you wait — she swims. She follows official session activity and switches animations while waiting, thinking, using tools, composing a reply, celebrating completion, or reporting failure; you can also pat her head, feed her dried fish, and watch her grow from a baby whale into your deep-sea bond.
+While the model thinks, you wait — your pet swims. It follows official session activity and switches animations while waiting, thinking, using tools, composing a reply, celebrating completion, or reporting failure; you can also pat its head, feed it dried fish, and watch its affinity grow. Pets are registry entries, not code: every pet is one `pet.json` manifest plus one atlas image, and the host discovers them at startup.
 
 Re-implemented from the pet feature of the Codex desktop app, as an official DSH plugin shape (cordis bundle: host half + client half in one package).
 
@@ -12,17 +12,49 @@ Re-implemented from the pet feature of the Codex desktop app, as an official DSH
 
 | Feature | Description |
 |---|---|
-| State animation | Official session activity → whale-girl animation: `thinking → running`, `tool → running-right`, `review → review`, `waiting → waiting`, `done → jumping`, `failed → failed` |
-| Head-pat interaction | Click the whale-girl → bubble feedback + affinity +1 (10s cooldown) |
-| Feeding | Hover panel "喂食" (Feed) → consumes 1 dried fish + affinity +5 (30s cooldown) |
-| Treat economy | Dried-fish stock (cap 20): +1 every 3 rounds of work, +1 every 30 minutes; when low it prompts "多陪鲸鱼娘工作一会儿" (Work with the whale-girl a bit more) |
-| Affinity | +1 per round completed; 4 levels: 幼鲸 (baby whale) → 伙伴 (companion) → 挚友 (close friend) → 深海羁绊 (deep-sea bond, capped at 100) |
-| Custom naming | Hover panel "改名" (Rename) → 1–20 characters, persisted, echoed in the summon button/panel |
-| Dragging | Hold and drag the whale-girl to reposition; position persisted |
-| Hide/Summon | Hover panel "隐藏" (Hide); after hiding, a "召唤{name}" (Summon {name}) button appears in the input selector row |
+| Multi-pet registry | The host scans built-in `assets/`, the hatch-pet custom pets directory, and composed config entries; each pet is a manifest plus an atlas |
+| Pet selection in settings | The plugin settings card lists every registered pet; switching persists and the sprite swaps immediately |
+| Per-pet naming | Rename from the hover panel; each pet keeps its own name (stored per pet id, migrated from the legacy flat name) |
+| State animation | Official session activity → 9-state animation: `thinking → running`, `tool → running-right`, `review → review`, `waiting → waiting`, `done → jumping`, `failed → failed` |
+| Head-pat interaction | Click the pet → bubble feedback + affinity +1 (10s cooldown) |
+| Feeding | Hover panel 喂食 (Feed) → consumes 1 dried fish + affinity +5 (30s cooldown) |
+| Treat economy | Dried-fish stock (cap 20): +1 every 3 rounds of work, +1 every 30 minutes |
+| Affinity | +1 per round completed; 4 levels: 幼鲸 → 伙伴 → 挚友 → 深海羁绊 (capped at 100) |
+| Dragging | Hold and drag the pet to reposition; position persisted |
+| Hide/Summon | Hover panel 隐藏 (Hide); after hiding, a 召唤{name} (Summon {name}) button appears |
 | Status bubble | Shows the current session stage or tool name; transient interaction feedback temporarily takes priority |
 | Multi-session activity | The pet is host-global: the most recent meaningful event controls its display, while completed turns from every session contribute affinity and treats |
 
+## Pet contract
+
+A pet is a directory holding one `pet.json` manifest and one atlas image. Nothing else is required — no host or client code changes.
+
+```jsonc
+{
+  "id": "whale-girl",                     // unique lowercase kebab id
+  "displayName": "鲸鱼娘",                 // shown in the settings selector and panel
+  "description": "A soft healing whale-girl.", // optional
+  "spritesheetPath": "spritesheet.webp",   // atlas, relative to the manifest
+  "cell": { "width": 192, "height": 208 }, // optional; defaults to the Codex contract
+  "columns": 8,                            // optional; default 8
+  "frames": [6, 8, 8, 4, 5, 8, 6, 6, 6],   // optional per-row frame counts
+  "tracks": {                              // optional per-track rhythm overrides
+    "idle": { "durations": [400, 400, 500, 400, 400, 500] }
+  }
+}
+```
+
+- The atlas is an 8-column × 9-row grid (192×208 cells by default); rows are fixed in this order: 0 idle, 1 running-right, 2 running-left, 3 waving, 4 jumping, 5 failed, 6 waiting, 7 running, 8 review. Unused cells stay fully transparent.
+- `frames` counts the used columns per row (defaults to the hatch-pet contract table `[6, 8, 8, 4, 5, 8, 6, 6, 6]`); `tracks` overrides per-frame durations (cycled to the row's frame count), `loop`, and `fallback` per animation (defaults: everything loops; `jumping` and `failed` hold their last frame, then fall back to `idle`).
+
+Where pets come from (later sources override earlier ones on id collision):
+
+1. **Built-in**: `assets/<dir>/pet.json` in this package.
+2. **Custom pets**: `${CODEX_HOME:-~/.codex}/pets/<pet>/pet.json` — the hatch-pet pipeline stages its output there, so a hatched pet appears in the selector with no further wiring.
+3. **Composed**: `PetConfig.pets` manifest entries passed to the plugin by the embedding application.
+
+The registry is built once at host startup; add or change a pet, then restart `dsh web`.
+
 ## Animation preview
 
 The sprites are an 8-column × 9-row atlas (192×208 cells) generated by the [hatch-pet](https://github.com/dsh2026) pipeline; below are previews of each state:
@@ -37,53 +69,57 @@ The sprites are an 8-column × 9-row atlas (192×208 cells) generated by the [ha
 
 ## Architecture
 
-```
+```text
 dsh-pet/
 |-- src/
-|   |-- index.ts        # host half: plugin entry (cordis apply, route registration)
-|   |-- service.ts      # PetService: pet state machine + affinity + config (HTTP API service face)
-|   |-- state.ts        # pet state machine: projected session activity → 9 state animations
-|   |-- affinity.ts     # affinity ledger (pure functions + cooldowns)
-|   |-- treats.ts       # dried-fish stock ledger
-|   |-- persist.ts      # persistence ($DSH_HOME/pet.json, atomic write)
-|   |-- routes.ts       # /api/pet/* JSON API + /pet/whale/* static asset routes
-|   `-- client/         # browser half
-|       |-- index.ts    # global mount (createRoot → body) + polling (800ms) + interaction wiring (fetch)
-|       |-- PetDockEntry.tsx  # global floating entry (document.body, always shown: no session / new session / mid-session)
-|       |-- WhalePet.tsx      # floating component (portal + rAF frame animation + dragging)
-|       |-- spritesheet.ts    # atlas geometry + per-state animation tracks (frames/duration)
+|   |-- index.ts             # host half: plugin entry (registry build, settings section, routes)
+|   |-- registry.ts          # multi-pet contract: manifest scan + normalization (assets + custom pets)
+|   |-- service.ts           # PetService: pet selection + state machine + affinity + config
+|   |-- state.ts             # pet state machine: projected session activity → 9 state animations
+|   |-- affinity.ts          # affinity ledger (pure functions + cooldowns)
+|   |-- treats.ts            # dried-fish stock ledger
+|   |-- persist.ts           # persistence ($DSH_HOME/pet.json: selection + per-pet names, atomic write)
+|   |-- routes.ts            # /api/pet/* JSON API + /pet/<id>/* asset routes
+|   `-- client/             # browser half
+|       |-- index.ts         # global mount (createRoot → body) + registry fetch + polling + wiring
+|       |-- PetDockEntry.tsx # global floating entry (document.body, always shown)
+|       |-- PetSprite.tsx    # definition-driven floating sprite (portal + rAF + dragging)
+|       |-- PetSettingsCard.tsx # settings card: pet selector + display layout
+|       |-- spritesheet.ts   # atlas geometry helpers + track trimming
 |       `-- pet.module.css
-|-- assets/whale/       # whale-girl assets (pet.json + spritesheet.webp + animation previews)
-`-- cordis.patch.yml    # bundle patch: inserts the pet plugin row
+|-- assets/whale/            # built-in whale-girl (pet.json + spritesheet.webp + previews)
+`-- cordis.patch.yml         # bundle patch: inserts the pet plugin row
 ```
 
 ### Data flow
 
-```
+```text
 official session events (turn/step/chunk/tool) ----\
-                                                    > PetService (host)
+                                                    > PetService (host) <-- registry (assets + custom pets)
 optional legacy activity/status ------------------/
                                                               | /api/pet/* JSON
-global React root (createRoot → document.body) <-- polling 800ms -- pet-client (browser)
+global React root (createRoot → document.body) <-- polling 2s -- pet-client (browser)
                                                               |
-                                                   WhalePet floating layer (portal + rAF)
+                                       PetSprite floating layer (portal + rAF)
 ```
 
 - **Status source**: the host projects official `turn/start`, `step/start`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, and `turn/end` events into waiting/thinking/tool/review/done/failed states. Optional legacy `activity/status` events remain a compatibility input.
+- **Registry**: the host normalizes every manifest into a full render definition (geometry, per-row frame counts, per-track durations) and serves it over `/api/pet/pets`; the browser half renders any entry from that definition and carries no per-pet code.
+- **Selection & naming**: `petId` lives in the settings namespace; per-pet names live in `pet.json` under `names`, edited through the hover-panel rename of the active pet. Legacy installs migrate their flat `name` onto the whale girl.
 - **Multi-session semantics**: the API and browser mount are host-global and expose no foreground-session identity, so the most recent meaningful event wins the display. Every session's completed turns are still rewarded independently, and disposing a non-current session does not reset the visible state.
 - **Mount point**: `document.body` (global React root, always shown: no session / new session / mid-session — the old mount point `conversation.composer.dock` only rendered in an active session, hiding the pet in new sessions); the component uses `createPortal` internally to render the global floating layer.
-- **Rendering**: CSS sprite (background-position) per-frame animation, frame durations from the track definitions in `spritesheet.ts`.
-- **Communication**: browser ↔ host over the same-origin `/api/pet/*` JSON endpoints (state/interact/set-visible/set-config); the atlas loads from `/pet/whale/spritesheet.webp` — both the RPC domain and the `/plugins/` static service are platform-registered, and the plugin self-sufficiently provides its own API and assets (the same pattern as dsh-remote-web-ui's `/api/pair`).
+- **Rendering**: CSS sprite (background-position) per-frame animation; frame durations come from the served definition's tracks.
+- **Communication**: browser ↔ host over the same-origin `/api/pet/*` JSON endpoints (state/pets/interact/set-visible/set-config/set-name/set-pet); each pet's atlas loads from `/pet/<id>/<spritesheetPath>` — the plugin self-sufficiently provides its own API and assets (the same pattern as dsh-remote-web-ui's `/api/pair`).
 
 ## Install
 
 Install the family aggregate package `@linxin666/dsh-web-ui-all` (all plugins and skins in one) or this plugin alone:
 
 ```sh
-### 从 npm 安装（推荐）
+### From npm (recommended)
 dsh plugin --profile web add @linxin666/dsh-pet
 
-### 从仓库安装（开发调试）
+### From the repository (development)
 git clone https://github.com/zhu1090093659/dsh-web-ui.git
 cd dsh-web-ui
 pnpm install && pnpm -r build
@@ -91,13 +127,13 @@ dsh plugin --profile web add link:$(pwd)/packages/dsh-pet
 
 ```
 
-After installing, **restart `dsh web`** — the whale-girl appears at the bottom-right of the interface. In link mode, `pnpm build` and refresh the page after a code change; no reinstall needed.
+After installing, **restart `dsh web`** — your selected pet appears at the bottom-right of the interface. In link mode, `pnpm build` and refresh the page after a code change; no reinstall needed.
 
 ## Development
 
 ```sh
 pnpm build        # tsc -b (types+declarations) && tsdown (node half + browser bundle)
-pnpm test         # vitest unit/component tests (event projection / state / UI / ledgers)
+pnpm test         # vitest unit/component tests (registry / event projection / state / UI / ledgers)
 pnpm prepare      # transpile-only build (no type checking, for consumer installs)
 pnpm typecheck    # type check only
 ```
@@ -106,9 +142,8 @@ The browser bundle rides the `window.__ModuleLoader__.load` contract; React/cord
 
 ## Sprites and animation-track calibration
 
-The whale-girl atlas is generated by the hatch-pet pipeline as 9 states × 8 columns: `assets/whale/spritesheet.webp` (1536×1872, 8 columns × 9 rows of 192×208 cells) + `assets/whale/pet.json`. The actual frame count and rhythm of each row are defined in `TRACKS` in `src/client/spritesheet.ts`. If the artwork is redone and the frame count changes, only that table needs updating (row-order contract: 0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review).
+The built-in whale-girl atlas is generated by the hatch-pet pipeline as 9 states × 8 columns: `assets/whale/spritesheet.webp` (1536×1872, 8 columns × 9 rows of 192×208 cells) + `assets/whale/pet.json`. The frame count and rhythm of each row live in that manifest's `frames` and `tracks` fields — the whale girl carries its own slower healing durations, while pets without overrides follow the hatch-pet contract rhythm. Redoing artwork therefore only edits `assets/whale/pet.json` (row-order contract: 0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review).
 
 ## License
 
 [BSD-3-Clause](LICENSE)
-

package/README.zh.md

@@ -1,83 +1,119 @@
-# dsh-pet — 鲸鱼娘宠物插件
+# dsh-pet — 多宠物伴侣插件
 
 [English](README.md) | 中文
 
-> 一只软萌治愈的鲸鱼娘，陪你在 DeepSeek Harness 里工作。
+> 一个注册表驱动的桌面伴侣：内置鲸鱼娘，也接受你放入的任何宠物。
 
-模型思考的时候你在等，她在游。她会跟随官方会话活动，在等待、思考、使用工具、整理回复、庆祝完成或报告失败时切换动画；你还可以摸头、喂小鱼干，看着她从幼鲸慢慢长成你的深海羁绊。
+模型思考时你在等待，你的宠物在游动。它跟随官方会话活动，在等待、思考、调用工具、整理回复、庆祝完成、报告失败时切换动画；你还可以摸摸它的头、喂它小鱼干，看着亲密度一点点成长。宠物是注册表条目而不是代码：每只宠物只需一份 `pet.json` manifest 加一张图集，宿主启动时自动发现。
 
-复刻自 Codex 桌面版的宠物功能，以 DSH 官方插件形态实现（cordis bundle：host 半区 + client 半区单包）。
+从 Codex 桌面应用的宠物功能重新实现，采用官方 DSH 插件形态（cordis bundle：host 半区 + client 半区，一个包）。
 
 ## 功能
 
 | 功能 | 说明 |
 |---|---|
-| 状态动画 | 官方会话活动 → 鲸鱼娘动画：`thinking → running`、`tool → running-right`、`review → review`、`waiting → waiting`、`done → jumping`、`failed → failed` |
-| 摸头互动 | 点击鲸鱼娘 → 气泡反馈 + 亲密度 +1（10s 冷却） |
-| 喂食 | 悬浮面板「喂食」→ 消耗 1 条小鱼干 + 亲密度 +5（30s 冷却） |
-| 饲料经济 | 小鱼干库存（上限 20）：工作每 3 回合 +1 条、每 30 分钟 +1 条；库存不足会提示「多陪鲸鱼娘工作一会儿」 |
-| 亲密度 | 每完成一个回合 +1；4 个等级：幼鲸 → 伙伴 → 挚友 → 深海羁绊（100 点封顶） |
-| 自定义命名 | 悬浮面板「改名」→ 1–20 字符，持久化，召唤按钮/面板同步显示 |
-| 拖动 | 按住鲸鱼娘拖动重新摆放，位置持久化 |
-| 隐藏/召唤 | 悬浮面板「隐藏」；隐藏后输入选择行出现「召唤{名字}」按钮 |
-| 状态气泡 | 显示当前会话阶段或工具名；短暂的交互反馈会临时优先显示 |
-| 多会话活动 | 宠物是 host 全局的：最近一条有效事件决定显示，所有会话的完成回合都会计入亲密度与小鱼干 |
-
-## 动画演示
-
-素材为 8 列 × 9 行图集（192×208 单元），由 [hatch-pet](https://github.com/dsh2026) 流水线生成，以下为各状态动画预览：
-
-| idle 待机 | waiting 等待 | running 干活 | jumping 庆祝 |
+| 多宠物注册表 | 宿主扫描内置 `assets/`、hatch-pet 自定义宠物目录和组合配置条目；每只宠物 = manifest + 图集 |
+| 设置中选择宠物 | 插件设置卡片列出所有已注册宠物；切换即持久化，精灵立即更换 |
+| 每只宠物独立命名 | 在悬浮面板改名；每只宠物保存自己的名字（按宠物 id 存储，旧版平铺名字自动迁移） |
+| 状态动画 | 官方会话活动 → 9 态动画：`thinking → running`、`tool → running-right`、`review → review`、`waiting → waiting`、`done → jumping`、`failed → failed` |
+| 摸头互动 | 点击宠物 → 气泡反馈 + 亲密度 +1（10s 冷却） |
+| 喂食 | 悬浮面板 喂食 → 消耗 1 条小鱼干 + 亲密度 +5（30s 冷却） |
+| 小鱼干经济 | 库存（上限 20）：每工作 3 轮 +1，每 30 分钟 +1 |
+| 亲密度 | 每完成一轮 +1；4 级：幼鲸 → 伙伴 → 挚友 → 深海羁绊（上限 100） |
+| 拖动 | 按住拖动宠物换位置；位置持久化 |
+| 隐藏/召唤 | 悬浮面板 隐藏；隐藏后出现 召唤{name} 按钮 |
+| 状态气泡 | 显示当前会话阶段或工具名；瞬时互动反馈临时优先 |
+| 多会话活动 | 宠物是宿主全局的：最近一次有意义事件驱动显示，每个会话完成的轮次都计入亲密度与小鱼干 |
+
+## 宠物契约
+
+一只宠物 = 一个目录 + 一份 `pet.json` manifest + 一张图集。除此之外什么都不需要——不用改任何宿主或客户端代码。
+
+```jsonc
+{
+  "id": "whale-girl",                     // 唯一的小写 kebab id
+  "displayName": "鲸鱼娘",                 // 显示在设置选择器与面板上
+  "description": "一只软萌治愈的鲸鱼娘。",     // 可选
+  "spritesheetPath": "spritesheet.webp",   // 图集，相对 manifest 所在目录
+  "cell": { "width": 192, "height": 208 }, // 可选；默认 Codex 契约
+  "columns": 8,                            // 可选；默认 8
+  "frames": [6, 8, 8, 4, 5, 8, 6, 6, 6],   // 可选的每行帧数
+  "tracks": {                              // 可选的每轨节奏覆盖
+    "idle": { "durations": [400, 400, 500, 400, 400, 500] }
+  }
+}
+```
+
+- 图集是 8 列 × 9 行网格（默认 192×208 单元格）；行序固定：0 idle、1 running-right、2 running-left、3 waving、4 jumping、5 failed、6 waiting、7 running、8 review。未使用的格子保持全透明。
+- `frames` 记录每行用到的列数（缺省按 hatch-pet 契约表 `[6, 8, 8, 4, 5, 8, 6, 6, 6]`）；`tracks` 按动画覆盖每帧时长（按该行帧数循环补足）、`loop` 与 `fallback`（默认：全部循环；`jumping` 与 `failed` 停在最后一帧后回到 `idle`）。
+
+宠物的来源（后注册的来源在同 id 冲突时覆盖前者）：
+
+1. **内置**：本包 `assets/<dir>/pet.json`。
+2. **自定义宠物**：`${CODEX_HOME:-~/.codex}/pets/<pet>/pet.json` —— hatch-pet 流水线把产物放在这里，孵化的宠物无需任何接线即可出现在选择器里。
+3. **组合注入**：嵌入应用通过 `PetConfig.pets` 传入的 manifest 条目。
+
+注册表在宿主启动时构建一次；新增或修改宠物后重启 `dsh web` 生效。
+
+## 动画预览
+
+精灵图是由 [hatch-pet](https://github.com/dsh2026) 流水线生成的 8 列 × 9 行图集（192×208 单元格）；各状态预览：
+
+| idle | waiting | running | jumping |
 |---|---|---|---|
 | ![idle](assets/whale/previews/idle.gif) | ![waiting](assets/whale/previews/waiting.gif) | ![running](assets/whale/previews/running.gif) | ![jumping](assets/whale/previews/jumping.gif) |
 
-| waving 挥手 | review 复盘 | failed 失败 | 左右移动 |
+| waving | review | failed | 左右移动 |
 |---|---|---|---|
 | ![waving](assets/whale/previews/waving.gif) | ![review](assets/whale/previews/review.gif) | ![failed](assets/whale/previews/failed.gif) | ![running-left](assets/whale/previews/running-left.gif) ![running-right](assets/whale/previews/running-right.gif) |
 
 ## 架构
 
-```
+```text
 dsh-pet/
 |-- src/
-|   |-- index.ts        # host 半区：插件入口（cordis apply，注册路由）
-|   |-- service.ts      # PetService：宠物状态机 + 亲密度 + 配置（HTTP API 服务面）
-|   |-- state.ts        # 宠物状态机：投影后的会话活动 → 9 状态动画
-|   |-- affinity.ts     # 亲密度账本（纯函数 + 冷却）
-|   |-- treats.ts       # 小鱼干库存账本
-|   |-- persist.ts      # 持久化（$DSH_HOME/pet.json，原子写入）
-|   |-- routes.ts       # /api/pet/* JSON API + /pet/whale/* 素材静态路由
-|   `-- client/         # 浏览器半区
-|       |-- index.ts    # 全局挂载（createRoot → body）+ 轮询（800ms）+ 交互接线（fetch）
-|       |-- PetDockEntry.tsx  # 全局浮层入口（document.body，无会话/新会话/会话中全程显示）
-|       |-- WhalePet.tsx      # 浮层组件（portal + rAF 帧动画 + 拖动）
-|       |-- spritesheet.ts    # 图集几何 + 每状态动画轨道（帧/时长）
+|   |-- index.ts             # host 半区：插件入口（构建注册表、设置区、路由）
+|   |-- registry.ts          # 多宠物契约：manifest 扫描 + 归一化（内置 + 自定义宠物）
+|   |-- service.ts           # PetService：宠物选择 + 状态机 + 亲密度 + 配置
+|   |-- state.ts             # 宠物状态机：会话活动投影 → 9 态动画
+|   |-- affinity.ts          # 亲密度账本（纯函数 + 冷却）
+|   |-- treats.ts            # 小鱼干库存账本
+|   |-- persist.ts           # 持久化（$DSH_HOME/pet.json：选择 + 每宠物名字，原子写入）
+|   |-- routes.ts            # /api/pet/* JSON API + /pet/<id>/* 静态资源路由
+|   `-- client/             # 浏览器半区
+|       |-- index.ts         # 全局挂载（createRoot → body）+ 注册表拉取 + 轮询 + 接线
+|       |-- PetDockEntry.tsx # 全局浮层入口（document.body，始终显示）
+|       |-- PetSprite.tsx    # 由定义驱动的浮层精灵（portal + rAF + 拖动）
+|       |-- PetSettingsCard.tsx # 设置卡片：宠物选择器 + 显示布局
+|       |-- spritesheet.ts   # 图集几何辅助 + 轨道裁剪
 |       `-- pet.module.css
-|-- assets/whale/       # 鲸鱼娘素材（pet.json + spritesheet.webp + 动画预览）
-`-- cordis.patch.yml    # bundle patch：插入 pet 插件行
+|-- assets/whale/            # 内置鲸鱼娘（pet.json + spritesheet.webp + 预览）
+`-- cordis.patch.yml         # bundle 补丁：插入宠物插件行
 ```
 
 ### 数据流
 
-```
-官方会话事件（turn/step/chunk/tool） ----\
-                                                    > PetService（host）
-可选的兼容事件 activity/status --------------/
+```text
+官方会话事件（turn/step/chunk/tool）----\
+                                                    > PetService（宿主）<-- 注册表（内置 + 自定义宠物）
+可选兼容 activity/status ------------------/
                                                               | /api/pet/* JSON
-global React root（createRoot → document.body） <-- 轮询 800ms -- pet-client（浏览器）
+全局 React 根（createRoot → document.body）<-- 2s 轮询 -- pet-client（浏览器）
                                                               |
-                                                   WhalePet 浮层（portal + rAF）
+                                       PetSprite 浮层（portal + rAF）
 ```
 
-- **状态源**：host 将官方 `turn/start`、`step/start`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result` 和 `turn/end` 事件投影为 waiting/thinking/tool/review/done/failed 状态。可选的旧版 `activity/status` 事件仍作为兼容输入。
-- **多会话语义**：API 和浏览器挂载是 host 全局的，也不提供前台会话标识，因此最近一条有效事件决定显示。各会话的完成回合仍独立奖励，销毁非当前会话不会重置可见状态。
-- **挂载点**：`document.body`（全局 React root，无会话/新会话/会话中全程显示——旧挂载点 `conversation.composer.dock` 只在活跃会话渲染，导致新会话界面看不到宠物），组件内部 `createPortal` 渲染全局浮层。
-- **渲染**：CSS sprite（background-position）逐帧动画，帧时长来自 `spritesheet.ts` 的轨道定义。
-- **通信**：浏览器 ↔ host 走同源 `/api/pet/*` JSON 端点（state/interact/set-visible/set-config），图集从 `/pet/whale/spritesheet.webp` 加载——RPC 域与 `/plugins/` 静态服务都是平台注册的，插件自足地提供自己的 API 与素材（与 dsh-remote-web-ui 的 `/api/pair` 同一模式）。
+- **状态来源**：宿主把官方 `turn/start`、`step/start`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`turn/end` 事件投影为 waiting/thinking/tool/review/done/failed 状态。可选兼容 `activity/status` 事件仍作为输入。
+- **注册表**：宿主把每份 manifest 归一化为完整渲染定义（几何、每行帧数、每轨时长），经 `/api/pet/pets` 下发；浏览器半区用该定义渲染任意条目，不携带任何宠物专属代码。
+- **选择与命名**：`petId` 存于设置命名空间；每只宠物的名字存于 `pet.json` 的 `names`，通过悬浮面板对当前宠物改名编辑。旧版安装的平铺 `name` 自动迁移到鲸鱼娘名下。
+- **多会话语义**：API 与浏览器挂载都是宿主全局的，不暴露前台会话身份，最近一次有意义事件赢得显示；每个会话完成的轮次仍独立计奖，销毁非当前会话不会重置可见状态。
+- **挂载点**：`document.body`（全局 React 根，始终显示：无会话 / 新会话 / 会话中都可见——旧挂载点 `conversation.composer.dock` 只在活动会话里渲染，新会话里宠物消失）；组件内部用 `createPortal` 渲染全局浮层。
+- **渲染**：CSS 精灵（background-position）逐帧动画；帧时长来自下发定义里的轨道表。
+- **通信**：浏览器 ↔ 宿主走同源 `/api/pet/*` JSON 端点（state/pets/interact/set-visible/set-config/set-name/set-pet）；每只宠物的图集从 `/pet/<id>/<spritesheetPath>` 加载——插件自给自足地提供自己的 API 与资源（与 dsh-remote-web-ui 的 `/api/pair` 同一模式）。
 
 ## 安装
 
-推荐直接安装全家桶聚合包 `@linxin666/dsh-web-ui-all`（一个包装齐全部功能插件与皮肤），或单独安装本插件：
+安装聚合全家桶 `@linxin666/dsh-web-ui-all`（全部插件与皮肤一次到位），或单独安装本插件：
 
 ```sh
 ### 从 npm 安装（推荐）
@@ -91,23 +127,23 @@ dsh plugin --profile web add link:$(pwd)/packages/dsh-pet
 
 ```
 
-安装后**重启 `dsh web`**，鲸鱼娘出现在界面右下角即生效。link 模式下改代码后重新 `pnpm build` 并刷新页面即可，无需重装。
+安装后**重启 `dsh web`**——你选择的宠物出现在界面右下角。link 模式下改代码后 `pnpm build` 并刷新页面即可，无需重装。
 
 ## 开发
 
 ```sh
 pnpm build        # tsc -b（类型+声明）&& tsdown（node 半区 + 浏览器 bundle）
-pnpm test         # vitest 单元/组件测试（事件投影 / state / UI / 账本）
-pnpm prepare      # 仅转译构建（无类型检查，供消费者安装）
+pnpm test         # vitest 单元/组件测试（注册表 / 事件投影 / 状态 / UI / 账本）
+pnpm prepare      # 仅转译构建（不做类型检查，供消费者安装）
 pnpm typecheck    # 仅类型检查
 ```
 
-浏览器 bundle 走 `window.__ModuleLoader__.load` 契约，React/cordis 等由 loader 模块表解析（external）；CSS Modules 由 lightningcss 内联为 `<style data-plugin>`。
+浏览器 bundle 走 `window.__ModuleLoader__.load` 契约；React/cordis 等从 loader 模块表解析（external）；CSS Modules 由 lightningcss 以内联 `<style data-plugin>` 编译进 bundle。
 
-## 素材与动画轨道校准
+## 精灵图与动画轨道校准
 
-鲸鱼娘图集由 hatch-pet 流水线按 9 状态 × 8 列生成：`assets/whale/spritesheet.webp`（1536×1872，8 列 × 9 行 192×208 单元）+ `assets/whale/pet.json`。每行实际帧数与节奏在 `src/client/spritesheet.ts` 的 `TRACKS` 中定义。若素材重做导致帧数变化，只需更新该表（行序契约：0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review）。
+内置鲸鱼娘图集由 hatch-pet 流水线生成，9 态 × 8 列：`assets/whale/spritesheet.webp`（1536×1872，8 列 × 9 行，192×208 单元格）+ `assets/whale/pet.json`。每行的帧数与节奏就写在该 manifest 的 `frames` 与 `tracks` 字段里——鲸鱼娘带着自己更慢的治愈系时长，未覆盖的宠物沿用 hatch-pet 契约节奏。重做美术因此只需修改 `assets/whale/pet.json`（行序契约：0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review）。
 
-## License
+## 许可证
 
 [BSD-3-Clause](LICENSE)

package/assets/whale/pet.json

@@ -3,5 +3,16 @@
   "displayName": "鲸鱼娘",
   "description": "一只软萌治愈的鲸鱼娘，来自深海的陪伴小伙伴。",
   "spritesheetPath": "spritesheet.webp",
-  "frames": [6, 8, 8, 4, 5, 8, 6, 6, 6]
+  "frames": [6, 8, 8, 4, 5, 8, 6, 6, 6],
+  "tracks": {
+    "idle": { "durations": [400, 400, 500, 400, 400, 500] },
+    "running-right": { "durations": [225, 225, 225, 225, 225, 225, 225, 225] },
+    "running-left": { "durations": [225, 225, 225, 225, 225, 225, 225, 225] },
+    "waving": { "durations": [350, 350, 350, 350] },
+    "jumping": { "durations": [300, 300, 300, 350, 350] },
+    "failed": { "durations": [450, 450, 450, 500, 550, 600, 450, 450] },
+    "waiting": { "durations": [450, 450, 500, 450, 450, 500] },
+    "running": { "durations": [250, 250, 250, 250, 250, 250] },
+    "review": { "durations": [550, 550, 550, 550, 550, 550] }
+  }
 }

package/cordis.patch.yml

@@ -1,10 +1,10 @@
 # dsh-pet bundle patch: inserts its plugin row into the web plugin roster.
 # The bundle is the official dsh plugin shape — install it into a dsh profile
 # (`dsh plugin --profile <name> add link:/Users/zcl/code/dsh-web-ui/packages/dsh-pet`). The single
-# row mounts BOTH halves: the host side (pet state machine, affinity score,
-# pet.* RPC service) and the browser side (the modules node half scans
-# dsh.client packages into the web plugin roster, served from this package's
-# lib/client.js plus the whale assets under assets/whale).
+# row mounts BOTH halves: the host side (pet registry, state machine,
+# affinity score, pet.* RPC service) and the browser side (the modules node
+# half scans dsh.client packages into the web plugin roster, served from this
+# package's lib/client.js plus the built-in pet assets under assets/).
 - insert:
     - id: pet
       name: '@linxin666/dsh-pet'