@linxin666/dsh-pet 0.2.1 → 0.2.3

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: 21245dc766ce4b58319a1c7087f3dba1a6b81a9d
-README.zh.md: 51b5c89489893197c8d691b843161a5334b2d8fd
+README.md: 9470df0da7fc9b8cdf0c3816d792a842f17a769c
+README.zh.md: 76fa58171d7c49d04da4e6663d7010e6662408e4

package/README.md

@@ -59,13 +59,77 @@ A pet is a directory holding one `pet.json` manifest and one atlas image. Nothin
 - `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`).
 - `sequences` optionally maps activity scenes (`idle` / `waiting` / `thinking` / `tool` / `review` / `done` / `failed`) to at least 5 animation tracks. Each item plays every frame for the durations in `tracks`, then the next item starts; the complete sequence loops. An omitted scene keeps its canonical single-track playback.
 
+### Manifest v2 (pet center, #623)
+
+A pet directory's `pet.json` declares its renderer explicitly in v2:
+
+- `petManifestVersion: 2` (absent = v1, compat-read as `sprite2d` with a migration hint);
+- `renderer`: `"sprite2d"` (the atlas contract above) or `"live2d"`;
+- `license` (required in v2): asset license identifier — community pets carry provenance;
+- a renderer block: `sprite2d` (spritesheetPath/cell/columns/atlasRows/frames/tracks) or `live2d` (model/motions/expressions/hitAreas/scale/translate).
+
+Validation is fail-closed on structure (unknown fields or renderer kinds reject the entry with a diagnostic) and warn-and-drop on sequence/remark content. The machine-readable schema lives at `contracts/pet-manifest-v2.schema.json`; the authoritative validator is `src/manifest-v2.ts`. Migrate v1 manifests with `node scripts/dsh-pet-migrate-v2.mjs <dir> --write` (dry-run by default; keeps `pet.json.v1.bak`).
+
 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.
