docs: 优化工作台的 spec 与 6 个实施 issue（.scratch/wallpaper-optimization/）

按本仓 issue-tracker 约定落盘：spec.md 记决策与验收，issues/NN-*.md 一步一票。 01 已完成，02-06 待做。
2026-09-19 19:27:47 +08:00
1 parent 09ff322fe8
commit 8ad177c822
@@ -0,0 +1,20 @@
+# 01 资源按 游戏/壁纸 分层，预设拆进各自壁纸目录
+
+Status: resolved
+
+## 目标
+
+把 `assets/{images,effects,audios}/` 三个平铺目录改成每档壁纸自包含的 `assets/<游戏>/<壁纸>/{effects,images,audios}/`，
+并让每档壁纸自带一份 `preset.js` 声明自己的资源，使新增一档壁纸不需要改动公共代码里的路径。
+
+## 验收
+
+- `godir` 式平铺目录消失，`assets/` 下只剩 `<游戏>/<壁纸>/`。
+- `check-paths` 对每份 `preset.js` 声明的路径全部命中。
+- 浏览器加载 0 个真实 404。
+- 与基线 worktree 同冻结设置对拍，存在逐像素完全相同的配对（即无回归）。
+
+## 结果
+
+commit `09ff322`。11/11 路径存在（含此前零引用的 `昔涟.flac`）；9 对跨版本比较中 4 对差异为 0，
+其余 ≤0.19/255，低于基线自身 2.27/255 的双模态抖动；无真实 404。
@@ -0,0 +1,24 @@
+# 02 体积：音频转码 + 未引用资源归位
+
+Status: ready-for-agent
+
+## 现状
+
+- `dist` 合计 105.1 MB，其中音频占 77.3 MB：
+  - `昔涟立绘/audios/「再度和你」.flac` 37.3 MB / 205.1 s / 1.52 Mbps
+  - `昔涟立绘/audios/昔涟.flac` 37.7 MB / 186.7 s / 1.69 Mbps（此前零引用，现已声明为第二音源）
+  - `「成为昨日的明天」/audios/pv37.mp3` 2.3 MB / 81 s
+- CEF 的解码白名单含 vorbis / libopus / flac / mp3 / pcm_*（不含 aac，`m4a` 大概率不可用）。
+
+## 步骤
+
+1. 无损母带移出 `dist/`（另存工作区外的 `masters/`，不入库）。
+2. 两首 flac 转 Opus（`libopus`，约 96–128 kbps，目标每首 ≤4.5 MB）：`ffmpeg -i in.flac -c:a libopus -b:a 112k out.ogg`。保留 `pv37.mp3` 原样。
+3. 用工具的音频波形/时长核对转码未截断。
+4. PNG → WebP **仅在对拍证明无可见差异后**逐张决定（atlas 页要整组一起转，并同步改 `.atlas` 里的页名）。
+
+## 验收
+
+- `dist` 总体积 ≤35 MB。
+- `check-paths` 全绿；本地 curl 确认转码后的音频能播放（时长一致）。
+- 每个比例的对拍像素无回归。
@@ -0,0 +1,20 @@
+# 03 健壮性：初始化状态机、死代码、用户级覆盖语义
+
+Status: ready-for-agent
+
+## 问题
+
+1. **初始化竞态（已实证）**：`SpineController.changeConfig()` 整个函数体都在 `if (this.player)` 里，
+   包括状态赋值。WE 可能在 `window.load` 之前就下发用户属性，此时预设被静默丢弃：
+   同一份代码、同一份属性，`load` 之后下发得到 `animation`（kv37，正确），
+   `DOMContentLoaded` 时下发得到 `idle`（xilian）——背景与音乐已切到 kv37、立绘还是昔涟。
+   修法：**状态先写、应用后置**；`changeX()` 无条件更新状态，只在有 `player` 时应用，加载完成时统一应用一次。
+2. `index.js` 里有一段重复的 `window.wallpaperRegisterListener`（该 API 在本机 WE 不存在），是死代码。
+3. `SpineController.adjustCanvas()` 与播放器自身的 resize 重复，且用 `getBoundingClientRect()` 写 `canvas.width` 而未乘 DPR。
+4. 用户级覆盖语义：用户自定义了音源/音量后，切换预设不得把它清回预设默认值。
+
+## 验收
+
+- 把"属性在 `DOMContentLoaded` 下发"这一路作为回归断言：玩家实际使用的动画必须与所选预设一致。
+- 死代码与重复 resize 移除后，对拍仍无回归。
+- 同一份预设往返切换 20 次，用户自定义音源/音量保持不变。
@@ -0,0 +1,20 @@
+# 04 比例适配：按容器比例重算视口
+
+Status: ready-for-agent
+
+## 问题
+
+viewport 以等比 "contain" 映射到画布：单轴贴边、另一轴多露出世界，因此现在的负 padding 只在目标比例下成立；
+在超宽屏（3440×1440）或竖屏（1080×1920）下会露出多余的世界或裁掉主体。
+
+## 步骤
+
+1. 测出每档壁纸在 21:9 / 16:9 / 9:16 下的构图偏差（已有对拍矩阵）。
+2. 按容器宽高比在运行时重算 pad（视口是活对象：原地改 pad 后调用 `player.setViewport(当前动画名)` 即生效，
+   整体替换 viewport 会丢 `viewport.animations` 并在 spine-player 第 14973 行崩溃）。
+3. 目标：主体完整、底部对齐、无空边。
+
+## 验收
+
+- 三种比例下都对拍留档，主体不被裁切、底部不悬空。
+- 切换窗口大小时不重建播放器（用 `setViewport`），连续 resize 无内存增长。
@@ -0,0 +1,17 @@
+# 05 WE 属性扩展：音源 combo、fps 限制
+
+Status: ready-for-agent
+
+## 内容
+
+1. **音源（音源作用域已定）**：新增 `project.json` combo `bgm`，列表是所有壁纸音源声明的**并集**（WE 的 combo 是静态列表，只能手工同步）；
+   每档壁纸在自己 `preset.js` 的 `audioChoices` 里声明可选音源。切换壁纸时，若当前音源不属于新壁纸，回落"随预设"。
+2. **fps 限制**：`properties.fps` 经 `applyGeneralProperties` 下发，WE 不会替壁纸限流，需自行实现。
+   实现方式：包裹实例上的 `player.drawFrame`（循环用箭头闭包懒查，因此可以门控）；注意 `config.frame/update/draw`
+   都在下一帧排程之后运行，用它们限不了流。
+3. `setPaused` 暂不实现（WE 会整体冻结进程）；除非用户在 WE 里实测发现音频仍在响。
+
+## 验收
+
+- combo 切音源即时生效，且切壁纸时的回落行为正确。
+- 设置 30/60 fps 时实际帧率符合，且不影响动画相位推进速度。
@@ -0,0 +1,10 @@
+# 06 打包 v3 并重新发布
+
+Status: ready-for-agent
+
+## 步骤
+
+1. `project.json`：`version` 升到 3，更新 `description`（提及新增音源切换等），核对 `properties` 与代码一致。
+2. `preview.gif` 现在 160×160 / 50 帧 / 840 KB——合规（≤256×256、≤1 MB）但超过推荐的 500 KB，重新压缩。
+3. 全量验收：0 死文件、≤35 MB、3 种比例 0 console 报错、预设往返不丢音源设置。
+4. 上传到 Workshop（人工步骤，需要用户操作）。