Impeccable Visualize 实战指南：方向构图（Direction Comps）与资产生产（Asset Production）全流程

Impeccable Visualize 实战指南：方向构图（Direction Comps）与资产生产（Asset Production）全流程

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

导读

本文基于 Impeccable 技能参考文档 visualize.md，完整讲解 comp-led（以构图为驱动）构建流程中"方向构图与资产生产"这一核心环节：如何围绕已锁定的视觉方向生成三个高保真构图、如何通过唯一审批点获得用户批准、批准后如何将构图转化为可度量的构建规格，以及每个栅格资产（plate）如何建立可追溯的 provenance（来源证据）。读完本文，你将掌握 Impeccable 从"构图三选一"到"规格化落地"的完整实操链路，并能理解底层命令（generate-image、serve-question、build-phase、comp-spec、embed-prompt）之间的调用关系与状态约束。

一、加载前提：何时进入 Visualize，何时明确跳过

visualize.md不是一份随时可以加载的通用文档，它只在满足以下全部条件时才被加载：

1. comp-led 构建：构建路径是构图驱动（由 new-work.md 在构图主导的构建上加载）；
2. 图像生成可用：存在 harness 原生的图像工具，或 API 回退命令impeccable context报告可用的图像能力；
3. 前置文档就绪：PRODUCT.md和DESIGN.md是进入本环节的前提条件，new-work流程已经解决视觉世界（visual world），本环节不得重新打开已确定的视觉世界；
4. 无重复轮：如果一次 surface-scope 结构轮已经把三张可视化卡片摆到用户面前（即 new-work.md 的 established world 分支），那么该轮已经履行了构图职责——此时锁定卡片上的构图即为已批准的构图，只需记录批准并直接从 "After approval" 继续，不要再生成任何新内容。

code-led（代码驱动）构建则按契约跳过本环节——这是有意设计而非流程漂移，加载本文件本身就是错误。这一点在 new-work.md 第 91 行有明确表述：comp-led 构建下只要有图像生成能力就必须先可视化再构建，而 code-led 构建下构图轮被契约跳过，其承担的野心转移至方向契约的 FIRST VIEWPORT 块与命名的 signature interaction，由 finish reviewer 在行为层面审计。

此外，构图探测（probe）测试的是构图、叙事、层级、密度、焦点时刻、签名使用与图像需求，它不是第二次身份工作坊。DESIGN.md中已确定的调色板、字体方向、材质语言、组件性格、图像立场与动效语法都必须保持固定，探测不得重新讨论。

二、生成三个构图选项（Generate three compositional options）

2.1 阶段状态约束：构图必须落在 phase 状态之内

构图轮运行在构建的阶段状态（phase state）中。进入本环节前必须已经执行：

impeccable build-phase start --direction <seed key> --kind <assigned|pick|challenger|canon>

具体命令由掷骰（roll）的输出命名。其comps阶段必须在第一张构图生成前处于 open 状态。在 start 运行之前渲染的构图位于状态之外，从该点恢复的会话将没有任何后续阶段可循。

这一点有强制的执行保证：从源码看，impeccable generate-image会拒绝写入.impeccable/mocks/，直到 start 已经运行（参见 crates/context/src/generate_image.rs 中 run 入口的调用链）；harness 原生图像工具同样受此顺序约束。

从 crates/comp-verbs/src/build_phase.rs 可以看到完整的阶段状态机定义：

pub const PHASES: [&str; 8] = ["comps", "spec", "plates", "hero", "sections", "motion", "responsive", "review"];

状态文件为.impeccable/build/state.json，其中每个阶段记录status（open / pending / skipped 等）、openedAt、closedAt、attempts、notes、gate、forced字段。当以start --comp <approved comp>方式启动时（例如 surface 轮已经锁定构图），comps阶段会被标记为skipped并写入说明"构图轮发生在本状态之前（surface 轮或手工完成）"。

2.2 渲染三个高保真 north-star 构图

