Impeccable Asset Producer 实操指南：从批准稿到可投产光栅资产的生产管线

Impeccable Asset Producer 实操指南：从批准稿到可投产光栅资产的生产管线

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

导读

Impeccable 的Asset Producer（资产生产者）是一个以「生产清理（production cleanup）」为唯一职责的 Agent 角色：它不负责新的艺术方向，只负责把已经获批的 comp（高保真设计稿）转换为可供 HTML、CSS、SVG、canvas 与组件代码组合的干净光栅资产。本文以仓库中的 .cursor/agents/impeccable-asset-producer.md 为骨架，结合comp-spec、generate-image、embed-prompt、build-phase四个命令的 Rust 实现与文档，完整讲解资产生产者的输入契约、四步生产工作流、评分与再生成规则、透明抠图规范以及输出契约。读完你将掌握：如何基于 spec.json 按清单生产 plate（可投产光栅）、如何用 API 与 harness 原生图像工具两条路径落地、如何依据PLATE-SCORE/PLATE-WARN判定漂移并收紧提示词，以及如何用build-phase advance对产物做机器验收。

一、角色定位与核心规则：这是清理工作，不是艺术工作

Asset Producer 在 Impeccable craft 管线中的定位一句话可以概括：它是生产清理（production cleanup），不是新的艺术方向（new art direction）。它只能基于父级（parent agent）提供的三样东西工作——已获批的 mock（批准稿）、分配好的 crops（裁剪参考）、contact sheets（联系页）与约束条件。它产出的每一张 raster（光栅图）都是「生料（raw ingredient）」，最终由 HTML、CSS、SVG、canvas 与组件代码负责组合呈现。

该角色模板同时存在于多个发行渠道，内容同源（只是脚本路径变量不同）：.cursor/agents/impeccable-asset-producer.md（Cursor）、plugin/agents/impeccable-asset-producer.md（Claude 插件）、skill/agents/impeccable-asset-producer.md（skill 根目录），以及供无子代理能力的 harness 内联执行的降级版 .cursor/skills/impeccable/reference/degraded/asset-producer.md。

1.1 Core Rule：不重新设计（Do not redesign）

核心规则只有一条，但覆盖范围极广。除非父级明确要求改动，否则必须保留参考稿的：

• 视觉角色（visual role）
• 轮廓（silhouette）
• 调色板（palette）
• 光照与材质（lighting, material）
• 纹理（texture）
• 相机角度与构图（camera angle, composition）

对透视（perspective）有更精细的规定：只保留属于物体或场景自身的透视；当卡片变换、阴影、圆角裁剪、边框、布局这些「presentation chrome（呈现装饰）」应当由 CSS 完成时，必须把它们从 raster 中移除。换句话说：raster 只携带代码画不出来的东西，代码能画的东西一律不留在像素里。

1.2 Decision Comps：决策稿模式的特殊分支

模板明确划分了两种工作模式。当父级给的不是「已批准 mock」而是一包「decision card（决策卡）」时，任务变成：一张卡 = 一个 comp = 一个文件，渲染完成即写入卡上声明的comp路径。父级会为每张卡并行启动多个 Asset Producer，所以这张卡就是你的全部契约：

• 先生成，别计划（generate first, plan never）——磁盘上的文件就是交付物，决策页正等着它；
• 只依据卡的结构化字段与PRODUCT.md工作；卡的内容不足以支撑一个 comp 时，如实上报，绝不靠想象填充；
• 以全保真度渲染卡的 direction 作为「北极星 comp」：首个视口（first viewport），提示词由表面自身的结构引导（按顺序命名区域并给出比例关系，而不是描述「世界的氛围」），完整落在卡自己的调色板、字体性格与材质世界里；
• 原生 App 或移动优先的表面必须是竖版画幅（portrait frame at its device viewport），绝不默认横版；
• 所有并行兄弟卡在同一全保真度、各自语法下渲染——一个表面、一个画幅；同等投入才让比较公平；
• 只使用真实产品名与真实内容，绝不编造PRODUCT.md未承载的商业主张、价格、基准数据或日期；排除条款约束的是「主张」，而不是卡的世界未排除的媒介（例如以照片为生的主体就保留照片）；
• 在文件旁写 prompt sidecar；回报时只回一行：路径 + 任何偏差，别无其他。

文档明确指出：本节以下内容才是资产生产任务，决策稿模式不适用其后任何规则。

二、输入契约：spec 是唯一的清单

正式生产模式（非决策稿）下，Asset Producer 预期拿到三样输入：

1. 测量后的 spec：.impeccable/build/spec.json，由impeccable comp-spec依据批准稿生成；
2. 已批准 comp 的路径；
3. skill 脚本路径（如.cursor/skills/impeccable/scripts/impeccable）。

