1. 项目概述：一个为AI设计工作流注入“灵魂”的检索增强技能库

如果你和我一样，长期使用Claude Code、Codex这类AI编程助手来生成前端界面，那你一定经历过那种“又爱又恨”的复杂心情。爱的是，它确实能快速产出一个看起来像模像样的HTML页面；恨的是，这些页面往往千篇一律，充斥着虚假的KPI卡片、意义不明的装饰性渐变，以及为了填补视觉空白而硬塞进去的“微小辅助文字”。更让人头疼的是，当你问AI“为什么这里要这么设计”时，它给出的理由常常是空洞的“为了美观”或“遵循现代设计趋势”，背后缺乏扎实的设计原则支撑。这感觉就像让一个厨艺高超的厨师，却只能用预制菜包来做饭——效率是高了，但作品始终缺少灵魂和独特性。

Design Fusion .skill 这个开源项目，正是为了解决这个痛点而生。它不是一个简单的提示词包装器，也不是一堆松散的设计笔记。你可以把它理解为一个“便携式的AI设计副驾驶技能库”。它的核心价值在于，将来自 design.google 的设计原则与判断力、来自 awesome-design-md 的风格种子，以及来自 uiverse-io/galaxy 的动效参考，融合成一个本地的、可检索的知识库。当你的AI助手（如Claude Code）调用这个技能时，它不再是凭空想象或依赖默认的、泛化的知识来生成设计，而是会先从这个高质量的设计语料库中检索相关的证据、原则和案例，形成一个“设计数据包”，然后再基于此进行创作。

简单来说，它把AI驱动的设计工作流，从一个“黑盒生成”过程，转变为一个“检索增强、证据先行”的、更透明、更可控的过程。无论是进行概念探索、UI设计、细节打磨还是设计审计，这个技能都能为AI提供具体、可追溯的设计依据，从而让产出的前端代码更具意图性、更经得起推敲，也大大减少了那种“AI味”十足的通用化设计。

2. 核心设计思路：从“生成”到“检索增强”的范式转变

2.1 传统AI设计工作流的瓶颈

在深入这个项目之前，我们需要先理解当前主流AI设计工作流的局限性。当我们向Claude或GPT-4发出“设计一个金融科技仪表盘”的指令时，模型内部发生了什么？它主要依赖的是其训练数据中关于“仪表盘”、“金融科技”、“现代UI”等概念的统计分布。这导致几个典型问题：

1. 设计决策不透明 ：模型选择某个布局、颜色或动效的原因，用户无法追溯。这就像让一个设计师交稿却不给任何设计说明。
2. 风格趋同与“AI味” ：由于训练数据的同质化，模型倾向于输出一套“安全”但缺乏个性的组件库风格组合，即所谓的“AI slop”（AI糟粕）。
3. 原则性错误频发 ：模型可能会违反基本的设计原则，例如创建没有信息层级的平铺式布局，或使用动效干扰核心任务流。
4. 难以进行定向优化 ：当你指出“这个部分视觉层次不够”时，模型很难系统性地从设计原则层面进行修正，往往只是对局部进行微调。

Design Fusion .skill 的核心理念，正是要打破这个黑盒。它认为，高质量的设计输出不应仅仅依赖于模型的“想象力”，而应建立在可靠的、经过验证的设计知识基础之上。

2.2 三层融合的知识体系架构

该项目构建了一个三层融合的本地设计知识库，这是其能力的基石：

第一层：判断层 来源是 design.google 网站的全部可爬取内容，以及其链接的部分高价值外部设计文章。这一层提供的是设计的“道”，而非“术”。它贡献的是关于层次与注意力设计、动效的意义（而非装饰）、排版与可读性、无障碍设计、AI信任与可解释性等高层原则和判断力。例如，当技能检索到关于“视觉层次”的页面时，它提供给AI的不是一个具体的组件，而是一套如何通过尺寸、颜色、间距来引导用户视线的方法论。

第二层：风格层 来源是 awesome-design-md 项目。这一层提供的是设计的“术”，即具体的视觉语言种子。它贡献了视觉氛围、排版个性、密度与节奏感、界面表面语言（如毛玻璃、新拟态）以及组件特征和构图参考。这些是激发具体视觉风格的“燃料”，让AI在遵循原则的同时，能有丰富的风格素材进行组合与创新。

