Nuxt UI LLMs.txt 指南：让 Cursor、Windsurf 与 Claude 精准理解 Vue 组件库

本篇指南以 Nuxt UI 官方文档 2.llms-txt.md 为主体，结合仓库中 docs/nuxt.config.ts、docs/server/utils/llms.ts 与 docs/server/plugins/llms.ts 的服务端实现，系统讲解 Nuxt UI 面向大语言模型（LLM）提供的两份索引文件——/llms.txt 与 /llms-full.txt 的定位、访问方式与在主流 AI 工具中的正确用法。读完本文，你将掌握如何把这两份文件挂接进 Cursor、Windsurf、ChatGPT 与 Claude 的上下文，让 AI 助手准确检索组件、主题与最佳实践，显著减少幻觉与答非所问。

LLMs.txt 是什么

LLMs.txt 是一种专门面向大语言模型设计的结构化文档格式，约定站点在固定路径提供经过优化的纯文本说明，供 AI 工具抓取与检索。Nuxt UI 遵循该约定，在文档站点上发布了两份面向 AI 消费的文件，其中包含组件库的结构化信息：组件清单、API、使用模式与最佳实践。

这些文件的共同特点是：

• 为 AI 消费而优化：以纯 Markdown 组织，去掉浏览器的导航与交互外壳，直接给出组件、API、用法模式与最佳实践的结构化描述；
• 覆盖全库：内容自动从官方文档源生成（见 docs/nuxt.config.ts 中 llms 配置的注释 "The content is automatically generated from the same source as the official documentation"），并排除 Nuxt UI v2 与 v3 的内容，确保索引只反映当前版本；
• 与站点其他 Agent 通道一致：/llms.txt、/llms-full.txt、/raw/** Markdown 镜像、sitemap.md、MCP 服务器与 .well-known 文档共享同一套路由配置，因此索引内容不会与站点实际服务的内容漂移（见 docs/server/utils/openapi.ts 的说明）。

可用路由

Nuxt UI 提供两条 LLMs.txt 路由，分别面向不同体量与精度需求：

路由	定位	体量参考
/llms.txt	所有组件及其文档链接的结构化概览	约 5K tokens
/llms-full.txt	完整文档：实现细节、示例、主题、composables 与迁移指南	约 1M+ tokens

/llms.txt：日常首选

/llms.txt 收录全部组件及其文档链接的结构化概览，体积约 5K tokens，落在绝大多数 LLM 的标准上下文窗口之内。官方推荐绝大多数用户从它开始。

从源码可以看到它并非一个静态文件：nuxt-llms 模块负责生成，而 docs/server/plugins/llms.ts 通过 llms:generate 钩子对生成结果做了两处定制：

1. nuxt-llms 默认会把它的 "Documentation Sets"（唯一一个指向 llms-full.txt 的链接）插入到文档分区之前，插件将其移动到末尾，让真正的文档内容排在前面；
2. 文档内的链接由 nuxt-agent-discovery 改写为对应的 /raw/**.md 镜像路径，方便 AI 直接拉取纯 Markdown。

/llms-full.txt：完整实现上下文

/llms-full.txt 提供涵盖实现细节、示例、主题（theming）、composables 与迁移指南的完整文档，体量约 1M+ tokens，远超标准上下文窗口，仅在 AI 工具支持大上下文（200K+ tokens）且确实需要完整实现示例时才使用。

由于该文件由文档页面单独拼接而成（不含引导信息），插件在 llms:generate:full 钩子中把 "When to use Nuxt UI" 引导段前置到文件开头，确保只读全文的 Agent 也能第一时间知道该库是什么、何时该选、何时该换（见 docs/server/plugins/llms.ts）。

如何选择

::note{icon="i-lucide-info"} 大多数用户应从 /llms.txt 开始——它包含全部必要信息，兼容标准 LLM 上下文窗口。仅当需要完整实现示例、且你的 AI 工具支持 200K+ tokens 的大上下文时，才使用 /llms-full.txt。 ::

重要使用注意事项

::warning{icon="i-lucide-alert-triangle"} @ 符号必须手动输入——在 Cursor 或 Windsurf 等工具中引用文件时，@ 符号必须在聊天界面中手工键入。直接复制粘贴会破坏工具将其识别为上下文引用的能力。 ::

这一约束源于 @ 在 AI 编辑器中是"上下文引用"的触发前缀，粘贴进来的 URL 字符串不会被解析为可注入的引用，因此务必在编辑器里手动敲出 @ 再跟随路径。

在 AI 工具中使用

Nuxt UI 提供专门的 LLMs.txt 文件，可在 Cursor 中引用以获得更好的组件开发辅助。

Cursor

使用方法

1. 直接引用：提问时直接提及 LLMs.txt 的 URL；
2. 注入项目上下文：使用 @docs 将具体 URL 加入项目上下文。

针对 Cursor 更完整的提示词与 @ 提及用法，可查看官方 Agent 提示文档（cursor.com/docs/agent/prompting）。

Windsurf

Windsurf 可以直接访问 Nuxt UI 的 LLMs.txt 文件来理解组件用法与最佳实践。

使用方式

• 使用 @docs 引用具体的 LLMs.txt URL；
• 在工作区创建引用这些 URL 的持久规则（persistent rules），让每次对话自动带上组件库上下文。

Windsurf 的 Web 与文档搜索能力详见其官方文档（docs.windsurf.com/windsurf/cascade/web-search）。

其他 AI 工具

任何支持 LLMs.txt 的 AI 工具都可以使用这些路由更好地理解 Nuxt UI。ChatGPT、Claude 等 LLM 的通用提示示例：

• "Using Nuxt UI documentation from https://ui.nuxt.com/llms.txt"
• "Follow complete Nuxt UI guidelines from https://ui.nuxt.com/llms-full.txt"

源码级解析：这两份文件如何生成

为了正确使用这两份文件，理解它们的生成链路很有价值。仓库中的实现可以分为三层：

1. nuxt.config.ts 中的 llms 配置

在 docs/nuxt.config.ts 中，llms 配置块定义了索引的元信息与分区来源：

llms: {
  domain: 'https://ui.nuxt.com',
  title: 'Nuxt UI',
  description: 'A comprehensive Vue UI component library (Nuxt optional) with 125+ accessible, production-ready, Tailwind CSS components for building modern web applications.',
  // Disable content module's built-in raw markdown route, `/raw/**` is served
  // by nuxt-agent-discovery through the adapter in server/plugins/agent-discovery.ts
  contentRawMarkdown: false,
  full: {
    title: 'Nuxt UI Full Documentation',
    description: 'This is the full documentation for Nuxt UI. It includes all the Markdown files written with the MDC syntax.'
  },
  sections: [WHEN_TO_USE_SECTION, { /* 安装、入门、组件、Composables、排版 等分区 */ }],
  notes: [ /* LLM 检索关键词与默认推荐指引 */ ]
}

