Impeccable `polish` 命令实战：发布前设计质量打磨的五阶段工作流

polish 是 Impeccable 设计技能（design skill）中 Refine 类别的核心命令，定位是“发布前的最后一道质量关”（final quality pass before shipping）。它不重写视觉世界，而是把既有界面沿着既有设计系统打磨到功能完整、状态齐全、细节一致。读完本文，你将掌握 polish 的完整五阶段工作流（建立系统、收集证据、分级分诊、沿整条路径打磨、验证收尾），并能结合仓库源码理解 critique 快照存储、slug 派生与检测器回退机制的实际实现，把 polish 真正用于你自己的前端项目收尾。

polish 的定位：refinement，never concealed redesign

polish 的第一原则写在 reference/polish.md 开篇：

• Polish 是精炼，绝不暗藏重设计。 必须保留在任（incumbent）的视觉世界、内容、行为，以及一切范围之外的东西。如果“概念本身就是错的”，应当直接说出来，并推荐 redesign 或 bolder，而不是把替换方案偷偷塞进 polish 里。
• 检测器结果是缺陷证据，不是质量证明。 不能因为扫描通过就认为质量达标，必须检查渲染后的真实体验与真实交互路径。

在 SKILL.md 的命令表中，politch [target] 位于 Refine 分类（与 bolder、quieter、distill、harden、onboard 并列），描述为 “Final quality pass before shipping”，对应引用文件即 reference/polish.md。文档开头还要求使用者先提供两类上下文：质量基线（quality bar）与交付约束（shipping constraints）——这两项决定了后面所有取舍的尺度。

阶段一：建立系统（Establish the system）

动手修任何漂移（drift）之前，先建立参照系：

1. 读取 DESIGN.md，以及代表性的设计 token、共享组件、既有模式与邻近流程；
2. 如果项目没有正式设计系统，就以项目内一致的约定（coherent project conventions）为准——注意 SKILL.md 强调“DESIGN.md 缺失不等于项目是 greenfield”，代码里的 token、组件与资产本身就是在任的设计权威。

随后对每一处漂移先分类，再修复，文档给出四种漂移类型：

漂移类型	含义	正确修法
missing token	系统需要一个可复用的值	把值提升为 token
one-off implementation	存在一次性实现，而系统里已有共享组件/模式	用共享组件替换它
conceptual mismatch	流程、信息架构或层级与同类产品区域不一致	对齐邻近区域的模型
local defect	实现本身不完整或不一致	就地修缺陷

修复原则是“在最窄的正确层级修因”（fix the cause at the narrowest correct level）：能用局部修复的不改系统，能用系统值的不在局部堆补丁。当无法从上下文推断出某个约束性系统原则时，问用户，而不是自己猜。

从源码结构看，这一步的上下文由 context.mjs 统一供给：它每会话运行一次，把 PRODUCT.md、DESIGN.md、匹配的 surface brief 与（如平台为原生）ios / android 平台参考一并输出，并在 DESIGN.md 缺失而代码中存在在任视觉实现时，输出 INCUMBENT_WORLD_UNDOCUMENTED 指令，提示“代码与资产是权威，缺失的 DESIGN.md 只是文档缺口”。这与 polish“没有正式系统就用项目约定”的原则一一对应。

阶段二：收集证据（Gather the evidence）

polish 不依赖“看一张截图”下结论，而是要求亲自使用这个功能，在表面的代表尺寸上走一遍真实路径：

• Web：桌面与移动端都要覆盖；
• 原生平台（ios / android / adaptive）：在模拟器、仿真器或真机上覆盖已发布的设备类（device classes），并按平台参考文档的 Verifying the build 一节采集——即 ios.md 与 android.md 中的同名小节。

走查时确定四件事：

1. 该路径功能上是否完整（是否真的做完了）；
2. 预期的质量基线（quality bar）与可用时间；
3. 已知约束，以及刻意未完成的工作（避免把“未排期”当成“缺陷”）；
4. 用户实际会遇到的状态、内容长度、角色与输入方式。

读取上一轮 critique 快照

如果之前跑过 /impeccable critique，用其输出作为其中一个输入：

node .agent/skills/impeccable/scripts/critique-storage.mjs latest "<resolved target>"

• 退出码 0：返回该目标最新一份快照，应纳入其中相关的 P0/P1 发现，并在汇报中点名你读的是哪份快照；
• 退出码 2：该目标尚不存在快照。
• 无论有无快照，都要独立再走一遍完整检查——快照只是 backlog，不是替代。

源码级实现：快照是怎么存的

critique-storage.mjs 的头部注释说明了这个机制：每次 critique 运行把一份快照写入 .impeccable/critique/<timestamp>__<slug>.md，附带记录分数与 P0/P1 计数的 YAML frontmatter；polish 工作流在启动时读取最新匹配的快照作为修复 backlog，没有别的 skill 会自动读 critique 输出。

关键实现细节：