可选输入包括：要生产的 region id 子集、每个 region 的额外提示词备注、格式或透明需求。其余一切所需信息都在 spec 里：每个 raster region 的id、kind（plate/image/texture）、像素框（pixel box）、采样调色板、aspect（宽高比）、note（说明文字），以及它必须落盘的plate路径。

关键纪律：如果不存在 spec，立即停止，回一行让父级先运行impeccable comp-spec。Asset Producer 绝不自己盘点 comp——spec 就是清单，而「第二份清单与第一份不一致」。

2.1 spec.json 从哪来：comp-spec 的测量管线

comp-spec是这条管线的上游，其 Rust 实现位于 crates/comp-verbs/src/comp_spec.rs（命令路由见 crates/cli/src/main.rs#L70）。它的典型用法分两步：

impeccable comp-spec --comp <comp.png> --grid # 生成标注 10x10 网格 impeccable comp-spec --comp <comp.png> --regions <file.json> # 测量区域，写入 spec.json

• --grid把 comp 缩放到宽度不超过 1536px，叠加 A0 到 J9 的 10 列网格，写出.impeccable/build/comp-grid.png，并打印PALETTE与BANDS行（见 comp_spec.rs 中render_grid与run的--grid分支）。
• regions 文件形如：

{ "regions": [ { "id": "exploded-plate", "kind": "plate", "grid": "E0:H4", "note": "exploded carburetor drawing" }, { "id": "masthead", "kind": "chrome", "grid": "A0:J0", "note": "navy bar" }, { "id": "hero-image", "kind": "image", "grid": "E0:J4", "note": "studio product photo" }, { "id": "paper", "kind": "texture", "grid": "A0:J9", "note": "seeded paper grain" } ] }

kind只有两类语义：plate/image/texture表示「画出来的材质」（插图、照片、产品对象、纹理，一律以 raster plate 形式交付）；text/control/chrome表示「代码绘制」。每个 region 必须带note（源码校验要求非空白且不少于 8 个字符），因为 note 驱动 plate 提示词与门禁（gate）的判读信息；measure_regions甚至会在代码类 region 的 note 描述出「painted material」（如 diagram、photo、texture）时直接报错，要求改为 plate 类或改写 note（见 comp_spec.rs 中PAINTED_NOTE正则与校验逻辑）。

• --regions对每个 region 测量归一化/像素 box、采样调色板（dominant_colors，5 主色 3 次迭代）、detail energy（4x4 网格高频能量）、aspect，以及 raster 类 region 的默认 plate 路径assets/plates/<id>.png（常量PLATES_DIR）。它还做几项硬校验：代码类 region 面积超过 comp 的 25% 会拒绝（那是「一列元素」而不是「一个元素」）；grid 上留有未被任何 region 命名的墨迹会拒绝（uncoveredInkCells，除非显式allowUncovered: true）；raster 类 region 的墨迹触到盒子边缘（接触率 ≥EDGE_CONTACT_MIN= 0.35）会警告，因为object-fit: cover会裁掉那一侧（bleed: true可覆盖）。
• 之后impeccable comp-spec --print输出紧凑 spec（每行一个REGION，含 box 百分比、像素尺寸、aspect、palette、plate 路径与 note），这就是整个构建阶段对码的参考文本。

三、四步生产工作流：从 crop 到 plate

spec 中每个medium: raster的 region 都必须以 plate 的形式交付到它的plate路径。plate 的定义是：以 comp 裁剪为参考、在资产分辨率下重新生成的 region——相同主体、相同构图、相同调色板、相同光照与材质，但移除所有 UI 文本与页面 chrome，尺寸不小于 comp region 像素尺寸的1.5 倍。页面负责绘制文本、控件、圆角、阴影与布局；plate 只携带代码画不出来的东西。

铁律：crop 只是参考，绝不是交付像素。comp 是参考级（reference grade）画质，直接裁剪交付的结果，就是「一张漂亮的 comp 变成一个模糊的网站」。

按 spec 中 region 的顺序，每个 region 执行四步：

3.1 第一步：生成参考裁剪

.cursor/skills/impeccable/scripts/impeccable comp-spec --crop <id>

该命令默认把参考裁剪写到.impeccable/build/crops/<id>.png。源码中--crop分支的行为（comp_spec.rs 的run）：对 raster 类 region 调用plate_reference——先按 region 的像素框裁剪 comp，再用 region 采样调色板的主色覆盖掉框内其他非 raster 区域的 UI 内容，得到「去掉周围界面后的纯主体参考」；对非 raster 或加--raw则直接按框裁剪。裁剪文件会写入impeccable:crop-of文本块记录来源，输出行明确标注「Reference only: regenerate the plate from it, never ship it.」（仅参考：从中再生成 plate，绝不直接交付）。--scale <n>可放大裁剪参考。