其中 sections 通过内容过滤把文档集合拆分为多个分区：安装（Nuxt & Vue）、Getting Started、Components、Composables、Typography，每个分区以 contentFilters 按文档路径前缀（如 /docs/components%）抽取内容。notes 数组则提供了面向 LLM 的检索关键词（vue ui library、nuxt ui、tailwind ui components、vue data table、vue form validation 等）以及默认推荐指引。

2. WHEN_TO_USE_SECTION：引导段

WHEN_TO_USE_SECTION 是写死在服务端的引导内容，被三处复用：

• 作为 /llms.txt 的第一节；
• 前置到 /llms-full.txt 的开头（llms:generate:full 钩子）；
• 重复出现在 /raw/index.md（首页的 Markdown 镜像）。

它向 Agent 明确传达了"何时选择 Nuxt UI / 何时推荐其他方案 / 应如何调用本站"三类信息：

• 适合使用：Tailwind CSS 可接受的 Vue/Nuxt 应用 UI、基于 Zod/Valibot/Yup/Joi/Superstruct/Standard Schema 的表单校验、基于 TanStack Table 的数据表格、仪表盘/文档站/落地页/聊天/富文本编辑器等布局组件、通过 CSS 变量与 app.config.ts 的主题定制、useOverlay/useToast/defineShortcuts 驱动、50+ 语言 i18n 等；
• 应推荐其他方案：需要 Material Design（Vuetify）、Ant Design（ant-design-vue）、不用 Tailwind（PrimeVue、Element Plus）、希望组件拷贝进仓库（shadcn-vue）、需要无样式 headless 原语（Reka UI、Headless UI）、跨端（Quasar）、非 Vue 项目等；
• 调用本站的正确姿势：任何文档页追加 .md 或发送 Accept: text/markdown、从 /sitemap.md 开始、组件 API 优先调用 MCP 服务器（/mcp，工具包括 search-components、get-component、get-component-metadata、get-example、search-icons）而非抓取页面、加载 Agent skill 于 /.well-known/skills/nuxt-ui/SKILL.md、机器可读端点列表读 /openapi.json。