+2. **Legacy 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. **Pet-center user directory**: `$DSH_HOME/pets/<id>/` — the recommended home for your pets (see the CLI below).
+4. **Composed**: `PetConfig.pets` manifest entries passed to the plugin by the embedding application.
+
+Validate and install a pet directory with the CLI (no build step, no npm publish):
+
+```sh
+node scripts/dsh-pet validate <dir>           # manifest + assets + Live2D reference closure
+node scripts/dsh-pet install <dir>            # validate, then copy into $DSH_HOME/pets/<id>/
+node scripts/dsh-pet install <dir> --force    # overwrite an existing same-id install
+```
+
+Invalid entries never override a working pet: they are skipped with a diagnostic listed in the settings (Pet section). The registry is built once at host startup; add or change a pet, then restart `dsh web`.
+
+## Live2D pets (renderer: live2d)
+
+Live2D pets render through PixiJS/WebGL: the MIT pixi.js + untitled-pixi-live2d-engine stack ships inside this plugin as a lazily loaded vendor bundle, so sprite-only installations never download or parse it. **The Cubism Core runtime is never bundled or downloaded by this plugin** — Live2D's proprietary license forbids redistributing it. To enable a Live2D pet:
+
+1. Obtain the official Live2D Cubism SDK for Web yourself (you accept Live2D's license) and take `live2dcubismcore.min.js` from it.
+2. Place it at `$DSH_HOME/pets/.runtime/live2dcubismcore.min.js` — the plugin serves it to the page from there, alongside its own vendor bundle.
+3. Install a Live2D pet (a directory with `pet.json` v2, `renderer: "live2d"`, and the model files).
+
+If the core is absent, a Live2D pet shows an install-guidance card where the model would render; sprite2d pets are unaffected. Legal note: this plugin is an "extensible application" in Live2D's terms — works you publish with user-loadable models may require a Live2D release license regardless of scale; evaluate your obligations before publishing derivative works.
 
-The registry is built once at host startup; add or change a pet, then restart `dsh web`.
+A Live2D manifest maps the seven activity phases onto the model's motion groups:
+
+```json
+{
+  "petManifestVersion": 2,
+  "id": "my-live2d-pet",
+  "displayName": "My Live2D Pet",
+  "license": "CC0-1.0",
+  "renderer": "live2d",
+  "live2d": {
+    "model": "model/my-pet.model3.json",
+    "motions": { "idle": "Idle", "thinking": "Think", "failed": "TapBody" },
+    "hitAreas": ["Body"]
+  }
+}
+```
+
+- `model`: the `.model3.json` path relative to the pet directory. Every file the model references (moc, textures, motions, physics, pose, expressions) must live inside the directory — the host serves exactly that reference closure.
+- `motions` (required, `idle` mandatory): phase → motion group. Unmapped phases and groups the model lacks fall back to `idle`; a group holding several motions plays a random one. The official Cubism sample models ship only `Idle` and `TapBody` groups.
+- `expressions` (optional): phase → expression name, layered over the motion.
+- `hitAreas` (optional): a tap landing on a listed hit area plays the model's `TapBody` group, then returns to the phase's group. Every tap still counts as petting — the chrome owns interactions exactly like sprite2d.
+- `scale` / `translate` (optional): the model auto-fits the display box; `scale` multiplies the fit (default 1, range (0, 10]) and `translate` offsets it in px from the center.
+
+Model licensing: the official Live2D sample models (Hiyori, Haru, and friends) are evaluation-only and must not be redistributed — ship only models you have rights to (original creations or permissively licensed ones).
+
+## Built-in pets
+
+| Registry id | Selector label | Source |
+|---|---|---|
+| `whale-girl` | 鲸鱼娘（原版） | The repository's original whale-girl atlas |
+| `whale-girl-refined` | 鲸鱼娘（精致版） | An AI-assisted derivative with repaired and refined details, based on the whale-girl design direction |
+
+The refined variant references DreamSkin's “DeepSeek-Whale” theme. The historical source record identifies `powerdog996` as the original theme author and marks the theme as MIT: [DreamSkin](https://dreamskin.cc), [repository source record](https://github.com/zhu1090093659/dsh-web-ui/commit/87edd7ff4800dffd40bc93fb76e4ae450390facd). This attribution records the source and derivative relationship; it does not present the refined variant as an official work of the original author or redefine the original artwork's licensing scope.
 
 ## Animation preview
 
@@ -101,7 +165,8 @@ dsh-pet/
 |       |-- sequences.ts     # full-track scene sequence timing
 |       |-- spritesheet.ts   # atlas geometry helpers + track trimming
 |       `-- pet.module.css
-|-- assets/whale/            # built-in whale-girl (pet.json + spritesheet.webp + previews)
+|-- assets/whale/            # built-in original whale-girl (manifest + atlas + previews)
+|-- assets/whale-refined/    # built-in refined whale-girl registry variant
 `-- cordis.patch.yml         # bundle patch: inserts the pet plugin row
 ```
 
@@ -156,7 +221,15 @@ The browser bundle rides the `window.__ModuleLoader__.load` contract; React/cord
 
 ## Sprites and animation-track calibration
 
-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, rhythm, and scene rotation live in that manifest's `frames`, `tracks`, and `sequences` fields; pets without overrides follow the hatch-pet contract rhythm and canonical single-track scene mapping. 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).
+The two built-in whale-girl atlases use the same 9-state × 8-column contract: `assets/whale/` is the original and `assets/whale-refined/` is the refined variant. Each atlas is 1536×1872 (8 columns × 9 rows of 192×208 cells). Frame counts, rhythm, and scene rotation live in each directory's `pet.json`; pets without overrides follow the hatch-pet contract rhythm and canonical single-track scene mapping (row order: 0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review).
+
+## Security model
+
+- All pet API and asset routes are fenced to loopback clients.
+- Asset serving resolves both the pet directory and the candidate file through `realpath`; symlink escapes are refused (403). Files are size-capped before being read into memory (manifest 64 KB, imagery 20 MB; over-cap answers 413).
+- Live2D models are served by closure: only the manifest, the declared primary assets, and the files the `.model3.json` references (each screened against traversal, absolute and URL forms).
+- The plugin never downloads executables and never bundles the Live2D Cubism Core.
+- Manifests are fail-closed on structure: unknown fields or renderers reject the entry with a diagnostic shown in settings.
 
 ## License
 

package/README.zh.md

@@ -59,13 +59,77 @@
 - `frames` 记录每行用到的列数（缺省按 hatch-pet 契约表 `[6, 8, 8, 4, 5, 8, 6, 6, 6]`）；`tracks` 按动画覆盖每帧时长（按该行帧数循环补足）、`loop` 与 `fallback`（默认：全部循环；`jumping` 与 `failed` 停在最后一帧后回到 `idle`）。
 - `sequences` 可选地把活动场景（`idle` / `waiting` / `thinking` / `tool` / `review` / `done` / `failed`）映射到至少 5 条动画轨道。每项按 `tracks` 中的时长播完所有帧后进入下一项，整条序列循环；未声明的场景保持标准单轨播放。
 
+### 清单 v2（宠物中心，#623）
+
+宠物目录的 `pet.json` 在 v2 中显式声明渲染器：
+
+- `petManifestVersion: 2`（缺省 = v1，按 `sprite2d` 兼容读并给出迁移提示）；
+- `renderer`：`"sprite2d"`（上文图集契约）或 `"live2d"`；
+- `license`（v2 必填）：资产授权标识——社区宠物必须携带来源声明；
+- 渲染器专属块：`sprite2d`（spritesheetPath/cell/columns/atlasRows/frames/tracks）或 `live2d`（model/motions/expressions/hitAreas/scale/translate）。
+
+校验纪律：结构 fail-closed（未知字段或未知渲染器直接拒载并给出诊断），sequences/remarks 内容维持 warn-and-drop。机器可读 schema 见 `contracts/pet-manifest-v2.schema.json`，权威校验器为 `src/manifest-v2.ts`。迁移 v1 清单：`node scripts/dsh-pet-migrate-v2.mjs <dir> --write`（默认 dry-run；保留 `pet.json.v1.bak`）。
+
 宠物的来源（后注册的来源在同 id 冲突时覆盖前者）：
 
 1. **内置**：本包 `assets/<dir>/pet.json`。
-2. **自定义宠物**：`${CODEX_HOME:-~/.codex}/pets/<pet>/pet.json` —— hatch-pet 流水线把产物放在这里，孵化的宠物无需任何接线即可出现在选择器里。
-3. **组合注入**：嵌入应用通过 `PetConfig.pets` 传入的 manifest 条目。
+2. **legacy 自定义宠物**：`${CODEX_HOME:-~/.codex}/pets/<pet>/pet.json` —— hatch-pet 流水线把产物放在这里，孵化的宠物无需任何接线即可出现在选择器里。
+3. **宠物中心用户目录**：`$DSH_HOME/pets/<id>/`——推荐安放位（见下方 CLI）。
+4. **组合注入**：嵌入应用通过 `PetConfig.pets` 传入的 manifest 条目。
+
+用 CLI 校验并安装宠物目录（零构建、零发布）：
+
+```sh
+node scripts/dsh-pet validate <dir>           # 清单 + 资产 + Live2D 引用闭包
+node scripts/dsh-pet install <dir>            # 校验通过后拷入 $DSH_HOME/pets/<id>/
+node scripts/dsh-pet install <dir> --force    # 覆盖同名已安装宠物
+```
+
+非法条目永不覆盖可用宠物：它们被跳过并在设置（宠物栏目）给出诊断。注册表在宿主启动时构建一次；新增或修改宠物后重启 `dsh web` 生效。
+
+## Live2D 宠物（renderer: live2d）
+
+Live2D 宠物经 PixiJS/WebGL 渲染：MIT 许可的 pixi.js + untitled-pixi-live2d-engine 栈以按需加载的 vendor 分包随插件内置，纯 sprite 用户永不下载、永不解析它。**本插件永不内置、永不代下 Cubism Core 运行时**——Live2D 专有许可不允许再分发。启用 Live2D 宠物：
+
+1. 自行从 Live2D 官方渠道获取 Cubism SDK for Web（你自行同意其许可），取得 `live2dcubismcore.min.js`；
+2. 放到 `$DSH_HOME/pets/.runtime/live2dcubismcore.min.js`——插件把它连同自带的 vendor 分包一起提供给页面；
+3. 安装 Live2D 宠物（含 `pet.json` v2、`renderer: "live2d"` 与模型文件的目录）。
+
+core 缺失时，Live2D 宠物在渲染位置给出安装指引卡；sprite2d 宠物不受影响。法律提示：本插件属 Live2D 术语下的「可扩展性 APP」——你公开发布基于可加载用户模型的衍生作品时，可能不论规模都须与 Live2D 签订发行许可；发布前请自行评估义务。
 
-注册表在宿主启动时构建一次；新增或修改宠物后重启 `dsh web` 生效。
+Live2D 清单把七个活动相位映射到模型的动作组：
+
+```json
+{
+  "petManifestVersion": 2,
+  "id": "my-live2d-pet",
+  "displayName": "My Live2D Pet",
+  "license": "CC0-1.0",
+  "renderer": "live2d",
+  "live2d": {
+    "model": "model/my-pet.model3.json",
+    "motions": { "idle": "Idle", "thinking": "Think", "failed": "TapBody" },
+    "hitAreas": ["Body"]
+  }
+}
+```
+
+- `model`：相对宠物目录的 `.model3.json` 路径。模型引用的一切文件（moc、贴图、动作、物理、姿态、表情）都必须放在目录内——宿主恰好只服务这个引用闭包。
+- `motions`（必填，且必须含 `idle`）：相位 → 动作组。未映射的相位与模型缺失的组一律回退 `idle`；组内有多条动作时随机播放一条。官方 Cubism 示例模型只带 `Idle` 与 `TapBody` 两个组。
+- `expressions`（可选）：相位 → 表情名，叠加在动作之上。
+- `hitAreas`（可选）：点击落在列出的命中区时播放模型的 `TapBody` 组，播完回到当前相位的动作组。任何点击仍计入摸头——交互经济与 sprite2d 一样由 chrome 掌管。
+- `scale` / `translate`（可选）：模型自动适配显示盒；`scale` 在适配结果上乘算（默认 1，范围 (0, 10]），`translate` 以中心为基准做像素偏移。
+
+模型授权：Live2D 官方示例模型（Hiyori、Haru 等）仅供评估、禁止再分发——只发布你有权的模型（原创作品或宽松授权的模型）。
+
+## 内置宠物
+
+| 注册表 id | 选择器名称 | 来源 |
+|---|---|---|
+| `whale-girl` | 鲸鱼娘（原版） | 仓库原有的鲸鱼娘图集 |
+| `whale-girl-refined` | 鲸鱼娘（精致版） | 以鲸鱼娘设计方向为基础，经 AI 辅助二次创作、修复和细节精修的衍生版本 |
+
+精致版参考了 DreamSkin 的「DeepSeek-鲸鱼娘」主题。历史来源记录标注原主题作者为 `powerdog996`，并标注主题为 MIT：[DreamSkin](https://dreamskin.cc)、[仓库来源记录](https://github.com/zhu1090093659/dsh-web-ui/commit/87edd7ff4800dffd40bc93fb76e4ae450390facd)。此处用于记录素材来源与衍生关系；精致版不表述为原作者的官方作品，也不重新定义原始美术作品的授权范围。
 
 ## 动画预览
 
@@ -101,7 +165,8 @@ dsh-pet/
 |       |-- sequences.ts     # 完整轨道场景序列计时
 |       |-- spritesheet.ts   # 图集几何辅助 + 轨道裁剪
 |       `-- pet.module.css
-|-- assets/whale/            # 内置鲸鱼娘（pet.json + spritesheet.webp + 预览）
+|-- assets/whale/            # 内置原版鲸鱼娘（manifest + 图集 + 预览）
+|-- assets/whale-refined/    # 内置精致版鲸鱼娘注册表变体
 `-- cordis.patch.yml         # bundle 补丁：插入宠物插件行
 ```
 
@@ -156,7 +221,15 @@ pnpm typecheck    # 仅类型检查
 
 ## 精灵图与动画轨道校准
 
-内置鲸鱼娘图集由 hatch-pet 流水线生成，9 态 × 8 列：`assets/whale/spritesheet.webp`（1536×1872，8 列 × 9 行，192×208 单元格）+ `assets/whale/pet.json`。每行的帧数、节奏与场景轮换写在该 manifest 的 `frames`、`tracks` 与 `sequences` 字段里；未覆盖的宠物沿用 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）。
+两套内置鲸鱼娘图集使用同一份 9 态 × 8 列契约：`assets/whale/` 是原版，`assets/whale-refined/` 是精致版。每张图集均为 1536×1872（8 列 × 9 行，192×208 单元格）。每行帧数、节奏与场景轮换写在各目录的 `pet.json` 中；未覆盖的宠物沿用 hatch-pet 契约节奏和标准单轨场景映射（行序：0 idle / 1 running-right / 2 running-left / 3 waving / 4 jumping / 5 failed / 6 waiting / 7 running / 8 review）。
+
+## 安全模型
+
+- 全部宠物 API 与资产路由仅服务回环客户端。
+- 资产服务对宠物目录与目标文件双双做 `realpath` 解析；symlink 越界一律拒绝（403）。文件读入内存前按类限大小（清单 64 KB、图像 20 MB；超限 413）。
+- Live2D 模型按闭包放行：仅清单、声明的主资产与 `.model3.json` 引用到的文件（引用先经穿越/绝对路径/URL 形态筛查）。
+- 插件从不下载可执行文件，也从不内置 Live2D Cubism Core。
+- 清单结构 fail-closed：未知字段或未知渲染器直接拒载，并在设置中给出诊断。
 
 ## 许可证
 

package/assets/whale/pet.json

@@ -1,27 +1,176 @@
 {
+  "petManifestVersion": 2,
   "id": "whale-girl",
-  "displayName": "鲸鱼娘",
-  "description": "一只软萌治愈的鲸鱼娘，来自深海的陪伴小伙伴。",
-  "spritesheetPath": "spritesheet.webp",
-  "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] }
+  "displayName": "鲸鱼娘（原版）",
+  "renderer": "sprite2d",
+  "sprite2d": {
+    "spritesheetPath": "spritesheet.webp",
+    "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
+        ]
+      }
+    }
   },