• 渲染三个彼此不同的、请求表面（surface）的高保真 north-star 构图，保存到.impeccable/mocks/下，这样它们能跨会话存续；
• 按表面自身的视口（viewport）构图：原生 App 或移动优先的表面用设备尺寸的竖版（portrait）；桌面端用横版（landscape）。一张手机屏幕被构图成横版，会在任何代码被构建之前就先错误陈述了构图；
• 构图是构建线程自己的工作，绝不委托：只有持有方向完整上下文、且构建开始时见过每一张构图的线程才能写出提示词；
• 用 workspace 相对路径打开每张图片：沙箱化的查看器拒绝绝对路径，而项目根目录下的所有内容都有相对路径；
• 基于真实内容：构图必须基于已与用户共同开发的真实内容与表面概念。

2.3 established world：用真实身份锚定每一张构图

当构建发生在已确立的世界（established world）中时，每一张构图都必须锚定真实身份：

1. 截取一张代表性现有页面的截图；
2. 将其作为参考图像传入（harness 图像工具的输入图像，或impeccable generate-image --ref）；
3. 提示词以新表面的结构开头，而参考图承载调色板、字体与组件性格——因为仅靠 DESIGN.md 的文字在缺少像素参考时会漂移。

参考图贡献什么、必须不贡献什么，需要明确命名：

一张被逐字照搬的 banner、hero 或卡片，是参考图的泄漏（reference leaking），不是保真。

2.4 为什么是"三"这个数字

一张构图会诱发橡皮图章式盖章（rubber-stamping）；三张之间的差异空间才能暴露值得构建的构图。三张中的第一张就是已选卡片上的决策构图（decision comp）——它已经在这个纪律下以全保真渲染了这一方向，所以只需再生成两张、在第一张所固定的变量上做变化，然后把三张一起送往审批点。

唯一例外：当一轮到达时没有决策构图（如 degraded roll、identity-mode 页面、未经过决策轮就锁定的方向），才需要在此处完整渲染三张。

2.5 构图的四条自我校验纪律

① 构图是设计好的表面，不是主题的图片。提示词以表面自身的结构开头：该设计拥有的区域，按顺序命名并说明比例关系；没有导航的页面就明说没有导航，而不是发明一个；非常规表面要陈述其非常规骨架。提示词若以氛围开头，得到的是一幅小插图（vignette）——模型画出了鱼市，而不是鱼市的网站。每次渲染后自检：如果它能当海报挂起来，或者读起来像"贴了字的照片"，它就不是构图，要用更字面的布局脚手架重新生成。

② 反方向的失败同样存在：表面里没有主题。主题以区域所承载的内容出现；世界只是装饰画框，永不取代画框所展示的内容。删除（deletion）通常搭乘在提示词的排除列表上，所以排除列表约束的是虚构声明，而媒介禁令（medium ban）属于已承诺的图像立场，不来自谨慎。接受渲染前，指向主题：一张把世界的一切都画了、却与主题无关的渲染，无论氛围多忠实都是失败，要用"按区域逐条命名主题内容"的方式重新生成。

③ 把构图当作已上线的屏幕来评判。访客的任务必须能仅凭图像读出来。不加说明文字地读出表面的模式；一张读不出模式的渲染只是没有表面的艺术指导。把"访客的任务"作为提示词的脊梁重新生成。

④ 承诺是深度，不是覆盖面。世界通过一个主导动作（dominant move）加上支撑它的材质、字体与间距进入；其余区域保持静止，让这个动作可以被读出来。一个"在世界语法中做好本职工作"的区域，比一个在表演概念的区域更能推进方向。这条检查削减的是竞争（competition），不是内容：被安静下来的区域保留其信息，只是停止表演。当第二个元素与命名的焦点时刻以相同尺度竞争，构图就在喊叫；没有命名的焦点时刻时，多个区域同时表演概念同样是喊叫。Busy 是更响，不是更大胆（Busy is louder, not bolder）。

2.6 变化策略