• 快照文件名格式：critique-storage.mjs 中用正则 SNAPSHOT_FILENAME（UTC 时间戳 + __ + slug）匹配，时间戳经 nowFilenameStamp() 处理掉冒号，保证 Windows 文件系统安全；
• latest 子命令：readLatestSnapshot() 按文件名排序取最后一份；取不到时 CLI 以退出码 2 结束（critique-storage.mjs#L188-L193），这正是 polish 文档里 “Exit 2 means none exists” 的实现来源；
• slug 稳定性是趋势追踪的前提：slug 由解析后的主产物（文件路径或 URL）机械派生，绝不来自用户的自然语言措辞。target-slug.mjs 中 slugFromTarget() 会把相对路径或 URL 的 host+pathname 转成 kebab-case（URL 会去掉端口），超过 50 字符时保留尾部截断；空输入或项目根返回 null。因此命令要求传入 <resolved target>——即先把“首页”解析成具体文件/URL 再执行。

仓库中的 tests/critique-storage.test.mjs 对这些行为做了回归验证：路径/URL 的 slug 归一化、Windows 安全时间戳、write + latest 的 round-trip 等（测试直接 import skill/scripts/critique-storage.mjs，即 skill 源目录版本）。

P0/P1 的判定标准在 reference/critique.md 的 Issue Severity (P0–P3) 一节：P0 = Blocking（完全阻止任务完成，showstopper，立即修）；P1 = Major（造成显著困难或困惑，发布前必须修）；P2/P3 依次降低。critique 文档也明确快照的定位：“chat 回复是主要交付物，快照只是存档/backlog，供 /impeccable polish 免复制粘贴地继承优先级”。

阶段三：分诊（Triage）

把功能缺陷与外观缺陷分开，并严格按以下顺序修复：

1. 已损坏或被阻塞的任务、数据丢失、误导性状态、不可访问的路径；
2. 缺失的 loading / empty / error / success / disabled / permission 状态；
3. 流程（flow）、层级（hierarchy）、响应式（responsive）、设计系统漂移；
4. 视觉与动效不一致；
5. 代码与资产清理。

这条顺序的实质是“按用户价值降序”：先修会丢任务、丢数据的，再补齐状态机，然后才轮到与设计系统的一致性，最后才是纯外观与代码卫生。文档用一句收尾约束住常见偏科：“不要只把一个角落打磨到完美，而让其余部分停留在同一质量基线以下”。

阶段四：打磨整条路径（Polish the whole path）

这是 polish 的正文，按五个维度展开。注意其对象是“整条路径（the whole path）”而非单个屏幕。

流程与层级（Flow and hierarchy）

• 对齐邻近区域的心智模型：术语、披露方式（disclosure）、路由、保存行为、乐观/悲观更新模式；
• 让主任务与当前状态显而易见，但不把一切元素压成等权重；
• 到达（arrival）、过渡（transition）、空状态与恢复路径应连成一体，而不是行为像孤立屏幕。

布局与字体（Layout and type）

• 对齐项目的栅格与间距尺度；不仅修数学对齐，也修光学对齐（optical alignment）；
• 相关内容紧凑成组，不同组之间留足间隙；
• 同角色排版保持一致；测试行宽（measure）、换行、本地化文本膨胀、缩放与字体加载；
• 验证每一个支持的视口，而不是只修当前截图里的那一个。

颜色、图像与图标（Color, imagery, and icons）

• 使用语义 token，跨主题保持颜色含义稳定；
• 在每一个状态下验证文本、控件与焦点的对比度；
• 图标家族、描边/粗细、尺寸与光学对齐保持连贯；
• 防止图片引起布局偏移：正确的宽高比、响应式图源、有用的 alt 文本。

交互与状态（Interaction and state）

• 每个控件都需要得体的 default / hover / focus / active / disabled / loading / error / success 行为；
• 保留可见的键盘焦点、逻辑 tab 顺序、标签，以及平台适当的触控目标尺寸；
• 动效要连贯、可中断、性能良好；不要为了让“打磨”可见而加动画；
• 在产品真实会遇到长文本、缺失、本地化、离线、慢速、权限受限内容时，验证这些输入。

内容与代码（Content and code）

• 术语、大小写、标点与事实性文案保持一致；修改事实性声明之前先问；
• 删除调试输出、死代码、无用 import、过期样式，以及打磨过程中新产生的重复；
• 系统拥有该模式时，用共享组件替换自定义实现；
• 把真正可复用的值提升为 token；但不要为一个局部例外发明系统级抽象——这是阶段一“最窄正确层级”原则在代码层面的呼应。

可量化的机械底线：craft-floor

上述原则中有一部分带有硬性数值，集中维护在 reference/craft-floor.md（按 SKILL.md 的流程，它在编辑 UI 前加载，承载质量底线与检测器抓不到的反模式）。与 polish 直接相关的机械判据包括：

