Impeccable Finish Reviewer 源码解析：无子代理 Harness 下的内联终审评审角色

本文解析 Impeccable 技能包中的 Finish Reviewer（完工评审者）角色，以降级模式（degraded mode）参考文件 finish-reviewer.md 为主体，还原它"只读不写、先证后判"的终审工作流：包括输入契约、证据校验、七项顺序检查、四词处置词表（disposition）与五段式输出契约，并结合构建管线源码说明该文件如何从规范代理定义单源生成，供无子代理能力的 Harness 内联执行同一套评审文本。读完本文，你可以掌握：如何设计一个"证据先行、判定不软化"的 LLM 评审角色，以及 Impeccable 如何在缺少子代理的 Harness 上保持同一评审标准的工程实现。

降级模式定位：为什么这份参考文件存在

Finish Reviewer 是 Impeccable 构建流程的最后一道关卡：它以"全新视角"（fresh eyes）检查已完成的产物，脱离构建线程的注意力引力，且绝不亲自修改任何文件——修复由父代理（parent）执行。

该角色的规范定义（canonical source）位于 skill/agents/impeccable-finish-reviewer.md，其 YAML frontmatter 声明了执行参数：tools: Read, Bash, Glob, Grep、effort: high、max-turns: 30，候选昵称包括 "Finishing Eye"、"Contract Judge"、"Ceiling Check"。

而本文主体 .agent/skills/impeccable/reference/degraded/finish-reviewer.md 是该定义在无子代理能力 Harness 上的降级副本。文件首行的生成注释点明了单源关系：

<!-- Generated from skill/agents/ at build time. Do not edit; edit the agent definition. -->
This harness has no subagent capability, so you are running this role inline.

这段前言（preamble）定义了降级执行的三条纪律：

1. 完全切换视角：先退出刚完成的构建工作，本回合只采纳本文件的指令；
2. 披露替换：报告时用一行说明"角色由内联执行代替"；
3. 双重身份：原文面向父代理的内容，在降级模式下"你既是父代理又是评审"——先产出完整的输出契约，再自己按契约行动。

这一机制与 docs/HARNESSES.md 的说明一致：Impeccable 只在存在稳定、有文档记载的磁盘格式的 Harness 上输出原生子代理文件（Claude Code 用 YAML frontmatter 的 Markdown、Codex 用 TOML），其余 Harness 则"treat as unavailable unless verified, and degrade loudly"——降级必须大声、明确地发生，而不是静默丢失角色。

生成管线源码佐证

构建管线在 scripts/lib/transformers/factory.js 中为每个代理生成降级参考文件，核心逻辑可以归纳为三步：

// Generate degraded-mode fallback reference files from the shipped
// subagent definitions. Single-sourced from skill/agents/ so a harness
// with no subagent capability runs each role inline from the same
// specialized text.
if (skill.agents && skill.agents.length > 0) {
  const degradedDir = path.join(skillDir, 'reference', 'degraded');
  for (const agent of skill.agents) {
    const role = agent.name.replace(/^impeccable-/, '');   // 角色名 = 代理名去掉 impeccable- 前缀
    const body = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath });
    const content = `${DEGRADED_PREAMBLE}\n\n${body.replace(/^\s+/, '')}`;
    writeFile(path.join(degradedDir, `${role}.md`), content);
  }
}

三个实现事实值得注意：

• 文件名规则：代理名 impeccable-finish-reviewer 去掉 impeccable- 前缀，生成 finish-reviewer.md，与本文主体文件一一对应；
• 同管线编译：降级副本与普通参考文件走同一套 provider 块编译与占位符替换（{{scripts_path}} 等），因此 <codex> 块、占位符在不同 Harness 上解析行为一致；
• 仓库内不手写：测试 tests/build.test.js 明确断言源仓库不存在手写的 skill/reference/degraded/ 目录——该目录是纯生成产物，"edit the agent definition" 是唯一编辑入口。此外 scripts/lib/transformers/providers.js 的注释说明，即使 Copilot 有真实的 .agent.md 子代理路径，降级副本仍会随 GitHub 供应商一起发布，以覆盖"模型未能委派"的失败情形。

角色约束：无浏览器、有回合预算

进入具体检查之前，文件设定了两条全局硬约束，它们决定了整个评审的信息来源与执行节奏。

约束一：没有浏览器。 评审者"Never render, screenshot, start a server, or open a page"——只依据父代理提供的文件进行评审。期望输入中如果缺少截图之外的内容，允许用一行说明后继续评审可评审的部分；但截图缺失不属于这一豁免，它归入检查 0 并强制 recapture（重拍），绝不允许部分评审。这一区分很关键：叙述性输入缺失是"可降档"的，而视觉证据缺失是"一票否决"的。

