修正美术包 API 指南、AGC 调用与切片用途判定 #628

Merged

lhk229 merged 15 commits from fix/525-art-package-contract into master 2026-10-07 19:35:21 +08:00

Conversation 2 Commits 15 Files Changed 24

+2265 -734

lhk229 commented 2026-10-05 14:28:49 +08:00

Member

Copy Link

Copy Source

AGC 美术包此前把内容、风格和排布要求放在未被提示词消费的元数据中，并要求恰好四张切片、按返回顺序分配用途。本 PR 完成以下三项修正：

• API 文档：修正整个 generationInputs 的定位、保存与读取方式、接口保留/重建规则及已知消费者。任意元数据不会自动进入提示词，服务端行为和校验约束保持不变。
• AGC 请求：美术包将原 brief 和内容、风格、排布要求写入实际消费的 iconDescriptions；普通图标入口继续原文单项透传。参考图、比例和尺寸使用正式参数，同步工具说明与随包 skill。
• 客户端切片处理：美术包和直接生图工具不再暴露或发送 sliceCount，取消固定四片和按序赋义；按实际产物保存、登记和返回。切片目录按源图集隔离，文件名使用中性序号，普通清单指向真实总图。

四类素材需求只表达内容覆盖，不能证明四个连通区域或固定语义顺序。两个工具返回总图、完整切片路径及资源身份，预览逐项标注路径，未内嵌的图片列出路径供 Agent 查看。Agent 看图识别实体、状态和用途后再接入或处理；有效总图零切片时仍交付并保留告警。

本轮切片改造仅限客户端：服务端 API、请求侧 sliceCount 契约、切分算法和计费行为不变。不新增为数量不符找回、补切或凑数的工作流。保留文件完整性、平台身份、资源预算、事务与重生成恢复；兼容历史四用途产物和旧数量参数账本，旧请求正文、幂等键及 operation 不改写，候选身份不唯一时要求对账。完成结果快照补存切分声明，避免重放丢失响应字段。

验证：

• API 文档阶段：MCP 25 项、External editor API 30 项测试及 OpenAPI 约束等价检查通过。
• 本轮：317 项定向 Rust 测试通过（生成 118、Direct 运行时 93、工具桥 44、MCP 32、账本 6、提示词 24）。覆盖新请求完全省略字段、0/2/4/6 片、目录隔离、完整资源投影、动态事务回滚、旧请求和旧输出槽恢复；已受理任务恢复不新增生成 POST。
• cargo check、rustfmt、skill-pack:check、文档索引、变更文件编码及 git diff --check 通过。
• 未调用真实付费 Provider，未做客户端视觉试玩；PR 保持草稿，等待视觉及产品验收。

Closes #525

AGC 美术包此前把内容、风格和排布要求放在未被提示词消费的元数据中，并要求恰好四张切片、按返回顺序分配用途。本 PR 完成以下三项修正： - [x] API 文档：修正整个 `generationInputs` 的定位、保存与读取方式、接口保留/重建规则及已知消费者。任意元数据不会自动进入提示词，服务端行为和校验约束保持不变。 - [x] AGC 请求：美术包将原 brief 和内容、风格、排布要求写入实际消费的 `iconDescriptions`；普通图标入口继续原文单项透传。参考图、比例和尺寸使用正式参数，同步工具说明与随包 skill。 - [x] 客户端切片处理：美术包和直接生图工具不再暴露或发送 `sliceCount`，取消固定四片和按序赋义；按实际产物保存、登记和返回。切片目录按源图集隔离，文件名使用中性序号，普通清单指向真实总图。 四类素材需求只表达内容覆盖，不能证明四个连通区域或固定语义顺序。两个工具返回总图、完整切片路径及资源身份，预览逐项标注路径，未内嵌的图片列出路径供 Agent 查看。Agent 看图识别实体、状态和用途后再接入或处理；有效总图零切片时仍交付并保留告警。 本轮切片改造仅限客户端：服务端 API、请求侧 sliceCount 契约、切分算法和计费行为不变。不新增为数量不符找回、补切或凑数的工作流。保留文件完整性、平台身份、资源预算、事务与重生成恢复；兼容历史四用途产物和旧数量参数账本，旧请求正文、幂等键及 operation 不改写，候选身份不唯一时要求对账。完成结果快照补存切分声明，避免重放丢失响应字段。 验证： - API 文档阶段：MCP 25 项、External editor API 30 项测试及 OpenAPI 约束等价检查通过。 - 本轮：317 项定向 Rust 测试通过（生成 118、Direct 运行时 93、工具桥 44、MCP 32、账本 6、提示词 24）。覆盖新请求完全省略字段、0/2/4/6 片、目录隔离、完整资源投影、动态事务回滚、旧请求和旧输出槽恢复；已受理任务恢复不新增生成 POST。 - cargo check、rustfmt、skill-pack:check、文档索引、变更文件编码及 git diff --check 通过。 - 未调用真实付费 Provider，未做客户端视觉试玩；PR 保持草稿，等待视觉及产品验收。 Closes #525