第三层：动效层 来源是项目内打包的一份 uiverse-io/galaxy 代码库快照，并从中衍生出结构化的动效证据层。这一层专门解决动效设计难题。它提供了悬停与转场参考、CTA按钮反馈模式、加载与通知动效样本等微交互示例。关键在于，技能能根据设计阶段（如 ui 或 polish ）智能地引入相关动效参考，而不是让用户必须明确说出“给我加个动画”。

2.3 基于设计阶段的检索引导机制

这是该项目最精妙的设计之一。它没有采用“一刀切”的检索策略，而是定义了六个设计阶段： research 、 concept 、 wireframe 、 ui 、 polish 、 audit 。每个阶段对应不同的检索权重和目标。

• 研究阶段 ：侧重于检索设计原则、先例和约束条件。此时，来自 design.google 的判断层内容权重最高。
• 概念阶段 ：侧重于检索不同的设计方向和论点，风格层的参考开始介入，帮助形成对比鲜明的方案。
• 线框图阶段 ：锁定信息层级、用户流程和交互节奏，检索内容偏向于布局和结构原则。
• UI设计阶段 ：定义具体的排版、表面处理和组件语言，风格层和动效层的权重显著提升。
• 打磨阶段 ：精炼状态、文案密度、完成度和动效，动效层的微交互样本成为检索重点。
• 审计阶段 ：批判现有设计，检索内容会同时包含原则（用于指出问题）和正面案例（用于提供改进建议）。

这种阶段感知的检索机制，确保了AI在设计流程的不同环节，都能获得最相关、最有效的指导，避免了在概念阶段过早陷入细节，或在UI阶段缺乏原则约束。

3. 核心组件与工作流程深度解析

3.1 语料库构建器：从原始资料到可检索的知识

项目的核心资产是一个本地的向量数据库。构建它并非简单地将网页内容抓取下来，而是经过了一系列精细化的处理流程，这些流程都封装在 build_design_fusion_vector_db.py 脚本中。

实际操作中的关键细节：

1. 智能爬取与清洗 ：对 design.google 的爬取需要处理重定向、识别并排除低价值页面（如纯视频外壳、无效跳转页）。脚本会保留规范的URL信息，并选择性摄入那些具有稳定访问性和高设计学习价值的外部文章。
2. 内容分块策略 ：设计文章往往较长，直接全文嵌入会丢失重点。脚本采用了智能分块策略，确保每个文本块在语义上是完整的（如一个完整的设计原则描述、一个案例研究段落），同时控制块的大小以优化检索精度。最终，项目包含了超过14000个这样的检索块。
3. 元数据丰富 ：为每个块附加丰富的元数据，如来源（是来自 design.google 的原则，还是 awesome-design-md 的风格示例）、原始URL、所属的设计阶段标签等。这些元数据在后续的检索加权中起到关键作用。
4. 动效层衍生 ：从 galaxy 快照中提取CSS和JavaScript动效代码，并为其生成描述性文本（如“平滑的按钮悬停填充效果”），将其转化为可被文本检索系统理解的“动效证据”。

避坑心得 ：在初次构建语料库时，最容易犯的错误是分块不当。过大的块会导致检索结果不精准，过小的块则会割裂语义。我的经验是，针对设计类文本，以“一个核心观点+其论证或示例”为一个块是比较理想的。此外，务必为外部链接设置严格的纳入标准，不稳定的源会成为整个知识库的脆弱点。

3.2 检索引擎：设计请求的“翻译官”与“调度员”

design_harness.py 脚本是技能的操作核心，它扮演着“翻译官”和“调度员”的角色。

其工作流程可分为四步：

1. 请求分类 ：解析用户或AI的请求，根据关键词和上下文将其映射到六个设计阶段之一。例如，“给我三个不同的设计方向”会被分类到 concept ，“优化这个按钮的交互反馈”则属于 polish 。
2. 阶段感知检索 ：根据分类结果，调用不同的“检索配置文件”。例如，在 research 阶段，配置会给 design.google 的原则性内容赋予更高权重；在 ui 阶段， awesome-design-md 的风格示例和 galaxy-motion 的动效参考权重会上升。脚本还会应用“每页上限”规则，防止某个单一来源的内容垄断检索结果。
3. 反模式护栏注入 ：这是该项目区别于普通检索系统的关键。在返回结果前，检索引擎会主动将一系列常见的设计反模式警告注入到设计数据包中。这些警告基于项目内的 research/ai-design-antipatterns.md 研究，例如：“警惕无意义的KPI数字”、“避免使用过小的辅助文本来弥补薄弱的信息层级”、“动效应服务于引导而非装饰”。
4. 生成设计数据包 ：最终输出不是一个简单的链接列表，而是一个结构化的JSON对象，包含： phase （阶段）、 goal （设计目标）、 ranked_evidence （按相关性排序的证据块，附带来源和摘要）、 guardrails （触发的反模式警告）、 motion_strategy （如适用，推荐的动效应用策略）。

