impeccable polish 指南发布前最后一轮全路径质量打磨【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccablePolish 是 impeccable 技能体系中的收尾型命令它承接critique留下的快照把界面在真实使用路径上的功能缺陷、状态缺失、层级漂移与视觉不一致逐一修正并在源码层面清理掉打磨过程产生的痕迹。本文以 .pi/skills/impeccable/reference/polish.md 为骨架结合仓库中 critique-storage 的 Rust 实现 与 critique 参考文档完整讲解 polish 的五步流程——建立系统、收集证据、分级处理、全路径打磨、验证收尾以及支撑它的快照指纹机制与关闭规则。读完你将能独立执行一轮不破坏既有设计语言、不遗留脏代码的发布前打磨。polish 是什么精修而不是隐藏式重设计在 impeccable 的命令体系中polish属于Refine精修类别与bolder、quieter、distill、harden等并列官方定义是 Final quality pass before shipping发布前最后一轮质量检查见 SKILL.md 的 Commands 表。它有一个不可逾越的边界写在本参考文档的第一段Polish is refinement, never concealed redesign. Preserve the incumbent visual world, content, behavior, and everything outside scope. If the concept itself is wrong, say so and recommend redesign orbolderinstead of smuggling in a replacement.翻译成工作准则就是精修保留现有视觉世界、内容、行为以及所有范围之外的东西如果概念本身是错的应该明说并建议重设计或bolder而不是借精修之名偷梁换柱。这与 SKILL.md 中的另一条原则互为表里——Refinement preserves; redesign replaces精修保留重设计替换。精修只处理细节层面的不一致绝不改变产品意图重设计才允许以旧视觉为反参考另起炉灶那属于new-work流程。第二段还立下了一条证据法则A detector result is defect evidence, not proof of quality. Inspect the rendered experience and real interaction path.检测器detector的输出只是缺陷证据不是质量证明。干净的全量扫描不等于界面真的好用最终判断必须落在真实渲染的体验和真实交互路径上。这条法则贯穿 polish 的每一步证据是起点视觉判断是终点。前置条件一次会话一份上下文polish 参考本身要求 Additional context needed: quality bar and shipping constraints——执行前需要补充两项上下文质量基准quality bar和交付约束shipping constraints。按 SKILL.md 的 Setup 约定每次会话开始时运行一次.pi/skills/impeccable/scripts/impeccable context它加载 PRODUCT.md、DESIGN.md、匹配的 surface brief 以及原生平台指导如适用并输出本次会话的指令directives。其中有一条与 polish 直接相关当项目没有接入自动检测 hook 时impeccable context会给出MANUAL_DETECTOR_REQUIRED指令要求会话在结束时手动执行一次 detector 扫描——见 .pi/skills/impeccable/reference/hooks.md 中Every hook is a mechanical pass一节的说明。也就是说polish 阶段不会再额外叠加自动 detector 轮次而是在没有 hook 的情况下补一次手动扫描。context的指令处理逻辑实现在 crates/context/src/context_cli.rsdetector 的 CLI 入口在 crates/detect/src/cli.rs。在 Windows 无sh的 shell 中命令应替换为.pi/skills/impeccable/scripts/impeccable.cmd。第一步建立系统认知Establish the system动手修改任何东西之前先建立对系统的完整认知。这要求你阅读 DESIGN.md以及有代表性的 tokens、共享组件、模式patterns和相邻流程neighboring flows如果项目没有正式的设计系统则采用项目自身连贯的约定coherent project conventions而不是凭空引入一套新规范。在动手修复之前对每一处 drift漂移做分类。参考文档给出四种类型每一类对应不同的修复层级分类含义修复方式missing token系统缺少一个可复用的值补充 token可复用的设计变量one-off implementation已有共享组件或模式可以替代的临时实现换成现有共享组件/模式conceptual mismatch流程、信息架构或层级与同类产品区域不一致修正概念层级而非打补丁local defect实现本身不完整或不一致就地修复缺陷分类的意义在于在最窄的正确层级修复根因能用 token 解决的不要写死能复用共享组件的不要复制粘贴概念错位时不要靠修样式掩盖。当无法从证据推断出某个约束性系统原则时应该向用户提问而不是自行假设。第二步收集证据Gather the evidencePolish 的证据来自两条线亲手使用功能和读取 critique 快照。亲手使用在代表性尺寸上走真实路径在界面的代表性尺寸上亲自使用该功能Web 端桌面desktop与移动端mobile原生平台ios/android/adaptive在模拟器、仿真器或真机上按平台参考文档的 Verifying the build 一节所描述的方式覆盖已发布的设备类别。使用过程中需要确定四件事路径在功能上是否完整预期的质量基准与可用时间已知的约束或故意未完成的部分用户实际会遇到的状态、内容长度、角色与输入方式。最后一点尤其重要——打磨的对象是用户真正会遇到的路径而不是你刚截图的那个角落。读取 critique 快照让上一轮评审的优先级自动接手如果存在先前的 critique将其作为输入之一。polish 与 critique 的衔接点正是快照机制critique 运行结束后会把完整报告写入项目内的.impeccable/critique/目录详见 .pi/skills/impeccable/reference/critique.md 的 Persist the Snapshot 一节so/impeccable polishcan pick up the priority issues without a copy-pastepolish 通过critique-storage latest读取.pi/skills/impeccable/scripts/impeccable critique-storage latest resolved target --json退出码 0返回最新快照的body完整评审正文和精确的snapshot_file身份标识。snapshot_file必须保留到本轮 pass 结束——它是最后关闭快照的凭据。退出码 2表示不存在快照或目标已改变。这套子命令的底层实现在 crates/context/src/critique_storage.rs几个值得注意的机制目标身份target_identity本地文件解析为file:resolved-pathURL 解析为url:originpathname见resolve_target_identity。写入快照时由 helper 自己生成调用方传入的副本会被丢弃防止伪造。内容指纹target_fingerprint对本地文件计算sha256:hex见fingerprint_target使 polish 能区分被评审的字节与之后被编辑过的字节不依赖 Git 状态或时间戳。快照文件名形如2026-05-12T18-30-00Z__slug.md同一秒内的第二次写入会附加~\d{4}固定宽度冲突后缀create_new独占创建不会覆盖历史对应测试snapshot_name_accepts_collision_suffix。closed 标志快照 frontmatter 中的布尔closed: true表示已关闭latest遇到已关闭的快照直接返回退出码 2对应测试latest on a closed snapshot - exit 2。对本地文件目标latest会把文件当前的真实内容指纹与快照记录做比对未变动的 staged、unstaged 或 untracked 内容视为current仍有效此时应采纳body中相关的 P0/P1 发现并在汇报中指名读取了哪个快照任何字节变化、删除或替换为非文件的操作都会先自动关闭旧快照在 frontmatter 写入closed: true再以退出码 2 结束——这既保留了趋势历史又结束了它所识别的 backlogURL 目标没有本地指纹因此一直保持 current直到被显式关闭。无论latest返回 0 还是 2都必须独立执行一遍自己的检查——快照是输入不是免检通行证。第三步分级处理Triage将功能缺陷与外观问题分开并按此顺序修复损坏或被阻塞的任务、数据丢失、误导性状态、不可达的路径无障碍缺失的加载、空、错误、成功、禁用与权限状态流程、层级、响应式与设计系统漂移视觉与动效不一致代码与资源清理。排序的原则是从功能到外观、从状态到样式、从系统到资源。参考文档明确警告不要只把一个角落打磨到完美而让其余部分停留在同一质量基准之下。均匀地低于基准好过参差不齐因为前者至少可预期后者让用户怀疑产品是否用心。这一顺序与 critique/audit 的 P0–P3 严重度分级是兼容的P0 阻断任务showstopper、P1 重大困难发布前必修、P2 轻微困扰下一轮修、P3 锦上添花有时间再修——见 .pi/skills/impeccable/reference/critique.md 的 Issue Severity (P0–P3) 一节。第四步全路径打磨Polish the whole path这是 polish 的主体参考文档从五个维度给出检查清单覆盖从宏观到微观的每一层。流程与层级Flow and hierarchy匹配相邻区域的心智模型术语、披露方式、路由、保存行为、乐观/悲观更新模式optimistic vs pessimistic。让主任务与当前状态显而易见但不要把每个元素都压成同等权重——扁平化不等于清晰。确保到达、过渡、空态、恢复四条路径彼此连通而不是各自孤立的屏。布局与排版Layout and type对齐项目自身的网格与间距刻度既要数学对齐也要光学对齐比如视觉重心、字形错觉。相关内容的组内紧密、组间疏朗。同类角色的排版保持一致测试字宽measure、换行、本地化扩展、缩放与字体加载。验证每一个受支持的视口而不是只修正当前截图。颜色、图片与图标Color, imagery, and icons跨主题使用语义 token保持颜色含义稳定。在每种状态下验证文字、控件与焦点的对比度。图标家族保持一致的族系、描边/字重、尺寸与光学对齐。防止图片布局偏移layout shift正确的宽高比、响应式来源、有意义的 alt 文本。交互与状态Interaction and state每个控件都需要合适的默认、悬停、聚焦、激活、禁用、加载、错误与成功行为。保留可见的键盘焦点、逻辑 Tab 顺序、标签以及平台合适的触控目标尺寸。动效保持一致、可中断、高性能不要为了让打磨看得见而加动画。在产品可能遇到的地方验证长内容、缺失内容、本地化、离线、慢速、权限受限等场景。内容与代码Content and code术语、大小写、标点与事实性文案保持一致改动事实性主张前必须先询问用户。移除调试输出、死代码、未使用的导入、过时样式与打磨过程中产生的重复。系统拥有该模式时用共享组件替换自定义实现。把真正可复用的值提升为 token不要为单一局部例外创造系统抽象——过度抽象与不足抽象同样有害。第五步验证与收尾Verify and finish全路径走查在适用处用鼠标、键盘与触控三种方式再走一遍完整路径检查Web 端的移动、中间与宽布局原生端的两个方向上的手机与平板尺寸类别加载、空、错误、成功、禁用、长内容与缺失内容状态缩放、对比度、焦点、语义与屏幕阅读器名称控制台错误、布局偏移、交互延迟与图片加载Web 端覆盖受支持的浏览器原生端覆盖受支持的 OS 版本、运行时警告与掉帧与 DESIGN.md、相邻功能以及用户范围的约定是否一致。QA 与上下文指令遵循impeccable context与 hooks 提供的质量指导然后运行其他相关的 QA 命令。参考文档特别约束只有没有自动 detector 处于激活状态时context才要求手动扫描绝不额外增加一次 detector 轮次。修复真实缺陷并且只为窄范围的刻意例外做文档化记录。还要记住一次干净的扫描不能替代视觉判断——detector 的证据口径在 crates/detect/src/cli.rs 的退出码约定中同样成立0 clean2 findings。源码差异清理收尾以一次 source diff 结束移除意外改动churn、孤立代码、冗余值与临时产物。只有功能完整且整条路径都一致地完成时才允许发布。关闭快照闭环的唯一正确方式当本轮 pass 清除了它从快照接手的每一个Priority Issue 时关闭该快照.pi/skills/impeccable/scripts/impeccable critique-storage close resolved target snapshot_file returned by latest关闭语义在 crates/context/src/critique_storage.rs 中执行得很严谨close子命令与close_snapshot函数文件名必须是合法的快照名is_snapshot_name且必须位于.impeccable/critique/目录内目标归属必须匹配快照记录的target_identity要与当前解析出的目标身份一致否则拒绝对应测试wrong target identity: refused (exit 2)关闭动作是在 frontmatter 中插入closed: trueinsert_closed_flag重复关闭是静默无操作返回退出码 2关闭后latest对该目标返回退出码 2对应测试latest on a closed snapshot - exit 2。三条明确的禁止规则没有读取过快照时不要关闭close要求传入snapshot_file空参数直接报用法错误没有保留snapshot_file时不要关闭仍有 Priority Issue 未解决时不要关闭。另外关闭只作用于本轮实际处理的那个快照如果在打磨期间又有一次更新的 critique 落地它的 backlog 仍然保持 live不会被误关。趋势历史critique-storage trend target 5会保留每次运行的分数用于观察跨轮次的改进曲线。polish 在命令生态中的位置搞清楚 polish 与相邻命令的边界能避免在错误层级上浪费轮次critique→polishcritique 生成带 P0–P3 优先级的问题清单并持久化快照polish 读取快照、修复并关闭它——这是评估 → 修复 → 归档的闭环。polishvsauditaudit 是代码级技术审计对无障碍、性能、主题化、响应式、实现完整性五维打分并只报告不修复见 .pi/skills/impeccable/reference/audit.mdpolish 是承接证据、动手修复、并在结束时清理代码的收尾命令。polishvsbolder/quieter/redesign概念本身错误时polish 无权越界——该建议bolder放大平庸设计或重设计走new-work就明说绝不借精修偷换设计。polishvsharden/onboardharden 专注生产就绪错误、i18n、边界情况onboard 专注首启与空态激活polish 是它们的收口——每个功能都必须完整且一致地完成。常见误区速查把 detector 干净当质量合格证据 ≠ 证明真实交互路径才是最终裁判只修当前截图要验证每个受支持视口、每种状态、键盘/触控/鼠标三种输入为可见性而加动画动效必须可中断、高性能、有意义为局部例外建系统抽象只有一个用例时不升级为 token 或组件修 A 留 B质量基准要整条路径一致不能一个角落完美、其余破败忘关快照snapshot_file是关闭凭据丢失则无法闭环有未解决的 Priority Issue 时关闭是被禁止的。小结一轮合格的 polish 是五步动作的组合拳读透 DESIGN.md 与共享组件以建立系统认知 → 亲手走真实路径并读取 critique 快照记住退出码 0 与 2 的含义→ 按功能 → 状态 → 流程 → 视觉 → 代码的顺序分级处理 → 沿流程、布局、色彩、交互、内容五条线打磨整条路径 → 用全维度走查、source diff 清理和critique-storage close完成闭环。它既是让界面达成发布标准的最后一轮工序也是评估闭环归档的最后一道闸门——精修保留世界绝不偷换概念证据驱动修复绝不伪造质量。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考