企业官网建设流程全解析

Impeccable Finish Reviewer 全解析：AI 构建收尾的合约式审查、四词裁定与 degraded 降级模式

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

本文围绕 Impeccable 技能体系中最关键的一道质量闸门——Finish Reviewer（收尾审查者）展开：它负责以全新视角审阅一个"已完成"的构建产物，依据方向合约、批准的设计稿（comp）与所选世界的质量标杆，输出有序的实质性修复清单，并以recapture/rebuild/fix/ship四个词给出最终裁定。读完本文，你将掌握该审查角色的完整输入契约、七项检查的顺序与判定标准、四词裁定的推导规则、五段式输出契约，以及在不支持子代理的宿主环境（degraded 降级模式）中如何以行内方式运行这一角色，并理解其背后由comp-diff测量、phase 状态机与 detector 规则构成的保真度基础设施。

一、角色定位：为什么收尾审查必须"不在场"

Finish Reviewer 的核心设定是一句话：它是构建线程之外的"新鲜眼睛"（fresh eyes on a done artifact, outside the build thread's attention gravity）。它不编辑任何代码——所有修复由父代理（parent）应用。它没有浏览器，绝不渲染、截图、起服务或打开页面，只基于提供的文件做审查。这一隔离是刻意设计的：skill/reference/new-work.md明确要求"spawn the reviewer fresh, with no forked conversation history"，因为"一个继承了你的 transcript 的审查者，会继承你的框架、你的乐观和你的抽象"（见 skill/reference/new-work.md 第 141 行附近）。构建者自己审查自己的产物，等于让作者给自己的翻译打分，这正是该角色存在的理由。

审查运行受硬性轮次上限约束：一个在合约要求的章节（五个 section，或 recapture 的单一 section）写出来之前就结束的运行，什么都不返回。阅读被当作一种"配额"而非权利：只允许读传入的输入加上工艺底线（craft floor），绝不读其他技能参考文件；每轮批量发起多个 Read；先读截图、comp、卡片和合约；对产物主文件做采样而非遍历目录树；大约在第 10 轮左右停止阅读、开始写作。任何未读的输入要在章节上方用一行说明。

二、degraded 模式：一份文档、两种运行方式

本文所述的.kiro/skills/impeccable/reference/degraded/finish-reviewer.md是构建期自动生成的降级回退文件，其文件头注释明确写着"Generated from skill/agents/ at build time. Do not edit; edit the agent definition."（由 skill/agents/impeccable-finish-reviewer.md 生成）。

从源码看，生成逻辑位于 scripts/lib/transformers/factory.js：

• 第 17–21 行定义了DEGRADED_PREAMBLE（降级模式前言），即文档开头的两行："This harness has no subagent capability, so you are running this role inline. Step fully out of the work you just finished, adopt only this file's instructions for the pass, and disclose the substitution in one line when you report."（本宿主无子代理能力，因此你以行内方式运行该角色：彻底脱离刚完成的工作，本轮只采纳本文件的指令，并在汇报时用一行披露这一替代。下面文本凡是对"父代理"说的，你一人身兼两角：先产出完整输出契约，再自行执行。）
• 第 348–365 行：为每个"发货的" agent 定义（skill.agents）生成reference/degraded/<role>.md，角色名 = agent 名去掉impeccable-前缀；内容经过与普通参考文件相同的 provider 块编译与占位符替换（<codex>块、{{placeholders}}同样解析）。

