Impeccable 方向构图轮次（Comp Round）：从三选一审批到资产溯源的可视化构建工作流

Impeccable 方向构图轮次（Comp Round）：从三选一审批到资产溯源的可视化构建工作流

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

导读：本文讲解 Impeccable 项目中visualize.md定义的方向构图（comp）工作流——当构建是 comp-led（以构图为先导）且图像生成可用时，如何产出三张高保真方向构图、通过唯一的审批点锁定方向，并在审批后把已批准的构图量化为可执行的构建规范（spec），最终为每个栅格区域（plate）生成资产并写入可审计的溯源（provenance）。读完本文，你将掌握impeccable build-phase、generate-image、comp-spec、embed-prompt、serve-question等命令在这一工作流中的完整调用关系与纪律约束。

一、这份文档在什么时候被加载

visualize.md不是一个随时都要执行的流程，它的加载有严格的前置条件。从文档开头可以看出，它只出现在两条路径都满足的时刻：

• 构建是comp-led（以构图驱动）的：new-work.md中记录了buildPath默认值（来自.impeccable/config.json或config.local.json，前者被 gitignore 且在本机有更高优先级），当图像生成存在时默认即为 comp-led；
• 图像生成可用：要么是 harness 自带的图像工具，要么是 API 回退方案impeccable context所报告的。

反之，code-led 契约会按设计跳过这份文档（文档原文是 "skipped by design, not by drift"）。不要因为"看起来像是漂移"而错误加载它。同时，PRODUCT.md与DESIGN.md是前置条件：视觉世界已经在new-work.md阶段解决，这份文档不得重新打开视觉世界的问题——它不是一个"第二次身份工作坊"。

还有一个特殊的"已清偿"（discharged）情况：如果new-work.md的 surface-scope 结构轮次已经把三张可视化卡片放到了用户面前（即"已确立世界"下的决策构图轮），那么这一轮已经完成——被锁定的卡片的构图就是已批准的构图，此时直接记录审批并跳到 "After approval" 阶段，不再生成任何新内容。

探测而非重新设计

文档明确指出：这一轮是一个"探测"（probe），它检验的是构图、叙事、层级、密度、焦点时刻、标志性用法与图像需求，而不是再来一次身份（identity）工作坊。DESIGN.md中已经确定的调色板、排版方向、材质语言、组件性格、图像立场与动效语法都必须保持不变。

二、生成三个构图选项：阶段状态与生成纪律

2.1 构图必须运行在 build-phase 状态机之内

构图轮次发生在构建的相位状态里。文档强调：impeccable build-phase start --direction <seed key> --kind <...>必须先运行（roll 的输出会指名具体命令），且其comps阶段在生成第一张构图之前就已经打开。

从源码实现看，build-phase是一个跑在磁盘上的状态机。在 build_phase.rs 中定义了完整的相位序列：

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

new_state（build_phase.rs）在start时把第一个相位置为open、其余置为pending，状态写入.impeccable/build/state.json。如果通过start --comp <approved comp>启动（surface 轮已锁定构图），comps相位会被标记为skipped并记录原因注释。

为什么必须在状态机内生成？文档给了一个关键理由：在start之前渲染的构图不在状态内，从该点恢复的会话没有可跟随的相位。同时impeccable generate-image会拒绝在start运行之前向.impeccable/mocks/写入任何内容；harness 自带的图像工具同样受此顺序约束。这保证每一张构图都归属于某个可审计的构建会话。

2.2 三张构图的产出要求

核心要求可以拆解为以下几条：

