Mlola UI

mlola-ui

Mlola UI 源码复制 CLI。它会将组件、区块、页面和模板写入你的项目，将它们的导入改写为适配项目的形式，并通过你的包管理器安装它们导入的 Mlola 包。与框架无关：复制的标记可用于任何能输出 HTML 的语言，React 源码则只使用 React。

该库的契约由其自身的样式表生成，因此读取它的模型不会凭空编造不存在的类或属性。

安装

npx mlola-ui init
npx mlola-ui add button sheet hero-split landing
npx mlola-ui doctor

init 会写入 mlola.config.json、引擎样式表，以及编码 Agent 会读取的说明（见下文），并安装 @mlola-ui/engine。它会适配检测到的项目：文件会放到 tsconfig.json 中 @/ 别名所指向的位置；如果项目有 src/ 目录，则放入其中。若没有别名（例如新建的 Vite 应用），它会设置 "imports": "relative"，让复制的文件通过相对路径互相导入，因此无需预先进行任何设置。

add 会解析依赖关系图（页面会拉取其区块，区块会拉取其组件），只复制你指定的内容，并安装复制的代码所导入、但 package.json 尚未声明的包。传入 --no-install 只会打印命令。doctor 会检查项目与注册表是否一致：已安装项目导入的包、引擎导入、主题属性，以及添加后发生更改的文件。

项目中可以继续使用 Tailwind。无论导入顺序如何，引擎都会将 Mlola 的层放在 Tailwind 的预检样式之上。

命令

命令	功能
init [--no-agents] [--no-install]	创建 mlola.config.json、样式表入口和 Agent 说明，并安装引擎
agents	在现有项目中写入或刷新 Agent 说明
mcp	通过 stdio 运行 Mlola MCP 服务，供编码 Agent 使用
add <items…> [--no-install]	将项目及其依赖复制到项目中，并安装它们导入的包
list [--json]	打印所有可安装项目
doctor	报告项目和注册表问题
check [path…] [--json] [--strict] [--all]	根据契约检查每个文件中的标记和 CSS，并统计手动输入的颜色和间距值
migrate [path…] [--write] [--json]	将 shadcn/ui 项目的 props、toast 和图标迁移到 Mlola，并列出需要人工处理的内容
render check <file | -> [--json]	根据 Mlola Render 目录检查 Agent 编写的 A2UI 消息；出错时退出码为 1
render catalog [--schema]	打印 Mlola Render 目录，作为 Agent 读取的指南或 A2UI 目录
render prompt [--tool] [--page-theme]	打印供你自行调用模型时使用的系统提示词：让每个回答都成为一个界面，或（使用 --tool）在有帮助时成为模型调用的工具；--page-theme 将主题交由页面处理
login <token>	为当前用户保存 Mlola Pro 令牌（来自 /account）
logout	清除已保存的令牌

检查项目

check 会对项目中的所有 HTML、JSX、TSX、Vue、Svelte、Astro 和 CSS 文件运行与 MCP 服务 check_markup 相同的检查（也可以检查你指定的路径），并报告每个问题所在的行及修复方法：

npx mlola-ui check            # the whole project
npx mlola-ui check src --json # one folder, every issue as data

