修正美术包图集生成需求的有效入参

将美术包内容、风格和排布要求写入 iconDescriptions 并复用元数据文案来源保留普通图标原文透传与旧生成账本的冻结请求和幂等身份同步工具说明、美术资源技能、主规范和里程碑验收证据补充真实 HTTP 请求、恢复防重及描述边界测试
2026-10-05 08:26:17 +01:00
parent dab51b0c71
commit b116cbc371
10 changed files with 573 additions and 85 deletions
@@ -10,7 +10,7 @@
  "agc_write_file.parameters.path": "当前项目根下的相对路径，例如 game/index.html、assets/manifest.json 或 data/gameplay-spec.md",
  "agc_write_file.parameters.content": "仅填写目标文件的完整原始 UTF-8 正文",
  "taonier_prepare_game_art.description": "创建或恢复当前 AGC 项目的陶泥儿标准游戏美术包。默认复用有效美术包；根据当前对话需要选择 regenerate 重新生成。授权使用 AGC 客户端当前登录会话；遇到 401/403 时报告客户端登录或权限状态异常并停止。",
-  "taonier_prepare_game_art.parameters.brief": "面向当前游戏的简洁视觉需求",
+  "taonier_prepare_game_art.parameters.brief": "面向当前游戏的简洁视觉需求：写明主题、风格、玩家主体及状态、目标或收集物、障碍或场景元素、反馈特效等具体需要的素材。工具会补齐沿用规范图和素材独立排布的通用要求；内容类别不代表切片数量或返回顺序",
  "taonier_prepare_game_art.parameters.mode": "缺省安全复用有效美术包；Codex 仅在当前对话需要换一套或重新生成时使用 regenerate",
  "agc_generate_image.description": "生成一张新图片：普通插画、角色立绘、统一视觉规范图、游戏 UI 设计图或透明游戏素材图集。仅在用户明确要求生成新图时调用。",
  "agc_generate_image.parameters.prompt": "完整图片描述；普通图片、角色、规范图、UI 设计图或透明图集均可。kind=icon-spritesheet 时，去除首尾空白后的描述须为 1 到 200 个 Unicode 字符，保留内部换行并作为单条 iconDescriptions 原样提交；超限拒绝，不截断、不拆条，客户端不追加生图指令",
@@ -15,8 +15,8 @@
  "scene_constraints": "必须是可见的真实图片产物，适合作为 Canvas 或 HTML 游戏场景底图；不得做成素材图集、完整游戏截图、海报或概念板；必须原创，不得复刻现有游戏场景、Logo、贴图、标志性布局或受保护视觉语言",
  "spritesheet_subject": "{}；使用项目原创命名和原创阵营设计",
  "spritesheet_style": "清晰可切分的原创 Web 游戏素材图集；严格沿用当前规范图的轮廓、材质、色板与光照，素材类别以当前玩法合同为准",
-  "spritesheet_composition": "{} 游戏素材图集，按玩家主体及状态、目标或收集物、障碍或场景元素、反馈特效分区，留出清楚切分间距",
-  "spritesheet_constraints": "生成可直接用于游戏的真实透明图片，素材仅包含当前项目玩法合同需要的实体和反馈；角色轮廓、图标排布与配色采用项目原创设计",
+  "spritesheet_composition": "{} 游戏素材图集，覆盖当前玩法需要的玩家主体及状态、目标或收集物、障碍或场景元素、反馈特效；每类可含多个素材，各素材独立排布并留出清楚切分间距",
+  "spritesheet_constraints": "素材仅包含当前项目玩法合同需要的实体和反馈，可独立用于游戏；角色轮廓、图标排布与配色采用项目原创设计",
  "image_generation": "根据用户需求生成一张全新的原创图片。主体、环境、风格、构图、光线和色彩以用户描述为准；不要生成素材图集、规范展板、完整游戏截图或文字说明。不得修改或复述为已有图片编辑。\n\n用户需求：{}",
  "character_generation": "根据用户需求生成一张全新的原创角色形象或人物立绘。清楚表现角色外貌、服饰、姿势、表情、画风、构图和背景；只生成一张完整图片，不要生成图集、规范展板、完整游戏截图或文字说明。不得复刻现有作品角色或 Logo。\n\n用户需求：{}",
  "publication_generation": "根据用户需求生成一张全新的原创游戏发布宣传图。突出主体、卖点、氛围、构图、色彩和适合发布展示的画面层次；只生成一张完整图片，不要生成素材图集、规范展板、完整游戏截图或文字说明。不得复刻现有作品角色或 Logo。\n\n用户需求：{}",
