feat: TS 构建管线、Spine 抓取器与 wallpapers/ 唯一真相来源

把项目从「手写 dist/」改成「wallpapers/ 是唯一真相来源，dist/ 由 pnpm build 生成」，并补上配套的类型、门禁与抓取器。一次提交落地整条管线，因为拆开会留下不能构建的中间态。 - src/：运行时与模拟器源码（TS，strict），编译到 build/ 再拷进各分发 - tools/：build / dev / check-{syntax,paths,dist}，以及抓取器与回归门禁 tools/checks/ （.scratch/ 下那批一次性脚本移入 tools/checks/ 并入库为长期门禁） - wallpapers/：七档壁纸的源数据 + README.md（id/音频/预设的完整规范） - docs/adr/0005-0008：构建管线与分发拓扑、模拟器契约、自包含 sim、每骨架资源布局 - .gitignore：排除 .scratch/ 的参考资料副本（上游 spine 整仓克隆 ~1.2 GB、抓取侦查数据 ~680 MB）与调试转储；这些是本地调查材料，补偿会让仓库无法克隆 - 归一化 .gitignore/CONTEXT.md 行尾（工作区 CRLF、索引 LF 造成的整文件假 diff）同时修掉三档卡住构建的未完工壁纸： - kv45 的 meta.json 里 id 还是抓取期场景名 scene_main，经 downloader promote 正名为 kv45 - shajin / zhigengniao_juheye 的 meta.json 误用了骨架描述文件（name/spine/animations/pages）、且都缺 preset.template.json；现按规范重建：骨架沉到 spines/<名>/（spine-ts 按 atlas 所在目录解析贴图页）、补上元数据与单骨架预设，并清掉 zhigengniao 骨架里指向作者机的绝对路径 - 顺带 promote 已在 sources.yml 里的 kv46（月升之前，与兽共舞） pnpm check 五道门全绿：10 个分发 / 7 档壁纸 / 141 处引用自包含。
2026-10-02 01:27:02 +08:00
1 parent b8eee05d78
commit 3f11426964
@@ -0,0 +1,181 @@
+// Issue 05 验收：bgm 音源 combo 与 fps 限流。
+//
+// A 段验音源优先级：用户自填 URL > bgm 选择（仅当本壁纸声明过）> 本壁纸默认音源；
+//   且 bgm 选择跨壁纸时"音频回落、选择保留"。
+// B 段验 fps：WE 不替壁纸限流，得自己门控。关键是限流只该丢帧，
+//   不该改变动画相位推进速度——用同一段真实时间里 trackTime 前进了多少来判定。
+import { withPage, sleep } from "../cdp.mjs";
+
+// 服务地址：默认 8190（调试服常用端口），可用 SIM_BASE 覆盖。
+// 写死端口会在换了端口或换成分发目录时静默测错东西——它只是"连不上"，
+// 看起来像功能坏了，实际是脚本连错了地方。
+const BASE = process.env.SIM_BASE ?? "http://127.0.0.1:8190/";
+const name = (src) => (src ? decodeURIComponent(String(src).split("/").pop()) : "(空)");
+
+let failures = 0;
+const check = (ok, msg, detail) => {
+  if (!ok) failures++;
+  console.log(`  ${ok ? "✓" : "✗"} ${msg}${detail !== undefined ? `  → ${String(detail)}` : ""}`);
+};
+
+// ───────────────────────── A 段：音源 ─────────────────────────
+console.log("=== A 段：bgm 音源选择与回落 ===");
+await withPage({ width: 1280, height: 720 }, async ({ send, evaluate, exceptions }) => {
+  await send("Page.navigate", { url: BASE + "?__freeze=1" });
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    if (await evaluate('!!(window.__test && (window.__test.successAt || window.__test.error))')) break;
+    await sleep(150);
+  }
+  await sleep(600);
+
+  const src = () => evaluate('document.getElementById("background-music").src');
+  const preset = (v) => evaluate(`window.wallpaperPropertyListener.applyUserProperties({ preset: { value: ${JSON.stringify(v)} } })`);
+  const bgm = (v) => evaluate(`window.wallpaperPropertyListener.applyUserProperties({ bgm: { value: ${JSON.stringify(v)} } })`);
+  const file = (v) => evaluate(`window.wallpaperPropertyListener.applyUserProperties({ audio_file: { value: ${JSON.stringify(v)} } })`);
+  // 「使用自定义音乐」是 audio_file 的总开关：关着时填了 URL 也不该生效。
+  const customAudio = (v) => evaluate(`window.wallpaperPropertyListener.applyUserProperties({ use_custom_audio: { value: ${JSON.stringify(v)} } })`);
+
+  const seen = [];
+  const step = async (label, action, expected) => {
+    await action();
+    await sleep(350);
+    const got = name(await src());
+    seen.push(`${label}=${got}`);
+    check(got === expected, label, `期望 ${expected}，实得 ${got}`);
+  };
+
+  // 载入即 xilian，默认音源应是「再度和你」
+  check(name(await src()) === "zaiduheni.flac", "初始默认音源 = 昔涟立绘默认", name(await src()));
+
+  // 无损是否真的可用，取决于 CEF 能不能解 FLAC——不能只看路径对不对。
+  // readyState>=1(HAVE_METADATA) 说明容器与编码被接受，duration>0 说明解析出了正确时长。
+  const healthProbe = `(function(){
+    var a = document.getElementById("background-music");
+    return { rs: a.readyState, dur: a.duration, net: a.networkState,
+             err: a.error ? a.error.code : null, flac: a.canPlayType("audio/flac") };
+  })()`;
+  let h = null;
+  for (let i = 0; i < 40; i++) {
+    h = await evaluate(healthProbe);
+    if (h.rs >= 1 || h.err !== null) break;
+    await sleep(250);
+  }
+  check(h.flac === "probably" || h.flac === "maybe", "CEF 支持 audio/flac", h.flac || "(不支持)");
+  check(h.err === null, "音频无解码错误", h.err === null ? "无" : `MediaError.code=${h.err}`);
+  check(h.rs >= 1, "FLAC 已解析出元数据（readyState≥1）", `readyState=${h.rs}`);
+  check(h.dur > 100 && h.dur < 300, "解析出的时长符合源文件", `${h.dur?.toFixed(1)} 秒`);
+
+  // 元数据能解析 ≠ 真的在放。等一会儿看播放头有没有前进——这才是"无损可用"的终局证据。
+  await sleep(1500);
+  const pb = await evaluate(`(function(){
+    var a = document.getElementById("background-music");
+    return { paused: a.paused, t: a.currentTime, loop: a.loop, vol: a.volume };
+  })()`);
+  check(!pb.paused, "音频处于播放状态", pb.paused ? "仍暂停" : "播放中");
+  check(pb.t > 0.5, "播放头已前进（确实在解码播放）", `currentTime=${Number(pb.t).toFixed(2)} s`);
+  check(pb.loop === true, "循环播放已开启", String(pb.loop));
+
+  // 音源 id 是 build 自增分配的（不再是 zaiduheni / xilian / pv37 这种手写名）：
+  //   分配顺序 = 游戏 → 共享音频 → 各壁纸（按 id 排序），所以 kv37 的「版本 PV」拿到 "1"，
+  //   xilian 的「「再度和你」」是 "2"、「昔涟」是 "3"。顺序变了这些数字就会变——这正是
+  //   自增 id 的代价，改音源清单时要回来同步这里。
+  await step("bgm 选「昔涟」", () => bgm("3"), "xilian-src.flac");
+  await step("切到 kv37（选择不属于它）→ 回落", () => preset("kv37"), "pv37.mp3");
+  await step("bgm 选「版本 PV」（属于 kv37）", () => bgm("1"), "pv37.mp3");
+  await step("切回 xilian（pv37 不属于它）→ 回落", () => preset("xilian"), "zaiduheni.flac");
+  await step("bgm 选「「再度和你」」", () => bgm("2"), "zaiduheni.flac");
+  await step("bgm 回到「随预设」", () => bgm("auto"), "zaiduheni.flac");
+
+  // 用户自填 URL 优先级最高——但要先打开「使用自定义音乐」这个总开关。
+  await step("开关关着时填 URL 不生效（回落预设默认）", async () => {
+    await customAudio(false);
+    await file("https://example.com/ignored.mp3");
+  }, "zaiduheni.flac");
+  await step("打开开关后 URL 生效", async () => {
+    await customAudio(true);
+    await file("https://example.com/custom-track.mp3");
+  }, "custom-track.mp3");
+  await step("切壁纸不得清掉自定义 URL", () => preset("kv37"), "custom-track.mp3");
+  await step("关掉开关 + 清空 URL → 回到预设默认", async () => {
+    await customAudio(false);
+    await file("");
+  }, "pv37.mp3");
+
+  console.log(`  音源轨迹: ${seen.join("  |  ")}`);
+  console.log(`  未捕获异常: ${exceptions.length ? exceptions.join(" | ") : "无 ✓"}`);
+  if (exceptions.length) failures++;
+});
+
+// ───────────────────────── B 段：fps ─────────────────────────
+console.log("\n=== B 段：fps 限流 ===");
+await withPage({ width: 1280, height: 720 }, async ({ send, evaluate, exceptions }) => {
+  // 空 __props 只用来触发测试驱动注入（不带它就不会注入），既不冻结也不改属性
+  await send("Page.navigate", { url: BASE + "?__props=%7B%7D" });
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    if (await evaluate('!!(window.__test && (window.__test.successAt || window.__test.error))')) break;
+    await sleep(150);
+  }
+  await sleep(1200); // 让动画先跑起来，避开启动瞬态
+
+  const probe = `(function(){
+    var p = window.__player;
+    var e = p.animationState.getCurrent(0);
+    return { trackTime: e.trackTime, duration: e.animation.duration,
+             draws: window.__test.drawCalls, t: performance.now() };
+  })()`;
+
+  const sample = async (seconds) => {
+    const a = await evaluate(probe);
+    await sleep(seconds * 1000);
+    const b = await evaluate(probe);
+    const wall = (b.t - a.t) / 1000;
+    let phase = b.trackTime - a.trackTime;
+    if (phase < 0) phase += b.duration; // 动画正好绕回
+    return { wall, draws: b.draws - a.draws, fps: (b.draws - a.draws) / wall, phaseRate: phase / wall };
+  };
+
+  const setFps = async (v) => {
+    await evaluate(`window.wallpaperPropertyListener.applyGeneralProperties({ fps: ${v} })`);
+    await sleep(400);
+  };
+
+  const results = [];
+  const run = async (label, target) => {
+    const r = await sample(2.0);
+    const row = { label, target, ...r };
+    results.push(row);
+    console.log(
+      `  ${label.padEnd(16)} 实测 ${r.fps.toFixed(1)} fps` +
+        (target ? `（目标 ${target}）` : "（不限流）") +
+        `   动画相位推进 ${r.phaseRate.toFixed(3)} 倍速`,
+    );
+    return row;
+  };
+
+  const base = await run("不限流", 0);
+  await setFps(30);
+  const f30 = await run("限 30 fps", 30);
+  await setFps(20);
+  const f20 = await run("限 20 fps", 20);
+  await setFps(0);
+  const back = await run("恢复不限流", 0);
+
+  check(Math.abs(f30.fps - 30) / 30 < 0.25, "限 30 fps 生效", `实测 ${f30.fps.toFixed(1)}`);
+  check(Math.abs(f20.fps - 20) / 20 < 0.25, "限 20 fps 生效", `实测 ${f20.fps.toFixed(1)}`);
+  check(f30.fps < base.fps * 0.75, "限流确实减少了绘制次数", `${base.fps.toFixed(1)} → ${f30.fps.toFixed(1)}`);
+  check(back.fps > f30.fps * 1.5, "取消限流后帧率恢复", `${f30.fps.toFixed(1)} → ${back.fps.toFixed(1)}`);
+  for (const r of [f30, f20, back]) {
+    check(
+      Math.abs(r.phaseRate - base.phaseRate) / base.phaseRate < 0.1,
+      `动画相位推进速度未受 ${r.label} 影响`,
+      `${r.phaseRate.toFixed(3)} vs 基准 ${base.phaseRate.toFixed(3)}`,
+    );
+  }
+  console.log(`  未捕获异常: ${exceptions.length ? exceptions.join(" | ") : "无 ✓"}`);
+  if (exceptions.length) failures++;
+});
+
+console.log(`\n结论：${failures === 0 ? "全部通过 ✓" : `${failures} 项失败 ✗`}`);
+process.exit(failures === 0 ? 0 : 1);