1. 项目概述与核心价值如果你和我一样在过去一年里深度使用过 Claude Code、Cursor 或者 Windsurf 这类 AI 编程助手来构建前端界面那你一定经历过那种“甜蜜的烦恼”助手能快速生成一个漂亮的登录页面但当你让它接着做用户仪表盘时它可能就“失忆”了用上了另一套间距、颜色甚至组件风格。屏幕与屏幕之间像是不同设计师的拼贴画缺乏整体性和一致性。这正是Decantr要解决的核心痛点——它不是一个替代 AI 写代码的工具而是为 AI 生成的 UI 提供设计智能、治理和验证的“契约层”。简单来说Decantr 扮演的是“产品意图”与“AI 生成实现”之间的桥梁。它给编码助手提供了三样它们原本不具备的东西结构化的设计输入、基于注册表的 UI 知识以及精准限定范围的上下文文件。有了这些AI 助手就不再是凭感觉即兴创作而是能够基于一套明确的规则和蓝图构建出内在统一、风格一致的产品界面。你可以把它理解为“AI 生成 UI 领域的 OpenAPI 规范”模型依然负责编写具体的代码但 Decantr 定义了代码的形状、词汇表以及围绕它的检查规则确保最终产出是可控且高质量的。2. 核心架构与设计哲学拆解2.1 双层级治理模型DNA 与蓝图Decantr 最精妙的设计在于它将设计治理清晰地分为了两个独立的层级这种分离直接对应了不同类型变更的治理严格度。DNA 层代表的是持久、不可轻易动摇的视觉与系统公理。这包括主题色彩体系、字体、圆角、阴影等设计令牌。间距系统一套定义好的间距比例尺如 4px 基准。动效规范过渡、动画的持续时间和缓动函数。无障碍访问对比度、焦点状态、屏幕阅读器支持等强制性规则。产品个性与语调界面的“性格”是活泼还是严肃用语风格如何。DNA 的变更比如不小心引入了一个不符合 WCAG 标准的颜色通常被视为“错误”。Decantr 的检查机制在这里会非常严格因为这类变更会破坏产品的视觉一致性和可用性基础。蓝图层则定义了产品的拓扑结构。这包括区块应用的功能模块如“用户资料”、“数据看板”、“设置中心”。页面路由URL 结构与页面间的导航关系。页面外壳与布局每个页面的基本框架如是否有侧边栏、页头页脚。功能特性跨区块的通用能力如“搜索”、“通知”、“多语言”。蓝图层的变更比如新增一个辅助性的“帮助中心”区块其影响范围相对可控。因此Decantr 对这类变更的治理可以更灵活通常以“警告”而非“错误”的形式提示交由开发者决策。实操心得理解这个分层至关重要。在实际项目中我通常会花大量时间与设计师一起打磨和锁定 DNA尤其是色彩和间距系统因为这是所有 UI 的基石。一旦 DNA 在decantr.essence.json中定义好就将其视为“宪法”。而对于蓝图我们保持一定的演进空间允许产品经理和开发者在框架内快速迭代页面结构。2.2 核心工作流契约生成与上下文供给Decantr 的工作流可以概括为“先定契约后生成代码”。这与传统的“先写代码后加 lint 规则”截然不同。定义 Essence一切始于decantr.essence.json文件。这个文件是人机可读的契约同时包含了 DNA 和蓝图的定义。你可以手动编写更常见的是通过 CLI 从一个“蓝图”初始化生成。生成上下文Decantr CLI 会根据essence文件生成一系列结构化的 Markdown 上下文文件存放在.decantr/context/目录下。这包括整个应用的概述 (scaffold.md) 以及每个区块的详细规格 (section-*.md)。AI 助手消费当你打开项目并使用 AI 编程助手时助手会首先阅读根目录的DECANTR.md文件理解本项目使用的方法论。然后在你编辑特定文件时助手会动态加载相关区块的上下文文件。例如当你编辑src/pages/Dashboard.tsx时助手会自动获取.decantr/context/section-dashboard.md中的信息。验证与同步当你修改essence比如更换主题后运行decantr refresh会更新所有上下文文件。运行decantr check或decantr audit则会扫描代码库验证现有代码是否仍然符合新的契约并报告任何“漂移”。这种机制的精妙之处在于按需供给、作用域清晰的上下文。它避免了将整个项目的庞大设计系统一次性塞给 AI 模型导致其注意力分散或上下文窗口浪费确保了 AI 在解决特定问题时拥有最相关、最精确的指导信息。3. 三种入门路径深度实操Decantr 提供了三种适配不同项目阶段的入口选择正确的路径能让你事半功倍。3.1 绿地开发从蓝图快速搭建这是最流畅的体验适合启动一个全新的项目。npx decantr/cli new my-saas-app --blueprintagent-marketplace cd my-saas-app关键步骤解析选择蓝图agent-marketplace、terminal-dashboard、portfolio是官方提供的几个示例蓝图。你可以通过decantr search浏览注册表获取更多。蓝图本质上是一个已发布的应用组合包包含了经过验证的 DNA 和蓝图设计。项目初始化上述命令会创建一个名为my-saas-app的目录并将所选蓝图的所有契约和初始上下文文件填充进去。检查生成物进入项目后你会看到如前文所述的文件结构。此时src/目录下可能只有样式文件没有实际的组件代码。这是正常且符合预期的。Decantr 完成了它的工作——提供契约。接下来是 AI 助手的工作——基于契约生成实现。注意事项目前react-vite是官方主要维护的“可运行启动器适配器”。这意味着选择此适配器的蓝图会生成一个可以直接npm run dev的 React Vite 项目骨架。其他框架目标如 Angular、Vue的契约仍然有效但可能初始化在“仅契约”模式需要你手动关联现有的或新创建的运行时项目。3.2 棕地集成为现有项目注入设计智能对于已有代码库比如一个正在开发的 React 应用Decantr 也能无缝集成。# 1. 分析现有项目 decantr analyze # 此命令会扫描你的代码库尝试识别现有的组件、样式和模式并生成一份分析报告。 # 2. 初始化并附加 Decantr 契约 decantr init --existing --yes # --yes 参数表示接受默认配置避免交互式提问。操作意图与细节decantr analyze不会修改你的任何代码。它只是作为一个侦察兵了解你项目的现状为创建初始的essence文件提供依据。报告会指出它发现了哪些可能的设计令牌、常见的布局模式等。decantr init --existing是关键。它会基于分析结果创建一个尽可能匹配你当前项目状态的decantr.essence.json文件并建立.decantr上下文目录。从此你的项目就被 Decantr “治理”了。集成后的工作流之后你可以通过修改essence文件来规范或调整设计然后使用decantr refresh和decantr check来确保新旧代码都逐步向统一的契约靠拢。这是一个“治理先行逐步重构”的过程。3.3 混合组合在已有契约上增量演进项目进行中你可能会想引入一个全新的、设计精美的“数据可视化”区块或者临时切换一个暗色主题用于演示。这就是混合组合的用武之地。# 从注册表搜索并添加一个预设的“数据分析”区块 decantr add section --from-registrydata-analytics # 切换到一个名为“midnight”的暗色主题 decantr theme switch midnight # 查看当前项目可用的注册表内容 decantr registry list --local使用场景这个路径非常适合团队协作和模块化开发。设计师可以在 Decantr 注册表上发布一个精心设计的“用户个人资料”区块包开发者只需一条命令即可将其设计契约整合进自己的项目然后由 AI 助手基于此高质量规范生成代码保证了跨团队、跨模块的 UI 一致性。4. 核心工具链与生态详解Decantr 不仅仅是一个 CLI它是一个围绕 AI UI 生成构建的小型生态。4.1 CLI本地开发的核心引擎CLI 是与 Decantr 交互的主要方式功能覆盖项目全生命周期。命令类别核心命令功能与使用场景项目脚手架new,init创建新项目或初始化现有项目是旅程的起点。上下文管理refresh在修改essence.json后重新生成所有派生上下文文件保持同步。验证与审计check,auditcheck用于快速检查本地变更是否合规audit用于生成完整的、包含历史漂移分析的报告适合 CI/CD 流程。注册表交互search,registry summary,registry compile-packs探索和利用社区共享的设计资产将远程蓝图或区块编译到本地上下文。智能发现magic,suggestdecantr magic “一个具有玻璃态效果的仪表盘”能基于自然语言描述在注册表中寻找匹配的蓝图或主题极大降低了探索门槛。4.2 MCP 服务器与 AI 助手深度集成MCP模型上下文协议是让 Decantr 能力直接暴露给 AI 助手如 Claude Desktop、Cursor Agent的关键。原理Decantr 的 MCP 服务器作为一个本地服务运行。当你的 AI 助手被配置连接到此服务器后它就获得了直接读取essence、查询注册表、获取精准上下文、甚至执行即时检查 (critique-file) 的能力。优势这比单纯让 AI 读取文件更强大。AI 可以通过 MCP 主动询问“当前项目的主题色是什么”或“为这个文件运行一次设计规范检查”。这使得 AI 助手从被动的代码生成器变成了一个主动的、懂设计的协作伙伴。配置通常需要在 AI 助手的设置中添加一个指向本地decantr/mcp-server的 MCP 配置。具体步骤参考官方文档这步配置是解锁无缝体验的重点。4.3 验证器与托管服务质量守门员验证器这是一个独立的、基于模式的分析引擎。无论是 CLI 的check还是托管 API 的critique底层都是同一个验证器在工作。它保证了检查结果的一致性。托管注册表与 APIregistry.decantr.ai不仅是一个浏览界面更提供了 RESTful API。这意味着你可以将decantr registry audit-project集成到你的 CI 流水线中每次 Pull Request 都自动进行设计合规性审计并生成报告。5. 实战进阶从使用到定制5.1 自定义主题与设计令牌虽然可以使用注册表中的主题但为品牌定制独一无二的主题是必然需求。这需要直接编辑decantr.essence.json中的theme部分。// decantr.essence.json (部分) { dna: { theme: { name: MyBrand, tokens: { color: { primary: { 50: #f0f9ff, 100: #e0f2fe, 500: #0ea5e9, // 你的品牌主色 900: #0c4a6e } }, spacing: { unit: 4, // 定义基础单位所有间距将是 4px 的倍数 scale: [0, 1, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96] // 间距比例尺 }, typography: { fontFamily: { sans: [Inter, system-ui, sans-serif] } } } } } }修改后运行decantr refresh。你会发现src/styles/tokens.css中的 CSS 自定义属性CSS Variables已经自动更新。AI 助手在生成代码时就会引用这些变量如var(--color-primary-500)从而保证颜色使用的统一。5.2 创建并发布自己的区块到注册表当你设计了一个非常棒的通用“设置表单”区块并希望团队其他项目或社区都能使用时可以将其发布。在本地创建区块契约这通常是一个包含section-definition.json和若干示例上下文文件的文件夹。使用 Registry API 或 CLI 工具包decantr/registry包提供了将本地契约打包并发布到注册表私有或公共的工具函数。版本化与依赖管理发布的区块可以像 npm 包一样进行版本控制。其他项目可以通过decantr add section --from-registryyour-org/settings-formlatest来添加指定版本。实操心得内部共享区块是提升跨团队效率的利器。我们为公司的设计系统如导航栏、数据表格、空状态创建了 Decantr 区块包。前端团队在任何新项目中都能立即获得这些高质量、可 AI 生成的 UI 模块从第一天起就保证了与公司设计语言的 100% 一致。5.3 集成到 CI/CD 流程确保代码质量不因 AI 的引入而下降自动化检查是必须的。# 示例GitHub Actions 工作流片段 name: Decantr Audit on: [pull_request] jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 - name: Install pnpm and Decantr run: | npm install -g pnpm pnpm add -g decantr/cli - name: Run Decantr Audit run: | decantr audit --namespace official --formatjson --outputdecantr-report.json continue-on-error: true # 先完成审计再根据结果判断 - name: Upload Audit Report uses: actions/upload-artifactv4 if: always() with: name: decantr-audit-report path: decantr-report.json # 你可以进一步解析报告根据错误/警告数量决定是否阻塞合并6. 常见问题与排查技巧实录在实际使用中你可能会遇到一些典型问题。以下是我和团队踩过坑后总结的排查清单。6.1 AI 助手似乎“无视”了 Decantr 契约现象AI 生成的代码没有使用预期的设计令牌或者风格不符。排查步骤检查上下文加载确认你的 AI 助手如 Cursor已正确配置并连接到了 Decantr 的 MCP 服务器。在 Cursor 中可以尝试在聊天框输入/mcp查看已连接的服务器列表。验证上下文文件打开.decantr/context/下对应的区块文件看内容是否正确。运行decantr refresh确保它们是最新的。检查DECANTR.md确保根目录下的DECANTR.md文件存在且内容完整。这是 AI 助手读取的“使用说明书”。提供明确指令在向 AI 提问时可以明确引用契约。例如“请根据本项目的 Decantr 契约特别是section-dashboard.md中定义的间距系统重构这个组件的布局。”6.2decantr check报告了大量“漂移”现象运行检查命令后输出一堆错误指出代码与契约不匹配。排查与解决区分“错误”与“警告”首先看是 DNA 错误还是蓝图警告。DNA 错误如颜色对比度不足必须修复蓝图警告如布局轻微偏差可以评估影响。渐进式修复不要试图一次性修复所有问题。优先处理阻碍构建或影响核心功能的 DNA 错误。可以运行decantr check --rulecolor-contrast只检查某一类问题。利用 AI 辅助修复将decantr check的输出直接粘贴给 AI 助手并指令“请根据这些错误信息帮我修复SomeComponent.tsx文件中不符合设计契约的代码。” AI 在明确上下文的情况下修复效率很高。审视契约合理性有时报告“漂移”是因为契约本身过于严格或不适合当前场景。这时需要回到decantr.essence.json调整相关规则例如放宽某个场景下的间距要求。6.3 性能与速度问题现象项目较大时decantr audit或decantr refresh运行缓慢。优化技巧使用--since标志在 CI 中可以结合 Git 历史进行增量审计。decantr audit --sinceorigin/main只检查当前分支与 main 分支差异的部分大幅提升速度。忽略文件配置在项目根目录创建.decantrignore文件类似.gitignore将node_modules,dist,*.test.*等无需检查的目录和文件模式加入减少扫描范围。缓存机制Decantr 的 MCP 服务器和部分 CLI 操作会有缓存。如果遇到奇怪的问题可以尝试清除缓存通常位于~/.cache/decantr或项目内的.decantr/cache目录。6.4 与现有设计系统或组件库的整合现象团队已有成熟的 Material-UI 或 Ant Design 组件库如何与 Decantr 共存实践方案契约作为“上层规范”将 Decantr 的theme与你的组件库主题进行映射。例如在essence.json中定义primary-500然后在项目的主题配置文件中确保 MUI 的primary.main指向同一个颜色值var(--color-primary-500)。区块作为“组合指南”Decantr 的区块定义不直接生成具体的 Button 组件代码而是描述“这个区域需要一个主要操作按钮其文案是‘提交’遵循主色调”。AI 助手在生成代码时会调用你项目中的Button variantcontained colorprimary来实现。自定义验证规则通过扩展 Decantr 的验证器可以加入针对特定组件库的规则。例如检查是否错误地混用了 MUI 的Container和自定义的Box组件。这需要一定的定制开发能力。Decantr 的出现标志着一个新的协作范式人类负责定义规则和意图产品设计、设计系统AI 负责在规则内高效、一致地执行实现编写 UI 代码。它并没有取代设计师或开发者而是通过提供一个精确的、机器可读的“契约层”极大地放大了两者的能力让 AI 生成的 UI 从“能用”走向了“专业、一致、可维护”。对于任何正在或计划大规模使用 AI 进行前端开发的团队来说深入理解和引入 Decantr 这样的设计智能治理工具将是构建高质量、可持续数字产品的关键一步。