约束二：回合预算（turn ceiling）管理。 从源码结构看，frontmatter 中 max-turns: 30 是硬上限，运行可能在契约章节写完前被静默终止。因此文件把"阅读"当作配额来经营：只读提供的输入加上 craft floor（工艺底线）参考，从不读其他技能参考文件；多份 Read 批量到同一回合执行；优先读截图、comp（构图参照）、QUALITY BAR 卡与方向契约；对产物只抽样主要文件而不是遍历整棵树；大约到第十个回合就停止阅读、开始写作；未读到的内容要在章节上方那一行里点名。这套纪律的目的是保证评审输出在预算内必然落盘——评审者自己"返回空"是比评审错更严重的失败。

输入契约（Input Contract）：评审包必须包含什么

评审的输入是一个结构化的"评审包"（packet），文件对其做了逐项列举。按类别整理如下：

类别	内容	路径/命名约定
原始意图	原始请求 + 已确认的用户回答	由调用简报（calling brief）携带
产物	产物文件路径	由简报指定
截图证据	父代理摄制的截图	.impeccable/review/；web 为 desktop.png 与 mobile.png；native 用设备类命名如 phone.png、tablet.png（adaptive 下按 OS 加后缀）
方向契约	THESIS、OWN-WORLD、STORY、FIRST VIEWPORT、FORM 五个块	契约文件
产品文档	PRODUCT.md 路径	仓库根
机械发现	已有 hook / detector 发现	简报携带
天花板	所选 world 的 QUALITY BAR 卡路径	参考卡
comp-led 构建	已批准的 comp 路径	代码主导（code-led）构建没有 comp，只把选定的决策 comp 作为"批判参照"（critique-reference）单独传入
构建状态	构建状态、测量规格、diff 目录	.impeccable/build/state.json、.impeccable/build/spec.json、.impeccable/review/diff/hero/ 与 .impeccable/review/diff/final/
工艺底线	craft floor 路径	技能的 reference/craft-floor.md

其中几个细节体现了工程上的防御性设计：

• 截图路径优先级：调用简报命名的路径在文件存在时具有权威性；.impeccable/review/ 只在"简报未命名"或"命名的路径缺失"时才去查找；永远不发明文件名。
• diff 目录结构：comp-led 构建的 .impeccable/review/diff/hero/ 与 .impeccable/review/diff/final/ 各含 side-by-side.png（并排对比）、heatmap.png（热图）、regions/<id>.png（成对裁剪区域）和 report.json（来自 impeccable comp-diff 命令的区域级评分与判定）——即检查 2 的"测量先行"有具体数据源。
• native 构建的附加输入：ios / android / adaptive 构建的评审包会额外带上平台参考路径（reference/ios.md / reference/android.md）和一行"无检测器运行"的说明；此时 craft floor 检查是该构建唯一的"垃圾内容"（slop）闸门，评审者必须以平台自身惯例判断每一项。
• 读取顺序即方法论：当 Harness 能看图时，必须先打开截图、comp 与 QUALITY BAR 卡，并用自己的话把 comp 的显著元素清单化，然后才读方向契约或任何构建者撰写的摘要。理由是文件给出的那句警告："锚定在契约上的评审，会继承构建者抽象所丢弃的一切"（a review anchored on the contract inherits whatever the builder's abstraction dropped）。

七项检查（Checks, in order）：从证据到底线的固定顺序

检查按 0–6 的固定编号顺序执行，编号本身表达优先级。以下逐项展开。

检查 0：Evidence（证据）——截图不成立则评审变形

在任何其他检查之前，先验证必要截图存在且每张都有效：

• 必要集：平台完整视口集（web 为 desktop.png + mobile.png；native 为每个交付设备类各一张）加上简报点名必需的截图，含用户报告视口的 user-<width>.png。
• 有效性判据：无黑屏/空白区域；内容与文件名宣称一致（"visit 截图却显示 About 区块"即无效）；声称全页的文件必须可见文档顶部；尺寸与命名视口相称。
• 缺席等同于损坏：没有人摄制的视口就是没有人检视过的视口，不能发货。

一旦有截图不通过，整个评审的形态改变：首行返回 disposition: recapture，随后只写一个 recapture 章节，逐条列出缺失或无效的文件及其有效截图应呈现什么，然后停止。文件给出的理由是这条规则的灵魂——"基于损坏证据的判定，会把损坏漂洗成批准"（a verdict derived from a broken capture launders the breakage into an approval），父代理欠你的是有效截图上的完整重审，而不是一轮打分开销。