@@ -1,6 +1,6 @@
 {
  "schemaVersion": "agc-skill-pack.v1",
-  "version": "2026-08-26.40",
+  "version": "2026-08-26.41",
  "skills": [
    {
      "name": "agc-unity-editor",
@@ -101,7 +101,7 @@
        "agents/openai.yaml",
        "references/platform-art-contract.md"
      ],
-      "sha256": "dcf243784b7279fc4819140d746e607bde840a53bc419172d615c53364a2ecb4"
+      "sha256": "d38571ffb5b12b40f23d04b76edbb06cbda06a11590d4dd0f784b524bf30071c"
    },
    {
      "name": "agc-web-game-development",
@@ -35,6 +35,13 @@ required; choose it from the brief:
 Pass `sliceMode` only for `kind="icon-spritesheet"`, and `gridX`/`gridY` only for
 `sliceMode="grid"`. Read the selected mode from the returned result.

+For `taonier_prepare_game_art`, provide `brief` and optionally `mode`. Name the
+game's theme, style, and needed player states, targets or collectibles,
+obstacles or scene elements, and feedback effects in `brief`. The tool adds
+shared requirements for visual-spec consistency and separated asset placement.
+These content categories do not specify a slice count or returned ordering;
+inspect the actual images before deciding how to use them.
+
 ## Authorization boundary

 If the tool returns `401` or `403`, stop the operation and report that login or permission state needs attention.
@@ -2,6 +2,8 @@

 `agc_generate_image` and `taonier_prepare_game_art` are the reviewed paid art entries exposed to the AGC Codex thread. The former covers one ordinary/character/spec/UI/publication image; `agc_edit_image` covers edits to an existing registered image; the latter covers the complete game-art package and canonical slices. Call these tools only through the approved AGC session.

+- For a package, describe the concrete theme, style, entities, states, and effects in `brief`. The tool includes the package's shared visual-spec and placement requirements in generation. No additional tool fields are required. Ordinary `agc_generate_image` icon descriptions remain the supplied text without package requirements.
+
 - `mode="reuse-or-create"` reuses a complete trusted package and creates only missing assets. It is the safe default for existing games.
 - `mode="regenerate"` is reserved for an explicit user request to replace or restyle the package. Use it even when a complete package exists, but never bypass an unresolved paid operation.
 - `mode="regenerate"` requires a trusted, decodable, registered `art-spec.png` and background. An old spritesheet or canonical slices may be absent. If either the spec or background is missing or invalid, use `mode="reuse-or-create"`.
@@ -0,0 +1,25 @@
+# AGC 美术包生成需求入参修正实施计划
+
+- Version: 1
+- Status: Implemented, Awaiting Acceptance
+- Date: 2026-10-05
+- Parent Spec: [里程碑](./【里程碑】AGC美术包生成需求入参修正-2026-10-05.md)
+
+## 修改顺序
+
+1. 在 canvas_generation 的既有美术包专用入口显式传递调用用途，独立组装新图集请求的描述数组；复用 media 提示词来源，保留原 brief 意图和冻结请求路径。
+2. 同步必要的工具说明与 taonier-art-assets skill，更新随包摘要及共享排障记忆。
+3. 用 HTTP 夹具验证美术包与普通入口请求和旧任务恢复；定向测试描述边界。
+4. 完成普通 Rust 目标检查、定向 Rust 测试、runtime_prompt_bundle_build、prompt_source_boundaries、skill-pack:check、check:doc-index、check:encoding 和 diff 检查；记录实际证据与限制。
+
+## 检查点与风险
+
+首轮以 45 分钟完成请求修改与定向验证为检查点；仅测试失败或验收缺口扩展范围。旧请求按持久快照恢复，不能修改原幂等身份或借升级新建付费操作。付费 Provider 验证不在本地夹具中执行。
+
+## 回滚
+
+回退本次客户端请求组装和随包文案即可；没有服务端、工具参数或持久化 schema 迁移，已冻结的新旧请求继续按原快照恢复。
+
+## 验证完成
+
+按计划完成美术包入口隔离、描述数组组装、共享文案、skill 摘要与主规范同步。53 项定向 Rust 测试、普通构建检查和文档 / 编码 / 差异门禁通过，逐项证据见里程碑。没有执行真实付费生成；本次不修改服务端、brief 长度合同或切片处理。
@@ -0,0 +1,33 @@
+# AGC 美术包生成需求入参修正
+
+- Version: 1
+- Status: Implemented, Awaiting Acceptance
+- Date: 2026-10-05
+- Parent Spec: [AGC 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-08-23-direct-codex-美术包显式重生成与切片投影)
+
+## 目标与范围
+
+让美术包核心图集实际提交的 `iconDescriptions` 包含 brief 与现有内容、风格和排布要求。用户已确认此前方案并指示开工；实现前复核入口隔离、冻结请求恢复和服务端纯色底处理边界，评审通过。
+
+必须完成请求组装、Agent 可见说明、定向测试和文档同步。风险项是普通图标入口串用模板、超长描述与重复付费恢复。范围外保留 brief 长度契约调整、固定四片和用途识别、重生成授权措辞及服务端行为修改。
+
+## 验收标准
+
+1. 新美术包图集的真实 HTTP 请求保留 brief，并在有效字段中包含内容、风格与间距要求；参考与比例/尺寸仍由正式字段承载。
+2. 普通图标入口保持原文单项提交，规范图与背景生成参数不变。
+3. 新增描述满足 API 条数、单条、总字符与字节限制；不截断或拆分用户原文。
+4. 旧 prepared 请求保持原 POST 字节及幂等键；accepted / 已完成请求不新建付费请求，brief 变化仍拒绝冒充同一意图。
+5. 工具参数无新增；工具说明、随包 skill 与主规范一致。提示词、skill 包、编码及差异检查通过；真实 Provider 效果独立标记。
+
+## 证据
+
+| 验收项 | 证据 |
+| --- | --- |
+| 新请求与普通入口隔离 | `art_package_spritesheet_posts_requirements_but_ordinary_icons_keep_original_text` 经生产生成入口和本地 HTTP 夹具检查真实请求及重复调用，已通过 |
+| 原文与 API 边界 | `art_package_descriptions_keep_the_entire_brief_within_api_limits`、`art_package_description_limits_include_separators_and_utf8_bytes`，覆盖 200/201 码点、100/101 条、2000 字符及 6144 字节边界，已通过 |
+| 旧任务恢复 | `art_package_spritesheet_recovers_old_requests_without_injecting_new_requirements` 覆盖 prepared / accepted / legacy-completed 三种旧单条请求；正文与幂等键不变，重复调用不新增生成 POST，已通过 |
+| 相关回归 | 美术包过滤组 9 项、普通图标/背景/恢复/skill 包过滤组 20 项，全部通过 |
+| 提示词与普通构建 | `runtime_prompt_bundle_build` 18 项、`prompt_source_boundaries` 6 项及 `cargo check --locked --offline --bin genarrative-ai-game-creator-shell` 通过 |
+| 文档与资源 | skill-pack:check、check:doc-index、变更文件编码、rustfmt 和差异检查通过 |
+
+总计 53 项 Rust 测试通过。本地 HTTP 夹具需要监听回环端口，沙箱限制后已在获准的沙箱外环境重跑通过。真实客户端 / 付费 Provider 整包生成未执行；这些证据证明请求传输与恢复，不保证生成图片的视觉质量。固定四片、按序分配用途及 brief 长度不匹配仍属后续工作。本里程碑等待验收，不推进第三项。
@@ -7,6 +7,7 @@
 - **现象 / 根因**：调用方把构图等要求只写入 `generationInputs.artSpec`，但实际生图输入没有这些要求；把 `JsonValue` 和“可复用规范”误读为服务端会自动组装提示词、完整保留全部元数据或自动用于下一次生成。
 - **现行边界**：整个 `generationInputs` 承载生成上下文、来源和应用元数据，保存规则取决于接口。场景与音效重建配方；图集原图可保存自定义字段，透明图集与切片另建处理阶段 / 来源元数据。已知字段仍有实际消费者，例如规范图的“游戏类型”、V2 面板恢复字段和客户端来源标记，不能把整个对象描述为无业务作用。
 - **排查 / 使用**：同时核对正式请求字段、当前接口的重建 / 清理逻辑，以及最终资源 / 素材记录；重要要求必须进入 `prompt`、`iconDescriptions` 或场景结构化参数。项目与素材库读取可取得服务端实际保存的上下文，但它不等于完整 HTTP 重放载荷；重试仍保存原始请求和幂等键。
+- **AGC 美术包**：核心图集新请求将原 brief 与共用的风格、内容和间距要求分别写入 `iconDescriptions`；普通图标入口仍原文单项透传。新增模板只影响新请求，旧请求继续按冻结正文和操作身份恢复，不改原 brief 的意图判据。真实 HTTP 载荷与旧请求恢复必须同时验证，不能只测试 `artSpec` 包含文案。
 - **权威说明**：[External v1 OpenAPI](../../openapi/genarrative-external-v1.openapi.json) 与 [API 指南的 Generation Inputs Metadata](../../../.codex/skills/genarrative-external-editor-api/references/requests-and-outputs.md#generation-inputs-metadata)。本条记录现有行为，不引入 API、存储或 UI 行为变更。

 ## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过
@@ -1574,6 +1574,9 @@ game-project/

 ## 2026-08-23 Direct Codex 美术包显式重生成与切片投影

+- 美术包核心图集的新请求必须把 brief 原文与客户端的素材内容、风格和排布要求共同写入 `iconDescriptions`。内容覆盖当前玩法需要的玩家主体及状态、目标或收集物、障碍或场景元素、反馈特效；各素材独立排布并留出切分间距，沿用规范图的轮廓、材质、色板与光照。描述条数和内容类别不代表切片数量或返回顺序。规范图通过 `referenceId`、比例和尺寸通过正式参数传入；透明结果由服务端纯色底生成与抠图提供，不向模型追加直接生成透明背景的要求。`generationInputs.artSpec` 仅保留描述性上下文，不能作为要求已进入生成提示词的证据。
+- 美术包工具继续只接收 `brief` 与 `mode`，Agent 在 brief 中提供具体主题、风格、实体和反馈需求；客户端补齐通用要求。普通画布及 `agc_generate_image` 图标入口仍将 trim 后原文作为唯一描述项。美术包新增要求使用独立描述项并校验当前 API 的每条 200 字符、合计 2000 字符 / 6144 UTF-8 字节及 100 条上限，不挤占或截断原文；本次不扩展已有 brief 长度合同。只在没有冻结请求的新提交路径组装要求，已有 `prepared / accepted / legacy-completed` 请求按原请求体、幂等键与操作身份恢复，原 brief 的意图比较不受新增模板影响。验证必须覆盖实际 HTTP 请求、普通入口原文、描述边界及旧请求恢复，不以元数据或提示词文本存在代替传输证据。
+- 请求要求的自动化证据由 `art_package_spritesheet_posts_requirements_but_ordinary_icons_keep_original_text`、`art_package_spritesheet_recovers_old_requests_without_injecting_new_requirements` 与描述边界用例提供：生产生成入口经过本地 HTTP 夹具，核对真实 POST、原请求字节、幂等键及重复恢复零新增生成 POST。真实 Provider 的视觉效果不由请求夹具替代。
 - 标准美术包在客户端将规范图、背景图和主图集统一保存为 PNG：下载仍校验来源、声明类型与文件签名，随后按真实内容接受 PNG/JPEG/WebP，在已有 20 MiB、4096 像素单边和 64 MiB 解码内存限制内完整解码。有效 PNG 原样保留，JPEG/WebP 编码成 PNG，最终内容也不得超过 20 MiB；本地媒体类型固定为 `image/png`。转码不补造透明度，主图集与独立切片继续执行真实 alpha、可见像素、尺寸和唯一性合同；平台独立切片仍须为 PNG。此行为仅属于美术包，普通图片工具的指定扩展名合同不变。
 - 美术包的转码在项目提交锁和本地写入之前完成，文件摘要、已安装结果识别、替换恢复和 manifest 登记均使用最终 PNG。转码失败保留原生成账本与平台身份，同冻结意图重试重新读取已有结果，不提交新的付费生成；不改变请求快照、幂等身份、固定资源路径或旧 PNG 包的复用方式，无数据迁移。验收覆盖 JPEG/WebP 转码、PNG 字节不变、损坏/超限拒绝、真实透明度以及已有结果重复恢复零生成 POST；客户端真实 Provider 的整包验证单独记录。
 - 转码自动化验收由 `canvas_generation_tests` 的格式/边界用例和 `retained_runtime_generation_retries_a_completed_stage_without_posting_again` 本地 HTTP 夹具覆盖：PNG/JPEG/WebP 均先下载损坏内容，再从同一已完成账本恢复两次，核对最终 PNG、稳定本地 asset ID、Canvas 来源身份、账本保留/清理及零生成 POST；替换与补偿继续由现有图集事务和 Direct 重生成用例覆盖。真实 Provider 的客户端整包效果不由这些夹具替代。