Impeccable visualize 流程解析：方向样张（Direction Comp）生成与资产生产的完整实操指南

本文围绕 Impeccable 技能中的 visualize.md 展开，讲解「comp-led 构建」中从生成三张方向样张、单一批准点、实现保真度清点，到图片资产生产与 provenance（来源记录）的完整链路。读完本文，你将掌握：如何用结构优先的提示词生成高保真样张、如何把批准结果落成机器可读的记录、以及如何通过 embed-prompt.mjs、generate-image.mjs、serve-question.mjs 三个脚本把「生成意图」随文件一起跨机器、跨会话保留。

何时加载 visualize.md：触发条件与前置约束

visualize.md 不是独立命令，而是 new-work.md 主流程中的一个条件分支，其加载条件在文档开头被逐条限定：

• 仅限 comp-led 构建：当构建路径为 comp-led（视觉样张主导）且存在图片生成能力时才加载。图片生成能力有两个来源：harness 原生图片工具，或 context.mjs 在启动时报告的 API 回退。从源码可以确认，context.mjs 在检测到 OPENAI_API_KEY 环境时输出 IMAGE_GEN_AVAILABLE 指令，声明「harness 原生工具永远优先，generate-image.mjs 只是回退」；code-led 契约按设计跳过本文件，而不是因为遗忘跳过。
• PRODUCT.md 与 DESIGN.md 是前置条件：init.md 若未完成（缺 PRODUCT.md）需先补齐；而 new-work 已解决的「视觉世界」在本文件中不得重开——它固定 DESIGN.md 中的调色板、排版方向、材质语言、组件气质、图像立场与动效语法。
• 例外短路：如果 surface 级结构轮已经把三张可视化卡片摆到用户面前（established world 场景），该轮已履行本文件的职责：被锁定卡片的 comp 即为已批准 comp，此时直接记录批准并跳到「批准之后」继续，不生成任何新图。

它的自我定位很关键：这是一次 probe（探测），测试的是构图、叙事、层级、密度、焦点时刻、signature 用法与图像需求，而不是第二场身份工作坊。

生成三张构图选项：数量、视口与参考图锚定

核心规则是「三张是定数」：一张样张诱导橡皮图章式批准，而三张之间的张力恰恰暴露了值得构建的构图差异。具体操作约束如下：

视口纪律：样张必须按 surface 自身的视口出图——原生应用或移动优先的 surface 用设备尺寸的竖屏，否则用桌面横屏。用横屏去表达手机屏幕，会在构建之前就歪曲构图。

产出位置与所有权：

• 全部保存至 .impeccable/mocks/，使其存活于会话之外；
• 样张是构建线程自己的工作，绝不委托——写提示词的线程持有方向的完整上下文，并在构建开始时见过每一张样张；
• 用工作区相对路径打开每张图（沙箱查看器拒绝绝对路径，而项目根下的一切都有相对路径）。

已确立世界的像素锚定：这是文档中最有实战价值的规则之一——DESIGN.md 的文字描述会漂移，像素参考不会。操作方式是：截取一个有代表性的现有页面截图，作为参考图传入（harness 图片工具的输入图，或 generate-image.mjs --ref），提示词以新 surface 的结构开头，参考图承载调色板、字体与组件气质。同时必须声明参考图的贡献边界：chrome、调色板、字体、组件气质带过来，参考页自己的内容不带过来——逐字搬运的 banner、hero 或卡片是「参考泄漏」，不是保真。

generate-image.mjs 的源码印证了这条链路：--ref 参数（可重复）会把请求路由到 OpenAI 的 edits 端点而非 generations 端点，参考图以 multipart image[] 附上，模型固定为 gpt-image-2，默认 1536x1024、medium 质量。完整用法：

# 无参考图：直接生成
node .agent/skills/impeccable/scripts/generate-image.mjs --prompt "..." --out mock.png [--size 1536x1024] [--quality medium]

# 带参考图：锚定既有视觉身份
node .agent/skills/impeccable/scripts/generate-image.mjs --prompt-file prompt.txt --out mock.png --ref screenshot.png [--ref more.png]

