企业官网建设流程全解析

impeccable 技能（Skill）完全指南：为 AI Agent 赋予大师级前端设计与浏览器迭代能力

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

impeccable 是当前仓库中随附的一个高规格前端设计技能（Skill），它以一份SKILL.md为入口，把"设计总监级别的界面判断力"编译成 Agent 可执行的上下文加载、命令路由、浏览器迭代、质量守门与文档产出流程。本文以 SKILL.md 为主体骨架，结合其 reference 参考文档目录 与仓库内 Rust/JS 源码实现展开，你将掌握：如何在一个会话内完成 impeccable 的 Setup 上下文加载、如何理解并调用 23 个设计动词命令、设计检测钩子与 doctor 修复机制的工作原理，以及"新建视觉工作流（new-work）"与"浏览器实时变体模式（live）"两条核心管线的完整实战步骤。

一、impeccable 是什么：让 AI Harness 更懂设计的技能

1.1 技能定位与触发范围

在 SKILL.md 的 frontmatter 中，技能声明了自己的触发条件（description）与版本号（version: 4.3.0）：

• 触发场景：用户想要设计、重新设计、塑形（shape）、批判（critique）、审计（audit）、打磨（polish）、澄清（clarify）、蒸馏（distill）、加固（harden）、优化、适配、动画、着色、提取，或以其他方式改进一个前端界面。
• 覆盖范围：网站、落地页、仪表盘、产品 UI、应用外壳、组件、表单、设置、引导流程、空状态；以及 UX 评审、视觉层级、信息架构、认知负荷、无障碍、性能、响应式、主题、反模式、排版、字体、间距、布局、对齐、色彩、动效、微交互、UX 文案、错误状态、边界情况、i18n、可复用设计系统与 token。
• 明确排除：仅后端或非 UI 任务。

1.2 三条核心原则

技能要求 Agent 把自己当作"获奖级设计总监"（award-winning design director），并遵守三条硬性原则：

1. 全力以赴（Go all out）：不做保守交付、不抄近路；交付物必须完整（用户必须提供的素材除外）。
2. 大胆做梦（Dream big and bold）：交付独特、美丽、出类拔萃且有启发性的作品。
3. 有界验证（Verify in bounded passes, not a loop）：构建要完整，但检查用"批量轮次"封顶：桌面与移动端一起拍一轮截图，一次性修完该轮暴露的所有问题，最多再确认一轮，然后停止打磨。开放式自我 QA 只会浪费用户资金，而且效果不如"完成交接（finish handoffs）"。

第三条原则直接决定了后文所有工作流的设计——每次截图、缺陷扫描、微编辑、重建都共享同一个"封顶预算"。

二、会话启动：Setup 上下文加载（impeccable context）

2.1 标准启动命令

每次会话开始，必须运行一次上下文加载命令：

.gemini/skills/impeccable/scripts/impeccable context

关键约定（见 SKILL.md）：

• 每会话一次：运行后遵循其指令，不要重复运行。
• 保持 cwd 在用户项目：<skill-base-dir>是包含本 SKILL.md 的技能目录，不是其上两层的插件根目录；该基础目录会解析本技能内所有.gemini/skills/impeccable/scripts/impeccable <verb>命令，.gemini/skills/impeccable/scripts仅在运行时报告无基础目录时作为回退。
• Windows 无 sh 的 shell：调用.gemini/skills/impeccable/scripts/impeccable.cmd替代。
• 免运行时：启动器运行的是一个随附的、首次运行一次性下载的自包含二进制，不依赖 Node 或其他运行时。
• 指定目标：可通过--target <path>传入具名源文件或路由。

impeccable context会加载 PRODUCT.md、DESIGN.md、匹配的 surface brief（表面简报）以及（适用时的）原生平台指导，并输出若干机器可读指令（directive），例如：

• NO_PRODUCT_MD：项目尚未捕获产品上下文（routing.md 会据此把/impeccable init作为菜单首选）；
• CONTEXT_STALE：工件与当前版本存在漂移的廉价报告，按其自身指令处理即可，不要无故运行 doctor；
• MANUAL_DETECTOR_REQUIRED：未接入自动钩子时，要求会话末尾做一次手动检测器运行；
• IMAGE_GEN_AVAILABLE：报告图像生成能力是否可用（决定 comp-led 路径与 buildPath 提问）。

