Impeccable Asset Producer：以 Comp 为参考的可复用栅格资源生产线

导读

本文讲解 Impeccable 设计系统工作流中的 Asset Producer（资源生产 Agent）：一个专门把“已批准的视觉稿（approved comp）”转化为干净、可复用、供 HTML/CSS/SVG/canvas/组件代码合成使用的栅格素材（plate）的角色。文章以 .qoder/skills/impeccable/reference/degraded/asset-producer.md 为骨架，结合仓库中 comp-spec、generate-image、embed-prompt、build-phase 的实际实现，完整还原从测量规格（spec.json）到逐区域出片、再到质量门禁验收的全流程。读完你将掌握：如何判定透明/不透明 cutout、如何生成并落盘 plate、如何自查 alpha 通道与边缘、以及如何按固定格式上报并配合 build-phase advance 通过 plates 门禁。

---

1. 角色定位：Comp 是参考，不是发货像素

Asset Producer 在 Impeccable 的 craft 流程中负责生产清理（production cleanup），而不是新的美术方向。它只基于父级（parent agent）给出的已批准 mock、指派区域、联系表和约束工作，不自行发挥。

它的核心输出是一个plate：

A plate is the region regenerated at asset resolution from the comp crop as reference: same subject, same composition, same palette, same lighting and material, with the UI text and page chrome removed, at 1.5x the comp region's pixel size or more.

也就是说，plate 是“以 comp 裁剪图为参考、按资源分辨率重新生成”的区域素材：主题、构图、调色板、光照、材质与原稿一致，但移除了 UI 文字与页面装饰，且像素尺寸至少是 comp 对应区域的 1.5 倍。页面里的文字、控件、圆角、阴影与布局全部由代码绘制，plate 只承担“代码画不出来的部分”。

文档中有一句精辟的警告：

Crops from the comp are references, never shipping pixels: a comp is reference grade and a shipped crop is how a beautiful comp becomes a blurry site.

（来自 comp 的裁剪图只是参考，绝不是发货像素：comp 是参考级，而把裁剪图直接发货，是美丽的 comp 变成模糊网站的途径。）

这一角色定义对应仓库中的 agent 源文件 skill/agents/impeccable-asset-producer.md，后者声明了该角色的工具集（Read、Write、Edit、Bash、Glob、Grep）、模型继承与 24 轮最大执行轮数。.qoder、.cursor、.claude、plugin、cursor-plugin 等目录下的同名文档均由它构建时生成，并额外带有一段“无子 Agent 能力时内联执行”的头部说明：先输出完整输出契约，再以自己同时扮演父级与子级的方式执行，并在报告中用一行披露替换关系。

2. 核心规则：不重新设计

文档的 Core Rule 是所有产出的底线：

• 除非父级明确要求更改，否则保留参考稿的视觉角色、轮廓（silhouette）、调色板、光照、材质、纹理、相机角度与构图；
• 仅当透视属于物体或场景本身时才保留；当卡片变换、阴影、圆角裁剪、边框或布局应由 CSS 创建时，必须从栅格中移除这类呈现性装饰（presentation chrome）。

这意味着 Asset Producer 的输出必须是“原料”：背景干净、无 UI 叠加、无边框阴影，把呈现层职责让渡给代码。补充禁令还包括：不添加对象、不换风格、不重新诠释；不改页面代码、不改 spec、不改 comp；不生产 spec 未列出的任何内容——父级遗漏的区域应作为一行备注返回，而不是擅自产片。

3. 决策卡（Decision Comps）模式：一次并行出片

当父级递来的是决策卡包（decision card packet）而非已批准的 mock 时，任务变成“一张卡 = 一个 comp = 一个文件”，立刻写到卡片声明的 comp 路径上。父级会按卡片并行运行多个 producer，因此这张卡就是你的全部契约：先产出，不规划，磁盘上的文件就是交付物，决策页在等它。

决策卡模式的关键约束：

• 只依据卡片的结构化字段与 PRODUCT.md 工作；卡片信息薄到无法支撑 comp 时，如实报告，绝不用想象力填充；
• 以卡片方向渲染全保真度的北极星 comp：请求表面的首屏、以表面自身结构为提示词引导（按顺序命名区域及其比例关系，而不是描述“世界的氛围”）、完全承诺卡片的调色板、字体气质与材质世界；
• 原生 App 或移动优先的表面是竖屏画幅（portrait frame），按其设备视口呈现，绝不默认横屏；
• 兄弟卡片以同样全保真、各自语法渲染，一张表面、一个画幅，同等承诺保证对比诚实；
• 只使用真实产品名与真实内容，绝不虚构 PRODUCT.md 未携带的商业声明、价格、基准或日期；
• 排除条款约束的是“声明”本身，而不是卡片世界未排除的媒介——活在照片里的主体就保留它的照片；
• 提示词侧车（prompt sidecar）写在文件旁边；返回一行，说明路径与任何偏差即可。