源码还包含一个值得注意的测试设施：设置 IMPECCABLE_IMAGE_GEN_FAKE=1 后，脚本离线生成确定性的「合成样张」（同一提示词产出相同字节、$0.00 计费），让 new-work 冒烟测试套件无需真实 API 调用即可跑通 concept / serve-question / image 全链路——同一提示词哈希出 2–3 色调色板，并在 PNG tEXt chunk 中写入 SYNTHETIC COMP 标记供下游工具识别。

决策 comp 的优先序：被选卡片的 decision comp（位于 .impeccable/mocks/decision/）就是三张中的第一张——它已在本纪律下以全保真渲染了该方向，因此只需再生成两张「在第一张固定点上做变化」的样张，三张一起送审。只有到达时没有 decision comp 的轮次（degraded roll、identity-mode 页面、未经决策轮就定下的方向）才在此处从零生成全部三张。

样张提示词的六条自检纪律

文档为每张样张给出六条失败模式判定，全部可执行：

1. Comp 是被设计的 surface，不是题材的照片。提示词必须以 surface 自身结构开头：按顺序点名每个区域及其尺度关系；没有导航的页面就明说没有，非惯例骨架就明说非惯例。以氛围开头的提示词，得到的将是「渔村风情画」而不是「渔村官网」。自检：如果这张图能挂上墙当海报，或读起来是「照片上糊了点字」，它就不是 comp，用更字面的布局脚手架重新生成。
2. 反向失败同样致命：一个不包含自己题材的 surface。题材以「区域所承载的内容」的形式出现，世界装扮画框但从不取代画框所显示的东西。删除题材的惯常载体是提示词的排除清单——因此排除条款只约束虚构声明，媒介禁令属于已承诺的图像立场，而不属于谨慎。接受渲染前，用手指指出题材在哪；描绘了世界的一切却没有任何题材的渲染，氛围再忠实也是失败。
3. 以已交付的屏幕来评审：访客的任务必须能从图像本身读出。不加图注就能从渲染中叫出该 surface 的 mode；叫不出，就是「没有 surface 的美术指导」。
4. 承诺是深度，不是覆盖面：世界通过一个主导动作进入，辅以支撑它的材质、字体与留白；其余区域保持静止让这个动作被读出。检查削减的是竞争，永远不是内容——被安静的区域保留信息、停止表演。两个同尺度的元素与点名的焦点时刻竞争，意味着样张在喊叫。忙乱是更响，不是更大胆。
5. 用户入围了多个概念时，三张样张横跨它们分布。
6. 单一方向已确定时，变化的必须是「图像能解决的结构性不确定」：拓扑、序列、密度、层级、焦点构图或交互框架。

此外：要展示开屏时刻之外足够多的内容，证明该概念能治理整个 surface；不得生成调色板产物、追问新的氛围问题、引入不同的字体声音或发明新 motif——若已承诺的世界撑不起该概念，回到概念入围名单，而不是改世界。最后一句边界声明：每张 comp 是方向测试，不是截图规格说明；核心 UI 文本、响应式行为、无障碍、语义与交互状态仍是实现侧的职责。

单一批准点：无替代品、无跳过条件

批准点的机制在文档中被表述为整个流程中最刚性的约束：