• 当用户把多个概念列入候选短名单（shortlist）时，把三张分布在多个概念之间；
• 当一个方向已被承诺，变化图像能够解决的结构不确定性：拓扑（topology）、序列（sequence）、密度（density）、层级（hierarchy）、焦点构图（focal composition）或交互取景（interaction framing）；
• 展示超出开场时刻的足够内容，证明概念能统治整个表面；
• 不要生成调色板制品、不要问新的氛围问题、不要引入不同的字体声音、不要发明新母题。如果已承诺的世界无法支撑该概念，回到概念短名单，而不是改变世界。

2.7 构图是方向测试，不是截图规格

每张构图都是方向测试，而不是截图规格（screenshot specification）。核心 UI 文本、响应式行为、可访问性、语义和交互状态仍然是实现责任，不会在构图轮中解决。

三、唯一审批点（One approval point）

3.1 展示方式与提问

把三张构图一起展示在决策页上：

• 决策页：impeccable serve-question，每个构图一个选项，构图作为其 hero 图；
• 或 harness 原生：仅当 harness 能内联渲染图片时；纯文本表面不算展示。

然后向用户提问三件事：

1. 哪些应该保留（carry forward）？
2. 哪些对世界而言感觉是假的（feels false to the world）？
3. 选中的概念应该批准（approve）、合并（combine）、修订（revise）还是拒绝（reject）？

提问后停下并等待。结构化的模拟用户（structured simulated user）视为已到席，并收到同样的问题。

3.2 委托与边界

在用户批准方向或明确委托选择之前，不得开始写代码。如果用户委托，使用任务简报、PRODUCT.md 与 DESIGN.md 进行选择，并陈述证据。批准提炼的是任务概念，不修改 DESIGN.md。

3.3 无替代、无跳过条件

这个审批点没有替代品，也没有跳过条件：

• 结构化提问工具报错时，回退到决策页；
• 仅当两者都失败，才能把选择视为已委托；
• 委托的选择与批准一样被记录，并且在你的第一次回复中披露（而非最后一次）。

finish reviewer 会把"构图轮产物没有记录批准"视为实质性发现（material finding）。注意区分：.impeccable/mocks/decision/下的决策构图是方向轮（direction round）的产物，不是构图轮的输出，其存在本身不构成批准。

3.4 批准后的记录：工具能找到的地方

批准之后，把选择记录在工具能找到的位置：

1. 已批准构图的路径写入 surface brief；
2. 其.json提示词 sidecar 中写入"approved": true——每张经impeccable generate-image生成的构图都有一个 sidecar；如果原生工具没有生成，手动创建它。

sidecar 随 mocks 文件夹一起移动，因此批准能跨越会话与机器存续（即使这些机器从未见过 brief）；它也是impeccable build-phase advance读取以关闭 comps 阶段的数据源。

从源码看 comps 阶段的 gate 检查（crates/comp-verbs/src/build_phase.rs 中gate_comps）会逐一验证：

• .impeccable/mocks/下至少有3 张构图（.png/.webp/.jpg/.jpeg）；
• 每张构图都有携带prompt的.jsonsidecar（缺失会报 "no prompt sidecar for: ..."）；
• 恰好一张构图带有"approved": true（零张报 "no comp is approved"，并提示用决策页或结构化提问工具把三张放到用户面前后写入；多于一张则报错，因为只允许一张）；
• gate 通过后才允许进入下一阶段，approved路径被记录进 gate 记录供后续build-phase advance使用。

随后：总结构图方案与构图中不得被字面化（must not be literalized）的部分，返回 new-work.md，从已批准概念记录方向契约，然后开始构建。

四、批准之后：构图变成规格（After approval: the comp becomes a spec）

4.1 north star，而非重新构图许可证

已批准的构图是翻译为语义化、响应式、可访问代码的北极星（north star），绝不是重新构图的许可证：保留调色板和情绪、却重绘拓扑，是第二次艺术指导。

三条硬性约束：