一个实操示例： 当你运行 python design_harness.py “premium glassmorphism landing page with calmer hierarchy” --phase ui --top-k 8 ，脚本会：

• 识别为 ui 阶段，侧重视觉和组件。
• 从语料库中检索与“glassmorphism”（毛玻璃）、“premium”、“landing page”、“hierarchy”相关的证据。
• 可能返回来自 awesome-design-md 的毛玻璃实现案例、来自 design.google 的关于视觉层次和留白的文章片段、以及来自 galaxy-motion 的适用于英雄区域的微妙背景动效。
• 同时注入警告：“避免过度使用模糊效果导致可读性下降”、“确保玻璃态效果有明确的背景对比支撑”。

3.3 技能表面：让AI学会“调用”与“遵循”

SKILL.md 和 agents/openai.yaml 文件定义了AI模型应如何与这个技能交互。这本质上是一份给AI的“说明书”和“操作手册”。

它的核心作用是：

• 技能触发 ：教导模型在何种语境下应主动使用 google-design-fusion 技能（例如，当用户请求涉及前端设计、原型制作、设计评审时）。
• 工作流规范 ：明确要求AI遵循“先检索，后生成”的流程。即，必须先调用检索引擎（或利用已提供的设计数据包），基于证据形成设计思路，再输出代码。
• 阶段化行为 ：引导AI根据不同的设计阶段调整其输出重点。在 concept 阶段，输出应是文字描述的设计论点；在 ui 阶段，才输出具体的HTML/CSS代码。
• 保持透明度 ：鼓励AI在输出中引用其设计决策的来源（例如，“根据检索到的关于F型阅读模式的原则，我将主要行动按钮置于左上角…”），这使得设计过程可审查、可讨论。

与普通提示词工程的关键区别 ：普通提示词是静态的、一次性的指令。而 SKILL.md 定义的是一个动态的、可交互的协议。它让AI从一个被动的指令执行者，变成一个能主动利用外部知识库进行推理的协作伙伴。

4. 实战集成与应用指南

4.1 在不同AI客户端中的集成方法

该项目设计为便携式，支持主流的AI编程助手。集成方式的核心思想是：将 skills/google-design-fusion/ 目录作为本地技能库提供给AI客户端。

对于 Codex 用户（已验证适配）： 这是最原生的集成方式。你只需要创建一个符号链接，将技能目录链接到Codex的技能文件夹。

# 在项目根目录下执行（Windows PowerShell示例）
New-Item -ItemType SymbolicLink `
  -Path "$env:USERPROFILE\.codex\skills\google-design-fusion" `
  -Target (Resolve-Path ".\skills\google-design-fusion")

完成后，在Codex中，你就可以通过特定的指令格式来调用该技能。Codex的运行时能直接理解 SKILL.md 中定义的交互协议。

对于 Claude Code、OpenClaw、OpenCode 等用户： 这些客户端对本地技能的支持程度不一。最通用的方法是：

1. 将整个项目仓库克隆到你的工作空间。
2. 在与AI对话时，通过相对路径直接引用技能目录或其中的脚本。
3. 在提示词中明确指示AI去读取 SKILL.md 文件，并按照其中的工作流执行。

例如，在Claude Code中，你可以这样开始对话：“请参考位于 ./skills/google-design-fusion/SKILL.md 的技能说明。接下来，使用 google-design-fusion 技能为我设计一个数据可视化仪表盘的概念。阶段：概念。”

集成经验谈 ：并非所有客户端都能完美解析复杂的技能定义文件。如果遇到问题，一个退而求其次但非常有效的方法是：直接运行 design_harness.py 脚本，将得到的设计数据包（JSON格式）复制粘贴给AI，并指令它“基于这个设计数据包进行开发”。这虽然多了一步手动操作，但保证了检索逻辑的绝对执行。