lhk229 added 1 commit 2026-10-05 14:46:20 +08:00

修正 generationInputs 的 API 元数据说明 ... dab51b0c71

补齐 OpenAPI 全部 generationInputs 字段的保存、重建、读取和消费边界
更新 API 指南及美术规范示例，明确元数据不会自动进入提示词
同步长期排障记忆，保持服务端行为及请求校验约束不变

lhk229 added 1 commit 2026-10-05 15:27:09 +08:00

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

将美术包内容、风格和排布要求写入 iconDescriptions 并复用元数据文案来源
保留普通图标原文透传与旧生成账本的冻结请求和幂等身份
同步工具说明、美术资源技能、主规范和里程碑验收证据
补充真实 HTTP 请求、恢复防重及描述边界测试

lhk229 added 1 commit 2026-10-05 16:49:10 +08:00

合并最新 origin/master 到美术包修正分支 ... 7019dd8634

同步 master 的首页异步命名、窗口项目标签与构建修正
合并共享排障文档并保留双方新增记录
保留美术包有效入参与 generationInputs API 说明修正

lhk229 commented 2026-10-05 17:23:04 +08:00

Author

Member

Copy Link

Copy Source

补充第三项的设计结论：AGC 应停止暴露和发送 sliceCount，并移除客户端“必须恰好 N 张”的门禁，避免围绕数量不符增加找回、重拆、补齐或重新生成工作流。此结论更新此前“美术包继续传 4”的设想。范围已按后续讨论收敛为仅修改客户端；服务端 API 保持现状。

原因来自当前实现：

1. 该参数不参与生图提示词。 连通域模式的提示词构造没有接收 sliceCount，因此传 4 不会告诉模型生成四个素材。它只在生成后充当切片输出上限和数量相等检查，不能提高生成数量的准确性。提示词调用、切分数量检查。
2. 数量不符时丢掉的是本可交付的切片，不是取消生成。 切分错误被转换为 sliceWarning 和空切片列表；只要后续持久化成功，Provider 原图与透明总图仍进入用户云端资产，任务完成且保留扣费。这不意味着图片里没有素材，也不意味着生成退款，只意味着用户拿不到这次自动切分的独立产物。告警与资产提交。
3. 客户端已有取得总图的完整链路。 生成完成响应带有资源和下载信息，AGC 先下载主图，再执行本地严格切片校验。美术包当前是在图集已下载到内存后拒绝提交；为此另加资产库查找或恢复工作流，只是在绕过本来就不应存在的数量门禁。下载主图、本地校验。
4. 数量相等也不能证明语义正确。 四类素材需求可能对应多个状态、部件和特效；连通域及空间排序不负责识别玩家、目标、障碍或反馈。凑齐四张仍可能用途错配，增加“补齐四张”的流程不能解决 #525。
5. 现有网站画布已经不传该参数。 画布使用连通域模式，按实际结果展示图集与切片。服务端已有独立的切片数量、像素和处理预算上限，移除业务目标数量不会取消这些资源保护。画布请求。

本 PR 的客户端修改范围：