• 不栅格化核心 UI 文本或控件（Do not rasterize core UI text or controls）；
• 不替换视觉驱动器：批准后未经询问不得替换不同的视觉驱动器（visual driver）；
• 构图展示的内容是被测量的，不是被记住的（What the comp shows is measured, not remembered）。

4.2 spec 阶段：构图 → 区域框 + 采样调色板

按 new-work.md 第 6 节，构建以阶段方式运行（impeccable build-phase）。spec 阶段把构图转化为带采样调色板的区域框（region boxes）：

impeccable comp-spec --comp <comp> --grid # 在构图上画坐标网格 impeccable comp-spec --comp <comp> --regions <file> # 按网格跨度命名区域

从 crates/comp-verbs/src/comp_spec.rs 可以看到：网格为 10 列 × 10 行，列以A–J命名、行以0–9命名，区域跨度用<colrow>:<colrow>形式（如E0:J4）表示，输出.impeccable/build/comp-grid.png与.impeccable/build/spec.json；spec 还通过 dominant color 算法对构图做调色板采样（palette_of→ 5 个主色 × 3 次迭代）。

4.3 区域的媒介：由像素是什么决定，而不是由"什么好构建"决定

每个区域的媒介（medium）由像素本身是什么决定，绝不取决于"哪个更好构建"：

• 图（figure）、产品对象、机械、任何带透视/阴影/绘画技巧的插图、以及任何具名纹理（woven cloth、paper grain、fabric、leather、brushed metal）→ 属于plate/image/texture区域，以栅格（raster）形式交付；
• 文本、控件、chrome、含可数元素的图表、扁平形状系统、以及任何必须移动/缩放/响应的东西 →语义化。

在 comp_spec 源码中，is_raster_kind只认plate | image | texture三种；PAINTED_NOTE正则列出了判定"绘制类"内容的关键词（diagram、drawing、illustration、photo、photograph、painting、rendering、artwork、engraving、etching、texture、grain、fabric、watercolour、sketch、3d 等）。

为雕琢面板的质感写 "CSS"、为撕裂边缘写多顶点的clip-path，都是对已批准设计的安静删除（quiet deletion）；检测器的organic-clip-path规则与buried-raster规则、以及 hero gate 的区域评分（region scores）会捕获这类问题（organic_clip_regions扫描 HTML 中的 clip-path 形态并与 raster 区域匹配）。删除一个图像原生的区域是用户在审批点做出的范围决策，绝不是批准后的无声扁平化（silent flattening）。

4.4 生成图像是材料，不是声明

生成图像是材料（material），不是声明（claim）：证据规则约束的是断言、规格、证言与"以真实照片呈现"的图片，从不约束渲染保真度。即构图可以自由演示，但商业与事实性声明（价格、客户、基准、端点、产品不具备的能力）不可杜撰。

五、Plates 与 provenance（来源证据）

5.1 plates 阶段：先于任何页面代码

每个栅格区域的 plate 在 plates 阶段生产，先于任何页面代码，由随附的资产生产者（shipped asset producer）或当前线程完成：

impeccable generate-image --plate <id>

或使用 harness 图像工具，以 comp 裁剪（crop）为输入、spec 的 plate 提示词为生成提示。从 crates/comp-verbs/src/build_phase.rs 的gate_plates看，plates 阶段的 gate 会逐项检查：plate 文件存在且可解码、宽度满足资产尺寸下限（min(1536, px_w × 1.5)，纹理除外）、与 comp 区域的结构/颜色/细节对比得分达标（整体 ≥ 0.4，结构 ≥ 0.4）、以及拒绝"构图的裁剪即 plate"（若 plate 与 comp 区域裁剪的结构相似度 ≥ 0.95，判为使用同一像素的缩放，必须用裁剪作参考重新生成）。纹理区域（texture）则是 comp 区域的干净补丁镜像平铺，仅当没有干净补丁时才生成。

5.2 生成上下文是资产的一部分：embed-prompt

生成上下文（generation context）属于资产本身。无论用哪个工具生成了图像，都要运行：

