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

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 threads 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 files 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审查者只相信你传入的东西审查者无浏览器你未能传入的截图就是它无法执行的检查。一个完整的输入包应当包含类别内容说明背景原始请求、已确认的用户回答、产物路径重建审查的来龙去脉截图父代理捕获的截图位于.impeccable/review/Webdesktop.png与mobile.png原生设备类名如phone.png、tablet.png自适应平台按 OS 加后缀当用户视口被纳入检查集时还有user-width.png方向合约THESIS、OWN-WORLD、STORY、FIRST VIEWPORT、FORM 五个块定义这个页面承诺了什么文档PRODUCT.md 路径产品事实的唯一权威来源发现已有 hook 或 detector 发现机械性发现交给父代理的 hooks审查者不再跑第二遍 detector质量标杆所选世界的 QUALITY BAR card 路径决定天花板commitment 与 finishcomp-led 专属批准的 comp 路径.impeccable/build/state.json.impeccable/build/spec.json.impeccable/review/diff/hero/与.impeccable/review/diff/final/每个 diff 目录含side-by-side.png、heatmap.png、regions/id.png成对裁剪图以及带每区域评分与判词的report.json由impeccable comp-diff产出code-led 专属无批准 comp选中的决策 comp 作为独立的批判性参考输入传入并如实标注所有约束批准 comp的条款对它不生效native 专属平台参考reference/ios.md/reference/android.md路径 一行detector 未运行说明审查者按平台自身惯例判定把截图当作设备实拍此时它的工艺底线检查是构建唯一的 slop劣质痕迹闸门工艺底线reference/craft-floor.md路径七项检查中第 6 项的直接依据关于截图路径有一条重要的权限规则调用方 brief 点名的截图路径在文件存在时具有权威性brief 未点名或点名路径缺失时审查者才去.impeccable/review/查找绝不臆造文件名。此外当宿主能查看图片时审查者应先打开截图、comp 与卡片并用自己的话清点 comp 的显著元素然后才读方向合约或任何构建者撰写的摘要——基于合约的审查会继承构建者抽象过程丢掉的东西。new-work.md第 139 行补充了截图捕获阶段的规范将截图捕获到.impeccable/review/每视口一个文件传入审查者的路径就是它的规格你检查过的每个视口都要在包中标记为必需。四、七项检查从证据到工艺底线的顺序裁定审查按固定顺序执行七项检查前一项失败会直接改变整个审查的形态。Check 0证据Evidence——先于一切的截图像验任何其他检查之前先验证必需截图存在且有效。必需集合 平台完整视口集Webdesktop.pngmobile.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区主要看 detailtext区看 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重建指令条件触发时保真度整体性失败而非局部可修补fixmaterial_fixes非空时ship仅当矩阵中没有contradicted或missing行时。校准对象是批准 comp 与世界的质量标杆绝不是构建中可见的努力程度设计总监会退回的页面无论多能用至多是 fix焦点工艺远低于 comp 的页面无论结构多完整都是 rebuild。父代理原样汇报你的裁定词无权软化它。六、输出契约Output Contract先裁定后五节先返回裁定行然后严格返回五个章节persistence通过/失败附具体细节fidelity元素矩阵——每个显著元素标 match、adaptation、missing、contradicted 或 added without approval改编必须引证其证据或整体写 faithfulceiling未用的原生设备或 reachedmaterial_fixes按重要性排序最多八条保真度失败压过工艺点每条一行并绑定某个检查或合约承诺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打分而非重新狩猎当父代理带着修复后的重新捕获返回时审查者进入评分模式——打分不是重新狩猎。三个条件会把你带出评分模式重新捕获未通过 check 0 → 与审查轮完全相同的disposition: recapture跟随重建指令而来的返回 → 新的完整审查重建整体替换区域只评指令会放过重建遗漏的一切携带与先前裁定相矛盾的用户提供截图的包 → 以用户截图为第一证据的新完整审查用户对真实页面的截图压过父代理摆放的每一张捕获。评分规则父代理在你审查轮读过的同一批截图文件上重新捕获所以要重读这些确切路径——你发明的带轮次戳的文件名指向虚无。父代理对修复内容的叙述不是证据你在新截图中看不到的所谓修复就是未解决。对审查轮每条材质性修复输出一行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 报告正是这套状态机写下的。十、给集成者的要点清单永远单独召唤审查者绝不运行在构建线程内绝不用分叉的会话历史fork_turns: 0无子代理能力时才以行内降级模式替代并披露。证据先于判定缺一张必需截图 recapture畸形证据上永不出裁定。矩阵三行必填TYPE、MATERIAL、GROUND无 comp 时按 OWN-WORLD 与真实材质判定。整体失败用 rebuild局部失败用 fix对否决的页面列补丁清单是洗白否决。四个词是全部词汇recapture / rebuild / fix / ship汇报原词无权软化。评分模式边界重读同一批文件、叙述不是证据、最多三个回归、未决项永不重算为 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考