4.2 有效的提示词模式与阶段选择

要让技能发挥最大效力，关键在于如何向AI下达指令。项目推荐了一种最可靠的提示词结构：

Use google-design-fusion for [任务描述]. Phase: [阶段]. Return a retrieval-backed design packet first, then the final direction.

分阶段任务示例精讲：

1. 概念探索阶段 ：

   • 提示词 ： Use google-design-fusion for an AI finance landing page. Phase: concept. Give me 3 distinct theses before any UI code.
   • AI预期行为 ：AI会调用技能，检索关于金融科技、登陆页、价值主张传达的设计原则和风格参考。然后，它会输出三个文字描述的设计方向（论点），例如“ Thesis A: 聚焦信任与安全，采用深色系、坚实质感”、“Thesis B: 强调智能与未来感，使用渐变和动态数据可视化”、“Thesis C: 突出简洁与人性化，采用明亮色彩和亲切的插画风格”。每个论点都应附带简要的检索依据。

2. UI设计阶段 ：

   • 提示词 ： Use google-design-fusion to redesign this dashboard. Phase: ui. Keep one dominant task, cut fake metrics, and define motion only where it improves feedback.
   • AI预期行为 ：AI会检索仪表盘设计、任务聚焦、数据可视化、动效反馈等证据。在输出HTML/CSS代码时，它会刻意避免堆砌无意义的指标卡片，确保视觉焦点单一，并且只在不干扰主任务的地方（如按钮点击反馈、数据更新提示）添加有意义的动效。

3. 设计审计阶段 ：

   • 提示词 ： Use google-design-fusion to critique this existing mockup. Phase: audit. Flag hierarchy problems, tiny helper text, AI slop, and motion misuse.
   • AI预期行为 ：AI将待审计的代码或描述与检索到的设计原则进行比对。它会系统性地指出问题，如“左侧导航栏与主内容区缺乏视觉权重区分，违反层次原则”、“图表下方的说明文字字号过小，属于‘tiny helper text’反模式”、“这个背景粒子动画与产品功能无关，属于装饰性动效滥用”。

阶段选择决策指南：

• 当你毫无头绪，需要灵感和方向时，用 concept 。
• 当你确定了方向，需要产出可用的界面代码时，用 ui 。
• 当你有了初步代码，需要优化细节、状态和微交互时，用 polish 。
• 当你对现有设计不满意，但说不清具体问题时，用 audit 。

4.3 与Huashu Fusion Studio的协同工作流

项目中还包含第二个技能 huashu-fusion-studio ，它是一个“执行优先”的编排器。它的角色是：接收来自 google-design-fusion 的“设计数据包”，并将其转化为确定性的、可执行的开发简报，最终路由到具体的代码生成或资产导出任务。

两者的关系可以理解为：

• google-design-fusion 是 “战略参谋” ，负责提供设计依据和方向。
• huashu-fusion-studio 是 “战术执行官” ，负责将战略拆解为具体的开发任务。

典型工作流：

1. 使用 google-design-fusion 技能，以 phase: ui 生成一个“毛玻璃风格设置页面”的设计数据包。
2. 将该数据包作为输入，传递给 huashu-fusion-studio 技能。
3. huashu-fusion-studio 会根据其集成的“华树设计”衍生原则（一个本地同步的设计系统子集），将设计数据包解析为具体的组件规范、布局约束和动效定义，并可能调用Playwright等工具生成截图或交互原型。

重要许可边界提示 ： huashu-fusion-studio/vendor/huashu-derived/ 目录中的内容，是通过脚本从上游 alchaincyf/huashu-design 项目同步而来的一个子集。这部分内容遵循上游的“个人使用许可”， 并未 像本项目其他部分一样采用MIT协议。在商业使用或分发时，需要特别注意这一点。

5. 常见问题、排查与高级技巧

5.1 部署与运行中的典型问题

问题1：克隆项目后，直接运行 design_harness.py 脚本报错，提示缺少向量数据库。

• 原因 ：项目默认不包含原始的爬取数据（因为体积和动态性），但已经预构建了一个可用的向量数据库快照，位于 google-design-vector-db/ 目录。
• 解决 ：确保该目录存在。对于绝大多数使用者， 无需 重新构建向量库，直接使用这个预构建的库即可。只有当你需要更新 design.google 或 awesome-design-md 的内容时，才需要按照README中的“重建”步骤操作。