• 从 AGC 新生成请求、Agent 工具 schema、解析与说明中移除 sliceCount。服务端请求契约、OpenAPI、外部 MCP 和响应字段保持不变；旧冻结请求按原正文、幂等键与 operation 恢复。
• 复用服务端既有的省略字段行为：不执行期望数量相等检查，在独立资源预算内返回实际切片。真实切分失败或零有效切片仍可能返回告警，客户端保留有效总图。
• 美术包和直接调用统一按实际切片集合保存、登记和返回，取消“四张才成功”及按返回顺序填写用途；不同图集的路径和清单互相隔离。
• 将总图、实际切片、资源身份和告警交给 Agent 看图识别与接入。素材数量要求写入实际生图描述，是否满足玩法由 Agent 验收；裁剪、组合、编辑或补充生成只应由实际内容需求触发。
• 更新现有回执、事务恢复与旧产物读取，使其支持实际集合并继续保证幂等；不新增专门为 sliceCount 数量不符服务的重试、找回或补齐流程，也不为凑数重新付费生成。

期望数量如需核对，调用方可比较实际返回数量并查看图片；本 PR 通过客户端不传该字段避开数量门禁，不改造服务端 API。

补充第三项的设计结论：AGC 应停止暴露和发送 `sliceCount`，并移除客户端“必须恰好 N 张”的门禁，避免围绕数量不符增加找回、重拆、补齐或重新生成工作流。此结论更新此前“美术包继续传 4”的设想。范围已按后续讨论收敛为仅修改客户端；服务端 API 保持现状。 原因来自当前实现： 1. **该参数不参与生图提示词。** 连通域模式的提示词构造没有接收 `sliceCount`，因此传 4 不会告诉模型生成四个素材。它只在生成后充当切片输出上限和数量相等检查，不能提高生成数量的准确性。[提示词调用](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/7019dd863425b2e55fef6d1e9f340061195621af/server-rs/crates/api-server/src/editor_project_icon.rs#L1757)、[切分数量检查](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/7019dd863425b2e55fef6d1e9f340061195621af/server-rs/crates/api-server/src/editor_project_icon.rs#L2650)。 2. **数量不符时丢掉的是本可交付的切片，不是取消生成。** 切分错误被转换为 `sliceWarning` 和空切片列表；只要后续持久化成功，Provider 原图与透明总图仍进入用户云端资产，任务完成且保留扣费。这不意味着图片里没有素材，也不意味着生成退款，只意味着用户拿不到这次自动切分的独立产物。[告警与资产提交](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/7019dd863425b2e55fef6d1e9f340061195621af/server-rs/crates/api-server/src/editor_project_icon.rs#L2158)。 3. **客户端已有取得总图的完整链路。** 生成完成响应带有资源和下载信息，AGC 先下载主图，再执行本地严格切片校验。美术包当前是在图集已下载到内存后拒绝提交；为此另加资产库查找或恢复工作流，只是在绕过本来就不应存在的数量门禁。[下载主图](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/7019dd863425b2e55fef6d1e9f340061195621af/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs#L3725)、[本地校验](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/7019dd863425b2e55fef6d1e9f340061195621af/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs#L8073)。 4. **数量相等也不能证明语义正确。** 四类素材需求可能对应多个状态、部件和特效；连通域及空间排序不负责识别玩家、目标、障碍或反馈。凑齐四张仍可能用途错配，增加“补齐四张”的流程不能解决 #525。 5. **现有网站画布已经不传该参数。** 画布使用连通域模式，按实际结果展示图集与切片。服务端已有独立的切片数量、像素和处理预算上限，移除业务目标数量不会取消这些资源保护。[画布请求](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/7019dd863425b2e55fef6d1e9f340061195621af/src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts#L1139)。 本 PR 的客户端修改范围： - 从 AGC 新生成请求、Agent 工具 schema、解析与说明中移除 `sliceCount`。服务端请求契约、OpenAPI、外部 MCP 和响应字段保持不变；旧冻结请求按原正文、幂等键与 operation 恢复。 - 复用服务端既有的省略字段行为：不执行期望数量相等检查，在独立资源预算内返回实际切片。真实切分失败或零有效切片仍可能返回告警，客户端保留有效总图。 - 美术包和直接调用统一按实际切片集合保存、登记和返回，取消“四张才成功”及按返回顺序填写用途；不同图集的路径和清单互相隔离。 - 将总图、实际切片、资源身份和告警交给 Agent 看图识别与接入。素材数量要求写入实际生图描述，是否满足玩法由 Agent 验收；裁剪、组合、编辑或补充生成只应由实际内容需求触发。 - 更新现有回执、事务恢复与旧产物读取，使其支持实际集合并继续保证幂等；不新增专门为 `sliceCount` 数量不符服务的重试、找回或补齐流程，也不为凑数重新付费生成。 期望数量如需核对，调用方可比较实际返回数量并查看图片；本 PR 通过客户端不传该字段避开数量门禁，不改造服务端 API。

lhk229 added 1 commit 2026-10-05 17:59:59 +08:00

移除客户端图集数量约束并按实际产物交付 ... ea18cf8f12

删除美术包和直接生图工具的切片数量参数及按序用途映射
按源图集隔离切片路径并返回完整资源身份与路径标注预览
支持零切片总图交付及动态集合事务和重生成恢复
保留旧数量账本原请求身份并修复完成结果切分声明持久化
同步工具提示词、美术技能、技术规范与定向测试证据

lhk229 added 1 commit 2026-10-05 18:13:28 +08:00

补充图集与美术包提示词中的素材数量指引 ... b254090680

在工具参数说明中要求按明确需求填写素材数量、状态和独立排布要求
同步美术包技能及参考合同，区分生成目标与实际切片数量
更新技能包版本和内容指纹，并同步技术规范

lhk229 added 1 commit 2026-10-05 18:20:09 +08:00

补记美术包技能通用校验通过证据 ... 68a3f596bb

记录安装 PyYAML 后美术包技能通用校验通过
同步里程碑和实施计划，移除已解决的依赖缺失状态

lhk229 added 1 commit 2026-10-06 17:21:40 +08:00

合并最新主分支并保留美术包合同修复 ... 576d2709e0

合并 origin/master 的 9f4c7d763 到当前修复分支
合并双方技能包内容，将版本递增至 2026-08-26.44
保留双方共享记忆条目以及本分支的 API 说明、提示词和实际切片处理修复
验证图集回归 26 项、Rust 技能包 7 项、提示词 24 项和技能包脚本 3 项通过
验证三个变更技能的通用校验、技能包指纹、文档索引、编码与差异检查通过
保留提交钩子对 Pingora 路由校验脚本的纯格式调整

lhk229 referenced this pull request 2026-10-06 18:39:27 +08:00

图集生成输入契约遗留 100 条描述与单条 200 字符限制，应统一完整提示词并提高上限 #660

lhk229 added 1 commit 2026-10-06 18:40:45 +08:00

补充美术包工具的描述长度要求 ... 654e98fb01

在 Agent 可见的 brief 说明中明确 1 到 200 个 Unicode 字符及计数规则
同步美术包技术文档，并关联输入契约后续改造 issue #660
保持 schema、请求组装、阶段校验与实际生成行为不变

lhk229 added 1 commit 2026-10-06 18:43:56 +08:00

精简美术包工具的长度提示 ... ac56b81249

将 brief 长度说明精简为不超过 200 字符
同步技术文档，保留现有校验和生成行为

lhk229 added 1 commit 2026-10-06 18:44:20 +08:00

merge latest master ede5243191

lhk229 added 1 commit 2026-10-06 19:01:55 +08:00

修复美术包缺失图集的续生成与完成判定 ... 67225824e7

复用有效规范图和背景图，补齐缺失图集并优先恢复原阶段请求
统一要求三张主图有效才返回完成，失败保留基础素材并返回原因
增加补齐、恢复幂等、失败保留与不完整包拒绝的关键回归
同步美术包规范、验收证据和共享排障记忆

lhk229 added 1 commit 2026-10-06 19:27:18 +08:00

删除美术包完成时多余的参考图身份比较 ... 3af6cd0484

移除参考图原始资源 ID 与请求参考 ID 的直接相等要求
保留本轮图集资源、对象和任务身份核对
调整现有完成与恢复用例覆盖规范图重新登记，删除过期拒绝断言
同步美术包规范、验收证据和共享排障说明

lhk229 added 1 commit 2026-10-07 16:58:40 +08:00

合并远端 master 到美术包合同修复分支 ... 09b0448862

同步 origin/master 的最新代码、测试与文档变更

保留图集按实际产物返回的提示词并移除已退役发布说明

合并技能包清单并递增版本，保留双方项目经验记录

lhk229 added 1 commit 2026-10-07 18:42:30 +08:00

Merge branch 'master' into fix/525-art-package-contract c53c73169d

lhk229 marked the pull request as ready for review 2026-10-07 18:47:02 +08:00

lhk229 commented 2026-10-07 18:58:25 +08:00

Author

Member

Copy Link

Copy Source

<img width="1240" alt="image.png" src="attachments/540309cd-c753-41c7-9ffa-a4daa25156b4">

image.png

803 KiB

lhk229 reviewed 2026-10-07 19:00:12 +08:00

lhk229 left a comment

Author

Member

Copy Link

Copy Source

审查结论

对照 c53c73169dbb06a80c747f04d95bca93be9ef44a（fix/525-art-package-contract 相对 origin/master）审查了已提交改动。

本次变更把美术包图集从固定切片数量改为按实际产物交付：新请求不再发送 sliceCount，连通域结果按服务端返回的真实切片落盘；美术包把风格、构图和约束写入 iconDescriptions，作为真正进入提示词的入参，generationInputs.artSpec 只保留来源元数据。缺失图集时先尊重已有阶段账本，没有账本才做只读恢复，否则只补生成图集；失败时保留规范图和背景图并报未完成。完成判定去掉了参考图远端身份的多余相等比较，谱系仍通过本地字节绑定校验。对照服务端切分、提示词拼接和空切片告警路径，以及续生成、冻结请求体和零切片提交测试，合同与实现一致。

未发现会发出错误请求或给出错误完成结论的缺陷。

• 缺陷：0
• 建议：0
• 风格：0

Reviewed by Grok

## 审查结论 对照 `c53c73169dbb06a80c747f04d95bca93be9ef44a`（`fix/525-art-package-contract` 相对 `origin/master`）审查了已提交改动。 本次变更把美术包图集从固定切片数量改为按实际产物交付：新请求不再发送 `sliceCount`，连通域结果按服务端返回的真实切片落盘；美术包把风格、构图和约束写入 `iconDescriptions`，作为真正进入提示词的入参，`generationInputs.artSpec` 只保留来源元数据。缺失图集时先尊重已有阶段账本，没有账本才做只读恢复，否则只补生成图集；失败时保留规范图和背景图并报未完成。完成判定去掉了参考图远端身份的多余相等比较，谱系仍通过本地字节绑定校验。对照服务端切分、提示词拼接和空切片告警路径，以及续生成、冻结请求体和零切片提交测试，合同与实现一致。 未发现会发出错误请求或给出错误完成结论的缺陷。 - 缺陷：0 - 建议：0 - 风格：0 Reviewed by Grok

lhk229 added 1 commit 2026-10-07 19:28:13 +08:00

删除已验收的美术包临时计划 ... 2c3f4cfbc9

删除美术包生成需求入参修正的里程碑与实施计划。
删除图集实际产物与语义识别的里程碑与实施计划。
主规范去掉已完成的真实出图视觉验收门禁措辞。

lhk229 merged commit 27e385785f into master 2026-10-07 19:35:21 +08:00

lhk229 deleted branch fix/525-art-package-contract 2026-10-07 19:35:21 +08:00

suzmii referenced this issue from a commit 2026-10-07 21:09:41 +08:00

Merge origin/master (b1c89fbba) into chore/rust-compile-warnings：按「让路 master + 最小集恢复」收口跨文件契约冲突

Sign in to join this conversation.

Reviewers

No Reviewers

lhk229

Labels

Clear labels

Compat/Breaking

Breaking change that won't be backward compatible

Kind/Bug

Something is not working

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Security

This is security issue

Kind/Testing

Issue or pull request related to testing

Priority

Critical

1

The priority is critical

Priority

High

2

The priority is high

Priority

Low

4

The priority is low

Priority

Medium

3

The priority is medium

Reviewed

Confirmed

1

Issue has been confirmed

Reviewed

Duplicate

2

This issue or pull request already exists

Reviewed

Invalid

3

Invalid issue

Reviewed

Won't Fix

3

This issue won't be fixed

Status

Abandoned

3

Somebody has started to work on this but abandoned work

Status

Blocked

1

Something is blocking this issue or pull request

Status

Need More Info

2

Feedback is required to reproduce issue or to continue work

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

18250971020 Fiorina (张馨月) HuangJiaJia JenkenB (包仲航) k88936 (王德宇) kdletters (段舒康) laura2008 (王乐) lhk229 (孔令弘) Loer (农洛儿) loong suzmii (董羽秦) taobaisu (叶东旭) wuxiangwanzi (王子民) YixuanLiu ziyu

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#628