dc-docs/output/feishu-docs/EpZZw1rT9iBZDFkrwo2cgImpngb.md

EpZZw1rT9iBZDFkrwo2cgImpngb

Source: https://dianchukeji.feishu.cn/wiki/EpZZw1rT9iBZDFkrwo2cgImpngb

一.工作内容概述

• 碎片收集系统功能收尾，bug修复
• 参照agent-sprite-forge项目，仿写 Codex 生图 Skill

二.参考项目学习分析

参考了 agent-sprite-forge 项目的设计思路。该项目的核心并不是简单提供一组 sprite prompt 模板，而是提供了一套面向 Agent 的 2D 游戏资产生产流程。 参考项目： https://github.com/0x0funky/agent-sprite-forge 它的基本工作方式是： 其中最值得参考的是它对职责的拆分：

• Agent 负责创意判断和流程决策
• 图像模型负责生成原始视觉结果
• Python 脚本负责确定性的工程处理 也就是说，参考项目并不指望 AI 一次性输出完美工程资产，而是让 AI 负责视觉生成，再通过脚本完成：
• 去背景
• despill
• 切帧
• 对齐
• 统一缩放
• 透明导出
• GIF 预览
• metadata 输出
• QC 检查 这种设计思路比较适合迁移到 UI 资产生产中。因为 UI 资产同样存在“视觉生成”和“工程可用”之间的断层：AI 可以生成好看的 UI 效果图，但要进入项目使用，还需要拆分、透明化、去边缘污染、统一命名和质检。

三.Codex Skill仿写思路

基于参考项目，本次没有直接照搬 sprite 生产流程，而是提取其核心模式：**Agent原生生图能力+本地确定性后处理，**然后将其迁移到静态 UI 资产生产中。 两者的对应关系大致如下：

[嵌入电子表格: Yvh9suruJhMp5otWY3Ac...]

因此，这个Skill的核心目标被定义为： 将 AI 生成的 UI 效果图，进一步转化为可交付的独立透明 PNG 资产包。 而不是只停留在“生成一张完整 UI 图”。

四.Skill 最终流程设计

设计的Skill流程如下：

4.1 需求确认

在用户提出 UI 需求后，Codex 先对需求进行整理和确认，包括：

• 页面类型
• 画布尺寸
• 视觉风格
• 功能元素清单
• 是否有参考图
• 输出目标
• 拆分原则 默认策略为：
• 默认输出透明 PNG 资产包
• 默认按最小可用单元拆分
• 默认普通文本不生成 PNG
• 默认装饰性文本作为 PNG 资产生成
• 默认生成黑 / 白 / 蓝底预览
• 默认启用后处理与 QC

4.2 整体效果图

效果图阶段用于确认整体视觉方向，包括：

• 整体风格
• 页面布局
• 色彩体系
• UI 密度
• 功能区层级
• 按钮 / 面板 / 图标的大致视觉语言 这一阶段的重点不是生成最终资产，而是确认设计方向。 同时，效果图生成时需要考虑后续拆分，避免 UI 元素过度融合，例如按钮、图标、文字、装饰和背景混成一体。

4.3 布局规格图

效果图确认后，会生成布局规格图，用于确认：

• 画布尺寸
• 安全区
• 主要功能区边界
• 核心组件尺寸
• 主要间距
• 主要对齐关系 布局规格图不是重新生图，而是基于 layout_spec.json 程序化标注，输出：
• layout_spec.json
• annotated_layout.png 这一步的作用是把“视觉确认”进一步转成“结构确认”，为后续拆分清单和资产生成提供依据。

4.4 拆分清单

拆分采用“最小可用单元”原则。需要独立拆分的元素包括：

• 按钮底板
• 按钮图标
• 面板底板
• 资源栏底板
• 资源图标
• 加号按钮
• 红点提醒
• 角标
• 奖励框
• 奖励图标
• 进度条底槽
• 进度条填充
• 装饰件
• 装饰性标题 / Logo / 艺术字 普通可编辑文本不进入图片生成流程，只记录到 manifest 装饰性文本、Logo、活动标题艺术字则作为图片资产单独生成。

4.5 单资产生成

单资产生成阶段默认优先使用：agent_native_image_generation，即 Agent 调用自身可用的生图能力生成 raw asset。 如果当前运行环境不支持 Agent 原生生图，则需要通过 API provider 补足生图能力；两者都不可用时，不允许退化为程序绘制占位图。 同时明确禁止将以下内容作为最终交付资产：

• SVG
• PIL 程序绘制
• procedural shapes
• mock assets
• placeholder graphics 这些只能用于 smoke test 或调试，不能作为正式资产交付。

4.6 后处理

后处理部分复用了昨日开发的图片后处理工具能力，并将其拆成代码库，用于处理：