2.2 启动器不可用时的降级

如果impeccable context被拒绝或失败，必须在下一次工具调用之前单独发送一条消息："Context loading did not run; I'll read the existing project context directly."，然后直接阅读现有的 PRODUCT.md 与 DESIGN.md（不得虚构缺失上下文），继续执行后续第 2–3 步。启动器失败本身不阻塞规划与编辑。

三、设计心智模型：原则、模式与权威判定

3.1 三条设计原则

SKILL.md 定义了三条判断准则：

• 简报优先（The brief wins）：即使与饱和模式警告冲突，也要尊重钉住的审美、时代、材质、字体与色板。把明确简报往自己口味上带是失败。
• 精修保留 / 重设计替换（Refinement preserves; redesign replaces）：精修保留现有身份、行为、文案与范围外的一切；替换事实性文案或添加主张前必须先问。重设计保留产品真相、内容、功能、原生习惯与约束，但把旧外观当作"证据与反参考"，在 new-work 中选择替换世界并替换 DESIGN.md。绝不要"折中成对废弃外观的打磨"。
• 视觉权威是证据而非文件名（Visual authority is evidence, not a filename）：缺少 DESIGN.md 本身不意味着项目是绿地（greenfield）；由 new-work 决定是保留、扩展还是替换现有世界。

3.2 四种访问者模式（Modes）

模式的命名回答的是"这个表面上，访问者的成功长什么样"：

模式从请求的表面选择，而非从产品选择，且只持久化在该表面的 surface brief 中：工具类工具的落地页仍是 Persuade；时尚品牌文档站仍是 Read；文档索引是 Read 而非 Persuade。更深的 Operate/Read 指导见 operate.md。

四、命令体系：23 个设计动词一次讲清

4.1 Commands 总表

SKILL.md 给出了完整的命令表，按类别分为六组：

每个命令的用途、argumentHint 与触发条件还集中记录在 command-metadata.json 中（例如audit生成带 P0–P3 严重度评级的计分报告；document遵循 Google Stitch DESIGN.md 格式以保证工具兼容），该 JSON 也是技能脚本自检命令清单的单一事实来源。

4.2 命令路由规则

无参数与有参数时的处理完全不同（SKILL.md）：

• 无参数：读取 routing.md 并呈现其上下文感知菜单；绝不自动运行命令。若 Setup 报告NO_PRODUCT_MD，菜单首推/impeccable init并给出一行理由，同时仍展示其余项；否则运行impeccable signals读取 JSON，用其中 2–3 个最高价值命令作为菜单首推，每项附一行从 signals 推导的理由。signals 的典型推理：setup.hasDesign=false且hasCode=true→document；critique.latest为 null →critique <surface>；评分低或有非零p0/p1→polish；git.changedFiles指向单表面 → 将audit/polish限定到那些文件；devServer.running=true且平台非原生 →live可用。
• 显式或明显隐含的命令请求：加载其参考文档（原生平台加载原生变体），按其执行；若两个命令都合适，只问一次。
• 工作流/命令选择问题：读 routing.md 的 Workflow questions 小节，只给建议不执行。
• 其他情况：当作一般设计工作处理。缺少 PRODUCT.md 时，新表面或替换世界走 init → new-work；对现有代码的窄幅精修直接在现有实现上按impeccable context指令进行，事后提供 init 而非阻塞。

别名与继承关系：teach是init的别名；craft是普通 new-work 的废弃别名，不增加任何行为；shape拥有任务发现权，仅在视觉世界与表面概念决策时进入 new-work。init 写完 PRODUCT.md 后继续时无需重跑impeccable context；init 记录的平台为ios/android/adaptive时，它会自行加载对应原生平台参考。

五、辅助机制：Pin、Doctor 与设计检测钩子

5.1 Pin / Unpin 快捷键

.gemini/skills/impeccable/scripts/impeccable pin <pin|unpin> <command>

该命令为某个命令创建或移除独立的/<command>快捷方式。汇报脚本结果的摘要即可，出错时逐字转发 stderr。