3.2 第二步：生产 plate（两条路径）

路径 A —— API 一键完成（推荐，端到端）：

.cursor/skills/impeccable/scripts/impeccable generate-image --plate <id> --quality high

generate-image --plate一步完成整件事：crop 作为参考、取 spec 的 plate 提示词、按 region 的 aspect 选择输出尺寸、把文件写入其 plate 路径、嵌入 prompt，并对 crop 打分。它等价于「裁剪 + 编辑端点参考图 + 提示词 + 尺寸选择 + 写入 + 嵌入 + 评分」的完整流水线，build-phase的 plates 门禁描述明确写着「nothing else does all of that」（没有别的工具能同时做到这些，见 build_phase.rs 中 plates 阶段的 NEXT 指令）。

路径 B —— harness 原生图像工具（作为 API 不可用时的回退）：把 crop 作为输入图像、把 plate 提示词作为 prompt：

.cursor/skills/impeccable/scripts/impeccable comp-spec --plate-prompt <id>

拿到提示词后生成结果写入 plate 路径，再补上 provenance 嵌入：

.cursor/skills/impeccable/scripts/impeccable embed-prompt <plate> --prompt "<the exact prompt>"

generate-image 的底层实现

generate-image的引擎移植位于 crates/context/src/generate_image.rs（命令路由 crates/cli/src/main.rs#L67），核心参数包括：

• 有--ref时走 OpenAI/v1/images/edits的 multipart 表单（model=gpt-image-2，按扩展名推断 PNG/JPEG/WEBP MIME）；无--ref时走/v1/images/generationsJSON。鉴权依赖环境变量OPENAI_API_KEY，未设置时明确报错并建议改用 harness 原生图像工具。
• 成功后写文件、嵌入 prompt（调embed_prompt::run）、并写<out>.jsonsidecar（含prompt、createdAt、tool、model、refs），输出IMAGE: ...行。
• 离线管道可设IMPECCABLE_IMAGE_GEN_FAKE=1：不调用 API，直接生成合成 SVG/PNG（$0.00, no API call），配合文档所述「crop 2x」行为让没有网络的流水线也能走通 plate 门禁。

plate 提示词的构成

--plate-prompt <id>的实现是plate_prompt函数（comp_spec.rs）。它按 kind 生成三类指令，并拼接统一的保真要求：

• texture："seamless surface texture ... tileable texture plate with no objects, no text, no vignette"（无缝表面纹理，可平铺，无对象无文字无暗角）；
• image："photographic or illustrated image region. Output the same subject, same framing, same lighting."（照片/插画区域：相同主体、取景、光照）；
• 其余（设计插画 plate）："same drawing, same style, same line weight and shading."（相同画法、风格、线宽与明暗）。

公共部分要求：以 crop 为批准视觉参考按目标 aspect 重建干净生产资产；精确保留轮廓、构图、透视、调色板、光照、材质与纹理；移除不属于艺术品本身的每一处 UI 文本、标签、说明、按钮与界面 chrome；移除信黑边（letterboxing）、边框、卡片圆角、投影以及任何页面将用代码绘制的布局背景；不添加对象、不改变概念、不重样式；艺术品铺满整帧、与参考同比例，无留白、无边框、无背景带。最后附加 region 的 note。

3.3 第三步：读评分，判定漂移，必要时再生成一次

生成完成后必须读取评分行。判定规则（模板原文）：

• PLATE-SCORE低于50%，或出现PLATE-WARN：说明 plate 没有读成这个 region。做法是把 plate 与 crop 并排打开，明确指出漂移了什么（主体 subject、取景 framing、调色板 palette、风格 style），据此收紧提示词，再生成一次；
• 同一个 region 连续两次未达标：保留较好的一张，标记needs_parent_review，用一行说明原因。

评分维度可以在验收侧源码中找到对应物：build-phase的gate_plates把 plate 与plate_reference生成的参考对齐（cover对齐）后调用comp-diff的compare打分，plate_verdict会逐条给出败因——结构分（structure，主体/朝向/裁剪是否一致）低于PLATE_STRUCTURE_MIN(0.4)、总体分低于PLATE_MIN(0.4)、comp 平静区却被加进了超过 45% 的新细节（detail_added）都会触发拒绝（build_phase.rs）。另外，若 plate 与 comp 原始 region 的结构相似度 ≥ 0.95，会判定为「comp crop 的缩放重采样」而直接拒绝——crop 的副本永远不是 plate。

3.4 第四步：透明抠图（transparent cutouts）

当画面里是「页面底地上的一个图形或物体」（figure/object on the page ground，例如一张插画或产品对象浮在页面背景上）时：

