@coralai/sps-cli 0.65.75 → 0.65.77

package/dist/providers/art/artGen.js

@@ -0,0 +1,1303 @@
+/**
+ * 美术资源生成 Job(阶段 1:串行生成)。
+ * 读 docs/art-manifest.json → 对每个 asset 调图像管线生成(prompt = desc + 全局 style)→
+ * 存 repo/assets/<id>.png + assets/asset-status.json(done/failed)。
+ * 失败不阻塞其它(代码侧回退矢量)。匹配复用/并发提速留阶段 3。
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import sharp from 'sharp';
+import { withinDir } from './withinDir.js';
+import { packSheet } from './sheet.js';
+import { fitAndRepackUiKit, renderUiWireframe, uiKitPrompt, UIKIT_STRUCTURE_BROKEN, UI_KIT_FRAMES, UI_KIT_CANVAS } from './uiKit.js';
+import { emitBuildEvent } from './artEvents.js';
+import { runWithJob } from './jobContext.js';
+import { detectFacing, inspectSheetLabels } from './visionJudge.js';
+import { withTransparency } from './artPrompt.js';
+import { composeAsset, defaultPixelOps } from './composeAsset.js';
+import { compressKeepFormat, genSizeFor, parseSize } from './imageSize.js';
+import { writeAssetAtomic } from './atomicWrite.js';
+import { withRateLimitRetry } from './rateLimitRetry.js';
+import { generateAsset } from '../media/generateAsset.js';
+import { listUsableProviders } from '../media/mediaProviders.js';
+import { resolveProjectDir } from '../../core/art/assetLocator.js';
+import { ART_ASSET_CONCURRENCY_MAX } from '../../core/art/artConcurrency.js';
+/**
+ * 归一化单条资产:把设计师自由发挥的旧/非标准 schema 修回标准结构字段。
+ * 背景(gmr1ze4zr 街头拳王事故):设计师加载了 skill 却写成 `{id,type,desc,frames,width,height}`——
+ * 没 `sheet` → 序列帧不打图集(动画废);没 `transparent` → 抠图跳过(白底)。pipeline 原本零校验、静默出废图。
+ * 这里在花钱生成【前】把能安全推断的补回来,并 warn 出来(违约可见)。返回是否发生了归一化(供上层汇总告警)。
+ */
+function normalizeAsset(a) {
+    const fixes = [];
+    const t = (a.type ?? '').toLowerCase();
+    const isAudio = t.startsWith('audio');
+    // 1) frames → sheet:{cols:frames,rows:1}(旧的横向序列帧写法)。width≈frames×height 时更笃定,但只要 frames≥2 就转。
+    if (!a.sheet && typeof a.frames === 'number' && a.frames >= 2 && !isAudio) {
+        a.sheet = { cols: a.frames, rows: 1, count: a.frames };
+        fixes.push(`frames:${a.frames}→sheet:{cols:${a.frames},rows:1}`);
+    }
+    // 2) transparent 缺失时按语义推断:音频不涉及;desc 明说 transparent → true;背景/铺满 → false;其余精灵/道具/UI/图标 → true。
+    if (typeof a.transparent !== 'boolean' && !isAudio) {
+        const hay = `${a.desc ?? ''} ${a.usage ?? ''}`.toLowerCase();
+        const id = (a.id ?? '').toLowerCase();
+        const saysTransparent = /transparent|透明|no background|alpha/.test(hay);
+        // 背景:type=scene/bg、或 id 以 bg_/background_ 打头(设计师常把背景 type 写成 image、只靠 id 前缀区分)、或 desc/usage 明说背景/铺满。背景绝不抠图(否则打洞)。
+        // 前景层(scene/foreground / fg_ 前缀,docs/25 多层视差)必须透明——它要叠在背景上
+        const isForeground = t.includes('foreground') || /^fg[_-]/.test(id) || /前景/.test(hay);
+        const isBackground = !isForeground && (t.startsWith('scene') || t.startsWith('bg') || /^(bg|background|backdrop|scene)[_-]/.test(id) || /\bbackground\b|backdrop|full[\s-]?screen|铺满|背景/.test(hay));
+        a.transparent = saysTransparent || isForeground ? true : isBackground ? false : true;
+        fixes.push(`transparent(缺)→${a.transparent}`);
+    }
+    return fixes;
+}
+/**
+ * 生图【前】合图兜底:设计师违反 design-art-manifest「成套/同类合一张 sheet、每局 ≤3 张」、把同类元素拆成一堆单张精灵时,
+ * 在花钱生成前自动把它们合并成一个 sheet 资产 → 生图只生 1 张 → 从根上规避几十张并行生成的图床限流 429(星际防线事故:20 单张→codex 限流→回退差供应商)。
+ * 这是「生图用合图」的确定性兜底(不是生图后拼接):合并发生在生成之前,生图任务本身就是一张 sheet。
+ *
+ * 保守判据(避免误伤真需要独立的图):
+ *  - 只合"同一大类 + 都是单张(无 sheet)"的资产;背景(scene/bg)、音频、3D、provided、已 sheet 一律不动。
+ *  - 分两大组各合一张:`ui/*` → UI 图集、其余精灵 → 精灵图集(正对 design-art-manifest 的「UI sheet + 精灵 sheet」)。
+ *  - 组内 ≥ MERGE_THRESHOLD 个才合(2–3 个的小游戏不折腾,只治"明显拆碎")。
+ * 合并顺序记进 desc(编号)+ mergedFrom → 写进 asset-meta(semanticId),worker 按帧对应回原语义。
+ * 就地改写 manifest.assets,返回合并说明(供上层 warn + 决定是否写回文件)。
+ */
+const MERGE_THRESHOLD = 4;
+export function mergeStraySprites(manifest) {
+    const notes = [];
+    const mergeable = (a) => {
+        const t = (a.type ?? '').toLowerCase();
+        if (t.startsWith('audio') || t === 'model3d' || t === 'ui/kit')
+            return false; // 声音/3D/UI契约套件不合
+        if (a.provided || a.sheet)
+            return false; // 用户给的 / 已是 sheet:不动
+        if (t.startsWith('scene') || t.startsWith('bg'))
+            return false; // 背景不合
+        const id = (a.id ?? '').toLowerCase();
+        if (/^(bg|background|backdrop|scene)[_-]/.test(id))
+            return false; // id 前缀判背景
+        return true;
+    };
+    const groupOf = (a) => ((a.type ?? '').toLowerCase().startsWith('ui') ? 'ui' : 'sprite');
+    for (const grp of ['sprite', 'ui']) {
+        const members = manifest.assets.filter((a) => mergeable(a) && groupOf(a) === grp);
+        if (members.length < MERGE_THRESHOLD)
+            continue; // 不够碎,保持原样
+        const n = members.length;
+        const cols = Math.ceil(Math.sqrt(n));
+        const rows = Math.ceil(n / cols);
+        const baseId = grp === 'ui' ? 'ui' : 'sprites';
+        const packId = manifest.assets.some((a) => a.id === baseId && !members.includes(a)) ? `${baseId}_pack` : baseId;
+        const merged = {
+            id: packId,
+            // desc 按 1)2)3) 编号列出各元素 → 与 mergedFrom / 生成布局顺序对齐;buildPrompt 的 isSheet 分支再补"禁网格线"等系统措辞。
+            desc: `共 ${n} 个独立元素,按 ${cols}×${rows} 均匀排开、每个居中等大、彼此留充足空隙:` +
+                members.map((m, i) => `${i + 1}) ${m.desc}`).join('; '),
+            type: grp === 'ui' ? 'ui/sheet' : 'sprite/sheet',
+            transparent: true,
+            orient: 'static',
+            sheet: { cols, rows, count: n },
+            size: '1024x1024', // codex 支持的方形;元素多也维持一张(守 ≤3 张)
+            mergedFrom: members.map((m) => m.id),
+            tags: ['自动合图'],
+        };
+        const memberSet = new Set(members);
+        manifest.assets = manifest.assets.filter((a) => !memberSet.has(a));
+        manifest.assets.push(merged);
+        notes.push(`${grp}: 合并 ${n} 个单张(${members.map((m) => m.id).join(', ')}) → sheet '${packId}' ${cols}×${rows}`);
+    }
+    return notes;
+}
+/** 资产描述指纹:二修时对比,变了 = 设计师改了这条资产 → 自动重生(确定性兜底,不依赖 regen 自觉)。
+ *  只含逐资产字段,不含全局 style(风格微调不该触发全量重生;整体换风格请显式 regen)。 */
+export function assetDescHash(a) {
+    const key = JSON.stringify({ d: a.desc ?? '', s: a.size ?? '', sh: a.sheet ?? null, t: a.transparent ?? null, o: a.orient ?? '', r: a.ref ?? '', p: a.provided ?? '' });
+    return createHash('sha1').update(key).digest('hex').slice(0, 12);
+}
+/** 读 art-manifest;缺失/非法返回 null。 */
+/**
+ * manifest 的落点。**导出**是因为子进程要区分三件今天长得一模一样的事(3.5):
+ * 「文件不存在(没有美术需求,合法)」/「文件在但读不出来(坏了,该响亮)」/「零资产」——
+ * 而 `readArtManifest` 对这三者一律返回 `null`/空。路径只能有一个真源,所以从这里拿。
+ */
+export function artManifestPath(repoDir) {
+    return join(repoDir, 'docs', 'art-manifest.json');
+}
+export function readArtManifest(repoDir) {
+    try {
+        const f = artManifestPath(repoDir);
+        if (!existsSync(f))
+            return null;
+        const j = JSON.parse(readFileSync(f, 'utf-8'));
+        if (!Array.isArray(j.assets))
+            return null;
+        const assets = j.assets.filter((a) => a && a.id && (a.desc || a.provided)); // 逐资产字段(含 ref/provided)原样保留;provided 资产可无 desc
+        // 🔴 归一化:设计师即便加载了 skill 也常写非标准 schema(frames/width 代 sheet、透明塞进 desc)。在花钱生成前把能安全推断的补回标准字段,并汇总 warn(违约可见,而非静默出白底/未切图的废图)。
+        const normNotes = [];
+        for (const a of assets) {
+            const fixes = normalizeAsset(a);
+            if (fixes.length)
+                normNotes.push(`${a.id}: ${fixes.join(', ')}`);
+        }
+        if (normNotes.length)
+            console.warn(`⚠️ art-manifest 非标准字段已归一化(${normNotes.length} 条):\n  ${normNotes.join('\n  ')}`);
+        // 🔴 兜底:设计师(尤其 MiniMax/GLM 等遵循较弱的模型)漏写 BGM 时,自动补一段游戏 BGM,保证游戏有声音(见 docs/19「音乐不生成」)。
+        if (assets.length && !assets.some((a) => (a.type ?? '').startsWith('audio'))) {
+            assets.push({ id: 'bgm_game', usage: '游戏循环 BGM(设计师未声明,自动补)', type: 'audio/bgm', desc: 'upbeat cheerful casual project background music loop, light and pleasant, melodic, moderate tempo around 110 BPM, looping instrumental' });
+        }
+        return {
+            style: j.style,
+            view: j.view,
+            ref: typeof j.ref === 'string' ? j.ref : undefined,
+            regen: Array.isArray(j.regen) ? j.regen.filter((x) => typeof x === 'string') : undefined,
+            concurrency: j.concurrency,
+            assets,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把一个资源的"功能理解"组装成精确的文生图指令(模型无关,所有 text2img 通用)。
+ * desc 只写主体/外观/姿态;**视角、朝向(按 orient)、构图、干净度由这里系统化补齐**,
+ * 不靠设计 agent 每条 desc 的发挥——这是我们可控的"指令精度"。透明抠图指令在 generateImage 里再补。
+ */
+function buildPrompt(a, style, view, artPrompts) {
+    const parts = [a.desc, style, view];
+    const t = a.type ?? '';
+    const isUI = t.startsWith('ui');
+    const isFg = t.startsWith('scene/foreground');
+    const isBg = !isFg && t.startsWith('scene/');
+    const isSheet = !!(a.sheet && a.sheet.cols >= 1 && a.sheet.rows >= 1);
+    if (isSheet && !isUI) {
+        // 图集(多个元素一张图):AI 常把 desc 里的"网格"理解成"画出格子线",把网格线/边框烤进图 →
+        // 游戏里精灵带框 + packSheet 的透明缝隙切分被带偏(gmqt87mec 事故)。这里系统化禁掉:只画元素本身、
+        // 元素间是透明空隙,绝不画任何网格线/边框/分隔线/底色。布局信息(cols×rows)给到、但与"画线"切开。
+        const n = a.sheet?.count ?? (a.sheet ? a.sheet.cols * a.sheet.rows : 0);
+        // 布局是通用的(cols×rows 由 manifest 定);措辞归产品(随请求下发的 artPrompts)。
+        parts.push(`共 ${n} 个独立元素,按 ${a.sheet?.cols}×${a.sheet?.rows} 均匀排开、每个居中等大、彼此留充足空隙;` +
+            '纯透明背景,元素之间只是透明空隙;' +
+            artPrompts.sheet);
+    }
+    else if (isUI) {
+        // UI 控件资产:系统化注入"决定生图质量"的游戏 UI 提示词(像真实可点控件 + 强层级 + 锐利清晰 +
+        // 纯件透明便于切分 + 不烤文字 + 负面词),不靠设计 agent 每条 desc 自觉。文案由引擎渲染。
+        parts.push(artPrompts.ui);
+    }
+    else if (isFg) {
+        // 前景视差层(docs/25 多层):透明底靠色键抠品红 → 辉光/半透明羽化与背景混色物理上抠不净
+        //(星际穿梭 fg 品红残留事故)。强制硬边剪影 + 贴边构图。
+        parts.push(artPrompts.foreground);
+    }
+    else if (isBg) {
+        // 横竖版构图方向(竖版游戏的背景要竖向延展,横图压竖屏必拉伸损失)
+        const dim = /(\d+)\s*x\s*(\d+)/.exec(a.size ?? '');
+        const ratio = dim ? Number(dim[1]) / Number(dim[2]) : 0;
+        if (ratio && ratio < 0.77)
+            parts.push('竖版画幅,竖向构图、上下延展(天空在上/地面在下之类的纵深层次)');
+        else if (ratio > 1.3)
+            parts.push('横版画幅,横向构图、左右延展');
+        parts.push(artPrompts.background);
+    }
+    else {
+        // 朝向/动作 ↔ 游戏逻辑强关联,按 orient 给死基线(代码再翻转/旋转);
+        // rotate 必须沿指向轴镜像对称、轴心在底,否则旋转起来歪。
+        if (a.orient === 'flipX')
+            parts.push('严格正侧面,面朝画面右侧(facing right)');
+        else if (a.orient === 'rotate')
+            parts.push('主体朝正上方,沿垂直中轴左右镜像对称,旋转轴心在底部中央');
+        else
+            parts.push(artPrompts.generic);
+        parts.push('单一主体,完整不裁切,紧凑铺满画面,四周尽量无留白,无边框,无地面阴影,无多余角色或文字');
+    }
+    return parts.filter(Boolean).join(', ');
+}
+/** 把 repo 相对路径的参考图读成 data URL(图生图用);缺失/越界/读失败返回 undefined。 */
+function refToDataUrl(repoDir, ref) {
+    if (!ref)
+        return undefined;
+    try {
+        const p = join(repoDir, ref); // ref 是 repo 相对路径(如 docs/refs/x.png)
+        if (!withinDir(repoDir, p) || !existsSync(p))
+            return undefined; // 防越界 + 缺失
+        const ext = (ref.split('.').pop() || 'png').toLowerCase();
+        const mime = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : ext === 'webp' ? 'image/webp' : 'image/png';
+        return `data:${mime};base64,${readFileSync(p).toString('base64')}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 写图集描述文件 `<id>.json`(TexturePacker JSONHash 格式)。
+ * Phaser/Pixi 可直接 load.atlas 原生加载;Kaplay 读 frames 映射。帧名 `<id>_0..<id>_N`(行优先=manifest 顺序)。
+ */
+// ══════════════════════════════════════════════════════════════════════════
+// 🔴 **这里曾经有音频**(`AUDIO_LIBRARY` + `pickLibraryBgm`:BGM 生成失败时从公共音频库取替代)。
+//
+// 本版**音频留 studio**(2.8):它的 `audioGen` 要 ffmpeg-static + spawnSync,
+// 而音频库在 coral 家(`DATA_DIR/audio-library`,sps 只读)—— 搬它是**另一次迁移的量**。
+// driver 按能力派发,audio 在**资产边界就明确跳过并回报**(不是 filter 抹掉),所以
+// sps 侧的音频代码永远走不到 ⇒ 留着它才是半途:两个 tsc 缺口(`audioGen`/`paths`)
+// 其实是**同一件事**,而它们让整个文件连 import 都进不来、测试无从写起。
+//
+// ⚠️ **音频后续同样归 sps**(Eddy 已定)。那天不是"重新发明音频",是**按能力补一个 case**:
+//    `generateAsset({ capability: 'music' })` + 这里补回库兜底。
+//    留这段注释是因为 —— **"这里什么都不做"和"这里从来没有过"是两回事,而代码默认表达后者。**
+// ══════════════════════════════════════════════════════════════════════════
+// 占位色板:高区分度、编号可读(worker 开工即接入,真图生成完原地替换)。
+const PLACEHOLDER_COLORS = ['#e74c3c', '#3498db', '#2ecc71', '#f1c40f', '#9b59b6', '#e67e22', '#1abc9c', '#fd79a8', '#95a5a6', '#8e44ad', '#d35400', '#16a085'];
+// 🔴 占位清单 docs/placeholder-assets.json:记录哪些 assets/<id> 当前是占位版。
+//    生成器把「占位」视同「缺失」(否则占位文件会骗过 kept 判定 → 真图永远不生成的回归);
+//    每个 id 真图生成成功后从清单移除。文件缺失/坏 → 空集(无占位,行为同旧)。
+const PLACEHOLDER_MARKER = 'placeholder-assets.json';
+export function readPlaceholderIds(repoDir) {
+    try {
+        const j = JSON.parse(readFileSync(join(repoDir, 'docs', PLACEHOLDER_MARKER), 'utf-8'));
+        return new Set(Array.isArray(j.ids) ? j.ids : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+function writePlaceholderIds(repoDir, ids) {
+    try {
+        const f = join(repoDir, 'docs', PLACEHOLDER_MARKER);
+        if (ids.size === 0) {
+            if (existsSync(f))
+                unlinkSync(f);
+            return;
+        }
+        mkdirSync(join(repoDir, 'docs'), { recursive: true });
+        writeFileSync(f, JSON.stringify({ ids: [...ids] }));
+    }
+    catch { /* 标记写失败不致命:最坏=当占位为真资产,回到旧行为 */ }
+}
+/**
+ * 🔴 占位资产:建卡瞬间按 art-manifest 确定性生成"同名、同帧结构"的编号色块图(+ 音频库 BGM),
+ * 让 worker 从第 0 秒就能按正式写法接入(load.atlas 按帧/load.image/load.audio),零等待开写;
+ * 真图生成完由 finalizeAsset 写到相同路径【原地替换】,代码零改动(帧名 <id>_<i> 两边同构)。
+ * 治的是实测 4~5 分钟的"worker 等资产才动笔"(gmrdj9udt:13:23 跑 wait-assets、13:27 才写第一行)。
+ * 幂等:目标文件已存在(续跑/用户 provided)一律不动。全程 best-effort,失败不阻断构建。
+ */
+/**
+ * @param only 只写这一类的占位(2.8)。
+ *   🔴 **这条最容易漏**:切换后视觉占位归 sps,而**音频占位仍归 studio** ——
+ *      漏了的话 `ART_DRIVER=sps` 之后占位 BGM 不再产出,
+ *      症状是"游戏没有 BGM",**不是报错**。
+ *      (真图生成的派发点和占位这条是**两个**位置,改一个不够。)
+ */
+export async function writePlaceholderAssets(repoDir, manifest, logical, only) {
+    const assetsDir = join(repoDir, 'assets');
+    mkdirSync(assetsDir, { recursive: true });
+    const marks = readPlaceholderIds(repoDir); // 累积(续跑幂等):真图生成成功时由 generateGameArt 移除
+    for (const a of manifest.assets) {
+        if (only && assetKind(a) !== only)
+            continue;
+        try {
+            const t = (a.type ?? '').toLowerCase();
+            // 🔴 音频占位仍归 studio(2.8 特意点名的"两处别漏"之一)—— sps 本版不写 .mp3。
+            //    症状警示原样留着:漏了占位 BGM 的表现是"游戏没有 BGM",**不是报错**。
+            //    音频归 sps 那天,在这里补回"从公共音频库取一首"的分支。
+            if (t.startsWith('audio'))
+                continue;
+            if (a.provided || existsSync(join(assetsDir, `${a.id}.png`)))
+                continue;
+            marks.add(a.id);
+            if (t === 'ui/kit') {
+                // 🔴 UI 契约套件:占位直接用灰阶线稿本体(结构=真图同契约、帧名固定)→ worker 从第 0 秒按语义帧名接入;
+                //    真图生成完原地替换,坐标/帧名不变。
+                {
+                    const wire = await renderUiWireframe();
+                    try {
+                        const rp = await fitAndRepackUiKit(wire);
+                        const m = await sharp(rp.buf).metadata();
+                        writeFileSync(join(assetsDir, `${a.id}.png`), rp.buf);
+                        writeAtlasJsonNamed(assetsDir, a.id, {
+                            frames: rp.frames.map((f) => ({ x: f.x, y: f.y, w: f.w, h: f.h })),
+                            width: m.width ?? 0, height: m.height ?? 0,
+                        }, rp.frames.map((f) => f.name));
+                    }
+                    catch {
+                        // 重组失败 → 线稿原图 + 契约矩形直切
+                        writeFileSync(join(assetsDir, `${a.id}.png`), wire);
+                        writeAtlasJsonNamed(assetsDir, a.id, {
+                            frames: UI_KIT_FRAMES.map((f) => ({ x: f.x, y: f.y, w: f.w, h: f.h })),
+                            width: UI_KIT_CANVAS.w, height: UI_KIT_CANVAS.h,
+                        }, UI_KIT_FRAMES.map((f) => f.name));
+                    }
+                }
+                continue;
+            }
+            if (t.startsWith('scene') || t.startsWith('bg')) {
+                // 背景:柔和渐变 + 资产名水印,尺寸=逻辑分辨率。
+                const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${logical.w}" height="${logical.h}">` +
+                    `<defs><linearGradient id="g" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#2c3e70"/><stop offset="1" stop-color="#1a1a2e"/></linearGradient></defs>` +
+                    `<rect width="${logical.w}" height="${logical.h}" fill="url(#g)"/>` +
+                    `<text x="${logical.w / 2}" y="${logical.h / 2}" font-size="28" font-family="sans-serif" fill="#ffffff55" text-anchor="middle">${a.id}(占位,真图生成中)</text></svg>`;
+                await sharp(Buffer.from(svg)).png().toFile(join(assetsDir, `${a.id}.png`));
+                continue;
+            }
+            // 精灵/UI:帧高按平台归一化档位(与真图一致 → 尺寸契约从第 0 秒就成立);图集帧名 <id>_<i> 与 finalizeAsset 同构。
+            const frameH = targetMaxH(a.type, logical.h);
+            const count = Math.max(1, a.sheet ? (a.sheet.count ?? a.sheet.cols * a.sheet.rows) : 1);
+            const cols = a.sheet?.cols ?? 1;
+            const rows = Math.ceil(count / cols);
+            const GAP = 2;
+            const W = cols * frameH + (cols - 1) * GAP;
+            const H = rows * frameH + (rows - 1) * GAP;
+            let cells = '';
+            const frames = [];
+            for (let i = 0; i < count; i++) {
+                const x = (i % cols) * (frameH + GAP);
+                const y = Math.floor(i / cols) * (frameH + GAP);
+                const color = PLACEHOLDER_COLORS[i % PLACEHOLDER_COLORS.length];
+                cells +=
+                    `<rect x="${x + 2}" y="${y + 2}" width="${frameH - 4}" height="${frameH - 4}" rx="${Math.round(frameH * 0.18)}" fill="${color}" stroke="#ffffff" stroke-width="2"/>` +
+                        `<text x="${x + frameH / 2}" y="${y + frameH / 2 + frameH * 0.12}" font-size="${Math.round(frameH * 0.34)}" font-family="sans-serif" font-weight="bold" fill="#fff" text-anchor="middle">${i}</text>`;
+                frames.push({ x, y, w: frameH, h: frameH });
+            }
+            const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">${cells}</svg>`;
+            await sharp(Buffer.from(svg)).png().toFile(join(assetsDir, `${a.id}.png`));
+            if (a.sheet)
+                writeAtlasJson(assetsDir, a.id, { frames, width: W, height: H });
+        }
+        catch { /* 单个占位失败不影响其它 */ }
+    }
+    writePlaceholderIds(repoDir, marks);
+}
+/**
+ * 造 TexturePacker atlas 对象(**只造,不写盘**)。两个 write 函数原来各内联一份,现在共用这里。
+ *
+ * 🔴 `imageFile` 是**参数,不是从 id 推的**(2026-08-11,sps 报的潜伏 bug)——
+ *    `meta.image` 要回答的是「**引擎该去加载哪个文件**」,而只有**写图的那个人**知道图去了哪。
+ *    从 id 推,等于假设「图一定叫 <id>.png」。
+ *
+ *    在 studio 这个假设**碰巧成立**:`writeAsset` 走 `assetPath()`,扩展名钉死 `.png`、
+ *    与 atlas 同 id 同目录(`repo-shared.ts:20`)。所以本仓从来没撞过。
+ *    但**碰巧成立的前提不会跟着调用方走** —— sps 的 CLI 面加了与 `--id` 解耦的 `--out`,
+ *    只要 out 不是 `<assets-dir>/<id>.png`,atlas 就指向一个不存在的文件:
+ *    **结构合法、无报错、加载器找不到图。**
+ *
+ * 🔴 这正是本函数注释里那条教条自己被违反的例子:
+ *    **对引擎的声明要描述「引擎将看到的东西」,不是「我们做过什么」。**
+ *    `meta.image` 描述的必须是图的实际去处。
+ *
+ * ⚠️ 形状值得记:`id` 在这里身兼三职 —— 帧名前缀 / 引用的图名 / 落盘路径。
+ *    `--out` 只接管了第三职,**另外两职静默留在原处**。
+ *    **拆一个身兼多职的参数时,没被接管的那几职会静默错。**
+ *
+ * @param imageFile 图的实际文件名(相对 atlas 所在目录),如 `hero.png`
+ * @param framePrefix 帧名前缀(`<prefix>_0`…);`names` 给了就按 names 命名
+ */
+export function buildAtlas(imageFile, framePrefix, packed, names) {
+    const frames = {};
+    packed.frames.forEach((f, i) => {
+        frames[names?.[i] ?? `${framePrefix}_${i}`] = {
+            frame: { x: f.x, y: f.y, w: f.w, h: f.h },
+            // 🔴 已在 sliceSheet 裁到紧致 bbox → 这里必须声明 false 且偏移 0,
+            //    否则引擎会**再补一次偏移**(atlas 合法、每帧偏一点)。
+            rotated: false,
+            trimmed: false,
+            spriteSourceSize: { x: 0, y: 0, w: f.w, h: f.h },
+            sourceSize: { w: f.w, h: f.h },
+        };
+    });
+    return { frames, meta: { image: imageFile, format: 'RGBA8888', size: { w: packed.width, h: packed.height }, scale: '1' } };
+}
+/** 具名帧版(UI 契约用):帧名由调用方给定(如 ui_btn_lg),不走 <id>_<i> 序号。 */
+export function writeAtlasJsonNamed(assetsDir, id, packed, names) {
+    // studio 侧图恒为 `<assetsDir>/<id>.png`(assetPath 钉死扩展名)—— 这个推导在**这里**是真的。
+    writeFileSync(join(assetsDir, `${id}.json`), JSON.stringify(buildAtlas(`${id}.png`, id, packed, names)));
+}
+export function writeAtlasJson(assetsDir, id, packed) {
+    writeFileSync(join(assetsDir, `${id}.json`), JSON.stringify(buildAtlas(`${id}.png`, id, packed)));
+}
+/** 在紧凑图集每帧左上角画红色序号(0,1,2…),供视觉打标签时显式对齐索引。 */
+async function numberedPreview(packed) {
+    const texts = packed.frames
+        .map((f, i) => `<text x="${f.x + 2}" y="${f.y + 14}" font-size="14" font-family="sans-serif" font-weight="bold" fill="#ff0000" stroke="#ffffff" stroke-width="0.6">${i}</text>`)
+        .join('');
+    const svg = `<svg width="${packed.width}" height="${packed.height}">${texts}</svg>`;
+    return sharp(packed.buf).composite([{ input: Buffer.from(svg), top: 0, left: 0 }]).png().toBuffer();
+}
+/**
+ * 写「美术就绪」信号 `docs/asset-ready.json`(供构建 worker 的 wait-assets 脚本轮询)。
+ * generating=生成中;done=全部生成+检测完成、配置就位。worker 据此在使用点同步(美术与构建并行)。
+ */
+/**
+ * 等美术就绪 —— **读工作区里的 `docs/asset-ready.json`,不等进程内 promise**。
+ *
+ * ─── 为什么换掉 `await artJobs.get(id)` ────────────────────────────────
+ * 美术迁进 sps 之后,studio 手里**没有那个 promise 了**。而"打包前必须等资产就位"
+ * 这个需求还在(`buildAndServe` → `npm run build` → smoke,缺图就 404)。
+ *
+ * 🔴 状态放在**工作区文件**里,谁来读都一样 —— 这正是 worker 一直在用的机制
+ *    (`scripts/wait-assets.mjs` 轮询同一个文件)。**studio 挂了重启也能接着读。**
+ *
+ * ⚠️ **诚实的限定**:这不是"取消了轮询"。
+ *    「读文件直到 done」本质仍是循环,只是它在**打包这一步内部**,不是后台常驻。
+ *    准确说法:**取消了后台常驻轮询,保留了打包步骤内的一次性等待。**
+ *
+ * 🔴 **而它本身也是过渡机制**:Eddy 已定打包 + smoke 后续也迁 sps ——
+ *    那时生产方与消费方同侧,**这个等待自然消失**。
+ *    别把它当终态去加固(加重试策略、加指数退避、抽成通用 waiter……)。
+ *
+ * 语义:
+ * - 文件不存在 → **立刻返回**(这个项目没有美术任务,不是"还没开始")
+ * - `done`     → 立刻返回
+ * - `generating` → 轮到 done 或超时
+ * - 超时       → **放行并大声记一笔**,不抛
+ *   理由:卡死打包比晚一点打包更糟;而缺图 smoke 会抓到(它自带重试)。
+ *   🔴 但日志必须说清"我是超时放行的",否则 smoke 挂了会被归因成 chromium 抖动 ——
+ *      那正是这条竞态最难查的地方。
+ */
+export async function waitArtReady(repoDir, opts) {
+    const f = join(repoDir, 'docs', 'asset-ready.json');
+    if (!existsSync(f))
+        return 'absent';
+    const deadline = Date.now() + (opts?.timeoutMs ?? 30 * 60_000);
+    const interval = opts?.intervalMs ?? 2_000;
+    for (;;) {
+        try {
+            const j = JSON.parse(readFileSync(f, 'utf-8'));
+            if (j.state === 'done')
+                return 'done';
+        }
+        catch { /* 写到一半读到半个 JSON → 下一轮再读 */ }
+        if (Date.now() > deadline)
+            return 'timeout';
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}
+export function writeArtReady(repoDir, state, total) {
+    try {
+        const d = join(repoDir, 'docs');
+        mkdirSync(d, { recursive: true });
+        writeFileSync(join(d, 'asset-ready.json'), JSON.stringify({ state, total }));
+    }
+    catch {
+        /* 写就绪信号失败不致命:worker 超时后会按现有资源降级继续 */
+    }
+}
+/**
+ * 把 level.json 渲染成【语义蓝图 PNG】(绿底 / 红粗折线=路 / 蓝方块=塔位 / 紫方块=base),供图生图当结构参考——
+ * AI 图生图会保持这张图的布局(路走向、塔位位置),精修成精美背景 → 图和坐标同源。复用 numberedPreview 的 SVG+sharp 手法。
+ */
+export async function renderLevelBlueprint(level) {
+    const W = Math.max(1, level.width || 960);
+    const H = Math.max(1, level.height || 540);
+    const roadW = Math.round(Math.min(W, H) * 0.08); // 路宽 ≈ 屏 8%
+    const s = Math.round(Math.min(W, H) * 0.09); // 塔位方块边长
+    const pts = (level.path ?? []).map(([x, y]) => `${x},${y}`).join(' ');
+    const road = pts ? `<polyline points="${pts}" fill="none" stroke="#c0392b" stroke-width="${roadW}" stroke-linejoin="round" stroke-linecap="round"/>` : '';
+    const spots = (level.buildSpots ?? []).map(([x, y]) => `<rect x="${x - s / 2}" y="${y - s / 2}" width="${s}" height="${s}" rx="6" fill="#2f6fd8" stroke="#173a73" stroke-width="3"/>`).join('');
+    const base = level.base ? `<rect x="${level.base[0] - s}" y="${level.base[1] - s}" width="${s * 2}" height="${s * 2}" rx="8" fill="#8e44ad" stroke="#4a235a" stroke-width="4"/>` : '';
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}"><rect width="${W}" height="${H}" fill="#4a7c3a"/>${road}${base}${spots}</svg>`;
+    return sharp(Buffer.from(svg)).png().toBuffer();
+}
+/** 支持图生图(image-to-image)的 adapter。codex 通过多模态输入(input_image)做图像编辑;minimax/openrouter/gemini 各有图生图。火山等只文生图。 */
+const IMG2IMG_ADAPTERS = new Set(['codex', 'chatgpt', 'minimax', 'openrouter', 'gemini', 'volcengine']);
+/** 蓝图图生图的 prompt 补充:告诉模型参考图是【布局结构】而非风格。 */
+const BLUEPRINT_HINT = '。🔴以参考图为【布局结构蓝图】(不是风格参考):红色粗线的走向=铺成石板道路/敌人行进路径,**严格保持这条路的走向和形状**;' +
+    '蓝色方块、紫色方块只是【位置标记】——把那些格子画成**平整的空地/草地(可微微不同色示意),绝对不要画成城堡/塔楼/建筑/任何立体物件**(大本营和防御塔由游戏程序另外放置,AI 画了会重叠冲突);' +
+    '其余精修成精美的草原战场地形(草地/树/石头点缀)。**只精修路径和地形,不添加任何游戏建筑/单位**。';
+/** 确定性 downscale 目标高(px):按 type 语义分档、相对游戏逻辑分辨率。
+ *  2026-07-21 与用户定案「资源尺寸相对适配游戏」:此前一刀切 35% 屏高,小道具实际只显示 4~8% 屏高
+ *  → 源图超出 5~8 倍(包体/加载浪费,且绝对值缩放 bug 一触发就是好几倍的巨物)。
+ *  按 manifest type 的语义定档(设计时已知),各档保留 1.5~3× 余量(TUNABLES 调参/二修放大仍清晰):
+ *    角色/主角/Boss(显示 10~18% 屏高)→ 30%;敌人/混合图集(含主角的合图)→ 24%;
+ *    道具/元素/特效/子弹(显示 4~8%)→ 16%;UI(非契约套件)→ 22%;背景整屏。 */
+function targetMaxH(type, logicalH) {
+    const t = (type ?? '').toLowerCase();
+    if (t.startsWith('scene') || t.startsWith('bg'))
+        return logicalH;
+    if (t.startsWith('ui'))
+        return Math.round(logicalH * 0.22);
+    if (/character|player|hero|boss|主角/.test(t))
+        return Math.round(logicalH * 0.3);
+    if (/element|item|effect|projectile|bullet|pickup|collect|prop|道具/.test(t))
+        return Math.round(logicalH * 0.16);
+    return Math.round(logicalH * 0.24); // enemy / sprite/sheet(混合合图,可能含主角)/未细分
+}
+/**
+ * 成品落盘前统一成 PNG(**#19d**,Eddy 2026-08-12 拍板的修法②)。
+ *
+ * 🔴 **这不是顺手优化,是在本次迁移唯一的防漂移网上有意开的一个口子。**
+ * 在此之前,产物的真实格式**随 provider 漂**:1.11b 真跑实测 doubao 返回 JPEG、
+ * agnes 返回 PNG,而 `<id>.png` 这个名字是写死的 ⇒ 文件名与内容可以不符,
+ * 且 JPEG **没有 alpha 通道**。它同时取决于哪家 provider 与这张资产 transparent 开没开。
+ * 归因:**本来就坏** —— studio 冻结基线 `imageGen.ts:733/:800` 同样不转码,逐字移植搬了过来。
+ *
+ * 🔴 **已知代价(拍板时已接受)**:「逐像素与 studio 一致」这条判据在**无 `logical` 的项目**上
+ * 不再成立 —— studio 那边不转。一致性测试(studio `artConsistency.test.ts`)若因此在无 logical
+ * 夹具上转红,**那是预期的**:要改就改断言并写明理由,**不要改夹具让它变绿**。
+ * (该测试在 4.2 会整体删掉,但**现在还不能删**。)
+ *
+ * ⚠️ 成本:只在**不是 PNG 时**多一次编码。有 `logical` 的项目(gameforge 的 `game.json` 有宽高)
+ * 末尾那次 `resize(...).png()` 本就已经转过,此处是 metadata 一次读、直接返回原 buf。
+ */
+async function ensureAssetPng(buf) {
+    try {
+        if ((await sharp(buf).metadata()).format === 'png')
+            return buf;
+        return await sharp(buf).png().toBuffer();
+    }
+    catch {
+        // 🔴 失败一律保守(与本文件其它 catch 同取向):转不动也不能毁掉产物。
+        // 代价是退回"名叫 .png 的非 PNG",但那正是改这条之前的行为,不会更糟。
+        return buf;
+    }
+}
+// (导出供修复脚本复用:从 _raw 原图重跑「抠图→切帧→归一→打包」链,修复被旧抠图算法损坏的成品资产)
+export async function finalizeAsset(buf, a, assetsDir, source, rawBuf, rawOnly = false, logical) {
+    // 🔴 留底【AI 直出原图】到 assets/_raw/<id>.png:优先用 rawBuf(抠图/缩放【前】、含品红底的真原图);
+    //    缺则退回 buf。下游后处理(抠图/图集切分/透明裁边/翻转)有损,原图必须可追溯/可恢复/可重切。
+    //    用户明确要求:_raw 要是 AI 首次返回、带品红背景、未经任何处理的图。
+    try {
+        const rawDir = join(assetsDir, '_raw');
+        mkdirSync(rawDir, { recursive: true });
+        const src = rawBuf ?? buf;
+        // 统一编码成 PNG 保证可预览(只换容器、不动像素,品红底保留)。
+        const png = await sharp(src).png().toBuffer().catch(() => src);
+        writeFileSync(join(rawDir, `${a.id}.png`), png);
+    }
+    catch { /* 留底失败不阻断主流程 */ }
+    // rawOnly:美术流水线的「生成棒」用——只落原图,把抠图/切分/裁边/翻转全留给后面的「处理 agent」,避免与之重叠打架。
+    if (rawOnly) {
+        // 🔴 成品落盘一律走原子写(1.10):幂等的判据是"目标文件存在就跳过",
+        //    直写最终名时任何一次中断都会留下顶着最终名的半截文件 → 下一轮当它已完成。
+        // #19d:这条路同样写成品 `<id>.png`(rawOnly 只是不做抠图/切分,不是"可以名不副实")。
+        writeAssetAtomic(join(assetsDir, `${a.id}.png`), await ensureAssetPng(buf));
+        return { id: a.id, ok: true, source };
+    }
+    let outBuf = buf;
+    let meta;
+    // 🔴 前景视差层验收:中央区(60%×60%)不透明占比 >35% = 模型把剪影画成了盖住玩法区的大块
+    //    (星际穿梭 fg 巨舰事故;prompt 只有劝导力)→ 抛错让 genOne 换 provider 重试;全败由
+    //    genOne 落【全透明整幅】优雅降级(fg 是增强层,缺了游戏无感)。
+    if ((a.type ?? '').toLowerCase().startsWith('scene/foreground')) {
+        try {
+            const { data, info } = await sharp(buf).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+            const W = info.width, H = info.height;
+            const x0 = Math.round(W * 0.2), x1 = Math.round(W * 0.8), y0 = Math.round(H * 0.2), y1 = Math.round(H * 0.8);
+            let n = 0, op = 0;
+            for (let y = y0; y < y1; y += 2)
+                for (let x = x0; x < x1; x += 2) {
+                    n++;
+                    if (data[(y * W + x) * 4 + 3] > 40)
+                        op++;
+                }
+            const ratio = op / Math.max(1, n);
+            if (ratio > 0.35)
+                throw new Error(`fg-center-covered: 前景层中央区不透明 ${Math.round(ratio * 100)}%(>35%),会盖住玩法区,拒用`);
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.startsWith('fg-center-covered'))
+                throw e;
+            /* 读图失败 → 放行(别为校验挂正常资产) */
+        }
+    }
+    const isUiKit = (a.type ?? '') === 'ui/kit';
+    if (isUiKit) {
+        // 🔴 UI 线稿契约(uiKit.ts):帧矩形生成前已知 → 图集 json 直接按契约写(帧名全平台固定),
+        //    跳过缝隙切分与视觉打标。先把成图精确拉回画布尺寸(provider 可能按自家档位回图,
+        //    坐标契约以画布为基准,fit:fill 保契约优先);下游 trim/downscale 对 ui/kit 一律豁免(会移坐标)。
+        try {
+            outBuf = await sharp(outBuf).resize(UI_KIT_CANVAS.w, UI_KIT_CANVAS.h, { fit: 'fill' }).png().toBuffer();
+        }
+        catch { /* resize 失败保持原图:若 provider 恰好同尺寸仍可用 */ }
+        // v1.3 裁切重组:bbox 逐帧裁出(搜索窗=邻帧半距)→ 紧凑重排(尺寸=实际内容 + 挤掉空隙)。
+        //    失败退回契约矩形直切(图保持画布尺寸)。
+        let fit = UI_KIT_FRAMES.map((f) => ({ name: f.name, x: f.x, y: f.y, w: f.w, h: f.h }));
+        let outW = UI_KIT_CANVAS.w, outH = UI_KIT_CANVAS.h;
+        try {
+            const rp = await fitAndRepackUiKit(outBuf);
+            outBuf = rp.buf;
+            fit = rp.frames;
+            const m = await sharp(outBuf).metadata();
+            outW = m.width ?? outW;
+            outH = m.height ?? outH;
+        }
+        catch (e) {
+            // 🔴 结构失守 = 这张图不能切(位置锚定切分会把错位控件切成几块)→ 上抛,genOne 按
+            //    provider 失败处理(换下家重试,链全败落线稿兜底)。其余异常退回契约矩形直切。
+            if (e instanceof Error && e.message.includes(UIKIT_STRUCTURE_BROKEN))
+                throw e;
+        }
+        const packed = {
+            buf: outBuf,
+            frames: fit.map((f) => ({ x: f.x, y: f.y, w: f.w, h: f.h })),
+            width: outW, height: outH, detected: true,
+        };
+        writeAtlasJsonNamed(assetsDir, a.id, packed, fit.map((f) => f.name));
+        meta = { frames: UI_KIT_FRAMES.map((f) => ({ name: f.name, label: f.label })) };
+    }
+    else if (a.sheet && a.sheet.cols >= 1 && a.sheet.rows >= 1) {
+        // 成套图集:切出每元素 → 紧凑重排成图集 + 写同名 .json(TexturePacker)→ 构建端 load.atlas。
+        try {
+            const packed = await packSheet(buf, a.sheet.cols, a.sheet.rows, logical ? { frameMaxHeight: targetMaxH(a.type, logical.h) } : undefined);
+            outBuf = packed.buf;
+            writeAtlasJson(assetsDir, a.id, packed);
+            const numbered = await numberedPreview(packed);
+            const insp = await inspectSheetLabels(`data:image/png;base64,${numbered.toString('base64')}`, packed.frames.length, a.desc);
+            const labels = insp.labels;
+            // 🔴 up/down 判定的几何护栏(Iron Wings 实测:俯视飞机全部朝右,视觉却误判 up/down,
+            //    烤转把对图转错)。机头真朝上/下的帧几乎必然"高>宽"(雷霆战机 4 帧全 h>w 实证);
+            //    判 up/down 但形状横扁 = 存疑,拒转保原图——误放行(不转)的代价远小于误转。
+            for (let i = 0; i < packed.frames.length; i++) {
+                const fc = insp.facing[i];
+                if ((fc === 'up' || fc === 'down') && packed.frames[i].h < packed.frames[i].w * 1.1) {
+                    console.warn(`⚠️ 图集 ${a.id}:帧 ${i} 视觉判 ${fc} 但形状横扁(${packed.frames[i].w}x${packed.frames[i].h}),存疑不转`);
+                    insp.facing[i] = 'none';
+                }
+            }
+            // 🔴 逐帧朝向纠正(平台契约:角色美术统一面朝右):left 水平翻转;up/down 旋转 90° 归一
+            //    (竖版飞机大战实测:desc 写"机头朝上"模型照样画横的、偶尔真画竖的——四向不归一,
+            //    worker 的固定校正角就永远不可靠)。重建整张画布逐帧 composite(不能只叠改动帧:
+            //    透明区 over 混合会留下原像素的叠影)。
+            const fixIdx = packed.frames.map((_, i) => i).filter((i) => insp.facing[i] === 'left' || insp.facing[i] === 'up' || insp.facing[i] === 'down');
+            if (fixIdx.length) {
+                try {
+                    const parts = [];
+                    for (let i = 0; i < packed.frames.length; i++) {
+                        const f = packed.frames[i];
+                        const fc = insp.facing[i];
+                        const region = await sharp(outBuf).extract({ left: f.x, top: f.y, width: f.w, height: f.h }).png().toBuffer();
+                        if (fc === 'up' || fc === 'down') {
+                            // 机头朝上→顺时针 90° 变朝右;朝下→逆时针。旋转后宽高互换,超出原格子就等比缩回、居中放置。
+                            let rw = f.h, rh = f.w;
+                            let img = sharp(region).rotate(fc === 'up' ? 90 : 270);
+                            if (rw > f.w || rh > f.h) {
+                                const s = Math.min(f.w / rw, f.h / rh);
+                                rw = Math.max(1, Math.floor(rw * s));
+                                rh = Math.max(1, Math.floor(rh * s));
+                                img = sharp(await img.png().toBuffer()).resize(rw, rh);
+                            }
+                            parts.push({ input: await img.png().toBuffer(), left: f.x + Math.floor((f.w - rw) / 2), top: f.y + Math.floor((f.h - rh) / 2) });
+                        }
+                        else if (fc === 'left') {
+                            parts.push({ input: await sharp(region).flop().png().toBuffer(), left: f.x, top: f.y });
+                        }
+                        else {
+                            parts.push({ input: region, left: f.x, top: f.y });
+                        }
+                    }
+                    outBuf = await sharp({ create: { width: packed.width, height: packed.height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } })
+                        .composite(parts).png().toBuffer();
+                    console.warn(`⚠️ 图集 ${a.id}:${fixIdx.length} 帧朝向已归一为面朝右(帧 ${fixIdx.map((i) => `${i}:${insp.facing[i]}`).join(',')})`);
+                }
+                catch { /* 纠正失败保持原图(朝向错但图不坏) */ }
+            }
+            // 自动合图的 sheet:即使视觉打标为空,也把 mergedFrom 的原语义 id 按帧序记进 asset-meta(semanticId),worker 据此映射回原语义。
+            // facing = 归一后的朝向落进配置(worker 可据此精确决定哪些帧要按场景校正角度):
+            //   'right' = 有明确朝向、已归一为面朝右(竖版射击等场景需 setAngle 校正);'none' = 对称/无方向物件,免转。
+            const semIds = a.mergedFrom;
+            if (labels.length || semIds?.length)
+                meta = { frames: packed.frames.map((_, i) => ({
+                        name: `${a.id}_${i}`,
+                        label: labels[i] ?? '',
+                        ...(insp.facing[i] ? { facing: insp.facing[i] === 'none' ? 'none' : 'right' } : {}),
+                        ...(semIds?.[i] ? { semanticId: semIds[i] } : {}),
+                    })) };
+        }
+        catch {
+            outBuf = buf; // 打包失败 → 退回原图(下游仍可按 cols/rows 等分)
+        }
+    }
+    else if (a.orient === 'flipX') {
+        // flipX 侧面精灵:约定"面朝右",模型/用户画成面朝左 → 视觉判出后水平翻转。失败/unknown 不动。
+        try {
+            if ((await detectFacing(`data:image/png;base64,${outBuf.toString('base64')}`)) === 'left') {
+                outBuf = await sharp(outBuf).flop().png().toBuffer();
+            }
+        }
+        catch { /* 检测/翻转失败 → 保持原图 */ }
+    }
+    // 单图透明精灵:裁掉四周透明边距,主体填满画框 → hitbox 才准。
+    // 🔴 场景层(scene/*:前景 fg 等透明整幅)不 trim:透明区是【构图】(草丛贴下缘、上方留空),
+    //    裁掉就只剩条带,上屏铺满时被拉伸成巨物(像素跑酷 fg_near 事故第二环)。
+    const isSceneLayer = (a.type ?? '').toLowerCase().startsWith('scene');
+    if (!isUiKit && !isSceneLayer && !a.sheet && a.transparent === true) {
+        try {
+            outBuf = await sharp(outBuf).trim().png().toBuffer();
+        }
+        catch { /* 全透明/裁剪失败 → 保持原图 */ }
+    }
+    // 确定性 downscale(压缩尺寸):单图(背景=整屏、其余按 type 档)缩到合理大小。图集在 packSheet 的 frameMaxHeight 已缩。
+    if (!isUiKit && !a.sheet && logical) {
+        try {
+            const t = (a.type ?? '').toLowerCase();
+            const opt = t.startsWith('scene') || t.startsWith('bg')
+                ? { width: logical.w, height: logical.h, fit: 'inside', withoutEnlargement: true }
+                : { height: targetMaxH(a.type, logical.h), fit: 'inside', withoutEnlargement: true };
+            outBuf = await sharp(outBuf).resize(opt).png().toBuffer();
+        }
+        catch { /* 缩放失败 → 保持原图 */ }
+    }
+    // #19d:落盘前统一成 PNG —— 末尾那次 resize().png() 只在有 logical 时执行,
+    //       没有它时上游给什么格式就写什么(1.11b 实测:doubao 给 JPEG)。
+    writeAssetAtomic(join(assetsDir, `${a.id}.png`), await ensureAssetPng(outBuf)); // 见上:成品一律原子写
+    return { id: a.id, ok: true, source, meta };
+}
+/** 生成单张资源(含尺寸+抠图)→ 存盘。**429/限流/5xx/超时 自动指数退避重试**(适配 API QPS 限制)。
+ *
+ * ⚠️ **导出仅为测试**:这段是「改了不会有任何测试发现」清单的所在
+ * (退避阶梯 / 失败分类 / 回退留痕 / 三条降级),而它今天唯一的网就是 `genOne.test.ts`。 */
+export async function genOne(providers, a, style, view, ctx, referenceDataUrl, rawOnly = false, logical) {
+    const { assetsDir, repoDir } = ctx;
+    // 蓝图图生图:prompt 追加"按参考图布局"说明(仅当 ref 是关卡蓝图);其余 ref(风格锚定)不加。
+    const isBlueprint = !!referenceDataUrl && !!a.ref?.includes('level-blueprint');
+    // 🔴 UI 契约套件:prompt 整体换成 uiKitPrompt(结构靠线稿参考图锁死,这里只注风格),不走 buildPrompt。
+    const prompt = (a.type ?? '') === 'ui/kit'
+        ? uiKitPrompt([style, a.desc].filter(Boolean).join(';'))
+        : buildPrompt(a, style, view, ctx.artPrompts) + (isBlueprint ? BLUEPRINT_HINT : '');
+    let lastErr = '';
+    // 🔴 图生图必须用支持图生图的 provider(minimax/openrouter/gemini);默认 codex/火山不支持会退化成文生图、蓝图白给。
+    //    有 referenceDataUrl 时把供应商链重排成"支持图生图的优先";一个都没配 → warn、退回文生图不崩。
+    let provs = providers;
+    if (referenceDataUrl) {
+        provs = [...providers].sort((x, y) => (IMG2IMG_ADAPTERS.has(y.adapter) ? 1 : 0) - (IMG2IMG_ADAPTERS.has(x.adapter) ? 1 : 0));
+        if (!provs.some((p) => IMG2IMG_ADAPTERS.has(p.adapter))) {
+            // 🔴 UI 契约套件:结构 100% 依赖图生图。纯文生图必然自由排版 → 契约切分错乱(画卷飞剑事故:
+            //    远程无 codex、火山未接图生图 → ui 布局乱 + 裁切碎)。无图生图 provider 时直接用线稿当成品
+            //    (灰阶但结构/坐标全对,可玩;下轮配好 provider 重生成即可换风格)。
+            if ((a.type ?? '') === 'ui/kit') {
+                console.warn(`⚠️ 资产 ${a.id}(ui/kit):未配任何图生图 provider,风格化降级为灰阶线稿本体(结构优先)`);
+                try {
+                    const wire = await renderUiWireframe();
+                    const st = await finalizeAsset(wire, a, assetsDir, 'generated', wire, rawOnly, logical);
+                    st.provider = 'uikit-wireframe/降级';
+                    return st;
+                }
+                catch { /* 线稿失败 → 继续走文生图(最后手段) */ }
+            }
+            console.warn(`⚠️ 资产 ${a.id} 需图生图但未配支持的 provider(codex/minimax/openrouter/gemini/volcengine),退回文生图`);
+        }
+    }
+    // 供应商回退链:首选失败 → 依次换其它。内容审核拒绝换家常能过;限流/超时则同一家退避重试。
+    for (const provider of provs) {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            if (attempt > 0) {
+                // 退避:1s/2s/4s/8s + 抖动,错开并发重试避免再次撞限流
+                const wait = 1000 * 2 ** (attempt - 1) + Math.floor(Math.random() * 600);
+                await new Promise((r) => setTimeout(r, wait));
+            }
+            try {
+                // 🔴 三段拆开(studio 侧它们长在 generateImage 一个函数里):
+                //    ① 出图 = media 层(provider 适配 + 点名这一家)· ② 抠图决策树 = composeAsset
+                //    ③ 生成尺寸/最终编码 = imageSize —— ③ 谁都不认领,但它是 `a.size` 唯一被兑现的地方。
+                const target = parseSize(a.size);
+                const gen = target ? genSizeFor(target) : null;
+                // _raw 就是 generateAsset 的落点:AI 直出、含品红底、未经处理 —— 留底本来就是设计要求的
+                //(`redo:post` 靠它重跑抠图→切帧→归一),所以这次落盘不是多余的中间产物。
+                // ⚠️ `finalizeAsset` 随后会把同一份 raw 再统一编码成 PNG 写回**同一个路径**(幂等):
+                //    留着那次写是因为"_raw 必须是 AI 首次返回的图"这条语义归 finalizeAsset 管,
+                //    provided/线稿降级等不走 generateAsset 的路径也靠它。
+                // 🔴 内层 `withRateLimitRetry` 是**限流退让**(只认 429,等一等就过去);外层 attempt 是
+                //    **供应商级**重试+换家。少了内层,限流会变成"消耗一次供应商配额" → 更快回退到差供应商。
+                const res = await withRateLimitRetry(() => generateAsset({
+                    capability: 'image',
+                    providerId: provider.id, // 🔴 点名:没有它,"换一家重试"会变成同一家跑五遍
+                    prompt: withTransparency(prompt, a.transparent === true),
+                    cwd: repoDir,
+                    outPath: join('assets', '_raw', `${a.id}.png`),
+                    size: gen ? `${gen.w}x${gen.h}` : a.size,
+                    referenceUrl: referenceDataUrl,
+                }));
+                const raw = readFileSync(join(repoDir, res.path));
+                let buf = await composeAsset(raw, { transparent: a.transparent === true }, ctx.ops);
+                // 最后一次编码:resize + 压缩一次完成(有 target);无 target 则纯压缩。内部失败回退原图。
+                buf = target ? await compressKeepFormat(buf, { resize: { w: target.w, h: target.h } }) : await compressKeepFormat(buf);
+                const pName = `${provider.name || provider.adapter}/${res.model || provider.adapter}`;
+                // 非首选生成成功 = 走了回退链 → 必须留痕(否则"配置 A、实际 B 生成"完全不可见,排查靠猜)
+                // 🔴 留痕是**运维信号**,不是用户叙事 —— 不要升级成事件。
+                if (provider !== provs[0])
+                    console.warn(`⚠️ 资产 ${a.id}:首选 provider 失败,回退到 ${pName} 生成(上家错误:${lastErr.slice(0, 160)})`);
+                const st = await finalizeAsset(buf, a, assetsDir, 'generated', raw, rawOnly, logical);
+                st.provider = pName;
+                return st;
+            }
+            catch (e) {
+                lastErr = e instanceof Error ? e.message : String(e);
+                console.warn(`⚠️ 资产 ${a.id}:${provider.name || provider.adapter} 生成失败(attempt ${attempt + 1}):${lastErr.slice(0, 200)}`);
+                // 结构失守(ui/kit 生成图没跟线稿布局)→ 同一家重试大概率还是不跟,直接换下一家
+                if (lastErr.includes('uikit-structure-broken'))
+                    break;
+                // 前景中央被盖 = 采样波动,同一家重画常能救 → 不 break,走退避重试(耗尽再换家)
+                if (lastErr.includes('fg-center-covered'))
+                    continue;
+                // 限流/网关/超时 → 同一家退避重试;参数错/鉴权错/内容审核拒绝 → 不重试,跳出换下一家供应商
+                if (!/429|rate|throttl|限流|timeout|超时|50[234]|网关|abort/i.test(lastErr))
+                    break;
+            }
+        }
+        // 这家失败(审核拒绝/重试耗尽)→ 外层 for 换下一家供应商
+    }
+    // 🔴 前景层链全败(各家都画满中心/失败)→ 全透明整幅优雅降级:fg 是增强层,透明=没有前景,游戏无感
+    if ((a.type ?? '').toLowerCase().startsWith('scene/foreground')) {
+        try {
+            const dim = /(\d+)\s*x\s*(\d+)/.exec(a.size ?? '');
+            const w = dim ? Number(dim[1]) : 1024, h = dim ? Number(dim[2]) : 1024;
+            const blank = await sharp({ create: { width: w, height: h, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } }).png().toBuffer();
+            writeAssetAtomic(join(assetsDir, `${a.id}.png`), blank); // 成品落盘一律原子写(1.10)
+            console.warn(`⚠️ 资产 ${a.id}(前景层):各 provider 均不合格,降级为全透明整幅(游戏无感,失去视差增强)`);
+            return { id: a.id, ok: true, source: 'generated', provider: 'fg-blank/降级', error: lastErr.slice(0, 160) };
+        }
+        catch { /* 落到 ok:false */ }
+    }
+    // 🔴 ui/kit 链全败(含各家结构失守)→ 灰阶线稿本体兜底:结构/坐标全对、可玩,绝不输出错乱切分
+    if ((a.type ?? '') === 'ui/kit') {
+        try {
+            console.warn(`⚠️ 资产 ${a.id}(ui/kit):所有 provider 失败/结构失守,降级为灰阶线稿本体(${lastErr.slice(0, 120)})`);
+            const wire = await renderUiWireframe();
+            const st = await finalizeAsset(wire, a, assetsDir, 'generated', wire, rawOnly, logical);
+            st.provider = 'uikit-wireframe/降级';
+            return st;
+        }
+        catch { /* 线稿也失败 → 落到 ok:false */ }
+    }
+    return { id: a.id, ok: false, error: lastErr };
+}
+/**
+ * 批量生成游戏美术资源 —— **并发 worker 池 + 限流**(阶段3)。
+ * concurrency 个 worker 从队列拉取并行生成(每张含尺寸+抠图);失败不阻塞其它。
+ * onProgress(done,total) 供编排层报进度。结果写 assets/asset-status.json。
+ */
+/** 占位资产的逻辑尺寸:产物清单权威 → build-manifest 兜底 → 默认 800×600。
+ *  `manifestFile` 随任务下发(`game.json` / `experiment.json` …)—— sps 不该知道哪个产品叫什么。 */
+function placeholderLogicalSize(repoDir, manifestFile) {
+    try {
+        const gj = JSON.parse(readFileSync(join(repoDir, manifestFile), 'utf-8'));
+        if (gj.width && gj.height)
+            return { w: gj.width, h: gj.height };
+    }
+    catch { /* 无产物清单 */ }
+    try {
+        const bm = JSON.parse(readFileSync(join(repoDir, 'docs', 'build-manifest.json'), 'utf-8'));
+        if (bm.width && bm.height)
+            return { w: bm.width, h: bm.height };
+    }
+    catch { /* 无 build-manifest */ }
+    return { w: 800, h: 600 };
+}
+function expectedAssetFile(a) {
+    const t = (a.type ?? '').toLowerCase();
+    return t.startsWith('audio') ? `${a.id}.mp3` : `${a.id}.png`;
+}
+export function assetKind(a) {
+    return (a.type ?? '').toLowerCase().startsWith('audio') ? 'audio' : 'visual';
+}
+// 🔴 studio 侧这里还有一个 `generateAudioAssets`(音频专用入口,刻意绕开单一开关,
+//    免得切换那一刻 BGM 跟着断)—— **sps 侧不要**:音频本版留 studio,
+//    在这儿摆一个跑不了的入口是**假的**(它会让人以为 sps 能出音频)。
+//    音频归 sps 那天再加,而那时它不需要"绕开开关"这条理由。
+export async function generateGameArt(task, onProgress, opts) {
+    // 🔴 它是**第二个入口**(index.ts:1330 绕过 runArt 直接调)——
+    //    ⚠️ studio 侧那句 assertLocalArtDriverAllowed() 在这里**删掉**:那是 studio 的"单一开关",
+    //    用来保证切换后旧 driver 不再动手;**sps 就是新 driver**,再守一次等于自己把自己关掉。
+    // 作业归因:计量随网关 token 走,sps 不维护 ALS(runWithJob 是显式空实现,见 jobContext.ts 头注)。
+    return runWithJob({ jobId: task.jobId, projectId: task.locator.projectId }, () => generateGameArtInner(task, onProgress, opts));
+}
+async function generateGameArtInner(task, onProgress, opts) {
+    // 落点由 sps 正向拼(调用方永远不传路径)——`repoDir` 的等价物。
+    const repoDir = resolveProjectDir(task.locator);
+    const { artPrompts, manifestFile } = task;
+    const manifest = readArtManifest(repoDir);
+    if (!manifest || !manifest.assets.length)
+        return [];
+    // 归一化 id:剥掉 id 里误带的图片扩展名(设计师有时写 bg.jpg/myplane.png,尤其套模板时)——
+    // 否则存成 bg.jpg.png(双扩展),代码按 assets/bg.jpg 加载 404、整局 smoke 挂。
+    // 在生成前重写 manifest 文件,构建 worker(等 wait-assets 后才读 manifest 接入)读到的就是裸 id。
+    const EXT = /\.(png|jpe?g|webp|gif)$/i;
+    if (manifest.assets.some((a) => EXT.test(a.id))) {
+        for (const a of manifest.assets)
+            a.id = a.id.replace(EXT, '');
+        try {
+            const mf = join(repoDir, 'docs', 'art-manifest.json');
+            const raw = JSON.parse(readFileSync(mf, 'utf-8'));
+            if (Array.isArray(raw.assets)) {
+                for (const a of raw.assets)
+                    if (typeof a?.id === 'string')
+                        a.id = a.id.replace(EXT, '');
+                writeFileSync(mf, `${JSON.stringify(raw, null, 2)}\n`);
+            }
+        }
+        catch { /* 重写失败:内存里已归一化,生成的文件仍裸名,worker 多数也能对上 */ }
+    }
+    // 🔴 生图前合图兜底:设计师把同类元素拆成一堆单张(违反 design-art-manifest「≤3 张」)时,自动合并成 sheet →
+    //    生图只生 1 张 → 规避几十张并行的图床限流 429(星际防线事故)。写回 manifest,worker 读到的就是合并后的 sheet。
+    const mergeNotes = mergeStraySprites(manifest);
+    if (mergeNotes.length) {
+        console.warn(`⚠️ 生图前自动合图(设计师未按 design-art-manifest 合并,${mergeNotes.length} 组):\n  ${mergeNotes.join('\n  ')}`);
+        try {
+            const mf = join(repoDir, 'docs', 'art-manifest.json');
+            const raw = JSON.parse(readFileSync(mf, 'utf-8'));
+            raw.assets = manifest.assets; // 用合并后的资产覆盖 → worker(wait-assets 后才读 manifest)按 sheet 接入
+            writeFileSync(mf, `${JSON.stringify(raw, null, 2)}\n`);
+        }
+        catch { /* 写回失败:内存已合并、生成仍走合并;worker 读旧 manifest 可能对不上散 id → 已 warn */ }
+    }
+    // ⚠️ studio 侧这里还有一句「没有 art 工序的通道直接空返回」的防御性护栏 —— **删掉**:
+    //    那是 studio 内部的工序表守卫,而调用方已经决定了要不要调这条流水线。
+    // 尽早写「生成中」(覆盖上次构建的 done,避免 revise 时 worker 读到陈旧 done 提前放行)。
+    writeArtReady(repoDir, 'generating', manifest.assets.length);
+    // ══════════════════════════════════════════════════════════════════════
+    // 🔴 studio 侧这里原有 18 行「选 provider」(fetchPartnerConfig → pcTool → listImageProviders
+    //    → getArtConfig → getImageProvider),**整段删掉**。
+    //    读整段才看得出:它在 import 列表里是三个独立依赖,实际是**一条链**,
+    //    而链的出口只有 `(provider, model)` 两个值 —— 而 sps 的 media 层
+    //    (`resolveMediaProvider(capability, cwd)`:项目级 `<cwd>/.sps/media-providers.json`
+    //    > 全局默认,按 capability 逐个覆盖)**已经在做同一件事**。
+    //    逐个替换会写出三层适配器去还原一个已经存在的能力。
+    //    ⇒ 这里只要"有哪些能用、谁排第一",provider/key 的解析在 `generateAsset` 内部完成。
+    // ══════════════════════════════════════════════════════════════════════
+    const assetsDir = join(repoDir, 'assets');
+    mkdirSync(assetsDir, { recursive: true });
+    // 改图:regen 列出的资产先删旧文件 → 下面 worker 见缺失即重生(只重生这些,其余 kept)。
+    // 删完即把 regen 从磁盘 manifest 清掉(一次性,避免下次构建又重删)。
+    if (manifest.regen?.length) {
+        const regenSet = new Set(manifest.regen);
+        for (const id of regenSet) {
+            // 🔴 删除前先把旧图快照到 docs/refs/<id>-prev.png:支持「微调型改图」——修改师把该资产
+            //    ref 设为这个快照路径 → 生成走图生图、大体保持原构图只按新 desc 微调(delete-first 的
+            //    顺序坑:不快照的话,生成时 ref 指向的原文件已被删)。没设 ref 的默认重生完全不受影响
+            //    (快照只是多一份文件);首次构建无 regen → 本段不跑,首次生图规则零影响。
+            try {
+                const prevPng = join(assetsDir, `${id}.png`);
+                if (existsSync(prevPng)) {
+                    const refDir = join(repoDir, 'docs', 'refs');
+                    mkdirSync(refDir, { recursive: true });
+                    copyFileSync(prevPng, join(refDir, `${id}-prev.png`));
+                }
+            }
+            catch { /* 快照失败不阻断:微调退化成普通重生 */ }
+            for (const f of [`${id}.png`, `${id}.json`, `${id}.mp3`, `${id}.glb`]) {
+                const p = join(assetsDir, f);
+                if (existsSync(p)) {
+                    try {
+                        unlinkSync(p);
+                    }
+                    catch { /* */ }
+                }
+            }
+        }
+        try {
+            const mf = join(repoDir, 'docs', 'art-manifest.json');
+            const raw = JSON.parse(readFileSync(mf, 'utf-8'));
+            delete raw.regen;
+            writeFileSync(mf, `${JSON.stringify(raw, null, 2)}\n`);
+        }
+        catch { /* 清空失败不致命:大不了下次再删一遍同样的文件 */ }
+    }
+    // 参考图(图生图):每张优先用资产自带 ref,否则用全局 ref;读成 data URL 传给生成。
+    const globalRef = refToDataUrl(repoDir, manifest.ref);
+    // 游戏逻辑分辨率(game.json)→ 确定性 downscale 的目标尺寸基准。读不到就不缩(保持原尺寸)。
+    let logical;
+    try {
+        const gj = JSON.parse(readFileSync(join(repoDir, manifestFile), 'utf-8'));
+        if (gj.width && gj.height)
+            logical = { w: gj.width, h: gj.height };
+    }
+    catch { /* 无 game.json → 不缩 */ }
+    // 🔴 背景/前景画幅:scene 契约(docs/25)优先——scroll 决定构图轴,画幅跟着 scroll 走;
+    //    无契约则缺 size 按逻辑分辨率兜底(横竖版画幅跟着游戏走,竖版游戏别再吃横图拉伸)。
+    {
+        let scroll;
+        try {
+            const bm = JSON.parse(readFileSync(join(repoDir, 'docs', 'build-manifest.json'), 'utf-8'));
+            scroll = bm.scene?.scroll;
+        }
+        catch { /* 无 build-manifest → 走逻辑分辨率兜底 */ }
+        const scrollSize = scroll === 'horizontal' ? '1536x1024' : scroll === 'vertical' ? '1024x1536' : scroll === 'free' ? '1024x1024' : undefined;
+        for (const a of manifest.assets) {
+            const t = (a.type ?? '').toLowerCase();
+            if (!(t.startsWith('scene') || t.startsWith('bg')))
+                continue;
+            if (scrollSize) {
+                // 以 scroll 为准纠正(设计师给了冲突的画幅也覆盖——滚动轴错了整图作废)
+                if (a.size && a.size !== scrollSize)
+                    console.warn(`⚠️ 资产 ${a.id}:size=${a.size} 与 scene.scroll=${scroll} 冲突,已按契约纠正为 ${scrollSize}`);
+                a.size = scrollSize;
+            }
+            else if (!a.size && logical) {
+                a.size = `${logical.w}x${logical.h}`;
+            }
+        }
+    }
+    // 🔴 布局型游戏(塔防等):有 docs/level.json → 渲染语义蓝图 → 给场景背景资产注入图生图 ref。
+    //    数据驱动:无 level.json 则整段跳过,非布局游戏零影响。
+    try {
+        const levelFile = join(repoDir, 'docs', 'level.json');
+        if (existsSync(levelFile)) {
+            const level = JSON.parse(readFileSync(levelFile, 'utf-8'));
+            const refDir = join(repoDir, 'docs', 'refs');
+            mkdirSync(refDir, { recursive: true });
+            writeFileSync(join(refDir, 'level-blueprint.png'), await renderLevelBlueprint(level));
+            // 背景资产没自己标 ref 时,注入蓝图 ref → 下面走图生图(以蓝图为布局结构)。
+            // 🔴 同时把 size 设成 = level 尺寸,让 codex 按蓝图【同尺寸】生成 → 零缩放变形、塔位精确对齐
+            //   (尺寸不一致会非等比压扁、建造位偏移)。level 尺寸最好用 codex 支持的宽高比(见 design-genre-slg)。
+            for (const a of manifest.assets) {
+                if ((a.type ?? '').startsWith('scene') && !a.ref) {
+                    a.ref = 'docs/refs/level-blueprint.png';
+                    a.size = `${level.width}x${level.height}`;
+                }
+            }
+        }
+    }
+    catch { /* 蓝图失败 → 背景退回普通文生图,不阻断整局 */ }
+    // 🔴 UI 契约套件(uiKit.ts):type='ui/kit' → 渲染灰阶线稿 → 注入图生图 ref(结构由线稿锁死,生成只换风格)。
+    //    ref/size/transparent/sheet 一律以契约为准覆盖(设计师只该给 desc=风格补充;误写 sheet 会带偏契约切分)。
+    try {
+        if (manifest.assets.some((a) => (a.type ?? '') === 'ui/kit')) {
+            const refDir = join(repoDir, 'docs', 'refs');
+            mkdirSync(refDir, { recursive: true });
+            writeFileSync(join(refDir, 'ui-kit-wireframe.png'), await renderUiWireframe());
+            for (const a of manifest.assets) {
+                if ((a.type ?? '') !== 'ui/kit')
+                    continue;
+                a.ref = 'docs/refs/ui-kit-wireframe.png';
+                a.size = `${UI_KIT_CANVAS.w}x${UI_KIT_CANVAS.h}`;
+                a.transparent = true;
+                delete a.sheet;
+            }
+        }
+    }
+    catch { /* 线稿失败 → 退回无参考生成(finalize 仍按契约矩形写 atlas,结构可能不准但不阻断) */ }
+    // 🔴 按归属过滤(2.8):`only` 给了就只处理那一类。
+    //    切换后 studio 只跑 audio,sps 只跑 visual —— 两边都拿全量 manifest,各取所需。
+    const scoped = opts?.only ? manifest.assets.filter((a) => assetKind(a) === opts.only) : manifest.assets;
+    const total = scoped.length;
+    // 🔴 封顶值与子进程的 `UV_THREADPOOL_SIZE` 是**同一个常量**(见 core/art/artConcurrency):
+    //    池的大小和"同时有几张图在处理"是同一个数的两面,分开写会各自漂,而漂了不报错。
+    const concurrency = Math.max(1, Math.min(ART_ASSET_CONCURRENCY_MAX, manifest.concurrency ?? 4));
+    const queue = [...scoped];
+    const status = [];
+    const placeholderIds = readPlaceholderIds(repoDir); // 占位的一律重生成(见 PLACEHOLDER_MARKER 注释)
+    // 🔴 上次生成的描述指纹:二修中设计师改了 desc 但忘写 regen(第三方模型常见)→ 按指纹差自动重生。
+    //    老资产无指纹(升级前生成)→ 视为未变,不触发大规模重生。
+    const prevHash = new Map();
+    try {
+        const prev = JSON.parse(readFileSync(join(assetsDir, 'asset-status.json'), 'utf-8'));
+        for (const st of prev)
+            if (st.descHash)
+                prevHash.set(st.id, st.descHash);
+    }
+    catch { /* 无历史 → 全部视为未变 */ }
+    let done = 0;
+    // 供应商回退链:**顺序即优先级**(默认那家在前,其余 capability=image 的兜底)。
+    // 某家被内容审核拒/限流耗尽时,genOne 依次换下一家(审核口径不同,常能救回)。
+    // 🔴 只拿"有哪些能用"(`listUsableProviders` 不给 apiKey/hasKey);"先用哪家 · 失败了怎么办"
+    //    是**消费方的使用策略**,就在 genOne 里 —— 这条切分是 media 层的对外契约。
+    const imageProviders = listUsableProviders('image', repoDir);
+    if (!imageProviders.length) {
+        // 🔴 **这条早返回也要守"跳过要可见"**:audio 不归 sps 做,它没出图**不是"缺 provider"**。
+        //    (1.4 子进程冒烟实测抓到的:一个只有 BGM 的 manifest 在没配图像 provider 时
+        //     整体报 `failed`,而正确答案是 `skipped` —— 一句"错的原因"比没有原因更难排查。)
+        for (const a of manifest.assets) {
+            if (assetKind(a) !== 'visual') {
+                status.push({ id: a.id, ok: false, source: 'skipped', error: '音频资产本版由 studio 生成(sps 只做视觉)' });
+                continue;
+            }
+            status.push({ id: a.id, ok: false, error: '未配置图像供应商(去工作台设置添加)' });
+        }
+        writeFileSync(join(assetsDir, 'asset-status.json'), JSON.stringify(status, null, 2));
+        writeArtReady(repoDir, 'done', total); // 放行 worker(没图也别让它干等)
+        return status;
+    }
+    const genCtx = { repoDir, assetsDir, artPrompts, ops: await defaultPixelOps() };
+    async function worker() {
+        for (;;) {
+            const a = queue.shift();
+            if (!a)
+                return;
+            // 🔴 取消检查点:**取下一个资产之前**,这是唯一允许停下的地方(1.9)。
+            //    半张图落盘后,"文件存在就跳过"的幂等会把它当成已完成 ⇒ 取消一次就永久污染一个资产,而且不报错。
+            //    ⚠️ studio 侧 `generateGameArt` **收了 `isCancelled` 却从未调用**(实测:整个 artGen 里
+            //       零个检查点)—— 参数接上了、没人读它,和 `native` 恒 undefined 同一族。已单独报给 coral。
+            if (opts?.isCancelled?.())
+                return;
+            const isAudio = (a.type || '').startsWith('audio'); // type:"audio/bgm" → 走音乐生成,落 .mp3
+            const isModel3d = (a.type || '') === 'model3d'; // type:"model3d" → 概念图→Tripo 图生3D,落 .glb
+            const outFile = isModel3d ? `${a.id}.glb` : isAudio ? `${a.id}.mp3` : `${a.id}.png`;
+            // model3d 以概念图 .png 为"已有"判据(glb 是加成,无 glb 用概念图当 billboard)→ 二修不再反复重试失败的 Tripo。
+            const haveFile = isModel3d ? `${a.id}.png` : outFile;
+            const channel = isAudio ? 'audio' : 'art';
+            // 🔴 事件只给**事实**({i18nKey, params}),不给文案:产品词表在消费方
+            //    (gameforge 说"游戏"、lab 说"实验"),而拼出来的占位符会一路漏到用户眼前。
+            //    `desc` 是 manifest 里设计师写的描述 = 数据,原样当参数递出去(studio 侧原本就拿它当 title)。
+            const evParams = { id: a.id, desc: a.desc || a.id };
+            const before = status.length;
+            // 🔴 占位文件不算"已有"(否则真图永远不生成):在占位清单里的一律重生成。
+            // 🔴 描述指纹变了(设计师二修改了 desc/size/sheet 等但忘写 regen)→ 视同 regen 自动重生。
+            const hashNow = assetDescHash(a);
+            const oldHash = prevHash.get(a.id);
+            const descChanged = !!oldHash && oldHash !== hashNow;
+            const willKeep = existsSync(join(assetsDir, haveFile)) && !placeholderIds.has(a.id) && !descChanged;
+            if (descChanged && existsSync(join(assetsDir, haveFile))) {
+                console.warn(`⚠️ 资产 ${a.id}:描述指纹变化(设计师改了但未写 regen)→ 自动重生`);
+                try {
+                    const refDir = join(repoDir, 'docs', 'refs');
+                    mkdirSync(refDir, { recursive: true });
+                    if (!isAudio && !isModel3d)
+                        copyFileSync(join(assetsDir, `${a.id}.png`), join(refDir, `${a.id}-prev.png`));
+                }
+                catch { /* 快照失败不阻断 */ }
+                for (const f of [`${a.id}.png`, `${a.id}.json`, `${a.id}.mp3`, `${a.id}.glb`]) {
+                    const pth = join(assetsDir, f);
+                    if (existsSync(pth)) {
+                        try {
+                            unlinkSync(pth);
+                        }
+                        catch { /* */ }
+                    }
+                }
+            }
+            // 🔴 只对【真要生成】的资产发 feed 事件;已存在(kept)= 这轮没生成 → 不输出(二修不重复刷已有图/音)。
+            // 🔴 skipped(本版不归 sps 做的类型)**连 running 都不发**。
+            //    1.11 真跑抓到的:audio 发了 running、却永远等不到终态(终态那一侧已经排除了 skipped)——
+            //    而 BuildEvent 是"同 id 新状态覆盖旧",于是 UI **永远显示它在生成中**。
+            //    这正是 `started` 事件那条判据的反面:**开了头没有尾,比压根没开头更糟**。
+            //    ⚠️ 而且音频归 studio 写,它会发自己那条 —— sps 再发一条就成了两个写者。
+            if (!willKeep && !isAudio)
+                emitBuildEvent(repoDir, { channel, id: a.id, i18nKey: 'build.event.asset', params: evParams, status: 'running' });
+            if (willKeep) {
+                status.push({ id: a.id, ok: true, source: 'kept', descHash: hashNow });
+            }
+            else if (a.provided) {
+                // 用户提供的资产:从 repo 内路径(设计师登记的 docs/refs/x.png)拷进 assets/、不生成。
+                let src = null;
+                try {
+                    const p = join(repoDir, a.provided);
+                    if (withinDir(repoDir, p) && existsSync(p))
+                        src = p;
+                }
+                catch { /* 越界/坏路径 → null */ }
+                if (!src) {
+                    status.push({ id: a.id, ok: false, error: `provided 路径越界或缺失:${a.provided}` });
+                }
+                else if (isAudio) {
+                    try {
+                        writeFileSync(join(assetsDir, outFile), readFileSync(src));
+                        status.push({ id: a.id, ok: true, source: 'provided' });
+                    }
+                    catch (e) {
+                        status.push({ id: a.id, ok: false, error: `provided 音频拷贝失败:${e instanceof Error ? e.message : String(e)}` });
+                    }
+                }
+                else {
+                    // 图像:归一成 png(用户可能传 jpg/webp)→ 走与生成图一致的后处理(图集打包/朝向/裁边)。
+                    try {
+                        const pbuf = await sharp(readFileSync(src)).png().toBuffer();
+                        status.push(await finalizeAsset(pbuf, a, assetsDir, 'provided', undefined, false, logical));
+                    }
+                    catch (e) {
+                        status.push({ id: a.id, ok: false, error: `provided 资产处理失败:${e instanceof Error ? e.message : String(e)}` });
+                    }
+                }
+            }
+            else if (isModel3d) {
+                // 3D 模型(Plan B):① 图床先出概念图(必出——既是 Tripo 输入,也是无 Tripo/失败时的 billboard 贴图兜底);
+                //   ② 有 3D 供应商才 Tripo 图生3D 出 GLB;无供应商 / 失败 / 无额度 → 概念图当 billboard(ok,不算失败,不阻断)。
+                //   worker 端:有 glb 用真模型,无 glb 但有概念图 → 当贴图/billboard(见 engines/three TEMPLATE)。
+                let conceptBuf = null;
+                try {
+                    const conceptPrompt = [a.desc, manifest.style, '单一主体居中、完整不裁切、3/4 斜俯视角、干净纯色背景、无场景无文字、适合转 3D 模型'].filter(Boolean).join(', ');
+                    // 概念图走首选那家(与 studio 同:概念图必出,它既是 Tripo 输入也是 billboard 兜底)。
+                    // 限流退让同样套在这条上 —— studio 那条注释写明「3D 概念图也走 generateImage,所以一并受益」。
+                    await withRateLimitRetry(() => generateAsset({ capability: 'image', providerId: imageProviders[0].id, prompt: conceptPrompt, cwd: repoDir, outPath: join('assets', `${a.id}.png`), size: '1024x1024' }));
+                    conceptBuf = readFileSync(join(assetsDir, `${a.id}.png`));
+                }
+                catch (e) {
+                    status.push({ id: a.id, ok: false, error: `概念图生成失败:${e instanceof Error ? e.message : String(e)}` });
+                }
+                if (conceptBuf) {
+                    // 🔴 "没配 3D 供应商"与"Tripo 失败"在 media 层是同一种表现(generateAsset 抛),
+                    //    而 studio 侧两者的**处置本来就一样**(概念图当 billboard,ok 不算失败)——
+                    //    所以这里合成一条 catch,不是把两种情况混掉。
+                    try {
+                        await generateAsset({
+                            capability: '3d',
+                            prompt: a.desc ?? a.id,
+                            cwd: repoDir,
+                            outPath: join('assets', `${a.id}.glb`),
+                            referenceUrl: `data:image/png;base64,${conceptBuf.toString('base64')}`,
+                        });
+                        status.push({ id: a.id, ok: true, source: 'generated' });
+                    }
+                    catch {
+                        status.push({ id: a.id, ok: true, source: 'billboard' }); // 无 3D 供应商 / Tripo 失败(余额/限流等)→ 概念图当 billboard
+                    }
+                }
+            }
+            else if (isAudio) {
+                // 🔴 音频本版由 studio 生成(2.8)。**正常走不到这里** —— driver 在资产边界就按能力
+                //    明确跳过并回报;派发漏了才会落到这条,所以它**必须响亮**:
+                //    静默当作已完成的症状是"游戏没有 BGM",**不是报错**。
+                //    ⚠️ 音频归 sps 那天,这里换成 `generateAsset({ capability: 'music' })` + 公共音频库兜底
+                //       (`ok:true, source:'library'` 那条语义一并补回)。
+                status.push({ id: a.id, ok: false, source: 'skipped', error: '音频资产本版由 studio 生成(sps 只做视觉)' });
+            }
+            else {
+                const ref = a.ref ? refToDataUrl(repoDir, a.ref) : globalRef;
+                status.push(await genOne(imageProviders, a, manifest.style, manifest.view, genCtx, ref, opts?.rawOnly, logical));
+            }
+            const r = status[status.length - 1];
+            if (r && status.length > before && r.ok && !r.descHash)
+                r.descHash = hashNow; // 成功项统一记录指纹(供下轮改描述自动重生)
+            // 🔴 kept(这轮没真生成)不发 done/failed 事件 —— 按实际生成输出,没生成就没输出(二修不重复刷)。
+            //    skipped(本版不支持的类型)同理:它不是"失败的资产",发 failed 事件会在 UI 上
+            //    把 studio 正常生成的 BGM 显示成红叉。**跳过要出现在 run 的结果里,不是出现在事件流里。**
+            if (r && status.length > before && r.source !== 'kept' && r.source !== 'skipped') {
+                // 概念图/普通图缩略图都是 <id>.png;音频是 <id>.mp3(3D 也用概念图当缩略)。
+                const asset = r.ok ? (isAudio ? `assets/${a.id}.mp3` : `assets/${a.id}.png`) : undefined;
+                // 「已用公共音频库替代」是另一句话 → 另一个 key,不是把后缀拼进参数里
+                //(拼后缀 = 在 sps 侧造了一句中文文案,而它会原样漏到界面上)。
+                const key = r.source === 'library' ? 'build.event.asset.library' : 'build.event.asset';
+                emitBuildEvent(repoDir, { channel, id: a.id, i18nKey: key, params: evParams, status: r.ok ? 'done' : 'failed', asset, mime: isAudio ? 'audio' : 'image', detail: r.ok ? undefined : r.error });
+            }
+            done++;
+            try {
+                onProgress?.(done, total);
+            }
+            catch { /* */ }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, total) }, () => worker()));
+    writeFileSync(join(assetsDir, 'asset-status.json'), JSON.stringify(status, null, 2));
+    // 语义层:合并写 docs/asset-meta.json(主 agent 读它把帧对到语义)。pool 后单次写 → 无竞态;
+    // 只更新本次生成出标签的资产,kept/无标签的保留旧条目(改图时不丢历史标签)。
+    const newMeta = status.filter((s) => s.meta?.frames.length).reduce((acc, s) => {
+        acc[s.id] = s.meta;
+        return acc;
+    }, {});
+    if (Object.keys(newMeta).length) {
+        try {
+            const metaFile = join(repoDir, 'docs', 'asset-meta.json');
+            let existing = {};
+            if (existsSync(metaFile)) {
+                try {
+                    existing = JSON.parse(readFileSync(metaFile, 'utf-8'));
+                }
+                catch { /* 坏文件 → 重写 */ }
+            }
+            writeFileSync(metaFile, `${JSON.stringify({ ...existing, ...newMeta }, null, 2)}\n`);
+        }
+        catch { /* 写 meta 失败不致命:几何在 <id>.json 里,标签可后补 */ }
+    }
+    // rawOnly 只是流水线的「生成棒」,后面还有处理/验证 → 不写 done(由 driver runAssetPipeline 在三棒完成后写),避免构建 worker 提前用到未处理的原图。
+    // 真图已就位的 id 从占位清单移除(失败的保留 → 续跑/下次构建会再试,占位图继续顶着)。
+    if (placeholderIds.size) {
+        for (const s of status)
+            if (s.ok && s.source !== 'kept')
+                placeholderIds.delete(s.id);
+        writePlaceholderIds(repoDir, placeholderIds);
+    }
+    if (!opts?.rawOnly)
+        writeArtReady(repoDir, 'done', total);
+    return status;
+}
+//# sourceMappingURL=artGen.js.map