“本节以下内容都属于资源生产任务，决策卡运行一概不适用”——即决策卡是另一条并行的快速通道，与常规 asset-production 流程解耦。

4. 输入契约：spec.json 是唯一清单

常规生产流程的输入包括：

• 测量规格：.impeccable/build/spec.json，由 impeccable comp-spec 依据已批准的 comp 生成；
• 已批准的 comp 路径；
• skill 脚本路径；
• 可选：要生产的区域 id 子集、每区域附加提示词、格式或透明度需求。

spec 中已包含每个栅格区域需要的全部信息：id、kind（plate、image、texture 三种栅格类别）、像素盒（pixel box）、采样调色板、宽高比（aspect）、备注（note）以及它必须落盘的 plate 路径。

如果不存在 spec，就停下来，返回一行请父级先运行 impeccable comp-spec。理由在文档中被说得非常明确：

You do not inventory the comp yourself; the spec is the inventory, and a second inventory disagrees with the first.

（你不自己清点 comp；spec 才是清单，第二份清单只会与第一份互相矛盾。）

从源码看，spec 由 crates/comp-verbs/src/comp_spec.rs 的 measure_regions 生成，固定写到 SPEC_PATH = ".impeccable/build/spec.json"，同时产出：

• 顶层字段：tool（comp-spec）、version、createdAt、comp（comp 路径）、warnings、uncoveredInkCells、compSize、aspect、orientation（landscape/portrait）、全稿调色板 palette、横向条带 bands、regions 数组；
• 每个 region 含：id、kind、note、grid、box（归一化坐标）、px（像素盒）、aspect、区域采样 palette、detail.energy（细节能量）、medium（raster 或 semantic）、可选的 clipped 与 coverBox，以及栅格区域的 plate 路径（未指定时默认为 assets/plates/<id>.png，见 PLATES_DIR）。

region 的 kind 支持六种：plate（插图、图表、图形）、image（照片）、texture（材质地面），以及由代码绘制的 text、control、chrome。栅格区域强制要求 note 至少 8 个字符，且如果备注描述了绘制/照片/纹理类材质而 kind 却不是栅格类，comp-spec 会直接报错——“任何绘制、拍摄或纹理化的内容都以栅格 plate 交付” 是一条硬校验。同时，code 区域面积超过 comp 的 25%（MAX_CODE_REGION_AREA）或存在未被区域覆盖的墨迹格子（uncoveredInkCells > 3）都会拒绝生成 spec。

5. 四步生产流程（The Job）

对 spec 中每一个 medium: raster 的区域，按 spec 顺序执行以下四步：

第 1 步：导出参考裁剪图

# 在 skill 脚本目录下（或以 npx impeccable 方式调用）
impeccable comp-spec --crop <id>

该命令把区域裁剪图写入 .impeccable/build/crops/ 下，作为参考。裁剪默认通过 plate_reference 处理：它会将与本区域重叠的其他语义区域（text/control/chrome）用区域地面色覆盖，确保传给图像模型的参考图里不含 UI 文字和控件。裁剪图带有 impeccable:crop-of 的 PNG 文本元数据（记录来源 comp 与区域 id），输出时明确提示 "Reference only: regenerate the plate from it, never ship it."（仅作参考：从中重新生成 plate，绝不发货）。裁剪还支持 --out 自定义输出路径、--scale n 放大倍数以及 --raw 跳过语义覆盖。

第 2 步：判定背景并生成提示词

先看已批准区域的材质，二选一：

• 透明 cutout：页面地面上的孤立图形、物体或线稿 → --background transparent；
• 不透明：照片、整幅插图或纹理 → --background opaque。

# 透明 cutout
impeccable comp-spec --plate-prompt <id> --background transparent > prompt.txt
# 不透明
impeccable comp-spec --plate-prompt <id> --background opaque > prompt.txt

把输出保存为 UTF-8 提示词文件。透明提示词会特别保留：参考稿的放置位置与清晰边距、白色油漆（不透明）、细边缘、内部孔洞（interior holes），并移除界面边框、卡片圆角与布局背景。

从源码看，--plate-prompt 只接受 transparent | opaque | auto 三种取值（crates/comp-verbs/src/comp_spec.rs）。提示词由 plate_prompt_background 组装（同文件 L648 起），结构为：