该文件会随每个 provider 的技能副本分发——本仓库中可确认的副本包括.kiro/、.claude/、.cursor/、.agents/、.github/、plugin/、cursor-plugin/等目录下的skills/impeccable/reference/degraded/finish-reviewer.md。每个 provider 的配置目录映射在 scripts/lib/transformers/providers.js 中定义（如kiro → .kiro、claude → .claude、github → .github等）。该文件第 97–99 行对 GitHub Copilot 的说明透露了 degraded 目录的定位：这些回退文件"still ship for Copilot surfaces where the model fails to delegate"——即当模型无法委托子代理时的行内兜底，真正的子代理路径是.github/agents/*.agent.md。

对应地，tests/skill-behavior-harness.test.mjs 第 136–140 行的测试断言了降级文件的产物形态：对finish-reviewer与documenter两个角色，读取.claude/skills/impeccable/reference/degraded/<role>.md，必须包含 "This harness has no subagent capability" 前缀，且不允许残留{{scripts_path}}或<codex>未解析占位符——保证"同一份专门文本"在任何宿主上都被完整解析。

而在具备子代理能力的宿主上，new-work.md给出了各平台的召唤方式：Codex 中为impeccable_finish_reviewer、Cursor 中为/impeccable-finish-reviewer、GitHub Copilot 中口头说 "Use the impeccable-finish-reviewer agent"。只有当宿主完全没有子代理能力时，才允许退化为行内模式：先彻底脱离构建上下文，从degraded/finish-reviewer.md运行，且被替代或失败的审查必须在收尾时用一行披露，绝不静默。

三、输入契约（Input Contract）：审查者只相信你传入的东西

审查者无浏览器，"你未能传入的截图，就是它无法执行的检查"。一个完整的输入包应当包含：

关于截图路径有一条重要的权限规则：调用方 brief 点名的截图路径在文件存在时具有权威性；brief 未点名或点名路径缺失时，审查者才去.impeccable/review/查找，绝不臆造文件名。此外，当宿主能查看图片时，审查者应先打开截图、comp 与卡片，并用自己的话清点 comp 的显著元素，然后才读方向合约或任何构建者撰写的摘要——"基于合约的审查会继承构建者抽象过程丢掉的东西"。

new-work.md第 139 行补充了截图捕获阶段的规范：将截图捕获到.impeccable/review/，每视口一个文件；传入审查者的路径就是它的规格，你检查过的每个视口都要在包中标记为必需。

四、七项检查：从证据到工艺底线的顺序裁定

审查按固定顺序执行七项检查，前一项失败会直接改变整个审查的形态。

Check 0：证据（Evidence）——先于一切的截图像验

任何其他检查之前，先验证必需截图存在且有效。必需集合 = 平台完整视口集（Web：desktop.png+mobile.png；原生：每个发货设备类一张）+ 调用方 brief 点名必需的全部截图 + 上报的用户视口user-<width>.png。有效性标准：无纯黑或空白区域；内容与文件名声称一致（"访问页截图却显示 About 区块"即无效）；文件声称整页时页首可见；尺寸与命名视口相符。

关键语义：缺失的必需截图与畸形截图同等失败——"没人捕获的视口就是没人检查的视口，它不能发货"。任何截图失败时，整个审查改变形态：第一行返回disposition: recapture，然后只返回一个recapture章节，列出每个缺失或无效文件及其有效捕获应展示的内容，随即停止。绝不在畸形证据上搭建矩阵——"从坏截图推导出的裁定，等于把损坏洗白成批准"，父代理欠你的是一次基于有效捕获的完整重审，而不是一次打分回合。

Check 1：持久性（Persistence）——产物与过程是否真实存在

依次核验：PRODUCT.md 存在；comp-led 构建下.impeccable/build/state.json存在且其comps（当 surface 轮已锁定 comp 时为skipped）、spec、plates、hero各 phase 均为closed。这里有若干比工艺更重要的实质性发现：

• 无 state 文件、或compsphase 从未 closed → comp 轮被跳过，构建仅凭世界描述进行，这是压过工艺的实质性发现；
• phase 带forced记录关闭 → 除非用户以包中引用的原话降级了 comp，否则必须作为实质性发现披露；
• hero.gate.score低于 0.72 或 state 缺失 → 复现未经验证，属实质性发现，且.impeccable/review/hero-repro.png无论何种情况都必须存在；
• DESIGN.md 早于本构建（扩展或重设计）时应匹配所构建的世界；新世界的 DESIGN.md 由 documenter 在本审查之后撰写，此处缺席不构成发现；
• .impeccable/mocks/下的 comp-round comps 必须有批准记录（命名批准 comp 的 surface brief，或其 sidecar 中的approved标志）；有 comp 无记录 = 批准点被跳过，实质性发现；
• .impeccable/mocks/decision/下的文件豁免：它们是方向轮的"发牌手"，先于任何 comp 轮产生，无论构建路径如何都不隐含批准；code-led 构建根本没有 comp 轮。

Check 2：保真度（Fidelity）——先信测量，再补测量测不到的东西

审查者从测量开始：先读.impeccable/review/diff/final/report.json（以及 hero 版）；每个被评missing或contradicted的区域，除非regions/下的成对裁剪图证明评分有误（并说明理由），否则就按该状态计入矩阵；被评match的区域仍要过目检查字形性格与材质——这些是数字测不到的。

测量背后是impeccable comp-diff这个纯计算引擎。crates/comp-verbs/src/comp_diff.rs 定义了Score结构（overall / structure / color / colorIntersection / paletteMatch / detail / detailRaw / detailAdded / bands 九项，输出时四舍五入到 4 位），docs/COMP-FIDELITY.md 则说明其原理：把构建截图对齐到 comp 宽度并取首屏行，用模糊灰度 SSIM 加小平移搜索评结构、量化直方图交叠 + Lab 主色板匹配评颜色、每单元高频能量比评细节（"材质是否幸存"）、水平分区边界对齐评 band；并按区域类型加权（plate区主要看 detail，text区看 structure），最终产出side-by-side.png、heatmap.png、regions/<id>.png与含区域判词match / drift / missing / contradicted的report.json。

然后，审查者对照自己对批准 comp 的元素清点（而不是合约对它的摘要）逐项判定：拓扑、阅读顺序、焦点比例、重叠与 z 序、密度、标志性几何、主行动的处理（comp 中"物理可按下、溶解或盖章"的 CTA 是标志性元素，其纯矩形再现即contradicted）、导航项与图标、标题层级与比例关系。每个显著元素分类为：match、acceptable adaptation、missing、contradicted、added without approval。

矩阵中三行是强制必填的：

• TYPE（字形）：展示性字体的性格、压缩、宽度、字重、对比、字脚与 comp 的对比。无论布局多忠实，性格不同的字体就是contradicted。该检查背后有font-match与字体指纹索引（docs/COMP-FIDELITY.md 第 4b 节）：对 comp 裁剪区做尺寸无关的形状特征指纹，在约 3,100 个 Google Fonts 家族的索引中检索最近邻，再以真实文本渲染后复测。
• MATERIAL（材质）：comp 显示为绘制、纹理、立体或摄影材质，而元素渲染成扁平 CSS 或干净矢量，无论位置多对都是contradicted——介质本身就是承诺的一部分。
• GROUND（底色）：页面场域的值与色温对照 comp，工具允许时从两侧像素采样而非凭记忆判断；纹理或瓷砖覆盖底色时按屏幕净效果读取。底色比 comp 暖或冷都是contradicted，且要专门追查"向先前还原漂移"的方向（浅底漂向暖奶油、深底漂向蓝黑石板）。

无批准 comp 时的降级规则：TYPE 与 MATERIAL 不缺席——改以合约的 OWN-WORLD 与世界的真实材质为判据，且"假装物理"（CSS 斜面、压花、模仿页面从未渲染的材质的冲压金属或粉笔效果）一旦出现即按contradicted处理："模仿材质是机器制造设计最可靠的单一标志"。GROUND 则收窄而非缺席：OWN-WORLD 点名了颜色就以该色为目标做同样的冷暖判定；未点名时无 GROUND 权威，审查者须在判定位置如实说明而非给出结论——"审查者自己发明的目标会把检查变成口味问题"。

批判性参考 comp 是挑衅而非规格：不建元素矩阵、不引用改编、不负资产义务，它唯一的贡献是"图像敢于做而构建没做的"，值得采纳的大胆之处作为普通有序修复进入material_fixes。改编只有在引用了强迫它的用户回答、surface brief、无障碍需求或产品事实时才被算作有意的；无引用依据的偏差就是缺陷。

三条铁律：缺失的标志性元素、改变的拓扑、未经批准添加的内容直接判定保真度失败，在material_fixes中压过一切工艺点；当焦点元素的 MATERIAL 被判定contradicted、或矛盾是整页性的而非例外时，停止逐条修补——第一条材质修复必须是重建指令（rebuild directive），点名需要重新推导的 comp 区域与需要产出的资产，因为"对着被否决的页面列补丁清单等于把否决洗白成批准"；需要产出资产的修复必须明说（"produce: as a raster asset"），绝不能表述成父代理会用 CSS 应答的样式调整。

最后一条边界：comp 是构图、拓扑、元素清单、密度、字形性格与材质的规格，不是语义、无障碍或响应式重排的像素规格；该余地只覆盖翻译，绝不覆盖替换。

Check 3：天花板（Ceiling）——对照 QUALITY BAR card

点名世界原生的、构建未用到的设备；审视取景（frame）、深度（depth）、字形处理、装饰密度、动效。卡片约束的是承诺度与完成度，绝不约束构图。

Check 4：合约逐条对账（Contract, promise by promise）

先验证 FORM 携带概念掷点（concept roll）打印的 seed key；无 seed key 或父代理无法佐证 → 掷点被跳过，这是先于一切工艺点的材质性修复。然后对五个块逐一问：渲染守住了承诺吗？对首屏应用"记忆测试"（memory test）——不看屏幕能否复述其内容。

Check 5：真实性（Truth）——演示数据与资产是否诚实

演示数据须以合成身份撰写并标注；无虚构商业主张；未回答的主张以标记的占位符呈现而非省略。spec 的每个栅格区域必须以**plate（素材版）**形式发货——spec 点名文件、页面引用它、该区域的 diff 行不是missing——而不是用渐变、内联 SVG 或多顶点clip-path顶替；每个产出的资产必须在截图中肉眼可见。以近零透明度应用、或被洗色层埋掉的资产是"合规凭证"而非已发货的材质；包中的buried-raster与organic-clip-path发现直接就是材质性修复。

这两条 detector 规则在 crates/core/src/browser/quality.rs 中有实现证据：第 215–244 行即buried-raster分支——元素计算后透明度opacity < 0.15且为<img>或带背景url()时命中（"[raster] at opacity 0.x"）。organic-clip-path的判定标准（10+ 个离网格顶点的clip-path: polygon()，或 3+ 曲线段的path()）在 docs/COMP-FIDELITY.md 第 5 节有完整定义，几何裁剪（切角、对角线、六边形、箭头）与circle()/inset()均通过。

Check 6：工艺底线（Floor）——照 Refuse 清单对质

读取工艺底线的 Refuse 清单并拿截图对质：skill/reference/craft-floor.md 列出的被禁元素包括标题上方的 kicker/eyebrow（这条是"禁令而非默认"：没有 brief 能赢回它）、非新粗野主义世界中的硬偏移阴影（box-shadow: 4px 4px 0）、字形图标（glyph icons）、系统展示字体、渐变文字、色条侧边线等。关键规则：被禁元素即使是材质性修复，即使与 comp 中任何内容都不匹配——"构建者在写它之前就加载了同样的禁令，对 comp 的忠实不能授权工艺底线所拒绝的东西"。

父代理的 hooks 在启用时会机械覆盖这些检查；本检查之所以存在，是因为无 hook 的宿主到达审查者这里时一个发现都没有——"最近两次 live 会话中，五个 kicker 越过了一个从未看过的审查者"。

文档还专门强调：不要跑第二遍 detector 通道——机械性发现属于父代理的 hooks。

五、裁定（Disposition）：只有四个词

返回的第一行是disposition: recapture、disposition: rebuild、disposition: fix或disposition: ship之一。这四个词是全部词汇表，绝不发明新词。裁定是推导出来的，不是感觉出来的：

• recapture：证据检查失败时；
• rebuild：重建指令条件触发时（保真度整体性失败而非局部可修补）；
• fix：material_fixes非空时；
• ship：仅当矩阵中没有contradicted或missing行时。

校准对象是批准 comp 与世界的质量标杆，绝不是构建中可见的努力程度："设计总监会退回的页面，无论多能用，至多是 fix；焦点工艺远低于 comp 的页面，无论结构多完整，都是 rebuild。"父代理原样汇报你的裁定词，无权软化它。

六、输出契约（Output Contract）：先裁定，后五节

先返回裁定行，然后严格返回五个章节：

1. persistence：通过/失败，附具体细节；
2. fidelity：元素矩阵——每个显著元素标 match、adaptation、missing、contradicted 或 added without approval，改编必须引证其证据，或整体写 "faithful"；
3. ceiling：未用的原生设备，或 "reached"；
4. material_fixes：按重要性排序（最多八条，保真度失败压过工艺点），每条一行并绑定某个检查或合约承诺；
5. keep：一行说明修复期间绝不能稀释的东西。

recapture 返回以 check 0 的单一recapture章节替换上述五节。缺失输入在章节上方用一行说明。不要赞扬，不要总结性散文。

七、裁定后的行动：父代理如何响应四个词

new-work.md第 143 行给出了父代理对每个裁定词的响应义务：

• recapture：证据失败而非构建失败。按返回中点名的捕获有效性规则重新捕获，然后基于新证据做完整复审。"基于无效证据的审查不约束任何事，裁定通过永远不能跟在它后面。"
• rebuild：保真度整体失败而非可修补。跳过修复批次立即执行重建：重新推导点名区域、产出点名资产，送回做全新的完整审查（重建整体替换区域，整个矩阵要在新截图之上重跑），绝不是裁定通过。要告诉用户正在发生什么，而不是请求允许去修一个失败；只在第二次重建指令、两个判定同时摆在桌上、或重建会丢弃用户已批准内容时，才咨询用户。
• ship：无欠账；按裁定范围汇报并继续交给 documenter。
• fix：将材质性修复合并为一个批次、重建一次、在相同文件上重新捕获相同视口。注意：重新捕获只能测量位置、加载与溢出，测不到修复是否达到该发现点名的质量，因此要把新截图送回同一审查者做裁定通过评分（verdict pass）。

两道轮次（two rounds）是无人工运行结束的预算；有人的会话上限属于用户——第二次裁定仍列有未决项时，把表摆在用户面前，让其在"照此发货"与"再投一轮"之间选择。无论谁决定，一旦某轮毫无进展就停止；你只按审查者的发现清单工作，绝不重开自己的缺陷搜寻。另外两条资产规则：任一修复/重建轮次创建或替换的栅格资产仍属visualize.md的 Produce 章节，保留与所有构建栅格相同的来源可溯（provenance）；轮次放弃的栅格在同一批次中删除。送审前需对资产目录运行impeccable embed-prompt --scan <asset-dir...>，清掉所有缺 prompt 嵌入的文件。

最终汇报必须用审查者自己的裁定词、在其实际范围内进行。用户以证据回应 ship 时——他们自己的截图、与 comp 命名的偏差——该证据压过你做过的所有捕获：把用户材料放进输入包，召唤全新审查者做新的完整审查。"就地补丁并自我认证，是让被否决的页面发货两次的方式。"

八、裁定通过评分（Verdict Pass）：打分，而非重新狩猎

当父代理带着修复后的重新捕获返回时，审查者进入评分模式——打分，不是重新狩猎。三个条件会把你带出评分模式：

1. 重新捕获未通过 check 0 → 与审查轮完全相同的disposition: recapture；
2. 跟随重建指令而来的返回 → 新的完整审查（重建整体替换区域，只评指令会放过重建遗漏的一切）；
3. 携带与先前裁定相矛盾的用户提供截图的包 → 以用户截图为第一证据的新完整审查（"用户对真实页面的截图压过父代理摆放的每一张捕获"）。

评分规则：父代理在你审查轮读过的同一批截图文件上重新捕获，所以要重读这些确切路径——"你发明的带轮次戳的文件名指向虚无"。父代理对修复内容的叙述不是证据；你在新截图中看不到的所谓修复就是未解决。对审查轮每条材质性修复输出一行：resolved、partial或unresolved，绑定新截图肉眼可见的事实——"被机械化应答的修复，位置挪了但发现点名的质量依然缺席，至多是 partial"。然后点名修复批次自身引入的至多三个回归（用同一套矩阵规则判定），除此之外什么都不做：不新狩猎、不新检查。

返回恰好两个章节：verdict（逐条评分列表）与remaining（仍开放项，或 "clear"），最后以对开放项重新计算的裁定行收尾，沿用同一个四词词汇表。未解决或部分解决的材质性发现永远不能重算为 ship；在这里赢得的 ship 覆盖的是被评分的修复，不是整个表面——必须照此如实陈述。

九、收尾工作流的完整链路与测试佐证

Finish Reviewer 是 Impeccable 收尾工作流的第二道闸门：构建轮两次检查后不再自行修缺陷（"新上下文找发现更便宜更好"），在 web 上先跑一次impeccable detect --json处理机械项，截图进.impeccable/review/，然后把剩余发现连同完整输入包交给审查者；native 平台跳过 detector（它只读 HTML/CSS，对原生代码无判定力），审查者的工艺底线检查成为唯一的 slop 闸门（见 skill/reference/new-work.md 第 139–141 行）。

这条链路有专门的测试守护：tests/skill-workflow/finish-handoff.test.mjs 模拟"合成的事后审查检查点"（synthetic post-review checkpoint）——一个已通过"桌面/移动捕获已验证、detector 运行过一次、发货的 finish reviewer 返回 ship 且无未决发现"的工作区，验证在 extension / new world / redesign 三种模式下，续跑流程是否正确保留或记录其视觉系统。而 tests/skill-behavior-harness.test.mjs 则守护降级文件的解析正确性（无未解析占位符、含降级前言）。

从工程实现看，审查者所依赖的"测量先行"证据链由impeccable comp-diff、comp-spec、build-phase三个动词支撑，Rust 实现位于 crates/comp-verbs/src/lib.rs（"四词"释义见该文件头注释：comp-spec、comp-diff、font-match、build-phase四个 orchestrator，纯comp基础加common注入）。phase 状态机定义于 crates/comp-verbs/src/build_phase.rs：第 27 行的 phase 序列["comps", "spec", "plates", "hero", "sections", "motion", "responsive", "review"]、第 29 行的HERO_MIN: f64 = 0.72（即审查者 check 1 引用的 0.72 阈值）、第 103–134 行new_state对 comp-led 构建将comps置为skipped并记录理由、第 1017 行起的gate_hero依次校验首屏捕获存在、未引用 plate（"页面用代码画该区域而产出的 plate 闲置"）、捕获帧尺寸与整体评分。审查者在 check 1 读的 state、check 2 读的 diff 报告，正是这套状态机写下的。

十、给集成者的要点清单

1. 永远单独召唤：审查者绝不运行在构建线程内，绝不用分叉的会话历史（fork_turns: 0）；无子代理能力时才以行内降级模式替代，并披露。
2. 证据先于判定：缺一张必需截图 =recapture，畸形证据上永不出裁定。
3. 矩阵三行必填：TYPE、MATERIAL、GROUND；无 comp 时按 OWN-WORLD 与真实材质判定。
4. 整体失败用 rebuild，局部失败用 fix：对否决的页面列补丁清单是洗白否决。
5. 四个词是全部词汇：recapture / rebuild / fix / ship，汇报原词，无权软化。
6. 评分模式边界：重读同一批文件、叙述不是证据、最多三个回归、未决项永不重算为 ship。

Finish Reviewer 的价值不在于多聪明，而在于位置：它是用户面前的最后一道闸门，"不是替同事向同事软化消息的人"。有了这道闸门，构建轮才能放心地把"打磨"结束在某个点，把剩余问题交给一个不会继承构建者乐观情绪的独立上下文去发现——这正是本仓库在 docs/COMP-FIDELITY.md 中所记录的设计动机："每一处保真度检查都曾由模型凭记忆自评复现，散文越写越长却论证不出它无法执行的行为；现在像素翻译交给机械测量，模型的判断交给结构、语义、控件与动效，审查者的眼睛交给测量测不到的字形性格与材质。"

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