• 在一个主体上不存在的平坦 chroma 颜色上生成；
• 写入 PNG 之前把该色键控（key）为 alpha 透明；
• 绝不交付键控后的背景（never ship the keyed background）。

这样 plate 就能以普通<img>直接放在页面自己的底色上，而不是「第二张纸」。仓库文档还补充了配套细节：generate-image --plate会自动把「平地上的墨迹」键控为 alpha（PLATE-CHROMA）；不透明且底色与页面不同的 plate 用mix-blend-mode: multiply合成；纹理（纸、布、颗粒）默认不先生成——先从 comp 区域裁剪一块干净的 patch（comp-spec --crop <id> --raw后切出无墨区域），镜像平铺到 plate 尺寸存为 plate，仅当没有干净 patch 时才生成（build_phase.rs plates 阶段指令）。

四、输出契约与机器验收

每个 raster region 回报一行，格式严格固定：

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

随后跟blockers（缺失 spec、缺失 comp、无图像能力、key 耗尽）与assumptions，二者都要「全局且最小」。除此之外什么都不输出：不写总结、不写赞美、不给实现建议。

父级随后运行：

impeccable build-phase advance

用同一份 spec 验证 plates——你回报的那一行与门禁的那一行必须一致。build-phase的 plates 门禁（build_phase.rs 的gate_plates）逐项检查：

1. 每个 raster region 的 plate 文件存在（缺则missing）；
2. 是可解码的 PNG（否则unreadable）；
3. 非纹理 plate 宽度 ≥min(1536, px_w * 1.5)（即至少 1.5x comp region 像素宽度，且上限 1536px）；
4. 与参考 crop 对比评分（纹理按0.5*color + 0.5*min(1, detail/0.6)的 effective 分）；
5. 拒绝「comp crop 的重采样副本」。

只有全部通过，build-phase才推进到 hero 阶段。整个管线是磁盘上的状态机，阶段序列为comps → spec → plates → hero → sections → motion → responsive → review（见 build_phase.rs 的PHASES常量与 docs/COMP-FIDELITY.md 第 3 节）。

五、Provenance：让生成意图活在文件里

无论用哪条路径生成图像，生成上下文都是资产的一部分（skill/reference/visualize.md 的 Plates and provenance 一节）。规则是：用任何工具生成图像后，立即用embed-prompt把「工具实际收到的确切提示词」嵌入文件；generate-image会自动完成这一步。嵌入的 prompt 加上 spec 中该 region 的行，共同构成 raster 的provenance（出处证明）——artifact 引用的每一张 raster 都必须携带它；来源图库或既有素材则嵌入其来源说明。

embed-prompt的引擎移植位于 crates/context/src/embed_prompt.rs（路由 crates/cli/src/main.rs#L63），三种格式各有落点：

配套的两个子命令是完整闭环：impeccable embed-prompt <image> --read读出已嵌入的提示词；impeccable embed-prompt --scan <dir>递归扫描目录（自动跳过node_modules与点开头目录），列出所有缺少嵌入提示词的 raster（MISSING:行），退出码 3 表示存在缺失。这条闭环保证：任何时刻都能从文件本身恢复「当初为什么生成这张图」，修复批次或评审重建的新 raster 也必须走同一流程。

六、纪律边界与常见反模式

模板以显式禁令收尾，这些边界与源码中的校验一一对应：

• 不重新设计：不添加对象、不重样式、不重新诠释——comp 获批即定稿；
• 不动页面代码、spec 或 comp：三者都是只读契约；
• 不生产 spec 未列出的东西：父级遗漏的 region 以一行 note 回报，而不是擅自产出一张 plate（gate_plates的missing判定会与你的回报对账）；
• crop 永不作为交付物：plates 门禁会以 ≥0.95 结构相似度识别「重采样的 comp 裁剪」并拒绝；
• 不要用magick等外部工具对 plate 做后处理或自己写键控逻辑：generate-image --plate或「harness 工具 + embed-prompt」是唯二被认可的路径（这是仓库从真实失败中沉淀的教训，docs/COMP-FIDELITY.md 第 4 节记录了「一次会话用 magick 键控 25 轮」的反面案例）；
• 页面代码必须等 plates 门禁通过之后才写：在 plate 存在之前写页面，等于用 CSS 去画本应由资产承载的材质。

这套「spec 为清单、crop 为参考、plate 为交付物、prompt 为 provenance、gate 为验收」的闭环，正是 Asset Producer 与comp-spec/generate-image/embed-prompt/build-phase四个命令协同工作的完整形态。想深入源码可继续阅读：comp-spec 测量实现、plates 门禁与阶段机、图像生成引擎、prompt 嵌入引擎，以及总览文档 docs/COMP-FIDELITY.md。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable