Impeccable:设计词库(2)

在上一部分的「项目概览」里，我们聊了 AI 生成前端页面时那种让人审美疲劳的"标准味儿"——满屏的 Inter 字体、紫蓝渐变、还有永远拆不完的卡片套卡片。我们也看过了 Villa Castagneto 的对照实验，初步认识了 pbakaus/impeccable（Paul Bakaus 发起、始于 Anthropic 的 frontend-design skill、基于 Apache 2.0 开源）是怎么靠"设计词库、评审员、slop 检测器"这三板斧，配合 init 写下的 PRODUCT.md、document 沉淀的 DESIGN.md，以及"具体命令 + 窄目标"的工作方式，把你的编程助手变成懂审美的搭档的。
但如果你打开过不少开源 Prompt 仓库，你可能会有一个很现实的戒心：很多所谓的"设计技能包"，拆开一看其实就是几段写得比较漂亮的系统提示词（System Prompt）。刚用的时候觉得挺惊艳，但聊上十几轮之后，上下文一长，模型又开始顺着训练数据的本能往回滑，照样给你塞紫蓝渐变。
Impeccable 真正有意思的地方，恰恰在于它没有把宝全押在"跟大模型讲道理"上。它确实是一套给编程助手用的设计词汇（The design vocabulary for your coding agent），但在词汇表底下，它塞进了一套相当扎实的工程底座：24 条各司其职的语义命令、一个包含 62 条确定性规则的本地引擎、一套能在浏览器里直接点选热替换的实时模式，以及深入到各个主流 Agent 内部的设计钩子（Design Hook）。今天这一篇，我们就掀开引擎盖，看看这四个技术亮点到底是怎么设计的，以及作者在背后做了哪些耐人寻味的工程取舍。

—

一、24 条命令的五个家族：把"凭感觉调样式"变成精准手术

平时我们让 Agent 改界面，最容易陷入一种"挤牙膏式"的拉锯战。你觉得页面太素，跟它说"再做得有设计感一点"，它反手就给你加了三个发光阴影和一堆悬浮动画；你觉得太吵了，说"收敛一点"，它又瞬间退回成了上世纪的后台管理系统。原因很简单："有设计感"和"收敛"在自然语言里太宽泛了，模型不知道你到底想动字号、间距、颜色还是动效。
Impeccable 的解法是把前端设计里的高频动作，拆解成了 24 条粒度极细的命令，并按工作流分成了五个家族。在 多数 Agent 里，你只要单独输入 /impeccable 就能看到完整列表（如果你用的是 Codex，前缀则是 $impeccable），而且每条命令在项目里都有独立的文档页。如果你发现自己整天都在跑某条命令——比如每次提交前都要查一遍质量——你还可以直接用 /impeccable pin audit 把它固定成顶层的 /audit 快捷方式，少敲一半键盘。
我们先来看看这五个家族是怎么配合的：

1. Plan and set up（规划与初始化）：先立规矩再动手

很多页面写崩，是因为第一行代码写得太急。这个家族有四条命令，专门管"动手之前"和"沉淀之后"的事：

• shape：在真正写代码之前先规划 UX。先把交互逻辑和骨架想清楚，而不是一上来就堆组件。
• init 与 document：上一篇我们提过，init 负责写 PRODUCT.md（把产品调性、目标受众定下来），document 负责写 DESIGN.md（把设计规范落成白纸黑字）。
• extract：当你写了好几个页面，发现有些组件或视觉模式反复出现时，用它把这些重复模式提炼进设计系统里，避免散落一地。

2. Steer（调方向）：九个旋钮，专治"差点意思"

这是平时写页面时最像"调音台"的一组命令。一共 9 条，每一条都对应一个非常具体的视觉维度：

• 调张力（bolder vs quieter）：这两个是一对反义词。页面太保守、像个默认模板时，用 bolder 把视觉表现力放大；如果哪个模块元素堆得太满、太抢戏，用 quieter 把过吵的设计压低下来。
• 做减法与上色（distill 与 colorize）：觉得页面啰嗦，用 distill 直接删掉页面不需要的元素；如果原型阶段全是黑白灰，用 colorize 给灰色界面合理地注入色彩层次。
• 基本功修整（typeset 与 layout）：不满意文字排版时，用 typeset 专门修字体、层级和字号；觉得元素之间要么挤成一团要么松松垮垮，用 layout 专门修间距与视觉节奏。
• 注入灵魂（animate、delight 与 overdrive）：这三个是按剂量递增的。animate 负责加上克制的过渡与交互反馈；delight 会给界面加一点让人会心一笑的个性细节；而如果你在做需要极强视觉冲击力的页面，直接呼叫 overdrive——它会给你搬上着色器（Shaders）、弹簧物理（Spring physics）以及滚动驱动效果（Scroll-driven effects）。

3. Iterate live（实时迭代）：所见即所得的变体试验

有时候文字描述再精准，也不如直接看三版方案来得直观。这个家族有两条命令：

• live：直接在浏览器里选中元素并轮换变体（这个模式的内部机制非常硬核，我们会在第三节专门拆解）。
• generate：如果你不需要进浏览器手动挑选，可以直接对指定元素运行 generate，让它一次性生成多个变体供你比对。

4. Review（评审）：一个看体验，一个抓技术硬伤

写完初稿不能自己看着顺眼就完事，Review 家族提供了两个不同视角的"挑刺专家"：

• critique：一份带评分的 UX 评审。它会按照可用性启发式原则（Usability heuristics）给你的界面打分，并且把发现的问题按优先级排好序。
• audit：一份硬核的技术质量报告。它会把查出来的问题严格按照 P0（阻塞级问题）到 P3（打磨级问题） 进行分级。哪些是上线前必须修的硬伤，哪些是有空再改的细节，一目了然。

5. Finish（收尾）：上线前的六道质检工序

很多 AI 写出来的页面之所以看着像玩具，是因为只写了 Happy Path（理想路径）。Finish 家族的 6 条命令，就是专门帮你在上线前把"玩具"变成"成熟产品"的：

• polish：上线前的最后一遍整体打磨，抠一抠像素级的对齐和细节。
• harden：专门处理那些让人头疼的工程边界——错误状态怎么显示、国际化（i18n）长文本会不会撑爆容器、内容溢出怎么截断、极端边界情况怎么兜底。
• clarify：专治"工程师文案"，帮你重写页面上那些含义不清、生硬拗口的提示语和按钮文字。
• adapt：检查并修复不同屏幕尺寸和设备下的响应式适配问题。
• optimize：聚焦在加载速度与渲染性能的优化上。
• onboard：很多开发者做完功能就忘了新用户进来看到的是什么。这条命令专门用来设计首次使用流程（Onboarding）和空状态（Empty states）。

算下来，上面五个家族一共是 23 条命令。那第 24 条呢？第 24 条叫 craft。在目前的文档里，它已经被标记为已弃用的别名（Deprecated alias），效果等同于一次普通的构建请求。之所以还留着它，显然是为了兼容老用户的肌肉记忆。
你会发现，这 24 条命令的设计哲学非常清晰：不求一条命令包打天下，而是把前端设计的生命周期切成明确的切片。 当你对 Agent 说 /impeccable harden 的时候，它脑子里装的不再是"怎么把颜色调好看"，而是完完全全锁定在溢出、报错和国际化上。这种注意力聚焦，是普通聊天很难做到的。

—

二、62 条规则的确定性检测器：三种跑法，把"AI 味儿"拦在门外

如果只有上面那 24 条命令，Impeccable 依然会面临一个问题：大模型是有随机性的。哪怕你在 Prompt 里千叮咛万嘱咐"不要用 Inter 字体、注意对比度"，它写代码写嗨了的时候，还是可能顺手塞一个不合规的样式进去。
为了治这个毛病，Impeccable 做了一个非常果断的工程决定：不靠大模型自己审自己，而是写了一个包含 62 条确定性规则的检测器（Detector）。 跑这个检测器完全不需要调用 LLM，也不需要配置任何 API Key。它底层是一个随 Skill 一起分发（或者在首次运行时自动下载到 ~/.impeccable/bin/ 目录下）的自包含引擎二进制文件；你环境里的 Node.js 甚至只被用来跑 npx 入口而已。因为是纯确定性的本地规则引擎，同一份代码，规则不变，结论就不会因为模型状态而飘。
为了让这个检测器能无缝塞进不同开发者的习惯里，作者给它设计了三种跑法：

跑法一：潜伏在 Agent 里的"设计钩子"（Design Hook）

这是最省心、也最能体现工程巧思的一种跑法。平时我们用代码检查工具，往往是"谁想起来谁才跑一下"，一旦忙起来就全忘了。
Impeccable 在安装时，会询问你要不要配置 设计钩子（Design Hook）——README 里明确建议你选 yes。目前这套钩子已经支持了 Claude Code、Cursor、Codex、GitHub Copilot、Grok Build 以及 Hermes Agent。
一旦装好，工作流就变了：每当 Agent 编辑完任何一个 UI 文件，准备拍拍手跟你说"我已经改好啦"之前，这个钩子会自动在后台触发，把刚改完的文件扫一遍，然后直接把发现的设计问题交回给 Agent。也就是说，你根本不用出面当坏人，Agent 在向你交差之前，就已经被本地检测器逼着把"AI 味儿"和低级硬伤自己改掉了。

跑法二：CI 流水线或终端直跑（彻底脱离 Agent）

如果你压根没用上面那些 Agent，或者你想在团队的 GitHub Actions 里设一道卡，防止同事把粗糙的 AI 页面合进主干，你可以直接在终端或 CI 里跑 npx impeccable detect。
这里有一个非常关键的技术细节：源码静态扫描和真实页面渲染扫描的区别。
当你直接扫本地源码目录时：

npx impeccable detect src/
如果里面是 JSX 或 TSX 源文件，检测器只会跑模式规则（Pattern rules）——比如检查你是不是又偷偷用了那些被滥用的套路代码。但有些设计缺陷，光看源码是算不出来的。比如"这段文字和背景的对比度到底够不够？“或者"这个字号在实际屏幕上是不是太小了？”，因为在现代前端里，样式可能经过了多层 CSS 变量继承、Tailwind 类名组合甚至是动态计算。
所以，对于这类需要计算最终视觉效果的规则，检测器支持直接扫一个 URL。它会调用你机器上已经安装好的 Chrome 或 Edge 浏览器，去扫描真正渲染出来的页面：

# 扫描正在本地跑着的开发服务器
npx impeccable detect 本地开发服务器地址

# 或者直接扫描任意线上地址
npx impeccable detect 线上地址
在输出的可读性上，它也照顾到了不同场景：默认输出人类可读的报告；加上 --json 可以拿到机器可读的 JSON，方便 CI 做二次处理；加上 --github 则会输出 GitHub Actions 注解格式，跑完直接在 PR 的 Review 界面就能看到哪些行出了问题。如果你只是好奇这 62 条规则到底覆盖了什么，跑一下 --list-rules 就能看到完整的规则 id 和描述列表。
还有一个很实在的细节是退出码设计。如果一切正常自然是 0；退出码 2 表示扫描成功但发现了设计问题；而退出码 1 则代表目标本身无法扫描。
当然，规则是死的，人是活的。万一你们公司的官方品牌字体偏偏就是 Inter，总不能每次提交都被检测器骂一顿吧？Impeccable 提供了两种优雅的豁免机制。第一种是在项目级别把特定值加进白名单，还能附上理由：

npx impeccable ignores add-value overused-font Inter --reason "Brand font"
第二种则是针对单个文件的注释豁免。比如你有一个专门用来导出品牌规范文档的特殊页面，可以直接在文件里加上注释关闭某条规则：

<!-- impeccable-disable overused-font: exported brand doc -->

跑法三：Chrome 浏览器扩展

如果你是个视觉动物，觉得看终端里的行号不够直观，Impeccable 还准备了第三种形态：Chrome 扩展。
装上之后，它可以把那 62 条规则扫出来的同样发现，直接像一层透视镜一样叠加在浏览器里的任何实时页面上。注意，这里是"任何实时页面"——不仅能用来找自己本地项目的茬，你平时逛别人的网站觉得哪里看着别扭，也能顺手打开扩展看一眼对方到底踩了哪些设计雷区。

—

三、实时模式 live：把浏览器变成设计画布，以及背后的安全红线

聊完了检测器，我们来看 Impeccable 里最让人眼前一亮的功能：实时模式（/impeccable live）。
写前端的人都有过这种体验：为了调一个卡片的圆角、内边距或者一段标语的排版，你要在编辑器里改两行代码、切到浏览器看一眼热更新、觉得不对再切回编辑器改，或者在 Chrome DevTools 里调好了 CSS，然后再战战兢兢地回忆刚才改了哪几个属性，手动抄回源码里。
当你运行 /impeccable live 时，它会直接打开你正在运行的本地开发服务器，并在页面上注入一层交互式的覆盖层（Overlay）。目前这套机制原生支持 Vite、Next、SvelteKit、Astro、Nuxt 以及纯 HTML 项目。
在这层覆盖层里，你的工作方式完全变了：你直接在浏览器画面上用鼠标点选你看着不顺眼的那个 DOM 元素，选定你想调整的方向，Impeccable 就会在当前页面上原地热替换（Hot-swap）不同的设计变体。你可以像在试衣间换衣服一样，原地轮换看效果；看到满意的那一版，点一下接受（Accept），它就会直接把对应的改动写回你的源码文件里。相关的工作配置会保存在 .impeccable/live/config.json 中。
听起来很美好对吧？但作为一个要把浏览器操作直接写回本地文件系统、甚至要在后台调起命令行 Agent 的工具，live 模式在架构上天然伴随着极高的权限风险。难得的是，作者没有为了吹嘘"丝滑体验"而把这些风险藏着掖着，而是在 README 里用非常直白的篇幅，把 live 的底层流转逻辑和三条安全红线摊开讲得明明白白：

红线 1：严禁碰生产环境，严禁削弱 CSP

README 里第一条警告就说得很重：live 模式的设计初衷仅仅是用来编辑你的本地代码检出（Local checkout）。你绝对不应该把它的脚本注入到任何已经部署上线的网站里，更不要为了让 live 的覆盖层能跑起来，去修改甚至削弱你生产环境的 Content-Security-Policy（CSP，内容安全策略）。本地开发归本地开发，线上安全边界一步都不能退。

红线 2：陌生仓库里的 impeccable:manual-edit-validate 脚本陷阱

当你在浏览器的 live 覆盖层里直接修改了页面文案并点击应用（Apply）时，Impeccable 为了保证改动符合项目规范，会自动去检查你的 package.json 里有没有定义一个可选的脚本：impeccable:manual-edit-validate。如果有，它就会自动执行这个脚本。
这里为什么要敲警钟？因为这个脚本是在你的本地用户权限下直接运行的。如果你是从网上随便 Clone 了一个不熟悉的陌生仓库，别人的 package.json 里万一在 impeccable:manual-edit-validate 里塞了一行恶意命令，你在浏览器里点一下保存文案，本地就中招了。所以 README 特别提醒：在陌生仓库里开启 live 模式之前，先低头看一眼 package.json 里干不干净。

红线 3：一分钟轮询超时与"关闭沙盒"的自动回退机制

这是 live 模式在技术实现上最需要你留心的一段逻辑。当你在浏览器里改好文案点下 Apply 时，这些暂存的文案编辑（Staged copy edits）到底是怎么写回代码的？

• 首选路径：live 服务器会先把这些改动发给正在和你聊天的 Agent，让当前会话里的 Agent 去改代码。
• 超时回退路径：但是，如果过了一分钟，发现根本没有任何聊天 Agent 在轮询（Polling）接单——比如你把终端里的聊天窗口关了，或者 Agent 卡死了——live 服务为了不让你的点击石沉大海，会自动触发兜底逻辑：它会直接顺着你系统的 PATH 环境变量，去后台启动 codex CLI（如果没找到 codex，就会退而求其次调用 claude）。
• 高危参数：重点来了。因为这是后台自动拉起的无头进程，没法弹窗让你点"同意修改文件"，所以它在调用 codex 或 claude 时，会直接挂上关闭审批、跳过权限检查和关闭沙盒的参数——具体来说，就是 --dangerously-bypass-approvals-and-sandbox 或者 --permission-mode bypassPermissions——而且这个进程会完整继承你当前的环境变量（包括你的各类密钥和系统权限）。

作者显然知道并不是所有开发者都喜欢这种"后台自动提权"的兜底行为，所以留了两个环境变量开关，让你可以在服务器启动时（注意，只在启动时读一次）按自己的偏好做选择：

# 让 Apply 产生的文案编辑留在聊天会话里，不自动拉起 CLI
export IMPECCABLE_LIVE_COPY_AGENT=chat

# 或者干脆彻底禁用文案编辑写回功能
export IMPECCABLE_LIVE_COPY_AGENT=off
把这种底层的进程调用参数和超时回退机制原原本本地写在文档里，不仅不会让人觉得这个工具危险，反而让人觉得作者是个真正懂工程安全的明白人——他给了你最顺手的武器，同时也把保险栓的位置指给你看了。

—

四、一些设计取舍：钩子越权、双轨构建路径与克制的遥测

除了上面三大核心模块，如果你仔细翻阅 Impeccable 的文档，还会发现不少细节处的设计取舍。这些取舍单拎出来看都不算惊天动地的大特性，但凑在一起，就能看出一个成熟开源项目对"真实开发场景"的理解深度。

1. 钩子在模型审批之外运行（以及各家 Agent 的信任机制）

前面我们夸过设计钩子（Design Hook）好用，但钩子机制在不同的 Agent 宿主里，其实有着很微妙的生命周期差异。
拿 Claude Code 来说，已经安装好的命令钩子（Command hooks）是运行在模型自身的审批流程之外的。这意味着什么？意味着哪怕你在界面上明确拒绝（Reject）了模型自己提出要执行的某条命令，只要触发了钩子条件，钩子脚本依然会照跑不误！这就带来一个连锁反应：如果你刚克隆完一个装了 Impeccable 的仓库，第一次尝试编辑文件时，哪怕你拒绝了模型的操作，钩子也可能已经在后台静默触发，并开始首次下载那个自包含的引擎二进制文件到 ~/.impeccable/bin/ 了。
所以，如果你打算在无人值守（Unattended）的自动化环境里跑 Claude Code，README 建议你事先检查好项目里的钩子配置，或者干脆在启动时加上参数把所有钩子一刀切关掉：

claude --settings '{"disableAllHooks": true}'
而在其他几个支持钩子的 Agent 里，安全策略又各有不同，你需要按各自的规矩给钩子"授信"：

• Codex：需要在交互界面里输入 /hooks 手动批准当前项目的钩子；
• Grok Build：需要使用 /hooks-trust 命令，或者在启动时带上 --trust 参数；
• Hermes Agent：则需要显式运行插件启用命令：hermes plugins enable impeccable-design-hook。

万一你在折腾这些配置、切换分支或者升级版本的过程中，觉得钩子突然不灵了，或者怀疑配置乱了套，也不用自己去翻隐藏目录。直接运行内置的诊断命令 /impeccable doctor，它会自动帮你排查过期的上下文文件、未使用的冗余设置以及损坏的钩子。

2. 构建路径（buildPath）：先画图还是直接写代码？

平时人类团队做前端，做营销落地页（Landing Page）和做后台应用界面（App UI）其实是两套完全不同的流程。前者讲究视觉冲击和构图破局，设计师往往会先在画布上出高保真效果图；后者讲究组件复用和信息密度，熟练的前端直接拉组件库写代码反而更快。
Impeccable 把这种行业常识做成了可配置的 buildPath（构建路径）：
当你要构建的是一个全新的落地页时，它提供两条路：第一条是先生成一张高保真效果图，然后再让 Agent 照着这张图去写代码——这条路出来的东西视觉上更大胆、更有突破性，但耗时也更慢；第二条则是直接写代码——更精简、速度更快。
但如果你要做的是应用界面（App interfaces）或者文档站点（Docs），Impeccable 根本不会让你纠结，它会总是直接写代码，因为在这种场景下先画张图纯属浪费时间。
更聪明的一点是：这个选择题只在你当前使用的 Agent 宿主（Harness）确实具备图片生成能力时才会跳出来问你。如果你用的环境压根生成不了图片，它连问都不会问。而且这个偏好只在你跑 init 时问一次，之后就会老老实实存进 .impeccable/config.json 里，以后不再烦你。

3. 遥测（Telemetry）：拉取灵感目录与绝对的隐私边界

一听到开源工具带"遥测（Telemetry）“，很多开发者的第一反应就是皱眉头。Impeccable 为什么会有网络请求和遥测？这跟它解决"千篇一律"的方式有关。
每当你开始一项新设计时，Impeccable 的 Skill 会主动联网，从 Impeccable 官方灵感目录拉取一组经过策展的视觉方向（Visual directions），给你的 Agent 注入新鲜的审美参考。在这个过程中，遥测默认做的事情只有一件：匿名记录一下"当时给你展示了哪些视觉方向，以及你最终选了哪一个”，用来帮社区了解哪些设计风格更受青睐。
至于开发者最担心的代码隐私，README 给出了非常硬气的承诺：你的项目名称、任何项目文件、源代码、以及记录了产品核心机密的 PRODUCT.md，从始至终绝对不会离开你的电脑。
而且，如果你连"选了哪个视觉方向"都不想被匿名统计，关掉遥测也完全不会影响你从 Impeccable 官方灵感目录拉取灵感——请求照常发，只是不记账了而已。关闭的方式给了足足三种，随便你挑顺手的用：

# 方式一：直接用命令行关闭
npx impeccable telemetry off

# 方式二：在环境变量里声明通用的防追踪标记
export DO_NOT_TRACK=1

# 方式三（配置文件中关闭）：
# 直接打开项目下的 .impeccable/config.json，
# 手动写上一行 "telemetry": false

4. .impeccable/ 目录：哪些该进 Git 仓库？

最后是一个很实在的团队协作细节。
用上 Impeccable 之后，你的项目根目录下会多出一个 .impeccable/ 文件夹，所有的工作文件都集中放在这里。很多人第一次用会纠结：这个文件夹到底该不该写进 .gitignore？
答案是：不要忽略核心配置和设计资产，它们属于团队的共享产物，应该直接提交入库（Commit to Git）。
具体来说，下面这些文件都应该跟着代码一起走：

• .impeccable/config.json（项目级配置，比如前面提到的 buildPath 和遥测开关）
• .impeccable/live/config.json（实时模式的相关配置）
• .impeccable/design.json（结构化的设计配置数据）
• .impeccable/surfaces/*.md（各个具体界面/模块的设计说明）
• .impeccable/critique/*.md（critique 命令生成的 UX 评审报告）

你想想看，把这些文件提交进仓库之后，团队里第二个同事拉下代码，他的 Agent 不光能读到源码，还能直接读到你们上一次跑出来的 UX 评审报告、各个表面的设计约束以及统一的设计配置。这样一来，设计上下文就不再是锁在某个人电脑聊天记录里的"一次性消耗品"，而是真正变成了像测试快照一样可以跟代码一起演进的工程资产。

—

本部分小结

拆完这一圈你会发现，pbakaus/impeccable 之所以能在众多前端辅助工具里脱颖而出，靠的是一套"软硬兼施"的组合拳：

• 在表达层（软约束），它用 24 条分属五大家族的精细命令（规划、调方向、实时迭代、评审、收尾），取代了含糊不清的自然语言抱怨，让 Agent 每次只打一场目标明确的局部战斗；
• 在守门层（硬约束），它彻底抛开大模型的幻觉，用一个包含 62 条确定性规则的自包含本地引擎，通过 Agent 内部钩子、终端/CI 命令行（兼顾源码模式扫描与真实浏览器 URL 渲染扫描）以及 Chrome 扩展三种形态，死死卡住劣质 UI 和"AI 塑料味"的流入；
• 在交互与工程层，它不仅提供了能在浏览器里点选元素、热替换变体并写回源码的 live 模式，还极其坦诚地给出了脚本校验、超时回退拉起 CLI 以及钩子越权运行的完整安全边界与控制开关。

把审美变成词汇，把规则变成二进制，把设计文档变成 Git 仓库里的共享产物——这就是 Impeccable 的技术底色。

—

下一部分预告

看完了底层的技术架构和设计取舍，你可能已经手痒想在自己的项目里试试水了。
在接下来的第 3 部分「使用场景与上手」中，我们将彻底回到实战视角：手把手带你走一遍安装步骤，演示几个最接地气的典型用法，聊聊它到底最适合哪类开发者、目前有哪些客观局限，并把它和市面上的同类方案放在一起做个横向对比，给出我们最终的总结建议。
我们下一篇见！