impeccable polish 命令实战面向 AI Harness 的发布前质量打磨流程【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccablepolish是 impeccable 设计技能体系中负责发布前最终质量收尾的 Refine 类命令。它解决的不是设计得更好看而是如何在不动摇既有视觉世界的前提下把功能路径、布局排版、色彩图标、交互状态与代码资产打磨到一致的发布水准。本文以 polish.md 为骨架结合 impeccable 仓库中 SKILL.md、critique.md、craft-floor.md 以及 critique_storage.rs 的实现细节完整还原 polish 的五段式工作流建立体系、收集证据、分流排序、整路径打磨、验证收尾。读完你将掌握如何从既有设计系统出发对漂移drift分类、如何用critique-storage latest继承上一次评审的快照待办、如何在修复后正确关闭快照以及每条打磨细则背后的源码级验证依据。polish 的定位细化refinement而不是改版redesign在 impeccable 的命令体系中polish 的官方定义是Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping.见 command-metadata.json。它与bolder放大平庸设计、quieter收敛过度刺激、distill去芜存菁同属 Refine 类命令但边界非常明确。polish.md 开篇给出了两条不可逾越的红线Polish is refinement, never concealed redesign打磨必须保留既有的视觉世界、内容、行为以及范围外的一切。如果概念本身是错的应当明说并建议改版或改用bolder而不是把替换偷偷塞进一次打磨。A detector result is defect evidence, not proof of quality检测器impeccable detect的扫描结果只是缺陷证据不是质量证明。必须实际查看渲染效果和真实交互路径干净的扫描结果永远不能替代视觉判断。这与 SKILL.md 中Refinement preserves; redesign replaces的原则一脉相承细化保留现有一切身份、行为、文案与范围外内容改版则把旧外观当作证据和反参考另立新世界。二者不可混用——在废弃的外观上做打磨是明确的失败路径。1. 建立体系先理解既有设计系统再对漂移分类打磨的第一步不是动手改代码而是建立体系阅读项目的DESIGN.md以及具有代表性的设计 token、共享组件、既有模式与相邻流程如果项目不存在正式设计系统则以项目自身连贯的约定为准在修复任何漂移之前先对每一处漂移分类。polish.md 定义了四种漂移类型它们的修复策略完全不同漂移类型含义典型修复方向missing token缺失 token系统需要一个可复用的值但不存在将该值提升为设计 tokenone-off implementation一次性实现已有共享组件/模式却被重复实现用共享组件替换conceptual mismatch概念错位流程、信息架构或层级与同类产品区域不一致对齐概念模型而非修补样式local defect局部缺陷实现本身不完整或不一致在局部修正修复原则是在最窄的正确层级修复Fix the cause at the narrowest correct level。当某个约束性系统原则无法从现有代码中推断出来时应当询问而不是臆测。值得一提的是extract命令负责把可复用模式与 token 收编进设计系统而 polish 只在打磨过程中顺带处理 token 提升polish.md 明确要求将真正可复用的值提升为 token但不要为单个局部例外创建系统抽象——这正是避免过度设计的关键。2. 收集证据亲手使用功能继承评审快照亲手走一遍真实尺寸polish 要求以功能在真实尺寸下的表现为准Web 端桌面与移动两种代表性尺寸原生平台ios/android/adaptive在模拟器、仿真器或真机上按对应平台参考文档Verifying the build一节所述的实际设备等级走查。在此过程中确定四件事路径是否功能完整预期质量线与可用时间已知约束或刻意未完成的工作用户真实会遇到的状态、内容长度、角色与输入方式。用 critique-storage latest 继承评审待办如果项目此前跑过critique评审polish 应当把那次评审作为输入之一。命令形式.hermes/skills/impeccable/scripts/impeccable critique-storage latest resolved target --json退出码与返回语义polish.md 原文规定exit 0返回 JSON内含最新快照的body与精确的snapshot_file标识必须将snapshot_file保留到本次打磨结束本地文件 target命令会把文件当前的确切内容指纹与 critique 记录时捕获的指纹比对。未修改的暂存staged、未暂存unstaged或未跟踪untracked内容视为仍然有效任何字节变化、删除或替换为非文件non-file都会关闭该快照标识的待办backlog、保留其趋势历史并exit 2URL target没有本地指纹保持有效直到被显式关闭当快照有效时把body中的 P0/P1 级发现纳入本次打磨并明确说明读取了该快照exit 2不存在快照或 target 已变更。无论哪种情况都必须执行一次独立的打磨走查。指纹机制的源码实现这一内容指纹逻辑并非黑盒其实现位于 critique_storage.rsget_critique_dirL12-L14把快照目录定位到项目根的.impeccable/critique/fingerprint_targetL230-L238对本地文件做 SHA-256生成sha256:hex形式的指纹——这就是 polish.md 所说不依赖 Git 状态或时间戳的实现方式resolve_target_identityL215-L227把本地路径解析为file:resolved-path、把 URL 解析为url:originpathname作为 target 的唯一身份标识latest子命令L538-L608在--json模式下输出{snapshot_file: 文件名, body: 完整评审正文}当本地目标指纹不一致时会自动把该快照标记关闭并返回 2快照文件命名遵循YYYY-MM-DDTHH-MM-SSZ[~NNNN]__slug.md格式is_snapshot_nameL140-L180同秒并发写入通过~NNNN四位冲突后缀避免覆盖历史L507-L526。这意味着 critique→polish 之间形成了一条可信的证据链评审快照记录了被评估字节的精确指纹polish 接手时能立即判断这期间的任何编辑是否使待办失效且完全不需要依赖 git diff 或文件时间戳。3. 分流排序功能缺陷永远优先于外观瑕疵polish 要求把功能缺陷与外观瑕疵分开并按以下顺序修复破损或受阻的任务、数据丢失、误导性状态、不可达路径——一切阻碍用户完成任务的问题缺失的状态——loading、empty、error、success、disabled、permission 等状态流程、层级、响应式与设计系统漂移视觉与动效不一致代码与资产清理。同时有一条硬性纪律不要把一个角落打磨到完美而让其余部分停留在同一条质量线之下Do not perfect one corner while leaving the rest below the same quality bar。打磨是按整条路径推进的不是按截图逐张修。这一分级与 critique.md 中的 P0–P3 严重度体系P0 阻断任务 / P1 造成显著困难 / P2 有绕行方案的小困扰 / P3 无实际影响的打磨项是同一套价值排序polish 从快照继承的正是这些带严重度标签的 Priority Issues。4. 打磨整条路径五类细则流程与层级Flow and hierarchy对齐相邻区域的心智模型、术语、披露方式、路由、保存行为以及乐观/悲观更新模式让主任务和当前状态显而易见但不要把所有元素压成同等权重确保到达arrival、过渡transition、空态empty与恢复recovery路径彼此衔接而不是各自孤立的屏幕。布局与排版Layout and type对齐项目的栅格与间距刻度既修数学对齐也修光学对齐optical alignment相关内容紧密成组不同组别慷慨分隔同角色排版保持一致实测 measure行长、换行、本地化扩展、缩放与字体加载验证每一个受支持的视口而不仅仅是修正当前截图。色彩、图像与图标Color, imagery, and icons跨主题使用语义 token 与稳定的颜色含义验证每种状态下的文本、控件与焦点对比度图标家族、描边/字重、尺寸与光学对齐保持一致防止图像布局偏移layout shift正确的宽高比、响应式图片来源与有用的 alt 文本。交互与状态Interaction and state每个控件都需要合适的 default、hover、focus、active、disabled、loading、error、success 行为保留可见的键盘焦点、逻辑 tab 顺序、标签与符合平台习惯的触摸目标动效保持连贯、可打断、性能良好不要为了让打磨看得见而添加动画在产品可能遇到的场景中验证长内容、缺失内容、本地化、离线、慢网络与权限受限内容。内容与代码Content and code术语、大小写、标点与事实性文案保持一致修改既有声明之前先询问移除调试输出、死代码、未使用导入、废弃样式与打磨过程中产生的重复系统拥有该模式的场合用共享组件替换自定义实现把真正可复用的值提升为 token不要为单个局部例外创建系统抽象。这些细则与 craft-floor.md 中的质量底线contrast ≥4.5:1 正文 / ≥3:1 大字号、阴影必须带偏移与柔和模糊、正文字体 65–75ch、展示字最大 6rem、tracking 下限 -0.04em、动效聚焦于一个编排时刻、状态齐全、浏览器原生表面同样入画等互相咬合。按 SKILL.md 的约定craft-floor 应在任何 UI 编辑前加载而 polish 阶段正是这些机械检查被逐条兑现的时刻。5. 验证与收尾完整走查、关闭快照、源码 diff最终走查清单以鼠标、键盘与触摸如适用再走一遍完整路径检查Web 端移动、中屏、宽屏布局原生端手机与平板尺寸类、两种支持方向loading、empty、error、success、disabled、长内容、缺失内容等全部状态缩放、对比度、焦点、语义与读屏器screen reader名称所有位置的 console 错误、布局偏移、交互延迟与图片加载Web 端覆盖受支持浏览器原生端覆盖受支持 OS 版本、运行时告警与掉帧与DESIGN.md、相邻功能及用户范围的最终一致性。扫描是证据不是结论polish.md 特别强调遵循impeccable context与 hooks 提供的质量指引然后运行其他相关 QA 命令只有当没有自动检测器在运行时context 才请求人工扫描绝不额外增加一次检测器扫描这与 SKILL.md Verify in bounded passes, not a loop的批量化验证纪律一致。修复真实缺陷只对收窄的刻意例外做文档化说明——一次干净扫描不能替代视觉判断。用 critique-storage close 关闭快照当本次打磨把从快照继承的每一个 Priority Issue 都清零时关闭该快照.hermes/skills/impeccable/scripts/impeccable critique-storage close resolved target snapshot_file returned by latestclose 语义L609-L659只关闭本次打磨实际处理过的快照如果期间又有更新的评审产生其待办保持活跃关闭动作向快照 frontmatter 写入closed: true标志insert_closed_flagL330-L334并做所有权校验——slug 加文件名不能证明归属必须以解析后的 target 身份target_identity匹配为准以下情况严禁关闭本次未读取任何快照、未保留snapshot_file、或仍有 Priority Issue 未清零。收尾源码 diff打磨最后一步是源码 diff移除意外改动churn、孤儿代码、冗余值与临时产物。只有当功能完整、且整条路径一致性收尾时才允许发布Ship only when the feature is functionally complete and consistently finished across the path。与其他命令的协作polish 在完整工作流中的位置polish 不是孤立命令它与生态中其他部分形成闭环critique → polish 的待办继承critique.md 规定评审报告必须持久化到.impeccable/critique/以便/impeccable polish无需复制粘贴即可拾取 Priority Issues。critique 每轮产出 P0–P3 分级问题与设计健康分polish 则以这些 Priority Issues 为待办清单signals 驱动的命令推荐routing.md 说明当impeccable signals报告critique.latest分数偏低或p0/p1非零时应优先推荐polish——它会读取该快照作为待办并在快照过期或清零时将其关闭质量底线共享craft-floor.md 在方向确定后加载其机械检查对比度、深度、间距、排版、动效、状态、浏览器表面、文案、覆盖率正是 polish 各小节细则的量化版本无 Node 依赖的启动器所有命令经由 scripts/impeccable 启动器执行它定位随附的平台二进制bin/os-arch/impeccable或按版本缓存无需 Node 或其他运行时Windows 下使用impeccable.cmd。启动器对下载的二进制强制 SHA-256 校验fail closed未验证的下载一律拒绝执行。总结polish 的本质是一次有纪律的收尾先建立对既有设计系统的理解把漂移正确归类用 critique 快照及其内容指纹继承可验证的待办按功能 状态 结构 视觉 清理的优先级在整条路径上推进打磨最后以完整走查、源码 diff 和快照关闭收尾。它反复强调两条底线——打磨绝不偷换成改版自动化证据绝不替代真实视觉判断——这正是它与普通UI 微调最根本的区别。需要深入源码验证细节时可继续研读 critique_storage.rs 与 critique.md 中的完整评审协议。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考