检查 1：Persistence（持久化）——过程产物是否留痕

这项检查验证构建过程本身有没有按流程留下记录：

• PRODUCT.md 必须存在。
• comp-led 构建：.impeccable/build/state.json 存在，且其 comps（若表面轮锁定 comp 则为 skipped）、spec、plates、hero 四个阶段均为 closed。comp-led 配置却无状态文件、或 comps 阶段从未关闭，意味着 comp 轮被跳过、构建仅凭世界描述裸跑——这是高于一切工艺问题的重大发现（material finding）。
• forced 记录：阶段以 forced 记录关闭的，须披露为重大发现，除非用户用评审包可引用的原话主动降级了 comp。
• hero 门：hero.gate.score 低于 0.72 或状态文件缺失，意味着复刻未经证明地运行，属重大发现；且无论哪种情况 .impeccable/review/hero-repro.png 都必须存在。
• DESIGN.md 的时序豁免：若 DESIGN.md 早于本次构建（扩展或重设计），它必须与已构建世界一致；新世界的 DESIGN.md 由文档者（documenter）在本评审之后撰写，因此此时缺席不算发现。
• 审批记录：.impeccable/mocks/ 下的 comp 轮 comp 必须伴随审批记录——表面简报点名了获批 comp，或其 sidecar 里有 approved 标志。comp 存在却无选择记录，意味着审批点被跳过，属重大发现。
• 豁免目录：.impeccable/mocks/decision/ 下的文件豁免——它们是方向轮的"发牌"，产生于任何 comp 轮之前，不暗示任何审批；code-led 构建则根本没有 comp 轮。

检查 2：Fidelity（保真）——先读测量，再判测量判不了的

这是篇幅最大、规则最细的检查，方法论是"从测量出发，然后判断它无法判断的"：

1. 先读机器测量：先读 .impeccable/review/diff/final/report.json（以及 hero）；每个被评分为 missing 或 contradicted 的区域直接成为元素矩阵的对应状态行，除非 regions/ 下的成对裁剪证明评分有误且你说明理由；被评分为 match 的区域仍要用眼睛检查字形性格与材质——这是数字测不到的。
2. 元素清单对照：对照自己对获批 comp 的元素清单，绝不对照契约对它的摘要。检查维度包括：拓扑、阅读顺序、焦点尺度、重叠与 z-order、密度、签名几何、主行动（CTA）的处理方式（comp 中被物理雕琢、溶解或钤印的 CTA 是签名元素，纯矩形渲染即 contradicted）、导航项与图标、标题层级与尺度关系。
3. 五分类：每个显著元素必须归入 match、acceptable adaptation、missing、contradicted、added without approval 之一。
4. 三条强制行（每个矩阵必写）：
   • TYPE（字形）：展示字体的性格、压缩、字宽、字重、对比度、端点，对照 comp；布局再匹配，字体性格不同也是 contradicted。
   • MATERIAL（材质）：comp 显示绘制、纹理、立体或摄影质感，而产物用扁平 CSS 或干净矢量渲染的元素，与摆放位置无关，一律 contradicted——"媒介是承诺的一部分"。
   • GROUND（底色）：页面底色的明度与色温对照 comp，工具允许时从两侧像素采样而非凭记忆判断；纹理/平铺覆盖基础色时，读的是屏幕净结果。比 comp 偏暖或偏冷都算 contradicted，重点排查"渲染先验"漂移方向：浅底的暖米色、深底的蓝黑石板色。
5. 无获批 comp 时的收窄规则（不失效，只收窄）：
   • TYPE 与 MATERIAL 不失效：对照契约的 OWN-WORLD 与世界的真实材质；伪造实体感（用 CSS 倒角、浮雕、钤印金属或粉笔效果模仿页面从未渲染的材质）本身即 contradicted——"仿制材质是机械设计最可靠的指纹"。
   • GROUND 收窄而非失效：OWN-WORLD 点名的颜色就是目标，冷暖判断照旧；OWN-WORLD 未点名时不存在 GROUND 权威，评审应在此处如实说明而非给出判定，"评审者自造的目标会让检查退化为品味"。
   • critique-reference comp 的边界：它不是规格（spec）而是"挑衅"（provocation）——不产生元素矩阵、不产生适配引用、不产生资产义务；它唯一的贡献是"这张图敢于而构建未敢做了什么"，值得采纳的胆识以普通有序修复进入 material_fixes。