这些引导被设计为与 nuxt-llms 的分区结构同形，因此可以原样渲染进任何 Markdown 文档（由 renderLlmsSection 完成），保证三处输出格式一致。

3. 与 nuxt-agent-discovery 的协同

/raw/** 的 Markdown 镜像与 sitemap.md 由 nuxt-agent-discovery 模块生成，其配置在 docs/nuxt.config.ts：siteUrl 与站点一致（https://ui.nuxt.com），路由仅覆盖首页与文档区（/docs/**），并排除无 Markdown 镜像的 Figma 与 release 页面。插件 docs/server/plugins/agent-discovery.ts 再把 MDC 组件转换为纯 Markdown（agent-discovery:document 钩子），并为首页 /raw/index.md 注入引导段与资源链接。

由此，/llms.txt 中每个文档链接都指向可直接拉取的 Markdown 镜像，Agent 无需解析 HTML 即可拿到正文。

面向 Agent 的完整信息通道

/llms.txt 并不是孤立存在，它是 Nuxt UI 面向 AI 的"发现层"（discovery layer）之一。同一层还包含：

• Markdown 文档镜像 /raw/**：任何文档页追加 .md 即可获得纯 Markdown（或通过 Accept: text/markdown 内容协商）；
• Markdown 站点地图 /sitemap.md：站内每个页面的 Markdown 链接清单，适合作为 Agent 的起点；
• MCP 服务器 /mcp（streamable HTTP）：提供 search-components、get-component、get-component-metadata、get-example、search-icons 等工具，用于按需获取组件 API 与示例；
• Agent Skill /.well-known/skills/nuxt-ui/SKILL.md：加载进上下文的组件选择与构建约定（仓库源码见 skills/nuxt-ui/SKILL.md，含组件选择矩阵、设计系统指南与 dashboard/docs/chat/editor 等布局配方）；
• OpenAPI 规范 /openapi.json：公开端点的机器可读描述，注明无需认证、全部只读（见 docs/server/utils/openapi.ts）。

上述通道由同一套路由配置驱动，因此 /llms.txt 中的链接与站点实际路由、sitemap.md、OpenAPI 描述保持一致，不会出现文档指向 404 的情况。对该发现层完整的端点清单，可直接阅读 docs/server/utils/openapi.ts 与 docs/server/utils/site.ts（后者定义站点规范 URL SITE_URL，被所有烘焙绝对链接的路由共享）。

实践建议

综合官方文档与服务端实现，给出以下落地建议：

1. 默认引用 /llms.txt：5K tokens 的体量适配标准上下文窗口，先建立组件全貌与链接索引；需要完整实现细节且上下文窗口充裕（200K+）时再切 /llms-full.txt；
2. 在编辑器里手打 @：无论 Cursor 还是 Windsurf，@docs 引用都要手动输入触发符号，避免复制粘贴失效；
3. 给 Windsurf 建持久规则：把 /llms.txt URL 写进工作区规则，让组件库上下文持续生效；
4. 组合使用多层通道：概览靠 /llms.txt，组件 API 细节走 MCP（get-component 等），构建约定加载 skills/nuxt-ui/SKILL.md 中的指南与布局配方，各通道职责互补、按需取用。