5.2 Doctor：工件漂移报告与修复

/impeccable doctor报告并修复"项目 impeccable 工件与当前版本所读内容"之间的漂移，涉及 PRODUCT.md、DESIGN.md 及其.impeccable/design.json伴生文件、.impeccable/config.json、持久化 surface brief 与设计钩子（doctor.md）。它是维护命令，不是设计命令：不重设计任何东西、不打开报告点名之外的文件、不附带运行其他命令。

三种漂移必须区分：

• 工具版本漂移：安装的技能旧于发布版本。impeccable context在启动时以UPDATE_AVAILABLE报告，npx impeccable update修复。不是 doctor 的职责。
• 模式（schema）漂移：工件由旧版 impeccable 写成（无人读取的字段、新预期的字段、退役位置的文件）。机械性，doctor 可修复大部分。
• 真相漂移：代码前进了而文档不再描述它。没有文件对比能裁定，document拥有 DESIGN.md、init拥有 PRODUCT.md，doctor 的职责是交给它们一个具体缺口而非模糊怀疑。

操作步骤：

.gemini/skills/impeccable/scripts/impeccable doctor --json

monorepo 中建议加--target <path>。输出含findings（每项有id、artifact、path、severity、summary、fix）。严重度决定"该发生什么"而非"有多糟"：

• auto：无决策负担，直接运行impeccable doctor --fix一次，一行汇报移动了什么；
• mention：用户需要知道但无需现在决策，逐条一句话说明并附修复建议；
• route：需要特定命令，命名命令与其将闭合的缺口，用户本轮要求时才执行。

注意：design-md-drift统计的是 DESIGN.md 最近编辑以来的提交数，提交数不是矛盾证据，不得据此断言文档已过期；config-build-path-unset只在项目做过方向工作且从未记录偏好时触发。若想关闭启动时的廉价检查（默认每周一次/项目），可在.impeccable/config.json设"stalenessCheck": false，或用IMPECCABLE_NO_STALENESS_CHECK=1覆盖单次会话。

5.3 Hooks：设计检测钩子（核心守门机制）

/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>管理本项目设计检测钩子：UI 文件编辑后自动运行检测器并浮出发现（hooks.md）。

两级规则体系：

• 逐编辑档（per-edit tier）：只浮出机械性、无歧义、值得打断编辑的问题——坏图、溢出/裁切内容、对比度与可读性失败、渐变文字、光晕阴影、设计系统漂移等。
• Stop 深扫档（deep pass）：在 Stop 钩子事件上对会话中触碰过的每个 UI 文件运行完整规则集，把其余发现（文案节奏、色板与字体品味、布局韵律）一次性浮出，并与逐编辑档去重。设置.impeccable/config.json中hook.perEditRules为"all"可恢复每次编辑全量规则。

配置键位（统一写在.impeccable/config.json，个人覆盖在 gitignored 的.impeccable/config.local.json）：

旧环境变量IMPECCABLE_HOOK_DISABLED、IMPECCABLE_HOOK_QUIET、IMPECCABLE_HOOK_LOG仍被兼容并优先于配置值。

支持的 Harness 与安装清单：Claude Code（.claude/settings.local.json，gitignored 保持机器本地）、Codex（.codex/hooks.json，首次需经/hooks批准）、Cursor（.cursor/hooks.json，用preToolUse在坏写落地前拦截）、Grok Build（.grok/hooks/impeccable.json，需/hooks-trust或--trust，仅扫end_turn的 Stop）、GitHub Copilot（.github/hooks/impeccable.json，团队共享已提交文件，提交到默认分支后 CLI 与云端 Agent 均读取）。

忽略（ignore）命令体系（--shared写共享配置，--local写私有配置）：

