diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs index 5c9613bdd..ffa9d901e 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs @@ -1240,13 +1240,13 @@ pub(in crate::agent) async fn request_platform_art_asset_with_runtime_options_at .then(|| canonical_art_spec_reference_at(root, &canvas_context.project_id)) .transpose()?; let (endpoint, request_body) = if is_canonical_art_spritesheet { - let reference_image_src = canonical_reference + let reference_id = canonical_reference .as_deref() .ok_or_else(|| "透明美术图集缺少规范图引用".to_string())?; ( "/api/external/v1/editor/icon-spritesheets/generations", serde_json::json!({ - "referenceImageSrc": reference_image_src, + "referenceId": reference_id, "iconDescriptions": canonical_art_spritesheet_icon_descriptions(&generation_prompt), "screenColor": "auto", "aspectRatio": options.aspect_ratio, diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs index 0de156f4f..b1e1759c9 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs @@ -344,11 +344,10 @@ pub(super) fn platform_art_generation_runtime_request_snapshot( (generation_kind, reference_resource_ids) } "/api/external/v1/editor/icon-spritesheets/generations" => { - let reference_resource_id = json_string_field(&request_body, "referenceImageSrc") + let reference_resource_id = json_string_field(&request_body, "referenceId") + .or_else(|| json_string_field(&request_body, "referenceImageSrc")) .filter(|value| !value.trim().is_empty()) - .ok_or_else(|| { - "External Editor 图集生成账本请求缺少 referenceImageSrc".to_string() - })?; + .ok_or_else(|| "External Editor 图集生成账本请求缺少 referenceId".to_string())?; ("icon-spritesheet".to_string(), vec![reference_resource_id]) } _ => return Err("External Editor 生成账本 endpoint 不受支持".to_string()), @@ -868,6 +867,35 @@ mod external_generation_state_tests { ) .expect("prepare generation ledger"); assert!(created); + let mut spritesheet_state = prepared.clone(); + spritesheet_state.endpoint = + "/api/external/v1/editor/icon-spritesheets/generations".to_string(); + spritesheet_state.request_body_json = serde_json::json!({ + "referenceId": "resource-icon-spec", + "iconDescriptions": ["玩家主体"], + "projectId": "canvas-project", + "assetFolderId": "asset-folder" + }) + .to_string(); + assert_eq!( + platform_art_generation_runtime_request_snapshot(&spritesheet_state) + .expect("parse current icon spritesheet ledger") + .reference_resource_ids, + vec!["resource-icon-spec"] + ); + spritesheet_state.request_body_json = serde_json::json!({ + "referenceImageSrc": "legacy-resource-icon-spec", + "iconDescriptions": ["玩家主体"], + "projectId": "canvas-project", + "assetFolderId": "asset-folder" + }) + .to_string(); + assert_eq!( + platform_art_generation_runtime_request_snapshot(&spritesheet_state) + .expect("parse already persisted legacy icon spritesheet ledger") + .reference_resource_ids, + vec!["legacy-resource-icon-spec"] + ); let mut invalid_key = prepared.clone(); invalid_key.idempotency_key = "invalid key".to_string(); assert!( diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/prompt.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/prompt.rs index 7a5dc9cc4..1f3c3d5cd 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/prompt.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/prompt.rs @@ -519,7 +519,7 @@ fn game_creator_art_asset_plan_tool_plan_prompt( ); } format!( - "{prompt}\n\n你负责首版美术素材实际生成。资产清单和美术计划只是中间结果；最终必须调用 canvas.asset_generate 生成并登记 assets/art-spritesheet.png，固定使用 1:1、1K、assetKind=art-spritesheet、assetLabel=游戏首版核心美术素材、replaceExisting=false，并写入可解析的 assets/manifest.art.json。调用前必须用 asset.list 确认 assets/art-spec.png 已登记为当前项目的 icon-spec 画布资源，并依据当前任务、game/game_design.md 与 manifest 逐项说明真实需要的玩家主体及朝向/状态、目标或收集物、障碍/场景元素和反馈特效，由 Runtime 形成 iconDescriptions；不得假设为塔防或加入合同中不存在的单位、敌人、波次、卡牌。Runtime 固定以规范图的权威 resourceId 作为 referenceImageSrc，调用 POST /api/external/v1/editor/icon-spritesheets/generations，并用 screenColor=auto 完成透明后处理；不得把 UI 原型、Data URL、Blob URL、本地路径或结构化 JSON 冒充规范图引用，不得回退普通生图或 UI extraction。缺少规范图时必须等待 art-director 依赖并如实阻塞。成功后回读 observation 与 asset.list，核对服务端返回的透明 spritesheet、真实 alpha、warning 和 sliceWarning。warning.code=postprocess-failed-source-preserved 时没有透明图集，不得登记、验收或自动重试；仅 sliceWarning 时可保留完整透明图集，但不得声称独立切片已生成。已有有效同路径资产时不得重复生成或扣费；只有带 repairOfDelegationId 的唯一返工轮可 replaceExisting=true 原位替换。不得运行 game.static_smoke 或 preview.validate，也不得编辑 game/index.html。图片生成未配置、待确认、失败或透明证据不足时不得提交最终回复。" + "{prompt}\n\n你负责首版美术素材实际生成。资产清单和美术计划只是中间结果；最终必须调用 canvas.asset_generate 生成并登记 assets/art-spritesheet.png，固定使用 1:1、1K、assetKind=art-spritesheet、assetLabel=游戏首版核心美术素材、replaceExisting=false，并写入可解析的 assets/manifest.art.json。调用前必须用 asset.list 确认 assets/art-spec.png 已登记为当前项目的 icon-spec 画布资源，并依据当前任务、game/game_design.md 与 manifest 逐项说明真实需要的玩家主体及朝向/状态、目标或收集物、障碍/场景元素和反馈特效，由 Runtime 形成 iconDescriptions；不得假设为塔防或加入合同中不存在的单位、敌人、波次、卡牌。Runtime 固定以规范图的权威 resourceId 作为 referenceId，调用 POST /api/external/v1/editor/icon-spritesheets/generations，并用 screenColor=auto 完成透明后处理；不得把 UI 原型、Data URL、Blob URL、本地路径或结构化 JSON 冒充规范图引用，不得回退普通生图或 UI extraction。缺少规范图时必须等待 art-director 依赖并如实阻塞。成功后回读 observation 与 asset.list，核对服务端返回的透明 spritesheet、真实 alpha、warning 和 sliceWarning。warning.code=postprocess-failed-source-preserved 时没有透明图集，不得登记、验收或自动重试；仅 sliceWarning 时可保留完整透明图集，但不得声称独立切片已生成。已有有效同路径资产时不得重复生成或扣费；只有带 repairOfDelegationId 的唯一返工轮可 replaceExisting=true 原位替换。不得运行 game.static_smoke 或 preview.validate，也不得编辑 game/index.html。图片生成未配置、待确认、失败或透明证据不足时不得提交最终回复。" ) } @@ -1224,7 +1224,7 @@ mod tests { assert!(with_canvas.contains("由 Runtime 形成 iconDescriptions")); assert!(with_canvas.contains("玩家主体及朝向/状态")); assert!(with_canvas.contains("不得假设为塔防")); - assert!(with_canvas.contains("权威 resourceId 作为 referenceImageSrc")); + assert!(with_canvas.contains("权威 resourceId 作为 referenceId")); assert!(with_canvas.contains("POST /api/external/v1/editor/icon-spritesheets/generations")); assert!(with_canvas.contains("不得回退普通生图或 UI extraction")); assert!(with_canvas.contains("screenColor=auto")); diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/static_deliveries.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/static_deliveries.rs index 64e1785db..86e58bedc 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/static_deliveries.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/static_deliveries.rs @@ -103,7 +103,7 @@ fn visual_specialist_prompts_require_real_registered_image_deliveries() { "assetKind=art-spritesheet", "用 asset.list 确认 assets/art-spec.png 已登记", "由 Runtime 形成 iconDescriptions", - "权威 resourceId 作为 referenceImageSrc", + "权威 resourceId 作为 referenceId", "POST /api/external/v1/editor/icon-spritesheets/generations", "screenColor=auto", "不得回退普通生图", diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs index 5595b49cb..71e092fb7 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs @@ -845,7 +845,7 @@ async fn background_agent_runtime_can_generate_platform_art_asset() { "fixture should exercise queued, running, and completed states" ); for expected in [ - r#""referenceImageSrc":"resource-icon-spec""#, + r#""referenceId":"resource-icon-spec""#, r#""iconDescriptions":"#, r#""screenColor":"auto""#, r#""projectId":"canvas-project-1""#, @@ -859,6 +859,10 @@ async fn background_agent_runtime_can_generate_platform_art_asset() { "generation request missing {expected}: {generation_request}" ); } + assert!( + !generation_request.contains(r#""referenceImageSrc":"#), + "generation request must not send the retired primary reference field: {generation_request}" + ); fs::remove_dir_all(root).ok(); fs::remove_dir_all(config_dir).ok(); diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index b14b67d88..e4ff4202d 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -5837,7 +5837,7 @@ ## 2026-07-28 AI 游戏创作正式视觉规范与透明 spritesheet DAG - 16-task 边界：继续复用现有 seed manifest 的 `art-director / design-foundation / art-asset-plan` 三个任务，不新增平行任务、会话或素材系统。`art-director` 是正式视觉规范前置：先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`。`generationInputs.artSpec` 只是辅助结构化上下文，不能替代这张真实规范图。 -- 路由与依赖：`design-foundation` 以已登记 `assets/art-spec.png` 的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，通过 `/api/external/v1/editor/images/generations` 的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 art-spec 资源 ID 作为必填 `referenceImageSrc`，调用 `/api/external/v1/editor/icon-spritesheets/generations`，提交具体 `iconDescriptions` 与 `screenColor=auto` 生成透明 `assets/art-spritesheet.png`。严禁把 `assets/ui-prototype.png` 当作规范图引用；`art-spec.png` 缺失、不是当前画布的 `icon-spec` 或缺少稳定 `resourceId` 时，两个下游任务都必须等待 `art-director`，不得把本地路径、Data URL / Blob URL 当成稳定引用，也不得退回普通生图。单波最多 `3` 个静态职责的资源上限保持不变，调度只调整现有任务的依赖边和就绪顺序。 +- 路由与依赖：`design-foundation` 以已登记 `assets/art-spec.png` 的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，通过 `/api/external/v1/editor/images/generations` 的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 art-spec 资源 ID 作为必填 `referenceId`，调用 `/api/external/v1/editor/icon-spritesheets/generations`，提交具体 `iconDescriptions` 与 `screenColor=auto` 生成透明 `assets/art-spritesheet.png`。严禁把 `assets/ui-prototype.png` 当作规范图引用；`art-spec.png` 缺失、不是当前画布的 `icon-spec` 或缺少稳定 `resourceId` 时，两个下游任务都必须等待 `art-director`，不得把本地路径、Data URL / Blob URL 当成稳定引用，也不得退回普通生图。单波最多 `3` 个静态职责的资源上限保持不变，调度只调整现有任务的依赖边和就绪顺序。 - UI extraction 边界：`/api/external/v1/editor/ui-designs/assets/extractions` 只适用于已有且带红框标注的 UI 设计图，不是 UI 设计图生成接口，也不进入本次 canonical DAG。后续若要生成独立 UI spritesheet，必须先补红框源图生成与正式产物合同，不得直接对无标注 `ui-prototype.png` 调用 extraction。 - 完成门禁：External Editor 2xx 只表示生成请求完成。通用 `warning` 优先于 `sliceWarning`；`postprocess-failed-source-preserved` 表示 provider 源图是唯一权威结果，但不满足透明图集合同，客户端保留服务端事实并失败关闭，不登记本地正式 spritesheet、不伪造切片、不自动重跑。仅 `sliceWarning` 时完整透明图集有效，Runtime 把原始 reason 写入私有审计与 Agent observation，但不得声称独立切片存在。下载结果还必须解码并至少包含一个真实透明像素，纯 RGB 或全不透明 RGBA 一律拒绝落盘和 manifest 登记。 - OpenAPI 同步事实：2026-07-28 从 `https://www.genarrative.world/api/external/v1/openapi.json` 获取的线上合同与 `docs/openapi/genarrative-external-v1.openapi.json` 原始 SHA-256 均为 `00fa39ea8781605b895b331a579fbf097eea7892962350cb2a82bed7e1024135`，逐字节一致，因此不制造无意义 JSON diff；实现按现有公开 `screenColor`、`assetLabel`、`warning` 与 `sliceWarning` 契约更新。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 50d111c2c..201117451 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -857,7 +857,7 @@ game-project/ - 自动验收现在严格要求 manifest 恰好包含固定 16 个不重复 task ID 且全部为 `completed`，并逐任务核对当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物存在并满足文件 / JSON / 非占位入口检查，配置画布 API Key 时再增加 `art-spec / ui-prototype / art-spritesheet` 三张图片。PNG 验收不止检查 magic / IHDR / 比例，还会校验 chunk CRC、zlib 解压、scanline 长度、索引色 PLTE 和未知 critical chunk。Runtime 根 Supervisor 的完成合同已升级为 `game-creator-autonomous-completion-contract.v2`，`baselineArtifacts` 必填并纳入指纹，旧 v1 或缺基线合同失败关闭；最终门禁要求最后一次验证工具是 `game.static_smoke`、状态通过且 `verifiedRevision == currentRevision`。`preview.validate` 回执必须绑定同一 Agent、run、current revision、当前 `game/index.html` 摘要、固定试玩场景、持久浏览器报告以及 desktop / mobile 两张截图的路径、摘要和 PNG 身份，任一证据缺失、变化、过期或来自其它 run / revision 都阻止最终回复。旧两图合同的确定性证据不替代新三图 DAG 验收；新合同实现后必须新起独立单轮。 - `design-foundation` 已增加专属职责边界：项目文件只允许写 `memory/project.md` 与 `game/game_design.md`；配置 External Editor API Key 且合同要求界面原型时，只额外允许固定 `assets/ui-prototype.png`。它不得创建、修改、删除或补丁 `game/index.html`，不得改动其它程序实现、发布、音频或美术素材，也不得调用 `preview.start`、`preview.validate`、`game.static_smoke`，或借 `command.exec / command.start / command.run_limited` 启动预览服务、浏览器、Playwright 和桌面 / 移动试玩。程序和质量 Agent 的共享 Runtime 工具合同不因此缩减；有 / 无画布配置和其它 Agent 不受影响的聚焦回归为 `3/3` 通过。 - `canvas.asset_generate.replaceExisting` 默认并必须保持 `false`；只有静态专业 Agent 的 `delegated-*` 唯一 repair run 才能申请 `true`。Runtime 要求当前 delivery 带 `repairOfDelegationId`，原 delivery 已被同一父 Agent / 父 run 认领，原始与返工合同的目标 Agent 和精确 `expectedArtifacts` 路径一致；普通 run、未声明路径、错误 Agent、未认领原交付或缺失原图都失败关闭。图片生成仍服从 `art-director` / `design-foundation` / `art-asset-plan` 的固定输出路径、比例、尺寸、kind 和 label，禁止先删除正式图片；请求前记录旧文件 SHA-256，外部生成返回后在项目写锁内复核，旧图在网络请求期间变化即拒绝覆盖。授权替换先写私有临时文件，再以备份 / rename 切换；落盘或 manifest 登记失败时恢复旧图，不把新旧文件并存状态当作成功。 -- 2026-07-28 起，在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，再通过同一 images 接口的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 `assets/art-spec.png` 资源 ID 作为必填 `referenceImageSrc` 调用 `/api/external/v1/editor/icon-spritesheets/generations`，传入具体 `iconDescriptions`、`screenColor=auto`、同名画布 / 素材库与 `canvasCompletion`，生成透明 `assets/art-spritesheet.png`。`generationInputs.artSpec` 只是辅助结构化上下文，不能代替真实 `art-spec.png`；严禁把 `assets/ui-prototype.png` 当作图集规范图。规范图缺失、未登记为当前画布的 `icon-spec` 或缺少稳定资源 ID 时，两个下游任务均等待 `art-director`，不得退回普通生图。UI extraction 只适用于已有且带红框标注的 UI 设计图，不用于生成完整 UI，也不进入本次 canonical DAG。单波最多 `3` 个静态职责的资源上限保持不变，只调整现有任务的依赖边与就绪顺序。图集返回 `warning` 时以 `postprocess-failed-source-preserved` 源图保留语义失败关闭，不把不透明源图登记为正式 spritesheet，也不自动重试；仅有 `sliceWarning` 时完整透明图集仍可登记，但必须原样保留切片失败原因。客户端下载后还要解码 PNG 并确认至少存在一个 alpha 小于 255 的像素，未形成真实透明像素时拒绝落盘和 manifest 登记。 +- 2026-07-28 起，在既有 16-task manifest 内固定正式视觉 DAG，不新增平行任务系统：`art-director` 先通过 `/api/external/v1/editor/images/generations` 的 `kind=spec` 生成 `assets/art-spec.png`，并登记为 `assetKind=icon-spec`；`design-foundation` 使用该规范图的 External Editor 稳定资源 ID 作为 `referenceImageSrcs` 中的视觉规范参考，再通过同一 images 接口的 `kind=ui-design` 生成完整 `assets/ui-prototype.png`；`art-asset-plan` 以同一 `assets/art-spec.png` 资源 ID 作为必填 `referenceId` 调用 `/api/external/v1/editor/icon-spritesheets/generations`，传入具体 `iconDescriptions`、`screenColor=auto`、同名画布 / 素材库与 `canvasCompletion`，生成透明 `assets/art-spritesheet.png`。`generationInputs.artSpec` 只是辅助结构化上下文，不能代替真实 `art-spec.png`；严禁把 `assets/ui-prototype.png` 当作图集规范图。规范图缺失、未登记为当前画布的 `icon-spec` 或缺少稳定资源 ID 时，两个下游任务均等待 `art-director`，不得退回普通生图。UI extraction 只适用于已有且带红框标注的 UI 设计图，不用于生成完整 UI，也不进入本次 canonical DAG。单波最多 `3` 个静态职责的资源上限保持不变，只调整现有任务的依赖边与就绪顺序。图集返回 `warning` 时以 `postprocess-failed-source-preserved` 源图保留语义失败关闭，不把不透明源图登记为正式 spritesheet，也不自动重试；仅有 `sliceWarning` 时完整透明图集仍可登记，但必须原样保留切片失败原因。客户端下载后还要解码 PNG 并确认至少存在一个 alpha 小于 255 的像素，未形成真实透明像素时拒绝落盘和 manifest 登记。 - 旧项目已有同路径派生图但缺少上述 provenance 时，一律标记为 legacy，不得只因文件、kind 或通用视觉检查存在就完成。原位替换仍走显式 repair：`design-foundation` 与 `art-asset-plan` 先在同一 Supervisor 批次分别建立 owner 精确原合同并交付 `needs-repair`，父 run 认领后再在同一批次分别发起各自唯一 repair；两个 repair 合称一个显式视觉返工阶段。`art-director` 不得跨 owner 声明或替换 UI / spritesheet，Runtime 在委派落盘前就拒绝这类合同，不再等到生图阶段才失败。 - 2026-07-27 新起的“16 任务正式产物 + 两张真实画布图片 + current revision 静态 / 双视口浏览器 / PNG 证据 + 受限 repair 替换”独立外部 Provider 验收，使用 `npm run agc:test:chat -- --timeout-minutes 75`，约 `59m50s` 后以退出码 `0` 完整 **PASS**。同一轮真实生成并登记 `assets/ui-prototype.png`（`2829418` bytes）与 `assets/art-spritesheet.png`（`1361906` bytes），固定 `16` 个 manifest task 均为当前父 Run 下唯一 logical run、一次 started、一次 completed、零 failed / cancelled 和一次 manifest projection；七份基础正式产物、两张 PNG、当前 revision 的 `game.static_smoke`、desktop / mobile `lane-defense-v1` playtest、浏览器报告与截图全部通过。`turn.report=settled` 且唯一 assistant，busy / pending / running / confirmation / user-input / reconciliation 均为 `0`；隔离 Runner、一次性项目和隔离 AppData 已自动清理。此前失败轮继续独立保留，不与本轮拼接；未来合同变化仍须新起完整轮次复验。 - 2026-07-27 补充 tool-plan 成功响应交接的内容边界：Provider 的自然语言计划叙述，以及结构化 arguments 中 `body / code / content / css / html / newText / oldText / patch / script / text` 等源码内容字段，只检查真实密钥 token 形状、凭据头标记和不安全控制字符；仅仅提及 `.env` 或 `game-creator.config` 不能阻断已经计费的安全响应。结构化输入中的敏感 JSON key、非内容字段中的配置痕迹或绝对路径、真实 token、容量、thinking、身份、顺序和账本完整性门禁仍失败关闭。成功 handoff 失败进入 reconciliation 时，Runtime 额外只持久化受控 `failureKind`、脱敏错误 SHA-256 和字符数，不保存 Provider 正文、function arguments、密钥或绝对路径。定向回归覆盖叙述/源码字段放行、`.env.local` 路径和真实 token 拒绝、全部 tool-plan handoff 回归及诊断零正文。