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 资产交付的要求。**
![图片](../feishu-images/EpZZw1rT9iBZDFkrwo2cgImpngb_XfyRbGpgbooP.png)
但对于复杂插画类资产，边缘质量仍然不够稳定。例如牛角色、公告图标、好友对战装饰图、皮肤图标等，这类素材通常包含：
  - 毛发或复杂外轮廓；
  - 柔和阴影；
  - 半透明高光；
  - 小粒子、小装饰；
  - 较复杂的体积光和颜色过渡。
![图片](../feishu-images/EpZZw1rT9iBZDFkrwo2cgImpngb_OaHwb2PGQoBM.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 等。后续可以将这部分公共规则模板化，只让每个资产填充差异描述。

> :bulb:
基于本轮测试，当前判断是：
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 调度、文件检查、脚本执行还是重试。