+  "description": "一只软萌治愈的鲸鱼娘，来自深海的陪伴小伙伴。",
+  "license": "BSD-3-Clause",
   "sequences": {
-    "idle": ["idle", "waving", "idle", "waiting", "idle", "idle"],
-    "waiting": ["waiting", "idle", "waving", "waiting", "idle", "waiting"],
-    "thinking": ["running", "running-right", "running", "running-left", "running", "waiting", "running"],
-    "tool": ["running-right", "running", "running-left", "running", "running-right", "running"],
-    "review": ["review", "waiting", "review", "running", "review", "idle"],
-    "done": ["jumping", "waving", "jumping", "waving", "jumping", "idle"],
-    "failed": ["failed", "waiting", "failed", "idle", "waiting", "failed"]
+    "idle": [
+      "idle",
+      "waving",
+      "idle",
+      "waiting",
+      "idle",
+      "idle"
+    ],
+    "waiting": [
+      "waiting",
+      "idle",
+      "waving",
+      "waiting",
+      "idle",
+      "waiting"
+    ],
+    "thinking": [
+      "running",
+      "running-right",
+      "running",
+      "running-left",
+      "running",
+      "waiting",
+      "running"
+    ],
+    "tool": [
+      "running-right",
+      "running",
+      "running-left",
+      "running",
+      "running-right",
+      "running"
+    ],
+    "review": [
+      "review",
+      "waiting",
+      "review",
+      "running",
+      "review",
+      "idle"
+    ],
+    "done": [
+      "jumping",
+      "waving",
+      "jumping",
+      "waving",
+      "jumping",
+      "idle"
+    ],
+    "failed": [
+      "failed",
+      "waiting",
+      "failed",
+      "idle",
+      "waiting",
+      "failed"
+    ]
   }
 }

package/assets/whale-refined/pet.json

@@ -0,0 +1,22 @@
+{
+  "petManifestVersion": 2,
+  "id": "whale-girl-refined",
+  "displayName": "鲸鱼娘（精致版）",
+  "renderer": "sprite2d",
+  "sprite2d": {
+    "spritesheetPath": "spritesheet.webp",
+    "frames": [
+      6,
+      8,
+      8,
+      4,
+      5,
+      8,
+      6,
+      6,
+      6
+    ]
+  },
+  "description": "基于鲸鱼娘形象进行 AI 辅助二次创作、修复与细节精修的内置变体。",
+  "license": "MIT"
+}