• 开头：“以提供的裁剪图为已批准视觉参考，在目标宽高比下重建为干净的生产素材”；
• 按 kind 区分：texture 强调“无缝可平铺材质板、无物体无文字无暗角”；image 强调“同一主体、同一取景、同一光照”；其余默认按“设计插图板”处理，强调“同一画法、同一风格、同一线宽与阴影”；
• “精确保留轮廓、构图、透视、调色板（含全稿前三主色）、光照、材质与纹理”；
• “移除一切不属于画作本身的 UI 文字、标签、标题、按钮与界面装饰”；
• 透明模式额外强调“移除界面边框、卡片圆角与布局背景，只保留属于被引用物体自身的阴影；不添加对象、不换概念、不换风格；保留参考稿的放置、比例与清晰边距，不放大主体填满画面；页面地面与内部空隙转为真实透明 alpha；白色油漆与其他实色前景保持不透明；保留细边缘；仅对参考中真正半透明的材质或软阴影保留部分 alpha；无色键背景、无烘焙棋盘格、无 matte；输出透明 PNG cutout”；
• 最后附上区域 note 作为 Region: ... 结尾。

第 3 步：产出 plate

先创建输出目录，选择与区域宽高比匹配、且至少 1.5 倍于其像素尺寸的受支持输出尺寸，然后按以下优先级生产：

首选：harness 原生图像工具。 以裁剪图为输入、保存的提示词为文本；cutout 请求透明 PNG。生成后运行：

impeccable embed-prompt <plate> --prompt-file <prompt.txt>

如果对提示词做过细化，务必把实际发送的原文保存下来再嵌入，保证可溯源。

API 兜底：generate-image。 命令格式为：

# 透明 cutout
impeccable generate-image --ref <crop.png> --prompt-file <prompt.txt> --out <plate.png> \
  --size <WxH> --quality high --background transparent
# 不透明
impeccable generate-image --ref <crop.png> --prompt-file <prompt.txt> --out <plate.png> \
  --size <WxH> --quality high --background opaque

参数语义与默认值（来自 crates/context/src/generate_image.rs）：

参数	默认值	说明
--ref	无	参考图（裁剪图），可多次传入；决定走 /images/edits 的 multipart 编辑接口
--prompt-file	无	提示词文件（UTF-8），与 --prompt 二选一，文件优先
--out	无	输出 PNG 路径；--background 要求 .png 后缀
--size	1536x1024	输出尺寸 WxH，需匹配区域宽高比
--quality	medium	质量档位，生产建议 high
--background	不传则不约束	transparent / opaque / auto；传了会同时带上 output_format: png
--model	gpt-image-2.5-flare	覆盖默认模型（如 gpt-image-2、gpt-image-2.5-sunburst）

关键点：API 兜底会自行嵌入提示词并记录背景到侧车文件（<out>.json，含 prompt、createdAt、tool、model、background、outputFormat、refs）；输出必须是 PNG；兜底请求原生 alpha，不做任何色键抠图（chroma-keying）。

两个运行前提值得注意：

1. 需要环境变量 OPENAI_API_KEY，否则会报 “use the harness-native image tool instead” 并退出；
2. 设置了 IMPECCABLE_IMAGE_GEN_FAKE 环境变量时进入离线合成模式：不调用任何 API，直接按提示词哈希生成带 SYNTHETIC COMP 水印的 SVG/PNG 占位图（透明模式输出真实 RGBA alpha，见 generate_image.rs 的 png_fake_background），stdout 打印 $0.00, no API call，适合离线联调流水线。

第 4 步：对照验证与重试策略

把 plate 与裁剪图并排打开，对照主体、放置、比例、调色板、风格。对 cutout 还必须：

• 验证真实 alpha 通道存在；
• 在亮底与暗底上分别合成检查：白色油漆必须保持实色、内部孔洞必须通透、细边缘不能出现光晕（halo）；
• 仔细检查玻璃与软阴影：仅有部分 alpha 并不代表可信的半透明；
• 绝不对原生透明输出做色键处理，也不在保存前压平（flatten）；
• 若原生工具返回了不透明像素或“画出来的棋盘格”，在可用时改用 API 兜底重试，否则如实上报透明度阻塞；
• 视觉不达标时收紧提示词并只重生成一次；同一区域两次不达标：保留较优的一张，标记 needs_parent_review 并点名偏差（drift）。

父级会在所有素材齐备后运行 plates 门禁；在拿到门禁评分之前，上报状态为 unscored。

6. 输出契约：一行一个区域

完成全部区域后，按固定格式返回，不多不少：

<id> <plate path> <WxH> <score%|unscored> <accepted|needs_parent_review|blocked> <one-line note or ->

随后是全局且极简的 blockers（如缺 spec、缺 comp、无图像能力、key 耗尽）与 assumptions。除此之外不输出任何内容：没有总结、没有赞美、没有实现建议。

最后一道防线交给父级：