.grok/skills/impeccable/scripts/impeccable embed-prompt <image> --prompt "<prompt>"

使用工具实际收到的精确字符串（impeccable generate-image自身会自动完成这一步），这样意图就存活在文件内部。

从 crates/context/src/embed_prompt.rs 的实现看，该命令支持三种载体：

• PNG：在 IEND 前写入关键字impeccable:prompt的tEXt文本块（幂等：已有则重建 body 并替换）；
• JPEG：写入impeccable:prompt\0<prompt>格式的 COM 段（受 0xffff 段长上限约束）；
• 其他格式：回退到<image>.jsonsidecar。

配套子命令：

impeccable embed-prompt <image> --read # 恢复嵌入的提示词 impeccable embed-prompt --scan <dir> # 列出仍缺提示词的栅格

--scan递归遍历目录（跳过 node_modules 与点开头的隐藏目录），对每个 PNG/JPG/JPEG/WebP 检查是否可恢复 prompt（先查内嵌，再查 sidecar），输出MISSING:列表；scan 只读，删除仅保留给被放弃的栅格，绝不用于 scan 标记的文件。

provenance = 嵌入的提示词 + spec 中该区域的记录行，artifact 引用的每个栅格都携带它；来源图、库存图或既有栅格则嵌入其来源（origin）说明。之后在修复批次（fix batch）或评审者重建中创建或替换的栅格，用同样方式生产；修复放弃的栅格在同一批次中删除。

5.3 自动集成：generate-image 的 sidecar 与嵌入

impeccable generate-image（crates/context/src/generate_image.rs）在 API 调用成功后自动完成三件事：

1. 将提示词嵌入图像文件（调用embed_prompt逻辑）；
2. 写出<out>.jsonsidecar，包含prompt、createdAt、tool、model（gpt-image-2）与refs（当使用了--ref）；
3. 输出IMAGE: ...行报告嵌入与 sidecar 状态。

参数方面：--prompt/--prompt-file、--out必填；--size默认1536x1024；--quality默认medium；--ref可重复传入参考图（有 ref 时走images/edits的 multipart 上传，无 ref 时走images/generations）；需要OPENAI_API_KEY环境变量，未设置时提示改用 harness 原生图像工具。环境中设IMPECCABLE_IMAGE_GEN_FAKE时会进入 fake 模式（本地合成占位图，不发 API 请求），便于无密钥环境下联调管线。sidecar 写入的"approved": true正是 build-phase 的 comps gate 读取的数据。

5.4 图片转换器（converter）

图像转换使用impeccable context在启动时报告的转换器（IMAGE_TOOLS 行）；仅当它报告无转换器时才执行 probe（探测），且每个会话至多一次，绝不逐图探测。

六、相关命令速查

七、总结：从构图到规格的闭环

整个 visualize 环节的本质是一条纪律严明的闭环：

1. 不重开视觉世界：方向、调色板、字体、材质全部锁定，探测只解决构图层问题；
2. 三张构图：结构优先的提示词、表面自身的视口、established world 用像素参考锚定身份；
3. 唯一审批点：三图并陈、提问后等待、无替代无跳过、委托必须披露；
4. 批准落盘：surface brief + sidecar"approved": true，build-phase advance据此关闭 comps 阶段；
5. 规格化：comp-spec把构图变成带采样调色板的区域框，媒介由像素决定，栅格区进入 plates 阶段；
6. provenance 随资产走：嵌入提示词 + spec 行，--scan兜底审计，修复批次同样遵守。

这套机制的关键价值在于：把"构图批准"从一次性的主观判断，转化为磁盘上可被后续阶段和 gate 反复读取的状态事实。构图是方向测试而非截图规格，而批准后的构图是度量契约（measured contract）而非氛围板——这正是 Impeccable 让 AI harness 在设计中表现得更好的核心手段之一。后续的方向契约、分阶段构建与打磨收尾，请继续阅读 new-work.md。

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