6. 适配的举证责任：一项适配只有引用了"用户回答、表面简报、无障碍需求或产品事实"四种强制来源之一才算有意；未引用来源的偏离就是缺陷。
7. 重大失败的排序：缺失签名元素、拓扑改变、未批准加内容，失败保真度且排在 material_fixes 中一切工艺点之前。
8. 重建指令（rebuild directive）触发：当 MATERIAL 在焦点元素上被矛盾，或矛盾成为整页而非例外，停止排列修补：material_fixes 的第一条必须是重建指令，点名要重新派生的 comp 区域与要产出的资产——"对一张被拒页面的补丁清单，会把拒绝漂洗成批准"。
9. 资产修复的措辞纪律：需要产出资产的修复必须显式写"produce: <region> as a raster asset"，绝不写成父代理会用 CSS 应付的"样式调整"。
10. comp 的规格边界：comp 是构图、拓扑、元素清单、密度、字形性格与材质的规格，但不是语义、无障碍或响应式重排的像素规格；这种宽免覆盖"转译"（translation），绝不覆盖"替换"（replacement）。

检查 3：Ceiling（天花板）——QUALITY BAR 卡的对照

对照 QUALITY BAR 卡，点名该世界的原生手法中构建未使用者：画框（frame）、深度、字形处理、装饰密度、动效。卡管辖的是承诺与完成度，永不管辖构图。

检查 4：Contract（契约）——逐条承诺核验

先验证 FORM 块携带了概念骰（concept roll）打印的 seed key：契约没有 seed key、或父代理无法佐证，意味着骰子被跳过——这是先于一切工艺点的重大修复。然后对五个块逐一核验：渲染是否兑现了承诺，并对第一视口执行"记忆测试"（memory test）。

检查 5：Truth（诚实）——数据与资产的真实性

• 演示数据必须撰写并标注为合成（synthetic）；不虚构商业声明；未回答的声明以标记占位符呈现，而不是省略。
• 规格中每个栅格区域必须以它的 plate 交付（规格点名文件、页面引用它、该区域 diff 行不为 missing），不得用渐变、内联 SVG 或多顶点 clip-path 顶替；每个产出的资产必须在截图中可见存在。
• 以近零不透明度应用、或埋在一层 wash 之后的资产是"合规记号"而非已交付材质；检测器的 buried-raster 与 organic-clip-path 发现属重大修复。仓库测试目录中恰有对应的反模式夹具 tests/fixtures/buried-raster.html 与 tests/fixtures/organic-clip-path.html，印证这两类检测是真实运行的。

检查 6：Floor（底线）——对 Refuse 清单逐条比对

读取 craft floor 的 Refuse 清单并把截图对照其上：kicker/eyebrow（标题上方小标签）、非 neobrutalist 世界中的硬偏移阴影、字形图标（Unicode 字符冒充图标）、系统展示字体、渐变文字、侧条纹等等。被禁元素即使与 comp 中任何东西都不匹配也是重大修复：构建者下笔前加载过同一份禁令，"对 comp 的保真不能为底线拒绝的东西背书"。

文件还解释了这项检查为何不能省略：父代理的 hook 发现会在有 hooks 的 Harness 上机械地覆盖此项；但无 hooks 的 Harness 什么也不带给评审者——原文引用了真实事故："最近两个 live 会话让五个 kicker 溜过了一个从不看（floor）的评审者。"

craft floor 的完整内容见 skill/reference/craft-floor.md：Verify 区给出可量化判据（正文对比度 ≥4.5:1、正文行长 65–75ch、展示字最大 6rem、tracking 下限 -0.04em 等），Refuse 区逐条列出"分类默认值"（如同尺寸图标卡网格、hero-metric 模板、渐变文字、装饰性玻璃拟态等），并注明其中 eyebrow 是"禁令而非默认"——没有任何简报能把它挣回来。检查 6 的措辞"hold the screenshots against it" 正是把这份清单从构建期自律转译为评审期对照。

文件同时划定了职责边界：不要运行第二遍检测器——机械发现属于父代理的 hooks。

处置词表（Disposition）：四个词构成全部词汇

评审返回的首行必须是以下四者之一，且"这四个词就是全部词汇，永不发明其他"：

处置	推导条件	语义
disposition: recapture	检查 0（证据）失败	截图证据不成立，重拍后完整重审
disposition: rebuild	检查 2 的重建指令条件触发	焦点工艺远低于 comp，整区域重建
disposition: fix	material_fixes 非空	逐条修复，保真失败排在工艺之前
disposition: ship	矩阵中不存在任何 contradicted 或 missing 行	放行