最后会汇总样式偏差：手动输入而非从令牌读取的不同颜色和间距值有多少，以及出现最多的是哪些值。它适用于任何项目，因此即使项目尚未使用 Mlola，也可以先测量。在 Mlola 项目中，它会排除 CLI 安装的内容（--all 会将复制的标记纳入检查；Mlola 自身的样式表，包括构建好的主题，都由该库的门禁把关，不会接受检查）；如果安装了 Tailwind、UnoCSS 或 Windi，它会忽略工具类，只统计其中手动输入的值（bg-[#fafafa]、p-[13px]）。

发现错误时退出码为 1（使用 --strict 时，警告也会导致退出）；在 GitHub Actions 中，每个问题还会作为批注显示在拉取请求上：

# .github/workflows/ui.yml
name: UI
on: pull_request
jobs:
  mlola:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx -y mlola-ui@latest check src

从 shadcn/ui 迁移

migrate 会完成无需猜测即可由机器执行的更改，并列出其余更改的位置和操作方法。Mlola 会将组件安装到与 shadcn/ui 相同的文件中（components/ui/button.tsx），因此导入保持不变。默认情况下，它只读取；使用 --write 才会执行更改。

npx mlola-ui migrate            # what would change, and what needs a person
npx mlola-ui migrate --write    # make the changes
npx mlola-ui add button badge toast --overwrite   # the command it prints

它会重写直接写成字面量的属性（variant="destructive" 会变为 variant="danger"，Badge 的 variant 会变为其 tone），将 sonner 和较旧的 use-toast 迁移到 Mlola 的 toast（toast.error 会变为 toast.danger），将 switch 改为 toggle，并将 Mlola 支持的 lucide-react 图标替换为 @mlola-ui/icons 中的图标，同时保持文件自身的导入风格。它会将运行时计算出的值、cva() 辅助函数以及 API 不同的组件（Dialog、Select、Dropdown Menu……）留给你处理，并指出对应的替代属性或组件。

编码 Agent

init（或在现有项目中使用 agents）会告知项目的编码 Agent，该项目的 UI 使用 Mlola：

• mlola.agents.md：设计指南，包含所有类、data-* 值和令牌，以及新 UI 的规则；
• AGENTS.md：标记之间的一段简短说明，指向该指南（合并内容，绝不覆盖）；以及为 Claude Code 导入该指南的 CLAUDE.md；
• .mcp.json（以及项目使用的 .cursor/ 或 .vscode/）：Mlola MCP 服务。

npx mlola-ui mcp 即为该服务。它会从此 CLI 内置的注册表离线应答：get_design_rules、search_components、get_component、get_tokens、check_markup（检查虚构的类、错误的 data-* 值、工具类，以及手写颜色、偏离 --ml-space-* 刻度的间距或褪色文本；检查范围包括 style 属性、<style> 块和工具类，并标出各自所在行）、get_render_catalog、check_render 和 render_ui（下文介绍的 Mlola Render）、add_components 和 init_project。对于未运行 init 的 Claude Code：

claude mcp add mlola --scope project -- npx -y mlola-ui mcp

它由你的 Agent 启动，并通过 stdio 通信，因此手动运行时，它会打印一行并等待。对于无法运行命令的 Agent，相同的工具（不包括两个写入工具）可通过 https://ui.mlola.com/mcp 使用（还提供 get_install_command，它也会提供 CDN 链接，以及适用于无需构建步骤的页面的脚本）；该服务也已列入 MCP Registry，名称为 io.github.mlolahq/mlola-ui。Cursor、VS Code、Codex 和聊天应用的相关说明，请参阅 https://ui.mlola.com/docs/agents。

Mlola Render

当 Agent 应该展示界面而不是编写界面代码时（例如在聊天中展示表单，或在 Agent 的应用中展示状态卡片），它会从 Mlola Render 目录中组合 A2UI v0.9 消息：使用免费组件和命名值，而不是颜色或类名。校验器会确保消息符合目录规范，并满足界面可用性的要求（每个字段都有名称、只有一个根节点、没有循环、标题顺序正确、值在范围内），并以 A2UI 的 VALIDATION_FAILED 格式返回结果，让 Agent 自行修正消息：

npx mlola-ui render catalog          # what an agent may compose
npx mlola-ui render check ui.json    # an array, one message, or JSON Lines

import { validateRender } from "mlola-ui/render";
import rules from "mlola-ui/render/rules" with { type: "json" };

const { valid, errors } = validateRender(messages, rules);

MCP 工具包括 get_render_catalog、check_render 和 render_ui。在支持 MCP Apps 的聊天中，render_ui 会在对话中绘制界面（其视图是资源 ui://mlola/render），用户按下的内容会作为下一条消息连同 A2UI 操作一起返回给 Agent。A2UI 目录为 mlola-ui/render/catalog 和 https://ui.mlola.com/a2ui/catalog/v1。

如果你自己调用模型，mlola-ui/render/ai 就是围绕调用所需的一切：系统提示词、用于读取模型回答的读取器（支持流式读取，也能处理 JSON 的各种包装形式），以及将被拒绝的回复连同错误一起传回的循环。Mlola 不会调用模型，也不会持有密钥：

import { composeRender } from "mlola-ui/render/ai";

const { valid, messages, turns } = await composeRender({
  rules,
  request: "A form to book a table for tonight",
  generate: ({ system, messages }) => callYourModel(system, messages), // answers with the model's text
});

renderSystemPrompt、renderTool、createRenderReader、readRenderReply、checkRenderReply 和 renderRepairPrompt 是可用于流式输出、工具调用或自定义循环的组成部分。运行 npx mlola-ui render prompt 可打印供其他语言编写的服务使用的提示词。

要自行绘制界面：在 React 中运行 npx mlola-ui add render-surface，或在不使用框架的页面中使用 @mlola-ui/behavior/render。请参阅 https://ui.mlola.com/docs/render。

Mlola Pro

此软件包不包含 Pro 组件、区块、页面和模板。获得许可证后，请在 https://ui.mlola.com/account 创建令牌，然后：

npx mlola-ui login mlp_…
npx mlola-ui add conversation bot

add 会从服务获取 Pro 项及其 Pro 依赖项，逐一使用完整性哈希校验文件，然后像添加其他项目一样写入文件。免费依赖项仍来自此软件包。Pro 样式表会放在 styles/mlola-pro/ 中，并汇总至 styles/mlola-pro.css：在引擎样式表之后导入一次即可。项目根目录中的 mlola-pro.agents.md 列出了供编码 Agent 使用的所有 Pro 类和属性；请让你的 AGENTS.md 指向它。在 CI 中，设置 MLOLA_PRO_TOKEN 即可，无需登录。令牌保存在 ~/.config/mlola-ui/credentials.json 中，仅你本人可读取。

配置

别名和目标位于 mlola.config.json 中：

{
  "aliases": {
    "components": "@/components/ui",
    "blocks": "@/components/blocks",
    "pages": "@/app/pages",
    "templates": "@/app/templates"
  }
}

CLI 可通过 npm tarball 运行，无需检出代码仓库；CI 中会测试打包后的安装。

采用 MIT 许可。属于 Mlola UI。