1. 渲染三张彼此不同、高保真的 north-star 构图，保存到.impeccable/mocks/下（这样它们能在会话结束后存活）。构图是构建线程自己的工作，绝不能委托出去：写提示词（prompt）的线程持有方向的完整上下文，并且在构建开始时已经见过每一张构图。
2. 以表面自身的视口来构图：原生 App 或移动优先的表面用设备尺寸的竖版（portrait），桌面 Web 用横版（landscape）。文档的原话是：一张手机屏幕却以横版构图，会在任何代码构建之前就错误陈述（misstate）这个构图。
3. 用相对路径打开每一张图片：沙箱化的查看器会拒绝绝对路径，而项目根目录下的一切都有相对路径。
4. 基于真实内容与已和用户开发的表面概念来构图。
5. "三"这个数字本身是纪律：一张构图会诱导橡皮图章式的点头（rubber-stamping）；三张之间的差异才能暴露值得构建的构图。三张之间的"铺开"（spread）正是价值所在。

comps阶段的门禁（gate）在 build_phase.rs 中实现：gate_comps检查.impeccable/mocks/下是否有至少 3 张PNG/WebP/JPG 构图、每张是否有携带 prompt 的.jsonsidecar（{ "prompt": "..." }）、以及是否恰好一张被标记为"approved": true。任何一项不满足都会以非零退出码拒绝推进。

2.3 已确立世界：用像素参考锚定真实身份

在"已确立世界"（established world）上，每张构图都必须锚定在真实身份上：截取一张有代表性的现有页面的截图，作为参考图像传入（harness 图像工具的 input image，或impeccable generate-image --ref）。提示词以新表面的结构为先导，而参考图承担调色板、字体与组件性格——因为DESIGN.md的文字转述会漂移，而像素参考不会。

文档对"参考图贡献什么、不贡献什么"做了明确划分：

• 应该继承：chrome（界面骨架）、调色板、字体、组件性格；
• 绝不能继承：参考页面自身的内容——一张被原样搬来的 banner、hero 或卡片是"参考图泄漏"（the reference leaking），而不是保真。

2.4 三张中有一张是"决策构图"

当方向轮已经产生了决策构图（.impeccable/mocks/decision/下的那张），它天然就是第一张：它已经在这一纪律下以全保真度渲染了该方向。因此本轮只需再生成两张——对第一张已固定的变量做变化——然后把三张一起送到审批点。

只有两种"降级到达"（degraded arrival）情况需要在这里渲染全部三张：

• 降级的 roll（degraded roll，没有 challenger）；
• 身份模式的页面（identity-mode page）；
• 方向被固定但没有经过决策轮（a direction pinned without the decision round）。

2.5 构图纪律：六条自检规则

文档用相当紧凑的篇幅给出了六条构图评审标准，这里逐条展开：

1. 构图是"设计过的表面"，不是"主题的照片"。提示词必须以表面自身的结构为先导：本设计的各个区域、按顺序命名、并给出它们之间的尺度关系。没有导航的页面要直接说"没有导航"，而不是发明一个；非常规的表面要说明它非常规的骨架。以氛围为先导的提示词得到的是一张氛围图（vignette）——模型会画出鱼市，而不是鱼市的网站。自检方法：如果这张图能当海报挂起来，或者读起来像"加了些文字的摄影作品"，那它就不是构图，需要用更字面的布局脚手架（layout scaffold）重新生成。

2. 反面同样是失败：表面里没有任何主题内容。主题以区域所承载的内容出现；世界（world）负责装扮画框，但永远不能取代画框所展示的东西。这种"删除"通常搭着提示词的排除列表（exclusion list）混进来，所以排除列表要用来约束虚构的主张（invented claims），而对某类媒介的禁令属于已承诺的影像立场（imagery stance），不属于谨慎。接受一张渲染前，先指向主题：一张描绘了世界的一切却与主题无关的渲染，无论氛围多忠实都是失败。解决办法：把主题的内容按区域逐一命名，重新生成。

3. 把构图当作上线后的屏幕来评判。访客的任务必须仅凭图像本身就能读出来。不看任何说明文字就能说出这张渲染是什么模式（persuade/operate/read/experience）——说不出来的渲染只是"没有表面的艺术指导"（art direction without a surface）。此时以访客的任务作为提示词的脊梁（spine）重新生成。

4. 承诺是深度，不是覆盖（Commitment is depth, not coverage）。世界通过一个主导动作（one dominant move）加上支撑它的材质、字体与间距进入；其余区域保持静止，好让那个动作能被读出来。一个只是在自己的语法里完成本职工作的区域，比一个在表演概念的 区域更能承载方向。检查会削减竞争（competition），而不是削减内容：被安静下来的区域保留信息、停止表演。如果第二个元素以同样的尺度与命名的焦点时刻竞争，构图就是在喊叫（shouting）；没有命名焦点时刻时，多个区域同时表演概念同样是喊叫。保持最强的动作，安静其余。文档有一句非常精辟的总结："Busy is louder, not bolder"（嘈杂只是更大声，不是更大胆）。

5. 当用户筛选了多个概念时，把三张铺开覆盖它们。

6. 当一个方向已承诺时，变化图像能够解决的结构不确定性：拓扑（topology）、序列（sequence）、密度、层级、焦点构图（focal composition）或交互框定（interaction framing）。

7. 展示的必须超出开场瞬间（opening moment），足以证明这个概念能统摄整个表面。

8. 禁止项：不生成调色板产物、不问新的氛围问题、不引入不同的字体声音、不发明新的母题（motif）。如果已承诺的世界无法支撑这个概念，回到概念短名单（concept shortlist），而不是改变世界。

最后提醒：每张构图都是方向测试，不是截图规格。核心 UI 文本、响应式行为、可访问性、语义与交互状态始终是实现阶段的责任，构图阶段不承担。

三、唯一的审批点

3.1 展示方式与问题

三张构图必须一起呈现在决策页上：impeccable serve-question，每个构图一个选项，构图作为该选项的 hero 图；或者，仅当 harness 能内联渲染图片时，才在 harness 内展示。纯文本的表面不算展示。

向用户提出的问题固定为三个：

• 什么应该被带向前（carry forward）？
• 什么对这个世界来说显得虚假（feels false to the world）？
• 选中的概念应该被批准（approved）、合并（combined）、修订（revised）还是拒绝（rejected）？

然后停下等待。一个结构化的模拟用户（structured simulated user）同样算作"已出席"，并收到同样的问题。

从实现看，serve-question是一个可守护进程化的决策服务（serve_question.rs）：它以--start启动后打印页面 URL 与 key 并退出，--wait --key <key>收集答案，ANSWER:以 JSON 输出。

3.2 委托与降级路径

在用户批准方向或明确委托选择之前，不要开始写代码。如果用户委托了选择，依据任务简报、PRODUCT.md和DESIGN.md来决定，并陈述证据。审批细化的是任务概念，它不修改 DESIGN.md。

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

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

finish-reviewer会把"构图轮产出但无记录的批准"视为实质性发现（material finding）。注意区分：.impeccable/mocks/decision/下的决策构图是方向轮的产物，不是构图轮的输出，它们本身不暗示任何批准。

3.3 审批后：把选择记录到工具能找到的地方

审批之后，必须留下工具可读的记录，共两步：

1. 被批准构图的路径写入 surface brief；
2. 其.jsonprompt sidecar 获得"approved": true。每一张通过impeccable generate-image生成的构图都有这个 sidecar（native 工具没有的话要手动创建）。

为什么 sidecar 是关键？因为sidecar 随 mocks 目录一起走，审批因此在"从未见过 brief 的会话和机器"上也能存活——impeccable build-phase advance读取的正是这个标记来关闭 comps 阶段。这也与gate_comps的逻辑完全一致：它要求恰好一个 comp 带"approved": true，多一个少一个都会拒绝。

之后：概括构图与"不得被字面化（literalized）"的部分，回到new-work.md，从已批准的概念记录方向契约（direction contract），然后开始构建。

四、审批之后：构图变成规范（spec）

