Cursor、Codex、Copilot 全适配impeccable 设计检测器 Hook 接入实战【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccableAI 编程助手正在以肉眼可见的速度提升前端产出效率但伴随而来的是一个让团队又爱又恨的现象——AI 网页味千篇一律的紫蓝渐变、嵌套圆角、低对比文案。GitHub 上已经 70K Star 的 impeccable 项目给出的解法很直接不是继续给模型讲道理而是把一个确定性的设计检测器以 Hook 的形式挂进 AI 编程工具的工作流让每次编辑都经过机械化的设计质检。本文基于 impeccable 仓库源码拆解其 Hook 系统的四个核心设计两级规则如何划分即时拦截与深度审查、五种主流 harness 的钩子事件差异、.impeccable/config.json的项目级配置以及值/文件/规则三级豁免策略的落地细节。读完你会清楚这套系统为什么能把设计审查变成像 lint 一样确定、可审计的工程行为。两级规则即时拦截与深度审查的区别impeccable 的 Hook 并不对所有规则一视同仁。设计问题天然分两种一种是机械、明确、值得当场打断编辑的硬伤另一种是依赖上下文和审美判断的软问题更适合在回合结束后统一复盘。仓库用一张白名单把规则切成两个层级。立即层immediate tier维护在 crates/foundation/src/registry.rs 的IMMEDIATE_TIER_RULES常量中源码注释写明了筛选标准broken output输出被破坏、objective legibility failures客观可读性失败、single-property mechanical slop单属性机械冗余、design-system drift设计系统漂移——每一条都是机械、无歧义、在编辑现场就值得修正的问题输出损坏类broken-image、text-overflow、body-text-viewport-edge对比度与可读性low-contrast、gray-on-color、tiny-text单属性机械冗余gradient-text、dark-glow设计系统漂移design-system-font、design-system-color、design-system-radius、design-system-font-size编辑现场per-edit pass只暴露这一层。其余规则文案节奏、调色板与排版的品味、布局韵律被 crates/hook/src/hook_lib.rs 的split_findings_by_tier归入 deferred 队列留到 Stop 深度审查deep pass阶段对会话中 touch 过的所有 UI 文件跑一遍完整规则集并且通过dedupe_against_cache与 per-edit 阶段已报过的发现去重——同一个问题不会让 AI 被提醒两次。有一个关键细节值得注意per_edit_tiering_active函数里cursor和github两个 harness 被强制返回false。注释解释了原因这两家的 stop 事件要么不稳定、要么无法把上下文回传给模型深度审查根本没接通如果还做分层 defer非立即层规则会直接静默丢失。换句话说分层是能接到 Stop 事件的 harness 的优化不是所有工具都能享受。如果你希望每次编辑就跑全套规则把配置里的hook.perEditRules设为all即可这也是官方文档明确给出的恢复手段。各 Harness 的钩子事件差异与配置五种 harness 的钩子能力差异是这套系统最工程的部分。impeccable 没有强行抹平差异而是为每个 harness 生成符合其原生契约的 manifest。manifest 的生成逻辑集中在 crates/hook/src/admin.rs 的HOOK_MANIFEST_TARGETS与各*_manifest()函数中Harness钩子事件安装位置行为差异Claude CodePostToolUsematcher:Edit\|WriteStop.claude/settings.local.jsongitignored编辑后推送简短提醒Stop 时做深度审查CursorpreToolUse.cursor/hooks.json写前拦截阻止坏写入落地CodexPostToolUsematcher:Edit\|Write\|apply_patchStop.codex/hooks.json需要/hooks信任审批GitHub CopilotpostToolUsematcher:edit\|create\|apply_patch.github/hooks/impeccable.json团队共享、提交到默认分支Grok BuildPostToolUse StopadditionalContext.grok/hooks/impeccable.json编辑时静默Stop 时才可见Cursor 是唯一做写前拦截的。它的事件是preToolUse对应二进制入口impeccable hook-before-editcrates/hook/src/before_edit.rs。这个入口的核心逻辑是把将要写入的内容在落盘之前跑一遍检测它会从事件的tool_input里解析出content、streamContent、text甚至能从 shell 命令中正则还原出重定向、tee、PythonPath.write_text、heredoc 的目标文件与内容shell_redirect_path、shell_python_write_destination等一整套解析函数再对投影后的完整文件内容做检测。检测出问题的响应是输出{permission:deny,user_message:...}拒绝该次写入让 agent 在坏代码落地前重新考虑。为了防死循环同一文件同一 finding 签名被连续拒绝超过EDIT_COUNT_THRESHOLD6 次后会自动降级为 allow 并附警告。Codex 与 Claude Code 是编辑后提醒型它们不拦截而是在PostToolUse后向上下文注入一条短提醒——有新发现就给出修正提示有遗留问题就再次提醒干净文件给一句简短确认。Claude Code 还独占一个能力stop_baseline模块crates/hook/src/stop_baseline.rs会记录会话中首次 Edit/Write 的文件前像Stop 深度审查用它区分本次会话新引入的问题和本就存在的存量问题避免把历史债务算到新改动头上。Grok Build 是最特殊的一个。它的 PostToolUse 扫描只是标记 touched 文件因为它会丢弃该 stdout见 crates/hook/src/hook.rs 中harness grok的分支真正用户可见的通道是 Stop 事件的additionalContext。同时 Grok 会发两次 Stopend_turn可注入的门和 observe-only 的shutdown代码里用reason字段精确过滤只扫end_turn。Gemini 是例外中的例外它不装 per-edit 检测器只在.gemini/settings.json里装BeforeTool把会话 id 注入build-phase的 shell 调用和AfterAgent构建完成提醒。事件识别的兜底逻辑也值得一看。crates/hook/src/hook_lib.rs 的resolve_harness在环境变量IMPECCABLE_HOOK_HARNESS未设置时通过事件载荷的指纹反推 harnessGrok 的 camelCasetoolName/toolInput信封、Copilot 的toolArgs、Cursor 的conversation_id、Codex 的turn_id、Claude 作为最终兜底。这份兼容性也让 docs/HARNESSES.md 中那句Source of truth名副其实——impeccable 把每个 harness 的 spec 差异都收敛到了同一个运行时入口。.impeccable/config.json项目级配置所有 Hook 行为都由项目根的.impeccable/config.json统一驱动个人覆盖写 gitignored 的config.local.json。读取与合并逻辑在 crates/hook/src/hook_lib.rs 的read_config逐层合并两个文件后再叠加默认值。配置分为两个命名空间hook键管 Hook 运行行为{ hook: { enabled: true, quiet: false, perEditRules: immediate, auditLog: .impeccable/hook-audit.ndjson, limits: { maxFindings: 5, maxChars: 8000, maxFileBytes: 131072 } } }其中perEditRules决定每编辑是只跑立即层immediate默认还是全量alllimits.maxFindings/maxChars限制单次注入上下文的体积避免 Hook 输出喧宾夺主maxFileBytes默认 128KB则是保护性上限——超大的文件不值得在编辑现场逐字扫描。detector键管检测器的过滤与扩展{ detector: { ignoreRules: [], ignoreFiles: [], ignoreValues: [], designSystem: { enabled: true }, advisoryRules: exclude, extensions: [{ ext: .blade.php, engine: html }] } }advisoryRules控制 advisory 级规则如em-dash-overuse是否参与输出designSystem.enabled控制 DESIGN.md 设计系统约束是否生效。extensions是给服务端模板预留的口子Blade、Twig、ERB、Handlebars 不在内置扩展表里内置表见 crates/hook/src/hook_lib.rs 的ALLOWED_EXTS声明后即可让 Hook 用对应引擎扫描它们——engine: html走静态 HTML 引擎text走纯文本检测。环境变量是配置之上的一键开关层IMPECCABLE_HOOK_DISABLED整体禁用、IMPECCABLE_HOOK_QUIET静默确认消息、IMPECCABLE_HOOK_HARNESS强制指定 harness、IMPECCABLE_CACHE_ROOT把hook.cache.json/hook.pending.json这类可变状态迁移到项目外。配置合并优先级依次是默认值 config.jsonconfig.local.json 环境变量。豁免策略值/文件/规则三级怎么设再好的检测器也会有误报和合理例外。impeccable 的豁免哲学是能多窄就多窄并提供三级粒度。所有豁免统一走impeccable hooks管理命令crates/hook/src/admin.rsHook 本身绝不写豁免配置——保证所有例外都沉淀在一个可审查的地方。值级ignore-value——最窄默认首选。针对某条规则在某个具体值上的误报impeccable hooks ignore-value overused-font Inter --shared --reason User confirmed Inter is intentional支持--shared写共享config.json/--local写个人config.local.json--reason强制要求给出证据。对overused-font、bounce-easing这类值敏感规则官方文档明确要求用值级豁免而不是规则级。有两个硬校验*通配值必须带--file作用域否则拒绝防止误伤全项目无法被提取器产出的空转值会被直接拒绝synthetic_ignore_value校验避免写一条永远不会生效的豁免。文件级ignore-file——整文件跳过。用于整个文件都脱离设计审查范围的情形fixture、生成产物、刻意保留的反模式演示impeccable hooks ignore-file src/legacy/Card.tsx它会压制该文件上的所有规则——包括未来新增的规则。正因为杀伤面大它被定位为最后手段一条规则吵就只豁免那条规则对应的值。规则级ignore-rule——全项目关停一条规则。只有用户明确要求时使用。值得注意的一个设计overused-font默认拒绝规则级豁免必须显式加--all-values因为某个字体被过度使用几乎总是值级问题impeccable hooks ignore-rule overused-font --all-values --reason User asked to ignore overused fonts generally内联标记是第四通道供文件要离开仓库的场景导出的独立 HTML、邮件附件等使用impeccable-disable rule整文件、impeccable-disable-line/impeccable-disable-next-line单行任何注释语法均可冒号或--后可带理由。最后是分级处置原则Triage它把人的判断嵌进了 Hook 工作流真实设计问题 → 修复绝不为了绕过拦截而豁免有证据的误报或授权例外 → 持久化最窄豁免并在回复中披露证据拿不准 → 留一条问题问用户一次一问。从值级到规则级豁免的沉默面积越来越大需要的人为确认也越来越多——这个梯度本身就是对AI 自主豁免边界的设计。结语impeccable 的 Hook 系统真正值得借鉴的不是某一家的钩子配置而是它对设计审查到底该以什么节奏发生的回答机械性问题在编辑现场即时拦截品味问题在回合结束后一次性复盘能拦截的工具用preToolUse把坏写入挡在门外只能提醒的工具就用克制、去重、可归因的提醒豁免永远走最窄粒度并留下证据。当这些约束被一个 Rust 二进制统一执行时AI 网页味就不再是模型审美的玄学问题而是一套可以在 CI 和每个开发者的编辑循环里稳定运行的质量门禁。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考