• Color Key Matting
• PyMatting 单主体抠图
• despill 去背景色污染
• alpha-aware resize
• RGB bleed
• alpha contract / feather
• 黑 / 白 / 蓝底预览
• 基础 QC
• postprocess_report 输出 后处理的职责是解决工程问题，例如：
• 透明背景
• 边缘污染
• 灰边 / 黑边 / 紫边
• 缩放后脏边
• 透明区 RGB 污染 但后处理不负责修复美术生成错误，例如图标语义错误、风格不一致、普通文本被画进资产等问题。

五.关键问题与修正

在测试过程中发现，单资产生成阶段存在一个比较明显的问题：即使整体效果图已经确认，单独生成某个 UI 元素时，模型仍可能根据资产名称生成“通用版本”，而不是继承效果图中的具体风格。 例如，效果图中的设置按钮是绿色 Q 版 UI 风格，但单独生成“设置齿轮”时，模型可能会生成灰色金属齿轮。这说明，仅在提示词中写“保持和效果图一致”并不够。模型很容易受到通用语义影响，比如：

• 设置齿轮通常被理解为灰色金属齿轮；
• 系统胶囊按钮通常被理解为灰白色通用胶囊；
• 加号、资源图标、红点等也可能被生成成通用 UI 素材，而不是当前页面里的风格。 针对这个问题，当前 Skill 增加了更强的“效果图继承机制”，让单资产生成不再是重新设计一个图标，而是尽量从已确认效果图中提取风格信息，再生成同风格的拆分资产。

5.1 以效果图为基准生成单资产

单资产生成不再被视为“重新画一个图标”，而是被定义为：基于已确认效果图，生成同一套 UI 风格下的独立资产。 因此，每个资产生成时都会参考以下信息：

• 最终确认的整体效果图；
• 该元素在效果图中的局部参考图；
• 整体 UI 的风格描述；
• 当前资产的生成说明。 这样做的目的是减少模型自由发挥，避免它生成脱离当前页面风格的通用图标。

5.2 局部参考图

对于拆分清单中已经标出位置的元素，会从最终效果图中裁剪出对应区域，作为该元素的局部参考图。 这张局部参考图的作用是帮助模型理解：当前要生成的不是任意一个设置按钮，而是这个页面里已经出现过的、具有特定颜色和材质的设置按钮。 它主要用于约束：

• 颜色；
• 外形；
• 描边；
• 高光；
• 阴影；
• 材质倾向；
• 整体视觉重量。

5.3 提取局部设计特征

在获得局部参考图后，系统会尝试从中提取一些可用的设计特征，例如：

• 主色；
• 辅色；
• 高光色；
• 阴影色；
• 描边色；
• 主色系；
• 大致尺寸比例；
• 大致形状；
• 材质倾向。 这些信息会被写入当前资产的生成说明里，用于强化提示词约束。 需要注意的是，这一步并不是“自动完美还原设计”。如果局部参考图太小、被遮挡，或者和背景混在一起，提取结果就可能不完整。因此，提取出的特征只作为辅助约束，必要时还需要 Agent 根据整体效果图和页面风格进行补全。

5.4 颜色锁定机制

为了减少颜色漂移，当前 Skill 增加了“颜色锁定”机制。 简单来说，就是从局部参考图中提取目标配色，并明确写入单资产生成提示词。例如，对于绿色设置按钮，会提取出类似这样的配色要求： 对应到生成提示词中，会明确要求：

• 必须使用绿色卡通 UI 配色；
• 禁止生成灰色金属齿轮；
• 禁止生成银色齿轮；
• 禁止工业质感；
• 禁止通用设置图标风格。 这样可以尽量让模型按照当前页面的配色体系生成资产，而不是根据“设置齿轮”的通用印象生成灰色金属图标。

5.5 失败处理规则

如果生成结果仍然出现颜色、风格或语义不一致，比如绿色设置按钮又变成灰色齿轮，则不对整套 UI 重新生成，只针对当前资产重新生成。 当前规则是不使用以下兜底方式：

• 不做多候选筛选；
• 不做脚本重着色；
• 不直接从效果图裁剪作为最终资产。 也就是说，流程保持为： 这样可以避免局部问题影响整套资产生产流程，同时保持最终资产仍然来自生图模型，而不是程序重绘或直接裁剪。

六.最终效果验证

6.1 产出质量验证

本轮测试已经完整跑通从单资产生成、后处理、QC、资源汇总到打包交付的流程。最终共生成 25 个透明 PNG 资产，并完成后处理报告（postprocess reports）、质检报告（QC reports）、资产汇总预览图（contact sheet）和资产包输出。最终 QC 结果为 FAIL 0、WARN 25，说明流程已经能够完成交付，但所有资产仍存在不同程度的质量警告，主要集中在边缘、颜色或视觉复核项上。 从资源汇总看，简单 UI 组件的处理效果相对较好，例如按钮底板、资源栏、红点、加号、金币、闪电等。这类资产通常具备以下特征：