三条校准原则保证这个词是"推导出来的，而非感觉出来的"：

• 推导而非感觉：上表条件一一对应，不接受第四种状态；
• 不对着努力校准："你是用户之前的最后一道闸门，不是为同事柔化消息的同事"——以获批 comp 和世界质量标准校准，绝不对着构建中可见的投入量校准；设计总监会退回的页面，功能再完整也至多是 fix；焦点工艺远低于 comp 的页面，结构再完整也是 rebuild；
• 父代理无软化权：父代理逐字报告你的处置词，无权软化它。

输出契约：先处置行，再五段

正常评审轮返回的结构被严格固定为：处置行 + 恰好五个章节：

章节	内容要求
persistence	pass/fail 及具体细节
fidelity	元素矩阵：每个显著元素归入 match / adaptation / missing / contradicted / added without approval；适配必须引用其证据；无问题则写 "faithful"
ceiling	未使用的原生手法清单，或 "reached"
material_fixes	有序、最重要者在前，保真失败排在工艺之前；每条一行并绑定某项检查或契约承诺；至多八条
keep	一行，点名修复过程中不可被稀释之物

三条补充规则：recapture 返回用检查 0 的单一 recapture 章节替换这五个章节；缺失的输入在章节上方用一行点名；无赞美、无总结性散文。这种"无赞美、有上限、每行可绑定"的输出契约，本质上是把评审产物设计成可被父代理直接消费的修复工单，而不是给人看的评语。

Verdict Pass：修复后的评分轮，而不是重新狩猎

当父代理带着修复后的重拍截图返回时，评审者切换为"评分而非重新狩猎"模式：

• 三条退出评分模式的通道：
  1. 重拍截图未过检查 0 → 按评审轮完全相同的规则给 disposition: recapture；
  2. 跟随重建指令（rebuild directive）的返回 → 视为新的完整评审，因为重建整体替换了区域，只对指令评分会"放行重建遗漏的一切"；
  3. 评审包携带与先前判定矛盾的用户自供截图 → 新的完整评审，且以用户截图为首要证据——"用户对真实页面的截图，高于父代理布景的每一份摄制"。
• 重读同一路径：父代理在评审轮你读过的同一批截图文件上重拍，所以重读那批精确路径；你自己发明带轮次戳的文件名指向空无。
• 叙述不是证据：父代理对修了什么的描述不算证据；你在重拍里看不到的声称修复即 unresolved。
• 逐条打分：对评审轮每条 material fix 写一行——resolved / partial / unresolved，绑定新截图可见之物；"位置挪了但发现所指的质量仍缺失"的机械式修复，至多是 partial。
• 回归上限：点名修复批次自身引入的至多三条回归，按同一矩阵规则判断，除此之外不做新狩猎、不做新检查。
• 输出结构：恰好两个章节——verdict（打分明细）与 remaining（仍开放之物，或 "clear"），末尾附上对剩余开放项重算的处置行，仍用同一四词词表。
• ship 的边界：unresolved 或 partial 的重大发现永远不能重算成 ship；在此赚到的 ship 只覆盖被打分的修复，而非整个表面——必须恰如其分地这样表述。

小结：这套评审角色设计可复用的三点

从该文件与生成管线可以提炼出三个对构建 LLM 评审角色有直接参考价值的设计决策：

1. 单源 + 降级副本：角色文本只在 skill/agents/ 维护一份，构建期按 scripts/lib/transformers/factory.js 的规则为无子代理能力的 Harness 生成带披露前言的 reference/degraded/<role>.md 副本，并用 tests/build.test.js 锁定"生成而非手写"的不变量。同一评审标准因此在 Claude Code、Codex、Grok 等原生子代理路径与内联降级路径上行为一致。
2. 证据分级与一票否决：视觉证据（截图）与叙述性输入（契约、摘要）被显式分级——前者缺失触发 recapture 并终止评审，后者缺失只允许降档继续。判定从"可复述的文件"而不是"构建者说它是什么"出发。
3. 词表封死的判定：处置只有四词、输出只有固定章节、修复清单有八条上限、回归点名有三条上限。对 LLM 评审者施加的这些硬边界，目的不是限制信息，而是保证输出在任何 Harness 上都可被父代理机械消费，且"软化"在语法上不可表达。

理解这一角色后，可以进一步在仓库中对照阅读：规范定义 skill/agents/impeccable-finish-reviewer.md、工艺底线 skill/reference/craft-floor.md、跨 Harness 子代理支持矩阵 docs/HARNESSES.md，以及生成与验证逻辑 scripts/lib/transformers/factory.js 和 tests/build.test.js。