问题2：在非Codex客户端中，AI似乎无法理解或调用技能。

• 排查 ：首先检查AI客户端的上下文是否包含了 SKILL.md 文件的内容。你可以手动将 SKILL.md 的关键部分（特别是“How To Use It”和示例提示词）粘贴到对话中。
• 备用方案 ：采用“人工检索+手动输入”模式。即，你手动运行 python design_harness.py “你的设计需求” --phase ui --format json ，然后将输出的完整JSON设计数据包提供给AI，并指令：“请基于以下设计数据包中的证据和原则，生成前端代码。”

问题3：检索结果感觉不相关或质量不高。

• 优化 ：尝试调整 --top-k 参数（默认可能不是8），增加或减少返回的证据数量。更重要的是， 精炼你的需求描述 。像“做一个好看的页面”这样的模糊描述，检索效果必然差。应使用更具体、包含设计关键词的描述，如“做一个具有沉浸感、使用视频背景和粗体无衬线字体的产品宣传页”。

5.2 技能效果评估与对比

项目在 examples/ 目录下提供了最直观的效果对比。

“无技能”示例 ：通常表现为组件堆砌、信息过载、滥用装饰性元素。例如，一个仪表盘可能同时显示6个同样大小的KPI卡片，每个卡片都有不同的渐变背景和图标，但数字本身没有实际业务含义。动效可能是页面加载时所有元素一起淡入，没有节奏感。

“有技能”示例 ：呈现出明确的信息层级。可能有一个占据视觉主导地位的关键指标图表，其余辅助信息以更小的尺寸或次要色彩呈现。动效被谨慎使用，例如只在数据更新时有一个细微的数字变化动画，用于吸引注意。设计说明中会提及依据，如“根据检索到的‘视觉焦点’原则，将最重要的用户转化按钮置于F型视觉路径的终点”。

量化评估 ：你可以从以下几个维度对比：

• 信息清晰度 ：主要任务是否一目了然？
• 决策可追溯性 ：设计选择是否有据可依？
• 代码特异性 ：生成的代码是简单的组件库拼接，还是包含了针对性的、有理由的样式覆盖？
• 反模式规避 ：是否避免了项目警告的那些常见问题？

5.3 高级技巧：定制化与扩展

技巧1：融入你自己的设计知识库 项目的架构是开放的。你可以仿照其脚本，构建自己的设计语料库。例如，将你公司内部的设计规范文档、你欣赏的竞品设计分析文章，通过类似的流程（爬取/清洗 -> 分块 -> 向量化）添加到本地向量数据库中。然后修改 design_harness.py 中的检索源配置，使其同时查询官方库和你的私有库。这样，AI生成的设计就能同时遵循通用设计原则和你的品牌特定规范。

技巧2：创建自定义的“反模式”护栏 深入研究 research/ai-design-antipatterns.md 文件，理解其模式。你可以根据自己团队常犯的设计错误，添加新的护栏规则。例如，如果你的产品常被用户抱怨“找不到保存按钮”，你就可以添加一条规则：“警告：主要表单操作按钮的视觉权重不足，或位置不符合用户预期”。在检索过程中，当请求涉及表单设计时，这条规则就会被注入到设计数据包中，提醒AI注意。

技巧3：将设计数据包用于团队评审 design_harness.py 输出的JSON数据包，不仅适用于AI，也是一个绝佳的 设计评审依据 。在团队协作中，可以将这个数据包作为设计稿的附件。评审者可以快速查看本次设计参考了哪些权威原则、借鉴了哪些风格、规避了哪些已知陷阱，使得设计讨论更加聚焦和有建设性，而不是停留在“我觉得这个蓝色不好看”的主观层面。

技巧4：与现有设计系统结合 如果你所在团队已经使用了Figma设计系统或类似 Tailwind CSS 的实用类优先框架，可以将此技能的输出作为“设计输入”，然后通过后续的提示词工程，让AI将检索得到的设计理念，转换为你团队设计系统中的具体Token或组件。例如，技能建议“使用一种温暖、可信赖的辅助色”，你可以让AI将其映射为“使用我们设计系统中的 --color-brand-secondary-300 ”。