• 轮廓清晰；
• 颜色块明确；
• 半透明区域少；
• 边缘结构简单；
• 不包含复杂毛发、粒子、阴影或柔光。 因此，当前的 color key、despill、alpha-aware resize 和 RGB bleed 流程，对这类标准 UI 组件是有效的，基本符合透明 PNG 资产交付的要求。 但对于复杂插画类资产，边缘质量仍然不够稳定。例如牛角色、公告图标、好友对战装饰图、皮肤图标等，这类素材通常包含：
• 毛发或复杂外轮廓；
• 柔和阴影；
• 半透明高光；
• 小粒子、小装饰；
• 较复杂的体积光和颜色过渡。 这些内容在生成阶段就已经和 key 背景发生一定混合，导致后处理只能缓解边缘污染，无法完全还原干净的 alpha。尤其是阴影和柔光类区域，本身就是低透明度、低饱和度、模糊边缘的图形，很容易在抠图过程中出现残留、断裂或边缘发脏的问题。 因此，本轮质量验证的结论是： 当前 Skill 已经能够跑通完整资产交付流程，并且对硬边 UI 组件和简单图标具备较好的处理效果；但复杂插画、角色头像、柔光阴影、粒子装饰等资产仍需要找寻更好的解决方案。 后续不应继续尝试用同一套后处理参数覆盖所有资产，而是需要根据资产类型区分处理方式：
• 硬边 UI 组件：按钮、面板、资源栏、进度条；
• 简单图标：金币、体力、加号、红点；
• 复杂插画：角色、头像、装饰图；
• 阴影 / 光效：柔光、投影、粒子；
• 艺术字 / 标题：Logo、活动标题、特殊字体。 不同类型应使用不同的后处理 preset 和 QC 标准。

6.2 耗时与成本问题

本轮测试也暴露出比较明显的效率问题：

• 首板拆分清单共包含 25 个 UI 元素。按照当前 Skill 流程，每个元素都需要先单独生成 raw asset，再进入本地后处理和 QC。实际运行中，25 个 raw asset 的生成整体耗时约 3 小时 24 分钟，是本轮流程中最主要的耗时阶段。相比之下，后处理和 QC 本身耗时很短：首轮 postprocess / QC 约 17.5 秒，背景色自动采样与修正约 1.6 秒，第二轮 postprocess / QC 约 15.3 秒。 这说明当前流程的主要瓶颈不在 Python 后处理，而在单资产生图和 Agent 调度阶段。 主要原因包括：

1. 单资产逐个生成导致调用次数过多

当前流程为了保证最小可用单元的独立性，要求每个元素单独生成。25 个元素意味着至少 25 次生图任务。虽然本轮没有发生 raw asset 的重新生图重试，但单次生成叠加后仍然带来较高耗时。

2. Agent-native 生图存在调度开销

本轮 raw generation 阶段总耗时约 204 分钟，其中真正 image tool 等待和 Agent 间隔混合在一起，无法精确拆分。复盘中估算，生图等待约占 45%～65%，Agent 组织 prompt、复制文件、状态检查和无效动作约占 35%～55%。

3. 后半段出现大量无效中间动作

前 15 张资产平均耗时约 1.5～4 分钟，较接近正常生图等待；但后 10 张平均耗时上升到 8～42 分钟。从 Codex 复盘结果看，后半段变慢的主要原因不是图片本身更复杂，而是 Agent 中间发生了大量无效 shell 输出、重复状态消息和重复检查，导致每张图之间的组织时间被明显拉长。 这里的“无效中间动作”主要指：Agent 在两次生图之间反复打印状态、重复确认剩余资产列表、重复检查 raw 文件是否存在、重复解释下一步，甚至执行一些只输出提示文本但不推进流程的 shell 命令。这些动作不会直接生成资产，也不会进入后处理，但会增加等待时间和 token 消耗。

4. token 消耗主要来自重复规则和长报告

当前环境没有暴露精确 token 计量，因此只能做相对估算。复盘中判断，token 消耗较高的部分主要包括：用户多次内联完整 SKILL.md、多次读取长脚本和报告、25 个 asset brief 生成逻辑中的重复规则、raw 生成阶段的大量重复状态消息，以及最终 QC summary 的全量输出。

5. prompt 公共规则重复