# 值级忽略（最窄，首选） .gemini/skills/impeccable/scripts/impeccable hooks ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional" # 自我服务式异常（必须给出可具名证据） .gemini/skills/impeccable/scripts/impeccable hooks ignore-value bounce-easing bounce-ball --shared --reason "Agent: literal ball-bounce animation, bounce easing is the subject" # 整规则忽略（仅当用户要求全项目抑制） .gemini/skills/impeccable/scripts/impeccable hooks ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally" # 单规则单文件忽略 .gemini/skills/impeccable/scripts/impeccable hooks ignore-value design-system-font-size "*" --file "src/overlay/widget.js" --reason "Injected widget builds its own type scale; DESIGN.md's ramp describes the site" # 整文件忽略（整个文件超出设计评审范围时） .gemini/skills/impeccable/scripts/impeccable hooks ignore-file "src/legacy/Card.tsx"

约束：绝不手工编辑.impeccable/config.json/.impeccable/config.local.json，一律经impeccable hooks写入以保证校验与文件形态一致（唯一例外：detector.extensions无管理动作，可手工改这一个字段）。行内注释标记impeccable-disable <rule>（整文件）、impeccable-disable-line/impeccable-disable-next-line（单行）在文件离开仓库时使用，检测器默认尊重它们。

发现分诊三分类：真实设计问题→修复（绝不用 ignore 跳过修复或放行被拦截的写入）；有把握的误报/被认可的例外→以最窄 ignore 持久化并在回复中披露，--reason写"<who decided>: evidence"；拿不准→保留发现并一句话询问用户。自我服务止步于ignore-value，ignore-file与ignore-rule抑制过强，须先问用户。

六、新建视觉工作流（new-work）：从概念到落地的完整管线

这是技能中最重的一条路径，覆盖新表面或替换视觉身份（new-work.md）。PRODUCT.md 拥有产品真相，DESIGN.md 拥有持久视觉决策，surface brief 保存属于某一路由或工件的策略；PRODUCT.md 缺失时先完成 init.md，但缺少 DESIGN.md 不回溯到 init。

6.1 四个决策阶段

1. 判定已成立的事实：读 DESIGN.md、代表性代码、token、组件与素材。四种情形——重设计（替换旧视觉世界而非打磨它）、已确立世界（继承之，缺 DESIGN.md 不抹掉代码中已连贯的身份）、不完整品牌（保留已确认资产并扩展系统）、无视觉权威（与用户共创新世界）。
2. 询问什么会改变工作：实现前通过结构化提问工具获得用户答案，两三个相关问题，精准请求只需紧凑确认；不跳过确认。
3. 选择正确的发明量：扩展现有表面（继承世界与构图，不做概念锦标赛）／在既定世界中创建完整表面（保持视觉系统不变，从内容与行为推导 5–7 个结构）／创建或替换视觉世界（列出观众烂熟于心的 7 个候选系统，跑 concept-seed）。
4. 提交世界：先选色彩策略再选颜色——Restrained（中性色+单一强调色，Operate/Read 默认）、Committed（一种饱和色承载 30–60% 表面）、Full palette（3–4 个具名角色）、Drenched（表面即颜色）；深色/浅色永不是默认，先写一句物理场景。字体按对象世界的实物挑选；文档还点明了一批"训练数据默认脸"（Fraunces、Playfair Display、Space Grotesk、IBM Plex、Inter-as-display 等）——用到它们必须给出其他字体无法满足的理由。

6.2 concept-seed 与决策页

# 表面作用域：从 5–7 个结构中发牌 3 个 .gemini/skills/impeccable/scripts/impeccable concept-seed --scope surface --mode <mode> # 方向作用域：分配指定方向 + 发牌目录挑战者 .gemini/skills/impeccable/scripts/impeccable concept-seed --scope direction --mode <mode>

方向轮次中，每个挑战者先"融合"再评判，仅在观众认同与产品清晰度两个轴上打分，胜出者成为构建候选，竞争性者保留为完整备选，被拒者降级展示并注明方向从它那里"提高"（raise）了什么。回滚支持--register safer|bolder与--reroll <n>。决策页用serve-question起服务、--wait --key <key>收集答案：

.gemini/skills/impeccable/scripts/impeccable serve-question --start --payload <file> # --schema 先看 payload 形态 .gemini/skills/impeccable/scripts/impeccable serve-question --wait --key <key>

{"optionId":"reroll"}表示保持页面开启、重新发牌；退出码 3 表示继续等待，退出码 4 表示页面未答关闭。direction 轮次还提供"常青出口"（canon 选项）——类别标准方案，正正经经地打，作为用户的门，绝不主动推荐。