被批准的构图是翻译成"语义化、响应式、可访问代码"的北极星（north star），绝不是重新构图的许可。文档给出两条硬约束：

• 保持调色板与氛围的同时重画拓扑，是第二次艺术指导——禁止；
• 不得栅格化（rasterize）核心 UI 文本或控件；审批后不得未经询问替换视觉驱动（visual driver）。

4.1 构图是被测量的，不是被记住的

new-work.md第 6 节将构建作为相位运行：spec 阶段把构图变成区域框与采样调色板（impeccable comp-spec）。从 comp_spec.rs 的实现看，流程是：

• impeccable comp-spec --comp <comp> --grid在构图上叠加一个10×10 坐标网格（render_grid，comp_spec.rs，左上角 A0、右下角 J9），并打印 PALETTE 与 BANDS；
• 打开网格图，在 regions 文件里按网格跨度（grid span）命名每个显著区域，然后impeccable comp-spec --comp <comp> --regions <file>测量生成.impeccable/build/spec.json；
• impeccable comp-spec --print从此是构建的参考。

每个区域携带box（相对坐标）、px（像素坐标）、采样调色板、medium与note。spec 的用途是：一切不在 spec 里的东西在页面上都不存在——没有构图未显示的边框、规则、容器或 chrome。文档只允许三个例外：字体（最近可得的字面）、图标字形（足够接近即可）、以及构图中的真实缺陷（如拼写错误）。

4.2 介质分类：像素是什么，就按什么交付

每个区域的介质（medium）由像素本身决定，而不是由"什么感觉好构建"决定：

把雕刻面板的饰面写成 "CSS"、或为一个撕裂边缘写一个多顶点的clip-path，都是对已批准设计的"安静删除"——设计系统检测器的organic-clip-path与buried-raster规则，以及 hero 门禁的区域得分，会抓住这类行为。删除一个图像原生（image-native）区域是用户在审批点做的范围决策，绝不是在审批后默默扁平化。文档还特别强调："生成的图像是一种材质（material），不是一种主张（claim）"——证据规则约束的是被当作真实的断言、规格、证词与照片，从不约束渲染保真度。

五、Plates 与溯源（provenance）

5.1 生产流程

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

1. 先用impeccable comp-spec --crop <id>写出参考裁切（reference crop）；
2. 把impeccable comp-spec --plate-prompt <id>的输出保存为 prompt 文件；
3. 把裁切与 prompt 交给 harness 图像工具；或使用 API 回退命令：

impeccable generate-image --ref <crop.png> --prompt-file <prompt.txt> \ --out <plate.png> --size <WxH> --quality high

从 generate_image.rs 的实现看，--ref走 multipart 的/images/edits接口（reference edit），无--ref走/images/generations；--size默认1536x1024，--quality默认medium，--model默认gpt-image-2.5-flare（generate_image.rs）。生成成功后它会自动写入两样东西：

• 在图片文件内嵌入 prompt（调用 embed-prompt 逻辑）；
• 写出<out>.jsonsidecar（含 prompt、createdAt、tool、model、refs 等）。

透明与不透明：隔离的剪影（cutout）要在 plate-prompt 与 API 生成命令上都加--background transparent——使用原生 PNG alpha，保留白色油漆与清晰的空隙；全幅图像用--background opaque。先创建输出目录，再在浅色与深色底上检查 alpha。--background只接受transparent、opaque、auto三个值，且要求输出路径是.png（否则命令直接报错，见 generate_image.rs）。

5.2 嵌入 prompt：让意图活在文件里

生成上下文本身就是资产的一部分。无论用什么工具生成图像，都要运行：

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

并且 prompt 必须是工具实际收到的原样字符串（impeccable generate-image会自动完成这一步）。从 embed_prompt.rs 的实现看：

• PNG 以tEXt块写入关键字impeccable:prompt（重复嵌入会幂等地替换旧块）；
• JPEG 以 COM 段写入；
• 其他格式回退到.jsonsidecar。