每个 asset brief 的 prompt 约 459～569 字符，英文词数约 70～88 词，单条 prompt 本身不算特别长。但其中重复包含大量公共规则，例如 isolated asset、flat chroma key background、match approved UI、no ordinary text、no full UI screenshot、no watermark 等。后续可以将这部分公共规则模板化，只让每个资产填充差异描述。

💡 基于本轮测试，当前判断是： Skill 的流程逻辑是成立的，但当前执行方式还不适合直接进行高吞吐的全量批量生产。 主要瓶颈集中在单资产逐个生图和 Agent 调度成本，而不是本地后处理。

6.3 效率优化方向

针对本轮测试中暴露出的耗时问题，后续可以从以下几个方向优化。

1. 增加“验证模式 / 正式模式”

首轮不建议直接执行完整拆分清单，而是先进入验证模式，只选择 5～8 个代表资产跑完整链路，例如：

• 1 个按钮底板；
• 1 个资源栏；
• 1 个图标；
• 1 个角标；
• 1 个复杂插画；
• 1 个装饰件；
• 1 个面板底板。 先验证生图一致性、透明化质量、边缘质量、QC 和交付结构，确认流程稳定后，再进入正式模式全量生成。

2. 拆分清单增加优先级

拆分清单可以增加 P0 / P1 / P2 优先级：

• P0：首轮必须验证的核心资产；
• P1：正式包需要生成的主要资产；
• P2：可后续补充的小装饰、弱功能元素、非核心变体。 这样可以避免每次测试都默认全量执行，减少无效消耗。

3. 引入“同类资产组生成”

当前流程是每个资产单独生成，调用次数较多。后续可以将功能相近、形式相近、风格一致的小资产放在同一张图里生成，再由后处理切分成独立 PNG。 适合资产组生成的类型包括：

• 小图标组；
• 资源图标组；
• 角标 / 红点组；
• 同规格按钮底板组；
• 小装饰组。 这样可以将 25 次生图压缩为更少的资产组生图任务，降低总耗时和 token 消耗，同时也有助于提高同组资产之间的风格一致性。

4. 增加静默批量执行模式

后续 raw asset 批量生成时，应减少 Agent 在每个资产之间的状态解释和重复确认。 可以在批量生成前先写入 asset_generation_queue.json，明确每个资产的生成顺序、状态和 raw 输出路径。生成过程中不再反复扫描目录或解释下一步，只在以下情况输出信息：

• 批量开始；
• 某个资产失败；
• 需要用户确认；
• 批量完成。 这样可以减少重复状态消息、无效 shell 输出和目录检查带来的时间与 token 消耗。

5. 禁止无效 shell 输出

后续 Skill 可以明确规定：shell 命令必须有实际工程作用，不能只是打印“下一步”“继续”“准备调用工具”等状态文本。 允许的 shell 操作应限定为：

• 读取必要输入；
• 写入或更新必要输出；
• 调用处理脚本；
• 校验生成文件；
• 打包交付物。 这可以减少 Agent 在批量生成阶段的空转操作。

6. 模板化 prompt 公共规则

当前每个资产 prompt 中都重复包含大量公共约束。后续可以将公共规则抽成 shared prompt suffix，由 prompt_builder.py 自动拼接。每个资产只需要填写差异化字段，例如：

• asset_id；
• asset type；
• expected visual；
• target palette；
• forbidden styles；
• reference crop。 这样可以减少 Agent 重复组织 prompt 的 token 消耗，也能提升 prompt 一致性。

7. raw 生成后立即自动采样 key 背景色

本轮首轮 postprocess / QC 全部 FAIL 的一个重要原因是：生图工具实际输出的 key 背景色并不严格等于预期色值，存在漂移和轻微渐变。后续应在 raw asset 生成后立即自动采样四角背景色，并回写 brief 中的 key color，再进入后处理。 这样可以避免后处理阶段再次整批失败。

8. 批量化后处理和 QC

后处理和 QC 本身耗时较短，但仍应继续减少 Agent 逐个调用脚本的次数。后续可以保持或强化批量脚本方式，例如：

• 批量 postprocess；
• 批量 QC；
• 批量生成 manifest；
• 批量生成 qc_summary；
• 批量生成 contact sheet。 让 Python 一次性处理多个资产，而不是由 Agent 对每个资产逐个调用脚本。

9. 增加性能日志

后续应增加 pipeline_metrics.json 或 asset_generation_timeline.json，记录每个阶段和每个资产的耗时、状态、重试次数和输出路径。 建议记录字段包括：

• 阶段开始时间；
• 阶段结束时间；
• 每个资产生成耗时；
• 是否发生重试；
• 重试原因；
• raw 输出路径；
• postprocess 耗时；
• QC 耗时；
• 最终状态。 这样后续可以更准确地区分瓶颈来自生图等待、Agent 调度、文件检查、脚本执行还是重试。