• 展示方式：三张一起放到决策页上（serve-question.mjs，每个 comp 一个选项、comp 作为其 hero），或在 harness 内联渲染图片时进行；纯文本 surface 不算展示。serve-question.mjs 的源码注释完整定义了载荷结构：每个 option 的 comp 字段指向样张路径，「选项渲染为大卡片：存在 comp 时它领衔，灵感图以小窗（picture-in-picture）形式叠加；本地图片路径由该服务器本地服务，不上传任何地方」。它还支持 shimmer-wait——决策页可先于样张生成而服务，每个槽位轮询等待文件落盘，因此「先 serve 后生成」是官方认可的操作顺序。
• 问题内容：问什么该被带下去、什么与这个世界不符、所选概念应批准 / 合并 / 修订 / 拒绝。然后停止并等待。结构化的模拟用户算作在场，收到同样的问题。
• 未批准不得动代码，直到用户批准方向或显式委托选择。若委托，用任务简报、PRODUCT.md 与 DESIGN.md 作为依据做出选择并陈述证据。批准细化任务概念，不修改 DESIGN.md。
• 降级链：结构化问题工具报错 → 回退决策页 → 两者都失败才可视为委托。委托选择与批准以完全相同的方式记录，并在第一次回复中披露（而不是最后一次）。
• 审计钩子：finish reviewer 把「没有记录批准的 comp 轮样张」视为实质性发现（material finding）；.impeccable/mocks/decision/ 下的 decision comp 是方向轮的手笔而非 comp 轮输出，不隐含任何批准。

批准后的记录——这是让批准「可被工具发现」的关键动作：

1. 已批准 comp 的路径写入 surface brief；
2. 其 .json prompt sidecar 加上 "approved": true（凡经 generate-image.mjs 生成的 comp 都有 sidecar；原生工具生成的则补建）。

源码证实 sidecar 的自动落盘：generate-image.mjs 在写入图片字节后，调用 embed-prompt.mjs 内嵌提示词，并写出包含 prompt、createdAt、tool: "generate-image.mjs"、model: "gpt-image-2" 及可选 refs 的 <image>.json。因为 sidecar 随 mocks 目录一起走，批准得以存活于会话与「从未见过 brief 的机器」之中。随后总结构图与 comp 中不可被字面化的部分，返回 new-work.md，从已批准概念记录方向契约，开始构建。

实现保真度清点：把样张读成设计系统

这是 .agent/ 版本文档中最重的章节（visualize.md），核心主张是：在构建前，把已批准的 comp 当作设计系统来读，并记录进 brief——组件语法、圆角语言、线宽、浮起处理、字阶（type ramp）。comp 未展示的一切，都从这份记录出发构建；没有它，回退就是模型的标准件工具箱：方盒子、1px 网格、bento 单元格与硬阴影。

物料清单表（Inventory）

把 comp 的主要可见成分以书面形式清点出来（surface brief 或工作笔记中的一张小表，finish reviewer 将对照它审计交付资产），为每项选择实现媒介：语义 HTML/CSS/SVG、现有项目资产、生成 raster、来源 raster、图标库、canvas/WebGL，或被接受的省略。同一份清单还命名 comp 的构图承诺：导航项与图标、标题层级及其尺度关系、signature 几何（接缝、遮罩、重叠）、每个区块的排布与密度。主 CTA 必须拥有自己的一行、自己的媒介：当 comp 让主按钮溶解、盖章、侵蚀或以其他方式被物理加工时，该处理是页面最重要元素上的 signature 材质，把它缩成边框小把戏是「合规代币版的承诺」。原则一句话：没写下来的元素，就是构建会悄悄丢掉的元素。

采样而非估计：颜色记录的纪律

记录必须从 comp 的像素中采样，而非估计：

• 用 ImageMagick、Python + PIL 或机器上任意像素读取工具，读出 comp 的页面底色（ground）、每个主导区域与每个 accent 的实际 hex，写入同一份记录；
• 平涂区域取任意内部像素；带纹理/颗粒的区域取内部补丁的平均值（裁一小块 swatch，缩放到 1×1）；渐进取两端色；
• 绝不采样边缘——抗锯齿会把邻居混入设计从未选择过的颜色；
• 形容词是方向，不是记录：「cream」覆盖从近白到米色的全部范围，「charcoal」覆盖明度标尺的三分之一；没有数字钉住的地方，渲染先验随手取点；
• 采样值取代决策卡与构图卡上的调色板 chip——那些 chip 创作于该 comp 存在之前，与 comp 像素不一致的 chip 是被批准淘汰的草稿。

媒介门（Medium Gate）：批准的设计最常死在这里

文档把媒介选择设为一道双向门，其核心判据是：媒介由 comp 区域显示的内容决定，永远不由「当前技术栈感觉可构建什么」决定。

• Raster 侧：人形、产品物体、机械、任何带光照与深度的材质，无论技术栈是什么都是 raster；任何仅凭名字成立的纹理——织布、纸纹、织物、皮革、拉丝金属——同样不需要深度论证，因为 CSS 渐变不是纹理媒介，「分层 CSS 纹理」根本不算一个媒介。把摄影人形写成「silhouette」、把雕刻面板的表面写成「CSS」，不是媒介选择，而是对批准设计的静默删除——正是这样，充满物理材质的 comp 才变成「区块顺序相同的扁平页面」。风格不移动这条边界：带透视、明暗、人物描绘或密集机械细节的区域，无论画得多线条化都是插画，而构建会话无法把插画以矢量形式创作出来，因此它和照片一样按 raster 重新生成。手工 SVG 覆盖「会话能精确指定的东西」（可数元素的图解、控件、扁平形状系统），在绘图技艺开始的地方终止。这类区域通过干净地重新生成来生产，以已批准 comp 及其内嵌提示词为参考、按资产分辨率做新渲染；绝不从 comp 本身裁剪像素，因为 comp 的有效分辨率远低于资产级。
• Vector/GPU 侧：精确几何、硬边形状系统、图解、表现性动效、shader 与一切交互性内容属于 SVG / canvas / WebGL 领地，raster 会压扁本应移动、缩放、响应的东西。由大量小元素构成的场/纹理带数量承诺：写下近似密度与覆盖率（例如「数千个字形覆盖三分之二首屏，顶部密集、沿路径渐淡」），因为按十分之一密度重建的场能穿过每一张检查清单，却仍然不是那个设计。
• TYPE 行遵循同样纪律：点名字体的压缩类别，在构建前把一个标题词对着 comp 渲染一次；明显更宽或更细的轮廓意味着字体选错了，建立在它之上的每个区块都继承这个误差。

两句收束性的判据值得原样保留：「raster 给世界所画的东西，代码给世界所绘制、动画、响应的东西，在那里选择代码是雄心，不是节省」；「有未生产条目的清单是未完成的构建——跳过这道门，就是无图像页面的来源」。另外注意：图像原生区域的取舍是用户在批准点做出的范围决策，绝不是其后的静默扁平化；生成的图像是材质而非声明——证据规则约束断言、规格、证言与被当作真照片呈现的图像，永远不约束渲染保真度，「手头没有摄影」禁止的是伪造证据，不是插画式 hero。

只生产构建所需的资产：Provenance 机制

资产生产章节的出发点是：生成上下文是资产的一部分——由一个从未看过提示词的线程来组合，它会摆放自己并不理解的资产。

embed-prompt.mjs：让意图住在文件里

统一的操作：无论用哪个工具（原生或 generate-image.mjs，后者自动完成）生成任何图片之后，执行：

node .agent/skills/impeccable/scripts/embed-prompt.mjs <image> --prompt "<提示词>"
# 用生成工具实际收到的完整字符串，整段粘贴

embed-prompt.mjs 的实现细节决定了这套机制的可靠性：

• PNG：在 IEND 之前插入（或幂等替换）关键字为 impeccable:prompt 的 tEXt chunk，含 CRC32 校验；
• JPEG：写入 COM 段（0xFFFE），超长提示词会明确报错拒绝；
• WebP 及其他格式：回退到 <image>.json sidecar，--read 对任何格式都会检查 sidecar，因此回退同样可恢复；
• 改写量最多几 MB，延迟是毫秒级（对比生成的分钟级）。源码头部还留下一个务实提醒：构建管道里的图片优化器通常会剥掉输出文件的元数据——意图住在源资产里，而源资产正是构建者读取的那个。

三个辅助子命令构成审计闭环：--read 从任何 impeccable 生成的图片中恢复提示词；--scan <dir> 列出目录中仍缺提示词的每一张 raster，有缺失时退出码为 3（可直接接入 CI 门禁）。注意「凭记忆重建的摘要记录的是一个从未被制造出的资产」——必须粘贴工具实际收到的精确字符串。