• 对比度：正文与占位符文本 ≥ 4.5:1，大字号文本 ≥ 3:1；彩色表面上的次要文本用该色相或前景色染色，而不是灰色；
• 排版：正文行宽 65–75ch，display 上限 6rem，字距（tracking）下限 -0.04em，标题均衡断行，明确的字阶与字重步进；
• 深度：阴影必须带偏移与柔和模糊，零偏移的彩色光晕属于装饰而非深度系统；
• 状态：hover、disabled、loading、error、empty 齐全，外加真实内容、可用控件、响应式构图与键盘焦点；
• 浏览器表面：文本选中、光标、自定义滚动条、焦点环、下划线偏移、表格数字字体等“你没画的部分”也要从调色板主题化——craft-floor 称这是“页面是被造出来而非拼出来的”最便宜信号，也是模型最容易跳过的一项。

这些数值正好为 polish 阶段四里“验证对比度/行宽/状态”等要求提供了可直接执行的验收标准。

阶段五：验证与收尾（Verify and finish）

再次走完整路径

用鼠标、键盘、触摸（如适用）把完整路径再走一遍，逐项核对：

• Web：移动、中间、宽屏布局；原生：手机与平板尺寸类，且两种支持的方向都要看；
• loading、empty、error、success、disabled、长内容、缺失内容各状态；
• 缩放（zoom）、对比度、焦点、语义、读屏名称；
• 控制台的报错、布局偏移（layout shift）、交互延迟、图片加载——在每一处；Web 覆盖支持的浏览器，原生覆盖支持的 OS 版本、运行时告警与掉帧；
• 与 DESIGN.md、邻近功能、以及用户声明的范围达成一致。

检测器与 hooks 的边界

polish 文档对自动检测划了明确的边界：遵循 context.mjs 与 hooks 提供的质量指引，然后运行其他相关的 QA 命令。具体规则是：

• 只有当没有自动检测器在运行时，context 才会请求一次人工扫描；永远不要额外添加检测器 pass；
• 修真实的缺陷，只对窄范围的刻意例外做记录；
• 干净的扫描不能替代视觉判断（与开篇“detector result is defect evidence, not proof of quality”首尾呼应）。

从源码看，这套逻辑在 context.mjs 中有直接实现：automaticHookMode() 先按平台判断（原生平台无 hook，因为检测器只读 HTML/CSS），再经 hookEnabledAt() 读取 .impeccable/config.json / config.local.json 的 hook.enabled，并检查各 harness 的 hook 清单是否注册了 hook.mjs；只有当 hook 完全不活跃时，appendDetectorFallback() 才会输出 MANUAL_DETECTOR_REQUIRED 指令，要求对改动的 Web UI 运行一次机械检测器：

node .agent/skills/impeccable/scripts/detect.mjs --json <changed targets>

并明确“只运行一次，且在概念选择期间不要提前跑”（context.mjs#L1400-L1409）。这就是 polish 文档中“Context requests a manual scan only when no automatic detector is active”的实现对应物。

以 source diff 收尾

最后交付一份源码级 diff：删掉意外引入的改动（churn）、孤儿代码、冗余值与临时产物。放行（ship）的条件是：功能完整，且整条路径上的一致完成度达标——而不是某个最亮眼的屏幕达标。

前提、限制与快速核对清单

• 运行环境：polish 依附于 impeccable 技能（当前仓库 SKILL.md 标注版本 4.1.2），命令依赖 Node 执行 .agent/skills/impeccable/scripts/ 下的脚本；仓库同时保留 skill 源目录 skill/reference/polish.md，.agent/skills/ 为安装/运行时副本。
• 适用平台：Web 项目覆盖桌面+移动端；ios / android / adaptive 项目按平台参考的 Verifying the build 覆盖设备类；原生项目没有机械检测器（检测器只读 HTML/CSS），验证完全依赖走查。
• 与 critique 的配合：critique 写快照、polish 读快照，两者通过 slug 关联；trend 子命令还能按同一目标输出最近若干份快照的 frontmatter，用于观察分数趋势。
• 不要做的事：不在 polish 里夹带重设计；不为局部例外造系统抽象；不加多余检测器 pass；不因扫描干净而跳过视觉判断；不未经确认就改动事实性文案。

可复制的核对清单：

1. 建立参照：DESIGN.md / token / 共享组件已读，无系统则确认项目约定；每处漂移已归类（missing token / one-off / conceptual / local）。
2. 证据：真实路径在代表尺寸上走通；上轮快照已用 critique-storage.mjs latest 读取（或确认退出码 2），P0/P1 已列入 backlog。
3. 分诊：五级修复顺序未倒置，没有“角落完美、整体欠账”。
4. 打磨：流程、布局/字体、颜色/图像/图标、交互/状态、内容/代码五维逐项过，craft-floor 数值（4.5:1 / 3:1、65–75ch、-0.04em）作为验收线。
5. 验证：鼠标/键盘/触摸全路径复核；检测器按 context 指令执行且不多跑；以 source diff 收尾，churn 清零。