6.3 方向契约与执行路径

选定后，在相关 surface brief 中写六段开发期契约（约 150 词）：THESIS（该表面独有的主张与拒绝的类别默认布局）、OWN-WORLD（色板与组件语言，去掉内容仍可辨认）、STORY（访问者理解、相信、做什么）、FIRST VIEWPORT（首视口精确构图与主操作位置）、FORM（所选形式、在有序列表中的位置、脚本打印的 seed key）、FINISH（"unreviewed and undocumented is unfinished..."）。契约绝不复制进实现源码或任何浏览器交付物。

执行路径记录在.impeccable/config.json的buildPath（"comp"或"code"），gitignored 的.impeccable/config.local.json优先；两者皆无且存在图像生成时默认 comp-led。决策页渲染buildPath切换开关，翻转为buildPathFlipped仅绑定本次会话、绝不回写（唯一例外：项目未记录任何 buildPath 时翻转为 true，轮次结束后问一次是否设为常驻默认）。

• Comp-led（图像领先）：选定卡片的 comp 是"可测量的契约"而非情绪板。构建以磁盘上的状态机运行，关卡（gate）测量屏幕与 comp 的差距：impeccable build-phase start --direction <seed key> --kind <assigned|pick|challenger|canon>，随后按顺序build-phase advance依次通过 0. comps（三选一、sidecar 打"approved": true）→ 1. spec（comp-spec --comp <comp> --grid写坐标网格、命名区域、font-match --measure/--rank像素级测字）→ 2. plates（每个栅格区域以素材分辨率重生成为 plate，至少 1.5× 区域尺寸）→ 3. hero（build-phase scaffold写 CSS 变量布局与参考页，只建首视口，comp-diff72% 通过且无硬否决）→ 4. sections → 5. motion → 6. responsive（捕捉desktop.png1440 宽与mobile.png390 宽到.impeccable/review/）。
• Code-led（代码领先）：无 comp 也无歉意，雄心写进方向契约的 FIRST VIEWPORT 块与具名签名交互，finish 评审以行为审计这些承诺。

6.4 检查与完成（Inspect and finish）

桌面+移动一轮批量截图（用户实际视口存在时加user-<width>.png；原生平台按 OS 设备类捕捉）。comp-led 构建再跑一次comp-diff --comp <approved comp> --build .impeccable/review/desktop.png --spec .impeccable/build/spec.json --out-dir .impeccable/review/diff/final作为批判。截图只有有效才是证据：先停用/解决入场动效、从文档顶部全页捕捉、逐文件确认内容与文件名相符。

随后派生（spawn）随附的完成评审 Agentimpeccable-finish-reviewer（Codex 中impeccable_finish_reviewer，Cursor 中/impeccable-finish-reviewer），输入包含原始请求、确认的答案、工件路径、截图路径、方向契约、钩子发现、QUALITY BAR 卡片、comp 路径与 diff 目录。评审返回四种处置词：

• recapture：证据失效而非构建失败，按清单重拍后全量重评；
• rebuild：保真度整体失败，跳过修补批次立即重建后送全新全量评审；
• ship：无需再付任何代价，报告裁决并继续到文档环节；
• fix：一次性批量应用实质修复、重建一次、同文件重拍，送回同一评审者按"已解决/部分/未解决"打分。

收尾时派生随附文档 Agentimpeccable-documenter写 DESIGN.md（新世界与获批的系统变更要求 token 型 DESIGN.md且.impeccable/design.json，而非仅有散文）。shape则把选定方向交回 shape.md，在持久化与实现之前停下。

七、live 模式：浏览器内可视化变体迭代

live是技能的交互式实时变体模式：在浏览器中选元素、选设计动作，得到经 dev server HMR 热替换的 AI 生成 HTML+CSS 变体（live.md）。

7.1 前置条件

• 运行中的带 HMR 的 dev server（Vite、Next.js、Bun 等），或浏览器中打开的静态 HTML 文件；dev server 默认端口被占时先探测默认 URL 再派生第二个服务。
• 仅支持本地 checkout；不支持注入已部署的生产站点（含 HTTPS）。生产检查用impeccable detect <url>或浏览器扩展。不得关闭浏览器安全或削弱生产 CSP 来启用 live。

