开源雷达 2026-10-28

来源:github · 原文链接:https://github.com/pbakaus/impeccable · 整理:github_bot · 发布时间:2026-10-28


一、项目概览

Impeccable 已经在 GitHub 上积累了约 9 万 star。这个数字出现在一个 2025 年 11 月才创建、自我定位为"让 AI 编码代理更懂设计"的项目上,说明它切中了真实痛点:模型写前端代码的能力早就够用,但产出的界面越来越像——同一个 SaaS 模板、同一个 Inter 字体、同一组紫到蓝的渐变。

项目起点是 Anthropic 官方的 frontend-design 技能,作者在此基础上做了三件事。第一,把"设计指导"从一段静态 prompt 升级成有状态、有上下文的命令体系:1 个技能入口 + 24 条命令,共享同一套设计词汇。第二,把审美判断中可以判定的部分抽成 62 条确定性检测规则,编译进 Rust 引擎,由 CLI 和浏览器扩展在本地执行,不调用 LLM、不需要 API Key。第三,把"产品事实"和"视觉方向"分层写入文件(PRODUCT.md、DESIGN.md、surfaces/*.md),让后续每条命令都有稳定依据,不会把"这个产品服务谁"和"这个页面用什么色调"混为一谈。

工程形态上,它是一个 Cargo workspace 多 crate 项目(foundation、common、core、detect、html、browser、live、context、hook,外加 comp、comp-verbs、cli、wasm、xtask 等),最终产物是一个自包含二进制;npm 上的 impeccable 包只是安装 shim,包版本 4.8.0 与引擎版本 0.1.18 独立演进。许可证 Apache-2.0,官网 impeccable.style 提供完整文档与案例。

二、核心特性速览

能力具体内容使用方式
一次性初始化检查项目、只追问真正缺失的产品事实,写出 PRODUCT.md;访客模式与视觉方向留到具体界面时再定/impeccable init
24 条设计命令craft、shape、critique、audit、polish、distill、bolder、quieter、harden、onboard、animate、colorize、typeset、layout、delight、overdrive、clarify、adapt、optimize、live、generate 等/impeccable <command> <target>
确定性检测62 条规则由 CLI 与浏览器扩展本地执行,无需模型与密钥;另有仅在 LLM 侧完成的评审检查项自动触发(hook)或 npx impeccable detect
浏览器内迭代live 模式对单个元素做视觉变体,generate 可批量出变体而不用手动挑/impeccable live / generate
反模式清单显式禁止滥用字体、彩色背景上压灰字、纯黑纯灰、卡片套卡片、回弹缓动技能内置,命令执行时强制
构建路径选择buildPath 取 comp(先出高保真稿再实现)或 code(直接写码)init 时询问,写入 .impeccable/config.json
命令固化把高频命令钉成独立斜杠命令/impeccable pin audit → /audit

值得注意的是命令的语义粒度:bolder 与 quieter、distill 与 delight、layout 与 typeset 成对出现,本质上是在给"设计调味"提供可反向调节的旋钮,而不是让模型自由发挥。这种设计让"再大胆一点"这种模糊需求变成可执行指令。

三、系统架构设计

Impeccable 系统架构

整个系统可以按三个层次理解。

交互命令层位于最上。入口是各种 AI 编码工具(Claude Code、Cursor、Codex、Copilot、Gemini CLI 等),用户输入的斜杠命令先进入命令路由,由它完成解析与分发——24 条命令共用一张命令表,参数是目标区域(blog、landing、checkout),因此同一套词汇在不同项目里含义一致。

核心引擎层是主体。路由把请求交给 Rust 引擎(单二进制、多 crate 编译),引擎按需加载技能包(skill/SKILL.src.md 与 reference/ 下的规范文档),并调用检测规则做静态扫描。技能包与引擎分离是关键设计:技能是纯文本,可读可改可 diff;引擎是编译产物,保证规则执行一致、可复现。二者通过 launcher 脚本衔接,引擎升级不需要改动技能内容。

能力与外部层负责与外部交互。安装与链接工具(npx impeccable install/update/link)负责把技能分发到各 harness 目录,同时读写项目资产(PRODUCT.md、DESIGN.md、surfaces/、critique/);live 模式调用引擎拉起本地服务,在真实浏览器里逐元素迭代;视觉目录则通过 impeccable.style 的 roll API 抽取一组"视觉世界"候选卡,供决策时挑选。检测规则发现问题后,也会经由这一层把发现结果回传给工具侧(hook 输出),形成"改完即被检查"的回路。

这种分层的直接收益是降级友好:没有 Node 也能跑(launcher 直接执行二进制),没有网络也能跑(引擎首次下载后本地缓存),没有 LLM 也能跑检测(确定性规则纯本地)。

四、核心流程或主循环

Impeccable 设计主循环

Impeccable 推荐的流程是一条从"事实"到"就绪"的闭环,六个站点都围绕同一个中心——产品事实基线。

初始化:/impeccable init 扫描项目,不重复问已知信息,只补真正缺失的产品真相(受众、目的、运行环境、约束、语气、证据),写入 PRODUCT.md。同时它记录访客模式、buildPath、是否启用 live,并推荐下一步。这一步是整个体系的基础:后续命令不再需要用户反复交代背景。

塑形:/impeccable shape 在写代码前规划 UX/UI 结构,产出的是策略与方向约束,而不是像素稿。这一步的产出会写入 surfaces/*.md,成为该界面的"方向契约"。

构建:craft 走完整流程。若 buildPath 为 comp,先生成高保真稿再照着实现,适合落地页与展示型界面;若为 code,则直接写代码,把"野心"写进仅开发期可见的方向契约,在收尾时校验。应用内页面与文档一律走 code 优先——README 说得直白:这类东西"建出来比画出来更好"。

评审:/impeccable critique 做的是体验评审,看层级、清晰度、情绪传达,是主观但结构化的人工/模型判断。

审计:/impeccable audit 跑技术质量检查——可访问性、性能、响应式,其中 62 条确定性规则在这里大量发挥作用,结果可复现、可对比。

打磨:/impeccable polish 做最后一遍收尾,对齐设计系统并判断是否达到可发布状态。

闭环之处在于:每一步的产物都写回仓库(brief、critique 报告、design spec),下一轮迭代时重新成为基线的一部分。

五、核心模块解析

模块职责
crates/foundation、crates/common基础类型与共享工具,其余 crate 的公共依赖底座
crates/core引擎主体,负责任务编排与命令语义实现
crates/detect62 条确定性检测规则的实现,纯本地、无模型调用
crates/html、crates/browserHTML/AST 侧解析与浏览器侧协作能力
crates/livelive 模式:本地服务、会话、预览与手动编辑证据链
crates/context产品事实与设计上下文的装载、合并与持久化
crates/hookhook 入口,处理编辑后/停止时的扫描与发现回传
crates/comp、crates/comp-verbs高保真构图(comp)路径及其动作动词实现
crates/cli、crates/skills、crates/bundle、crates/wasm、crates/xtask命令行外壳、技能装载、打包签名与构建任务
skill/SKILL.src.md 源文件、reference/ 设计规范与反模式、scripts/ launcher(含 Windows 的 impeccable.cmd)
browser-bundle/浏览器端分片脚本:探针、快照、通用扫描、视觉扫描、覆盖层、离屏扫描,按编号顺序打包
extension/Chrome MV3 扩展(background / content / devtools / offscreen / popup / shared)
vscode/、plugin/、cursor-plugin/各分发形态的插件包:Agent、Skill、Hook 清单
scripts/构建与发布流水线:build.js、fetch-engine.mjs、sign-bundle.mjs、release.mjs、CI 测试计划等

从 crate 划分能读出取舍:detect 被单独拆出来,说明规则集是被当作独立产品演进的核心资产;hook 独立,说明"编辑即检查"被视为一等入口而非附属功能;comp 与 comp-verbs 独立于 core,则让"先画后写"这条较重路径可以按需加载。

六、特色能力

反模式比正例更好用。 该技能列出五条禁令:不用被滥用的字体(Arial、Inter、系统默认)、不在彩色背景上压灰字、不用纯黑纯灰(必须带色相)、不把所有东西塞进卡片、不在卡片里再套卡片、不用回弹缓动。对模型而言,“不要做什么"比"要做什么"执行起来更稳定,也更容易被检测规则验证。

双轨质检。 确定性规则负责可复现的机械问题(对比度、间距节奏、字体族、嵌套结构),LLM 评审负责语义与情绪层面的判断。前者可以进 CI、可以做回归对比;后者不能,但恰恰是"设计感"所在。把两者分开报告,比混成一个"设计分"更诚实。

个人覆盖与团队共享分离。 config.json 进仓库、config.local.json 进 gitignore;buildPath 团队定一次,某台机器没有图像生成能力时在本地覆盖成 code。这类细节通常只有真正在多harness 环境里跑过一遍才会想到。

**pin**** 降低摩擦。** 常用命令固化成独立斜杠命令后,/audit 比 /impeccable audit 顺手得多,这是把"最佳实践"变成"默认行为"的低成本手段。

七、工具链或生态

# 在项目根目录
npx impeccable install          # 检测已安装的 harness,选择项目级或全局
npx impeccable update           # 刷新已有安装

# 在 AI 编码工具内
/impeccable init                # 一次性采集产品事实,写 PRODUCT.md
/impeccable audit the header    # 对首页头部做技术体检
/impeccable polish settings     # 上线前收口

安装方式覆盖五条路径:CLI 安装器(推荐)、Git submodule(npx impeccable link --source=.impeccable --providers=claude,cursor,适合把技能 vendored 进仓库的团队)、插件市场(VS Code Marketplace、Claude Code /plugin marketplace add、Grok Build grok plugin install)、官网下载 ZIP、直接从仓库 cp -r dist/<provider>/ 拷贝。

适配广度是这个项目最容易被低估的部分:Claude Code、Cursor、Codex CLI、GitHub Copilot、Gemini CLI、Replit Agent、Grok Build、Hermes Agent、Devin、OpenCode、Pi、Qoder、Trae(国内/国际双目录)、Rovo Dev、Mistral Vibe、Google Antigravity、Veto——每个 provider 在 dist/ 下有对应的技能目录形状和原生 hook 清单(.claude/settings.local.json、.cursor/hooks.json、.codex/hooks.json、.github/hooks/impeccable.json、.grok/hooks/impeccable.json)。这种"一套源、多种形态生成"的分发设计,是把技能当作可分发软件而非提示词集合来做。

八、部署与安全

运行时依赖几乎为零。 技能自带 launcher(scripts/impeccable 与 Windows 的 impeccable.cmd),执行器是同目录的引擎二进制,或首次运行时按固定版本下载到 ~/.impeccable/bin/。Node 只在用 npx 安装器时出现。手工拷贝或 submodule 方式完全不需要 Node。

遥测边界清晰。 新设计开始时,技能会向 impeccable.style 的 roll API 请求一组视觉世界候选——这个请求就是功能本身,必然发生。除此之外会匿名上报:roll key(每轮 128 位随机值)、scope、访客模式、轮次、目录版本、胜出卡片的类型与 id 及位置、客户端版本。明确不上报:项目名、文件、代码、PRODUCT.md、代理写出的方向名称。提交进仓库的 brief 只记录一个 seed 引用(在 ~/.impeccable/seed-salt 加盐后取哈希),无法保留 salt 时宁可不记也不降级。关闭方式有三:npx impeccable telemetry off、DO_NOT_TRACK=1、IMPECCABLE_NO_TELEMETRY=1,项目级还可在 .impeccable/config.json 写 "telemetry": false 一次性为全员关闭。

Hook 是权限敏感面。 安装器会保留无关 hook 条目;清单损坏时默认中止,只有 --force 才备份为 .bak 后替换。README 明确提示:Claude Code 的命令 hook 独立于模型工具审批执行,首次编辑或 Stop 事件可能在你拒绝模型命令的情况下仍然下载并缓存引擎;无人值守前应先审阅 hook,或用 --settings '{"disableAllHooks": true}' 一次性禁用。Codex 与 Grok Build 还需要额外信任动作(/hooks 审批、/hooks-trust 或 --trust)。

工作目录的管理同样被认真对待:README 给出带 # impeccable-ignore-start 标记的 .gitignore 块,把截图、会话、缓存、本地配置排除,同时明确要求保留 config.json、design.json、surfaces/*.md、critique/*.md。这个"什么该进仓库"的判断,比多数 AI 工具都严谨。

九、适用场景

批量产出前端的 AI 团队。 当多个代理、多个项目同时产页面时,反模式和检测规则是唯一能保证"不出模板脸"的机制性手段。

需要统一评审口径的产品与设计协作。 critique、audit、polish 提供了共享词汇:说"给它 quieter 一下"比说"能不能收敛点"精确得多。

上线前的技术体检。 62 条确定性规则覆盖对比度、字体、嵌套、响应式等常见问题,不需要密钥,可以进流水线。

设计规范沉淀。 PRODUCT.md → DESIGN.md → surfaces/*.md 的文档链,让"为什么这样设计"随代码一起进仓库,而不是留在某个人的脑子里。

十、总结评价

Impeccable 真正做的事,是把"设计品味"这个通常被认为不可言说的东西,拆成三种可操作形态:命令(可执行的动作)、规则(可验证的约束)、文档(可追溯的依据)。24 条命令给模型方向感,62 条规则给模型硬边界,PRODUCT.md 给模型背景事实。三者叠加,模型的设计行为就从"自由发挥"变成"在约束内发挥”——这才是它比一份长 prompt 强的地方。

双轨质检是第二个亮点:确定性规则可复现、可回归、可进 CI;LLM 评审承担主观判断。把两者分开而不是揉成一个分数,是对"设计质量"这个概念的尊重。

局限也明显。其一,配置项偏多:buildPath、访客模式、hook 生命周期、detector 忽略项、telemetry 三级覆盖、个人与团队配置分离——新人上手要读不短的文档,才能理解 init 到底写了什么。其二,强绑定文件约定:PRODUCT.md、.impeccable/ 目录结构一旦进入仓库,迁移成本就在。其三,规则的上限:62 条确定性规则能抓住机械问题,抓不住"这个交互逻辑是否成立",那部分仍要靠 critique 与人的判断。其四,遥测默认开启,虽然数据最小化做得相当克制(连 salt 缺失时宁可不记录),但在强合规环境里仍需要显式关掉。

适用人群很明确:已经用 AI 代理写前端、并且对产出观感有要求的团队;以及想把设计规范从口头约定变成仓库资产的个人开发者。如果你只偶尔让模型生成一个页面,装它的收益不如直接用一次 shape 来得快。但如果前端 AI 工作流是常态,它更像一个应该常驻的底座——而不是一次性工具。

参考链接:项目仓库 https://github.com/pbakaus/impeccable ;官网与文档 https://impeccable.style