配套的读取与扫描：

• --read恢复被嵌入的 prompt（PNG/JPEG 内嵌优先，sidecar 兜底）；
• --scan <dir>列出仍然缺少 prompt 的栅格资产，退出码 3 表示有缺失。

内嵌 prompt + spec 中该区域的行 = 栅格的溯源（provenance），被 artifact 引用的每个栅格都必须携带它。来源明确的、图库的或既存的栅格嵌入的是它的来源（origin）而不是 prompt。在修复批次（fix batch）或 reviewer 重建中产生或替换的栅格，必须以同样的方式生产；被放弃的栅格在同一批次中删除。

5.3 图像转换器

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

5.4 门禁如何验证 plates

plates 门禁（gate_plates，build_phase.rs）逐区检查：

• 每个 raster 区域都有 plate 文件，且是可解码的 PNG；
• plate 至少是区域尺寸的 1.5 倍宽（min_w = min(1536, px_w * 1.5)）——低于此会被拒绝："a shipping plate needs at least Npx. Regenerate at asset size, do not crop the comp"；
• plate 与构图的区域参考做结构/颜色/细节对比打分（阈值 PLATE_MIN = 0.4、PLATE_STRUCTURE_MIN = 0.4），打分逻辑在 comp_diff.rs 中按区域类型有不同的权重；
• 纹理区域（texture）按 50% 颜色 + 50% 细节的有效分评估，要求至少 0.4；
• 构图裁切（comp crop）永远不是 plate：如果 plate 与原区域像素的结构相似度 ≥ 0.95（structure_score），会被判定为"comp 的重新采样"而拒绝；
• 如果构图区域平静（energy < 12）而 plate 增加了超过 45% 的细节，也会被拒绝（噪声/纹理噪点被看作不该有的添加）。

comp_diff的 parity 测试（parity.rs）确认这套打分与原始 JS 实现逐字节一致，例如comp.png对build_flat.png的 overall 分 0.8374、verdict 为match。

5.5 hero 门禁的承接

在 plates 之后，hero 门禁把 spec 中测量到的数字变成 CSS custom properties 与参考页（impeccable build-phase scaffold生成.impeccable/build/scaffold/layout.css的--r-<id>-x/y/w/h与hero-reference.html），然后只构建首屏，comp-diff以72%总分为及格线（HERO_MIN = 0.72，build_phase.rs），并把每个文本区域的 cap height、行数、字重、墨色与位置、每个 chrome 条的规则高度、以及"构图平静处冒出的墨迹"逐一以数字形式报告——"那些数字就是编辑指令"（"those numbers are the edit"）。

六、返回 new-work：方向契约与收尾

构图轮在审批与 plates 溯源之后结束。文档最后回到 new-work.md——方向契约、分阶段构建与收尾（finishing pass）都在那里继续。构图的地位在 new-work.md 中也被反复强化：

• comp-led 构建下构图是测量过的契约：只有用户能用明确的言辞降低它的权威；构建以磁盘上的状态机运行，门禁用屏幕对照构图做测量，而不是让你凭记忆；
• finish review 以comp-diff --comp <approved comp> --build .impeccable/review/desktop.png --spec .impeccable/build/spec.json --out-dir .impeccable/review/diff/final作为最终保真度证据；
• 在代码（含 HTML 注释、data-*属性、序列化 props 等一切浏览器可达的产物）中绝不复制方向契约——它只存在于 surface brief。

七、关键命令速查

所有命令都以.trae-cn/skills/impeccable/scripts/impeccable（或 npm 安装后的impeccable）为前缀调用。需要说明的适用前提是：本工作流仅在 comp-led 构建路径且图像生成可用时启用；code-led 契约按设计跳过构图轮，其雄心转移到方向契约的 FIRST VIEWPORT 块与命名的标志性交互中，由 finish reviewer 在行为层面审计。

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