The parent runs impeccable build-phase advance to verify the plates against the same spec; a visual acceptance does not override a failing gate.

（父级运行 impeccable build-phase advance 按同一份 spec 校验 plates；视觉上的认可不能覆盖失败的门禁。）

7. 质量闭环：plates 门禁如何打分

build-phase 把 comp 主导的构建实现为磁盘上的状态机，阶段顺序为 comps → spec → plates → hero → sections → motion → responsive → review（见 crates/comp-verbs/src/build_phase.rs）。其中 plates 阶段的门禁（gate_plates）会逐区域执行：

• 存在性：plate 路径下文件必须存在，缺失即报 “plate missing for {id}: expected ...; produce it from comp-spec --crop {id} with generate-image --ref <crop.png> --prompt-file <prompt.txt> --out <plate.png>”；
• 可解码性：必须是可解码的 PNG；
• 分辨率：plate 宽度必须 ≥ 区域像素宽 × 1.5，否则报 “a shipping plate needs at least Npx. Regenerate at asset size, do not crop the comp.”；
• 相似度评分：用 comp_diff 把 plate 与区域参考对齐后比较，产出 structure / color / detail / overall 四项分数（Score 结构见 comp_diff.rs 的 compare），门禁阈值 PLATE_MIN = 0.4、结构分下限 PLATE_STRUCTURE_MIN = 0.4；
• 透明板合成：透明 plate 会先合成到区域采样的地面色上再参与评分（测试 plate_gate_scores_sparse_and_partial_alpha_on_the_sampled_ground 专门验证部分 alpha 素材的行为）；
• 拒绝 comp 裁剪当 plate：若 plate 与原始区域的结构分接近“同一像素的重采样”，会直接判定为 “a crop of the comp is never a plate”，要求用裁剪图做参考重新生成；
• 门禁通过后输出 N/M plates 汇总，并写入 .impeccable/build/state.json 中每个 plate 的 status、score。

也就是说，Asset Producer 的“视觉验收”只解决主观质量问题，客观的 1.5x 分辨率、结构/色彩/细节阈值与“非裁剪图”校验由同一份 spec 上的门禁强制执行——这与文档输出契约中的 unscored 机制完全对应。

8. 提示词溯源：embed-prompt 到底写了什么

embed-prompt 把生成提示词写进图片元数据，实现“任何一张 plate 都能反查它当年用什么提示词、以什么参考生成的”。源码（crates/context/src/embed_prompt.rs）显示：

• PNG 走 tEXt（明文）或 zTXt（zlib 压缩）文本块，关键字为 impeccable:prompt（KEYWORD 常量）；
• JPEG 走 COM 标记段，同样以 impeccable:prompt\0 为前缀；
• 解析器逐块遍历 PNG chunk，正确区分字节范围并提取首个嵌入提示词。

这也是为什么文档要求“如果你细化了提示词，保存并嵌入实际发送的原文”——嵌入的文本必须与真实发送的一致，溯源才成立。API 兜底生成时若嵌入失败会打印 failed to embed prompt in the image，并保证侧车 JSON 仍然写出。

9. 运行前提与环境

• 所有 impeccable <verb> 命令由 skill 脚本目录下的启动器解析，即 .qoder/skills/impeccable/scripts/impeccable（Windows 上为 impeccable.cmd），也可经 npx impeccable 调用；启动器运行自包含二进制，无需 Node 或其他运行时，按平台分发（cli/platform-packages 下提供 darwin-arm64/x64、linux-arm64/x64、windows-x64 各平台包）；
• 生产图像需要 harness 原生图像工具或 OPENAI_API_KEY；离线联调可设 IMPECCABLE_IMAGE_GEN_FAKE 走合成占位；
• 工程产物统一落在 .impeccable/build/（spec、crops、grid、state、review 等）与 assets/plates/（默认 plate 落盘目录）。

10. 小结：从 Comp 到可合成素材的最小纪律

Asset Producer 的全部工作可以压缩成三条纪律：

1. 不重新设计——参考稿的视觉角色、轮廓、调色板、光照与构图是硬约束；呈现性装饰交给代码；
2. spec 即契约——不自行清点、不越权生产，一切以 .impeccable/build/spec.json 的 region 清单为准；
3. 交付即报告、验收靠门禁——一行式输出契约配合 build-phase advance 的 plates 门禁（1.5x 分辨率、结构/色彩/细节 ≥ 40%、拒绝 comp 裁剪图），让“视觉好不好”与“规格过不过”分成两层，互不覆盖。

理解这条流水线，就等于理解了 Impeccable 如何保证“comp 有多美、上线的页面就有多美”——因为每一块代码画不出的像素，都是从一个被审慎测量、严格重建、可溯源提示词、并经门禁打分的 plate 开始的。