Provenance 的定义：内嵌提示词 + 书面清单中该资产的行 = 该 raster 的 provenance；artifact 引用的每张 raster 都必须携带它。来源型、图库型或既有的 raster 没有生成提示词，则改嵌入其出处。

Provenance 的时效纪律与资产生产者子代理

• Provenance 对整次运行负责，而非构建阶段：修复批次或 reviewer 重建中创建/替换的 raster，同样在本节规程下生产——内嵌提示词、加清单行，因为清单是下一个线程知道「什么在发货」的唯一途径；
• 被修复放弃或取代的 raster 在同一批次中从资产目录删除——没有记录的未引用 raster 是 provenance 泄漏，不是备用件。
• 资产生产者必须每次 spawn，即使清单的 produce 桶看起来是空的：它的 manifest 是对你媒介判断的独立第二意见，「跳过 spawn 的那些运行，正是棉布变成 CSS 的那些运行」。各 harness 的调用形式：impeccable-asset-producer（codex 中为 impeccable_asset_producer，Cursor 中为 /impeccable-asset-producer，GitHub Copilot 中说 "Use the impeccable-asset-producer agent"）。交给它的输入：已批准 comp、输出路径、必需尺寸与格式、透明需求、裁剪说明、以及必须保持语义代码的部分。无子代理能力的 harness 按 degraded/asset-producer.md 在当前线程内联执行——该降级文档定义了完整的输入契约、produce / direct / semantic 三桶分类、图片到图片的提示词模板与 manifest 输出契约，其中「comp 裁剪是约束性视觉参考，永远不是可发货像素」与本文「绝不从 comp 裁剪像素」的门规则互为呼应。
• 图片转换用 context.mjs 启动时报告的 converter（IMAGE_TOOLS 行，探测 cwebp、sips、magick、ffmpeg）；仅当报告为无时才探测，且每会话至多一次，绝不按每张图探测——源码中该指令的措辞与文档完全一致，无 converter 时的官方行为是「以未转换的 PNG 交付，而不是反复探测」。

边界与回归：comp 是北极星，不是描摹对象

流程的最后一节划定批准后的行为边界，这也是 visualize.md 与实现阶段的接口契约：

• 已批准的 comp 是翻译为语义、响应式、可访问代码的北极星，绝不允许重组（recomposition）：保住调色板与氛围却重画拓扑，是第二场美术指导，不是适配；
• 不将核心 UI 文本或控件栅格化；
• 批准之后不询问就更换视觉驱动，是被禁止的；
• 需特别关注的对象：主导构图、signature 用法、图像原生内容、第二折屏系统，以及静帧图像仅仅暗示的交互。

完成上述步骤后，按文档结尾的指引返回 new-work.md，继续方向契约、实现与收尾流程；new-work.md 中对应条款（「comp-led 构建中，只要有图片生成能力，锁定的方向在构建前必须被可视化，绝不跳过」）与本文构成闭环——finish reviewer 最终拿已批准 comp 的截图路径做并排比对，把样张承诺逐项审计进交付物。

小结：这套流程解决的真实问题

把 visualize.md 的规则压缩成三条可迁移的工程经验：

1. 批准必须机器可读："approved": true sidecar + 写入 brief 的路径，让批准脱离会话存活，并让 finish reviewer 能把「无批准的 comp 轮样张」升级为实质性发现；
2. 意图必须随文件旅行：embed-prompt.mjs 的 tEXt/COM/sidecar 三级嵌入 + --scan 的退出码 3 门禁，使「这张图为什么存在」在任何一台机器上都可回答；
3. 媒介由像素决定，不由栈决定：媒介门把「CSS 能做多少」从设计决策中剔除，而采样纪律（内部像素、补丁平均、禁采边缘）把「形容词漂移」从颜色决策中剔除。

这三条共同保证了 Impeccable 的核心承诺——先看到方向，再构建代码，且每一步承诺都有可审计的记录载体。