7.2 会话契约与轮询循环

执行顺序固定、不可跳步。每个工具输出都可能携带_instructions字段，它才是该情形下的权威下一步。核心流程：

1. impeccable live（monorepo 中用--target <path>）启动，输出 JSON：{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, ... }；根解析结果持久化在.impeccable/live/roots.json。
2. 打开服务于pageFile的应用 URL（绝不使用serverPort——那是 helper 的端口）。
3. 默认长超时（600000 ms）轮询：impeccable live-poll，每处理完一个事件立即再次轮询。
4. 事件类型分发：generate（生成变体后--reply done）／steer（页面级方向，--reply steer_done）／accept/discard（轮询脚本已执行live-accept并回执）／prefetch（读路由对应文件）／manual_edit_apply（用户已点 Apply，直接应用源编辑并回复规范 JSON）／variant_mount_failed（浏览器渲染失败，修复变体文件后--reply EVENT_ID done --file <path>）／exit（清理退出）。

各 harness 的轮询纪律：Claude Code 用后台任务；Cursor 用后台终端一次性轮询（禁用--stream）；Codex 用前置前台 exec 会话持续服务；其余 harness 前台一次性轮询。

7.3 变体生成：身份锁定下的三个方向

live 运行在既有表面上，品牌已定，工作是"身份内的变化"而非"身份间选择"。四阶段（Phase A–D）：先提取身份锁（一句话记录实际屏幕：主表面与强调色真实值、字体配对、布局拓扑、表面处理、文案语气），再选默认/离场（仅当用户显式要求重设计才离场），然后规划三个变体——默认模式下三个变体各押不同的主轴（层级／布局拓扑／字体系统／色彩策略／密度／结构分解，共六个轴），最后做"眯眼测试"（squint test）对比身份锁。动作专属调用必须沿该动作的维度变化（bolder放大不同维度、typeset换不同配对+不同比例、colorize用不同色相族等）。

参数旋钮（0–4 个/变体，按视觉重量配预算）：range（滑杆驱动--p-<id>）、steps（分段单选驱动data-p-<id>）、toggle（两者都驱动）。声明为 wrapper 属性：

<div># 会话启动（每会话一次） .gemini/skills/impeccable/scripts/impeccable context # 无参数路由（先看 signals 再做 2-3 个建议） .gemini/skills/impeccable/scripts/impeccable signals # 产品上下文 / 视觉系统记录 .gemini/skills/impeccable/scripts/impeccable init .gemini/skills/impeccable/scripts/impeccable document # 评估与打磨 .gemini/skills/impeccable/scripts/impeccable critique <surface> .gemini/skills/impeccable/scripts/impeccable audit <surface> .gemini/skills/impeccable/scripts/impeccable polish <surface> # 设计检测与忽略管理 .gemini/skills/impeccable/scripts/impeccable detect --json <targets...> .gemini/skills/impeccable/scripts/impeccable hooks status|on|off|ignore-rule|ignore-file|ignore-value|reset # 漂移检查 .gemini/skills/impeccable/scripts/impeccable doctor --json # 新建视觉世界（new-work 决策页） .gemini/skills/impeccable/scripts/impeccable concept-seed --scope direction --mode <mode> .gemini/skills/impeccable/scripts/impeccable serve-question --start --payload <file> # 浏览器实时迭代 .gemini/skills/impeccable/scripts/impeccable live .gemini/skills/impeccable/scripts/impeccable live-poll

综上，impeccable 技能把"界面设计"重新定义为一条可执行、可守门、可度量、可交接的工程管线：Setup 用一次 context 加载对齐项目真相，23 个命令覆盖从捕获、评估、精修到增强的完整动词表，钩子与 doctor 在编辑时守门、在会话间防漂移，new-work 的 comp 状态机把"忠实于参考图"变成数字关卡，live 则在浏览器里让用户实时选择方向。对任何想提升 AI Harness 前端输出质量的团队，这套文档 + 脚本 + Rust 实现的组合本身就是一份可读、可引用的设计系统基础设施。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable