@coralai/sps-cli 0.65.75 → 0.65.77

package/dist/providers/art/artDriver.js

@@ -0,0 +1,119 @@
+/**
+ * @module        providers/art/artDriver
+ * @description   美术流水线 driver 的**外壳**(1.1 骨架):派发、边界、落盘纪律、事件。
+ * @layer         provider
+ * @boundedContext art
+ *
+ * 🔴 **确定性 driver,不是 agent 编排。** 实测(2026-08,gameforge):agent 主导整个处理
+ * **更慢、更费 token、无独特价值**。进了 sps 的地盘也别顺手改成编排 —— **那个实验已经做过了。**
+ *
+ * 本文件只放「**外壳**」:资产遍历、取消边界、原子落盘、事件、跳过回报。
+ * 单个资产的**生成与后处理**(prompt → provider → 抠图/切帧/归一/打包)在 `processAsset`,
+ * 由 studio `artGen.ts` 的 `genOne` / `finalizeAsset` 移交 —— 那部分**按只读件对待**。
+ *
+ * ⚠️ **`verify` 是尾部可选的一步,不是分支**:两个取值下**图处理的每一行都必须相同**。
+ * 若你发现自己在写 `if (verify) …else…` 包住任何处理逻辑,就是走岔了。
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isCancelRequested } from './cancelMarker.js';
+import { resolveAssetsDir, resolveProjectDir } from '../../core/art/assetLocator.js';
+/**
+ * 🔴 **这一格是暂时的**(与 studio `assetKind` 同判据)。Eddy 已定:音频后续同样由 sps 做成工具产出。
+ *
+ * 所以这里刻意只有**一个类型别名 + 一行判据** —— **不建策略注册表 / 能力路由 / 可插拔 dispatcher**。
+ * 将来接音频时是**补一个 case**,不是改结构。
+ *
+ * ⚠️ 同理:遍历**全部**资产、对暂不支持的类型**明确跳过并回报**,
+ * 而不是 `filter(isVisual)` 把音频从视野里抹掉 ——
+ * > **「我只做视觉」和「我目前只支持视觉」是两句话:后者加音频时补一个 case,前者要改结构。**
+ * 它顺带兜住"上游拆派发漏了某个 audio 资产"的情况:**回报"跳过了 N 个",而不是静默当作全做完。**
+ */
+export function assetKind(a) {
+    return (a.type ?? '').toLowerCase().startsWith('audio') ? 'audio' : 'visual';
+}
+/** 读 manifest。读不到 → null(空跑,不抛:没有 manifest 不是错误,是没活干)。 */
+export function readArtManifest(projectDir) {
+    try {
+        const raw = readFileSync(join(projectDir, 'docs', 'art-manifest.json'), 'utf-8');
+        const j = JSON.parse(raw);
+        if (!Array.isArray(j.assets))
+            return null;
+        return { assets: j.assets };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 跑一轮美术流水线。
+ *
+ * 🔴 **取消只在资产边界问一次** —— 半张图停下会留坏文件,而"文件存在就跳过"的幂等
+ * 会把它当成已完成:**取消一次就永久污染一个资产,而且不报错**。
+ * (崩溃/OOM/硬杀不经过这里 —— 那条靠 `atomicWrite`,两层都要。)
+ */
+export async function runArtPipeline(locator, runId, deps) {
+    const projectDir = resolveProjectDir(locator);
+    const assetsDir = resolveAssetsDir(locator);
+    const manifest = readArtManifest(projectDir);
+    const assets = manifest?.assets ?? [];
+    // 🔴 started 事件:崩溃时**一个终态事件都不会写**,UI 会永远停在"生成中" ——
+    //    有了 started,"开了头没有尾"才是一个可判据的状态(消费方据此按需查 run 终态)。
+    deps.emit?.('notif.msg.art.started', { total: assets.length, runId });
+    const outcomes = [];
+    let cancelled = false;
+    for (const a of assets) {
+        // ── 资产边界:唯一允许停下的地方 ──────────────────────────────
+        if (!cancelled && isCancelRequested(projectDir, runId))
+            cancelled = true;
+        if (cancelled) {
+            outcomes.push({ id: a.id, state: 'cancelled' });
+            continue;
+        }
+        if (assetKind(a) !== 'visual') {
+            // 明确跳过并回报 —— 不是从视野里抹掉
+            outcomes.push({ id: a.id, state: 'skipped', reason: 'audio 资产本版由上游处理' });
+            continue;
+        }
+        try {
+            await deps.processAsset(a, { assetsDir, projectDir });
+            outcomes.push({ id: a.id, state: 'done' });
+        }
+        catch (e) {
+            // 单个资产失败不阻塞其它(移交语义):半套资产是有效产物
+            outcomes.push({ id: a.id, state: 'failed', reason: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    const interrupted = cancelled || outcomes.some((o) => o.state === 'cancelled');
+    const outcome = summarizeRun(outcomes, assets.length, interrupted);
+    deps.emit?.(outcome.status === 'succeeded' ? 'notif.msg.art.done' : 'notif.msg.art.partial', {
+        ok: outcome.ok,
+        total: outcome.total,
+        runId,
+    });
+    return outcome;
+}
+/**
+ * 逐资产结果 → run 终态。**只此一份**。
+ *
+ * 🔴 抽出来是因为它有了**第二个调用方**(`artRunChild`:子进程里跑的是移交件的
+ * `generateGameArt`,而终态语义在这里)。同一条"什么算 partial"的规则写两遍,
+ * 迟早会在一边被改 —— 而两份规则的分歧**不会有任何报错**,只会让同一次运行
+ * 在"运行状态"和"事件流"里显示成两回事。
+ *
+ * 🔴 中断 → `partial`,**不是 `failed`**:已生成的半套资产保留不回滚(删掉等于把已花的钱扔了)。
+ */
+export function summarizeRun(outcomes, total, interrupted) {
+    const ok = outcomes.filter((o) => o.state === 'done').length;
+    const skipped = outcomes.filter((o) => o.state === 'skipped');
+    const failed = outcomes.filter((o) => o.state === 'failed');
+    const status = interrupted
+        ? 'partial'
+        : failed.length && ok === 0
+            ? 'failed'
+            : failed.length
+                ? 'partial'
+                : 'succeeded';
+    return { status, total, ok, skipped, failed, outcomes };
+}
+//# sourceMappingURL=artDriver.js.map

package/dist/providers/art/artDriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artDriver.js","sourceRoot":"","sources":["../../../src/providers/art/artDriver.ts"],"names":[],"mappings":"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"}

package/dist/providers/art/artEvents.d.ts

@@ -0,0 +1,23 @@
+export interface ArtBuildEvent {
+    channel: string;
+    id: string;
+    status: 'running' | 'done' | 'failed';
+    /** 🔴 i18n 键。字典与渲染都在消费方 —— **我们产出事实,它产出文字**。 */
+    i18nKey: string;
+    /** 插值参数。只放**事实**(数量/id/尺寸),不放拼好的句子。 */
+    params?: Record<string, unknown>;
+    /** 产物相对路径(给 UI 预览用)。 */
+    asset?: string;
+    mime?: 'image' | 'audio';
+    /** 🔴 **给人看的失败原因**,只在 failed 时给。
+     *  不要把机器标识(runId 等)塞进来 —— 用途不同的东西不共用一个字段,
+     *  塞进去下一个人会把它一起显示给用户,而**类型拦不住**(都是 string)。 */
+    detail?: string;
+    /** 机器标识,顶层字段。 */
+    runId?: string;
+}
+/** 事件流落点(与 studio `buildEvents` 同一约定)。 */
+export declare function buildEventsPath(repoDir: string): string;
+/** 追加一条事件。写失败不抛 —— 事件是**旁路**,不该让它中断生成。 */
+export declare function emitBuildEvent(repoDir: string, ev: ArtBuildEvent): void;
+//# sourceMappingURL=artEvents.d.ts.map

package/dist/providers/art/artEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artEvents.d.ts","sourceRoot":"","sources":["../../../src/providers/art/artEvents.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACtC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB;;mDAE+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,0CAA0C;AAC1C,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAQvE"}

package/dist/providers/art/artEvents.js

@@ -0,0 +1,40 @@
+/**
+ * @module        providers/art/artEvents
+ * @description   构建事件流(1.12):**只写 `{i18nKey, params}`,永不写 `title`**。
+ * @layer         provider
+ * @boundedContext art
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 🔴 **本模块故意没有 `title` 字段 —— 这是类型层的拦截,不是约定。**
+ *
+ * 两个理由,第二个是刚踩出来的:
+ * ① 文案里有产品词表(gameforge 说"游戏"、lab 说"实验")——**sps 不该有产品词表**。
+ * ② **拼出来的占位符会一路漏到用户眼前,而每一层都以为下一层会处理。**
+ *    studio 后端为了让 tsc 过写了 `` `__i18n:${e.i18nKey}` ``,结果那串会被直接画在界面上。
+ *    它的定性值得原样记住:
+ *    > **当一层没有渲染所需的数据时,它唯一正确的动作是透传** ——
+ *    > 任何"先拼一个看起来像文本的东西"都会漏到用户面前。
+ *
+ * 所以这里**连"看起来像文本的东西"都不给拼**:类型里根本没有可以放文本的地方。
+ * ⚠️ 移交过来的 `emitBuildEvent(repoDir, {title})` 调用点会因此**编译不过** ——
+ * **那是有意的**:它们必须在 1.12 逐个换成 i18nKey,而不是被默默塞一个字符串。
+ * ══════════════════════════════════════════════════════════════════════════
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** 事件流落点(与 studio `buildEvents` 同一约定)。 */
+export function buildEventsPath(repoDir) {
+    return join(repoDir, 'docs', 'build-events.jsonl');
+}
+/** 追加一条事件。写失败不抛 —— 事件是**旁路**,不该让它中断生成。 */
+export function emitBuildEvent(repoDir, ev) {
+    try {
+        const p = buildEventsPath(repoDir);
+        mkdirSync(dirname(p), { recursive: true });
+        appendFileSync(p, `${JSON.stringify({ ...ev, at: undefined })}\n`);
+    }
+    catch {
+        /* 旁路:事件写不进去也不该影响产物 */
+    }
+}
+//# sourceMappingURL=artEvents.js.map

package/dist/providers/art/artEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artEvents.js","sourceRoot":"","sources":["../../../src/providers/art/artEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAqB1C,0CAA0C;AAC1C,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC;AACrD,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,EAAiB;IAC/D,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACnC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,cAAc,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;AACH,CAAC"}

package/dist/providers/art/artGen.d.ts

@@ -0,0 +1,259 @@
+import { type PackedSheet } from './sheet.js';
+import { type ArtPrompts } from './artPrompt.js';
+import { type PixelOps } from './composeAsset.js';
+import { type UsableMediaProvider } from '../media/mediaProviders.js';
+import { type ProjectLocator } from '../../core/art/assetLocator.js';
+export interface ArtAsset {
+    id: string;
+    usage?: string;
+    desc: string;
+    type?: string;
+    size?: string;
+    transparent?: boolean;
+    orient?: 'flipX' | 'rotate' | 'static';
+    ref?: string;
+    provided?: string;
+    sheet?: {
+        cols: number;
+        rows: number;
+        count?: number;
+    };
+    mergedFrom?: string[];
+    tags?: string[];
+    frames?: number;
+    width?: number;
+    height?: number;
+}
+export interface ArtManifest {
+    style?: string;
+    view?: string;
+    ref?: string;
+    regen?: string[];
+    concurrency?: number;
+    assets: ArtAsset[];
+}
+/** 图集帧的语义条目(写进 docs/asset-meta.json,供主 agent 把帧对到正确语义)。 */
+export interface SheetFrameMeta {
+    name: string;
+    label: string;
+    semanticId?: string;
+}
+export interface ArtStatus {
+    id: string;
+    ok: boolean;
+    source?: 'generated' | 'kept' | 'provided' | 'billboard' | 'library' | 'skipped';
+    error?: string;
+    provider?: string;
+    meta?: {
+        frames: SheetFrameMeta[];
+    };
+    descHash?: string;
+}
+export declare function mergeStraySprites(manifest: ArtManifest): string[];
+/** 资产描述指纹:二修时对比,变了 = 设计师改了这条资产 → 自动重生(确定性兜底,不依赖 regen 自觉)。
+ *  只含逐资产字段,不含全局 style(风格微调不该触发全量重生;整体换风格请显式 regen)。 */
+export declare function assetDescHash(a: ArtAsset): string;
+/** 读 art-manifest;缺失/非法返回 null。 */
+/**
+ * manifest 的落点。**导出**是因为子进程要区分三件今天长得一模一样的事(3.5):
+ * 「文件不存在(没有美术需求,合法)」/「文件在但读不出来(坏了,该响亮)」/「零资产」——
+ * 而 `readArtManifest` 对这三者一律返回 `null`/空。路径只能有一个真源,所以从这里拿。
+ */
+export declare function artManifestPath(repoDir: string): string;
+export declare function readArtManifest(repoDir: string): ArtManifest | null;
+export declare function readPlaceholderIds(repoDir: string): Set<string>;
+/**
+ * 🔴 占位资产:建卡瞬间按 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 declare function writePlaceholderAssets(repoDir: string, manifest: ArtManifest, logical: {
+    w: number;
+    h: number;
+}, only?: AssetKind): Promise<void>;
+/**
+ * 造 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 declare function buildAtlas(imageFile: string, framePrefix: string, packed: PackedSheet, names?: string[]): Record<string, unknown>;
+/** 具名帧版(UI 契约用):帧名由调用方给定(如 ui_btn_lg),不走 <id>_<i> 序号。 */
+export declare function writeAtlasJsonNamed(assetsDir: string, id: string, packed: PackedSheet, names: string[]): void;
+export declare function writeAtlasJson(assetsDir: string, id: string, packed: PackedSheet): void;
+/**
+ * 写「美术就绪」信号 `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 declare function waitArtReady(repoDir: string, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<'done' | 'absent' | 'timeout'>;
+export declare function writeArtReady(repoDir: string, state: 'generating' | 'done', total: number): void;
+/**
+ * 资产后处理 → 写盘:图集(切+紧凑重排+atlas json+帧标签)/ 单图朝向校正(flipX)/ 透明裁边。
+ * 生成图(source=generated)与用户提供图(source=provided)共用同一套处理,行为一致。
+ */
+/** 塔防等布局型游戏的关卡数据(设计师产出 docs/level.json)。坐标相对 game.json 逻辑分辨率。 */
+export interface LevelData {
+    width: number;
+    height: number;
+    view?: string;
+    path?: [number, number][];
+    buildSpots?: [number, number][];
+    base?: [number, number];
+    waves?: unknown[];
+}
+/**
+ * 把 level.json 渲染成【语义蓝图 PNG】(绿底 / 红粗折线=路 / 蓝方块=塔位 / 紫方块=base),供图生图当结构参考——
+ * AI 图生图会保持这张图的布局(路走向、塔位位置),精修成精美背景 → 图和坐标同源。复用 numberedPreview 的 SVG+sharp 手法。
+ */
+export declare function renderLevelBlueprint(level: LevelData): Promise<Buffer>;
+export declare function finalizeAsset(buf: Buffer, a: ArtAsset, assetsDir: string, source: 'generated' | 'provided', rawBuf?: Buffer | null, rawOnly?: boolean, logical?: {
+    w: number;
+    h: number;
+}): Promise<ArtStatus>;
+/**
+ * 一次生成所需的上下文(sps 侧新增):落点 + 产品措辞 + 像素算子。
+ *
+ * `ops` 是注入口:生产用 `defaultPixelOps()`(= `pixels.ts`),测试注 mock 断言**调用序列** ——
+ * 决策树走错分支时每个算子仍然"算得对",算子级检查一条都不会红(见 `composeAsset` 模块头)。
+ */
+interface GenCtx {
+    /** 项目工作区根 —— 生成落点的 cwd,也是**项目级 media provider** 的解析基准。 */
+    repoDir: string;
+    assetsDir: string;
+    artPrompts: ArtPrompts;
+    ops: PixelOps;
+}
+/** 生成单张资源(含尺寸+抠图)→ 存盘。**429/限流/5xx/超时 自动指数退避重试**(适配 API QPS 限制)。
+ *
+ * ⚠️ **导出仅为测试**:这段是「改了不会有任何测试发现」清单的所在
+ * (退避阶梯 / 失败分类 / 回退留痕 / 三条降级),而它今天唯一的网就是 `genOne.test.ts`。 */
+export declare function genOne(providers: UsableMediaProvider[], a: ArtAsset, style: string | undefined, view: string | undefined, ctx: GenCtx, referenceDataUrl?: string, rawOnly?: boolean, logical?: {
+    w: number;
+    h: number;
+}): Promise<ArtStatus>;
+/**
+ * 资产归属:**视觉走 sps,音频留 studio**(2.8,docs/39 之外的追加决定 2026-08-12)。
+ *
+ * 🔴 音频本次不搬的实测依据:
+ * ```
+ * audioGen 只有 93 行,**但 import ffmpeg-static + spawnSync** → sps 要引一个二进制依赖
+ * AUDIO_LIBRARY 在 coral 家(DATA_DIR/audio-library),sps 只读不可写
+ * 音频**是活的**:项目里 104 个 mp3,近 30 天新增 37(对照:资源库两个月没动)
+ * ```
+ * 搬它是**另一次迁移的量**,不是本次的尾巴。
+ *
+ * ⚠️ 这不构成双写风险:双写 = **同一件事**在两个地方做;图与音频是**不同的事**,
+ *    走不同函数、不同入口 —— 2.5 那个开关的语义一点没松。
+ */
+/**
+ * 🔴 **这一格是暂时的。** Eddy 已定:音频后续同样由 sps 做成工具产出。
+ *
+ * 所以这里刻意**只有一个类型别名 + 一行判据 + 一个可选参数** ——
+ * **不建策略注册表 / 能力路由 / 可插拔 dispatcher**。将来整个删掉:
+ * ```
+ * 删除清单(音频迁走那天):
+ *   1. assetKind() 与 AssetKind
+ *   2. generateGameArt / writePlaceholderAssets 的 only 参数与那两行 filter
+ *   3. generateAudioAssets 整个入口          ← sps 侧已删(音频不搬,入口留着就是假的)
+ *   4. orchestrator 里对 generateAudioAssets 的那一次调用
+ * ```
+ * **写成"资产类型派发系统"的话,删起来会牵一片。**
+ *
+ * ✅ **sps 侧的"补回来"清单**(音频归 sps 那天,三处,都已就地留注释):
+ * ```
+ * ① 公共音频库兜底(原 AUDIO_LIBRARY / pickLibraryBgm)
+ * ② writePlaceholderAssets 的 audio 分支(占位 BGM)
+ * ③ worker 里的 audio 分支 → generateAsset({ capability: 'music' })
+ * ```
+ *
+ * ⚠️ 这条教训今天刚吃过一次:`artPipeline` 头注释里那句「所以 driver 留在 studio」
+ *    就是**把阶段性结论写成了长期结论**,结果它反过来挡了迁移,还得专门去改。
+ *    **过渡形态要写成过渡的样子,并把删除清单一起写下。**
+ */
+export type AssetKind = 'visual' | 'audio';
+export declare function assetKind(a: {
+    type?: string;
+}): AssetKind;
+/**
+ * @param opts.isCancelled 在**每个资产边界**被询问一次;返回 true 则干净停下。
+ *   🔴 **不能在资产中途停** —— 半张图落盘后,"目标文件存在就跳过"的幂等会把它当成已完成,
+ *      于是**取消一次就永久污染一个资产,而且不报错**(docs/39 §十五)。
+ *   ⚠️ 它只覆盖**优雅**取消;崩溃/OOM/硬杀不经过这里,那条要靠原子写(#32,单列不做)。
+ */
+/**
+ * 一次美术任务的**逻辑输入**(1.6/1.7 的契约在这里落地)。
+ *
+ * 🔴 **没有路径字段** —— 调用方给标识,`resolveProjectDir` 正向拼路径;
+ *    产品相关的两样(`manifestFile` / `artPrompts`)随任务下发,**sps 不持有产品词表**。
+ */
+export interface ArtGenTask {
+    locator: ProjectLocator;
+    /** 计量归因用,**per-attempt**;🔴 与 `projectId` 是两个概念,不可互推(见 jobContext)。 */
+    jobId: string;
+    manifestFile: string;
+    artPrompts: ArtPrompts;
+}
+export declare function generateGameArt(task: ArtGenTask, onProgress?: (done: number, total: number) => void, opts?: {
+    rawOnly?: boolean;
+    isCancelled?: () => boolean;
+    only?: AssetKind;
+}): Promise<ArtStatus[]>;
+export {};
+//# sourceMappingURL=artGen.d.ts.map

package/dist/providers/art/artGen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artGen.d.ts","sourceRoot":"","sources":["../../../src/providers/art/artGen.ts"],"names":[],"mappings":"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"}