企业官网建设流程全解析

为文档密集型站点发布 llms.txt：以 Front-End Checklist 的生产实现为例

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist

llms.txt是 llms.txt 约定提出的一个可选的纯文本/Markdown 索引文件，为 AI 工具（LLM、Agent、MCP 客户端）提供更干净的文档入口。本篇指南围绕 Front-End Checklist 仓库中llms-txt规则（SKILL.md 与 references/rule.md）展开，结合该仓库在 Next.js App Router 下的真实生产实现（apps/web/app/llms.txt/route.ts），讲清何时需要llms.txt、如何设计文件结构、如何用 Route Handler 动态生成、如何与robots.txt/sitemap/MCP 协作，以及一套可直接执行的审计与验证流程。读完你将能够在自己的文档型站点上落地一个稳定、可维护、对 AI 友好的llms.txt。

llms.txt 是什么：为 AI 工具准备的文档入口

大型文档门户（公开 API 文档、帮助中心、SDK 参考、知识库）往往把最重要的页面埋在密集导航、站内搜索 UI 或框架专属布局之后。llms.txt正是针对这一痛点：它是一个可选的文件，通过一份"精选 + 一句话描述"的链接清单，让 AI 工具在一开始就知道哪些文档页面值得读，而无需像人一样先点穿整个导航树。

需要明确的是，llms.txt不会替代Web 常规的爬取与索引机制。它只是"给 AI 一个更干净的起点"，正常的robots.txt、XML sitemap、canonical 与结构化数据仍然各司其职。这一点在规则的前言与 references/rule.md 中被反复强调。

在 Front-End Checklist 仓库中，llms.txt不是理论概念，而是真实落地的产物：站点在根路径动态生成并托管/llms.txt（实现见 apps/web/app/llms.txt/route.ts），并同步提供/llms-full.txt作为可选的扩展伴生文件；同时 apps/web/app/robots.ts 中明确注释：llms.txt与llms-full.txt提供 LLM 友好的内容，而爬取控制仍由robots.txt负责。

快速参考（Quick Reference）

审计或实现llms.txt时，先用这四条结论校准方向：

• 如果你的站点是文档密集型，在根路径（生产域名的/llms.txt）提供服务；
• 精选一小批稳定、高信号（high-signal）的文档页，而不是把每个 URL 都倾倒进去；
• 仅在你能持续维护其时效性的前提下，把llms-full.txt作为可选的伴生文件提供；
• 爬取与索引控制始终保留在robots.txt中；llms.txt不替代它。

Check：如何审计一个站点是否达标

对任意"文档密集型"站点做检查时，验证三点：

1. 根路径可用性：该站点是否在根路径发布llms.txt（生产域名下请求/llms.txt应返回 HTTP 200）；
2. 内容质量：文件内是否包含精选的、稳定的高价值链接，例如入门指南（getting-started）、概念说明（concepts）、API 参考、可复制示例——而不是营销页、定价页或登录流程；
3. 边界正确性：确认llms.txt没有被当作robots.txt或 XML sitemap 的替代品，且文件中列出的每个 URL 都返回 HTTP 200、可公开访问。

Front-End Checklist 的生产实现恰好满足上述全部条件：GET /llms.txt返回Content-Type: text/plain; charset=utf-8，缓存头为public, max-age=86400, s-maxage=86400（见 apps/web/app/llms.txt/route.ts），且文件按分类聚合了全部英文规则与指南链接。

Fix：在站点根路径添加 llms.txt

修复动作分三步：

1. 在站点根路径新增llms.txt，包含一段简短的项目描述 + 一份精选的最有用文档 URL 清单；
2. 如果文档集很大且你能维护，追加可选的llms-full.txt伴生文件，并从llms.txt中链接到它；
3. 爬取指令继续留在robots.txt中。

规则建议的最小文件结构如下（来自 references/rule.md 的 Code Examples）：

# Example API Docs > Official documentation for Example API, including quickstarts, concepts, and reference material. ## Docs - [Getting Started](https://docs.example.com/getting-started): Setup, authentication, and your first request. - [Concepts](https://docs.example.com/concepts): Core mental model, resources, and lifecycle concepts. - [API Reference](https://docs.example.com/api): Endpoint-by-endpoint request and response details. - [Examples](https://docs.example.com/examples): Copy-paste examples for common integration patterns. ## Optional - [Full Reference](https://docs.example.com/llms-full.txt): Expanded documentation index for tools that can handle larger context files.

与之相对的"错误示范"——把通用站点导航原样搬进去：

# ❌ Poor example - [Home](https://example.com/) - [Blog](https://example.com/blog) - [Pricing](https://example.com/pricing) - [Login](https://example.com/login) - [Random changelog entry](https://example.com/changelog/2024-01-11)

二者的差异一目了然：前者围绕"开发者/支持任务"组织（快速开始、概念、参考、示例），后者则是没有任务语义的导航转储。这也是后续 Code Review 的核心判据。

生产实现：用 Next.js Route Handler 动态生成

Front-End Checklist 的做法比静态文件更进一步——用 Next.js App Router 的 Route Handler在构建/请求时从内容集合动态生成文件，确保链接与站点内容永不脱节。核心代码（apps/web/app/llms.txt/route.ts）：

/** Builds the compact llms.txt summary with categories, MCP info, and rule links. */ function generateLlmsTxt(): string { // Filter to English rules only const englishRules = allRules.filter(rule => rule.language === 'en') const englishGuides = allGuides.filter(guide => guide.language === 'en') // Group rules by primary category const rulesByCategory = englishRules.reduce<RulesByCategory>((acc, rule) => { const category = rule.primaryCategory if (!acc[category]) acc[category] = [] acc[category].push({ slug: rule.slug, title: rule.title, priority: rule.priority }) return acc }, {}) // ... 拼接 # Front-End Checklist 标题、MCP 入口、Resources、Categories、Guides、Rules 等章节 return content } /** Serves the compact llms.txt summary as a plain-text response. */ export async function GET() { const content = generateLlmsTxt() return new Response(content, { headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'public, max-age=86400, s-maxage=86400' } }) }

llms.txt路由位于app/llms.txt/目录下，因此生成的 URL 恰好就是根路径/llms.txt（apps/web/app/llms.txt/route.ts中的目录结构决定了这一点），满足"必须在生产域名根路径发布"的最佳实践。

从 apps/web/app/robots.ts 可以看到该站点的分工非常清晰：

export default function robots(): MetadataRoute.Robots { return { rules: [ { userAgent: '*', allow: '/', disallow: ['/api/', '/_next/', '/static/'] } ], sitemap: `${SITE_URL}/sitemap.xml`, host: SITE_URL // Note: llms.txt is available at /llms.txt and /llms-full.txt // These files provide LLM-friendly content about this checklist } }

即：robots.txt继续管控爬取（/api/、/_next/、/static/等敏感/内部路径被 disallow），llms.txt只做 AI 内容索引，二者互不替代。

Explain：为什么 llms.txt 有价值、llms-full.txt 为何可选

向他人解释时抓住三个核心论点：

1. 更干净的起点：文档门户常把核心内容藏在复杂导航、搜索框或 JS 渲染之后，llms.txt用纯文本清单直接告诉 AI 工具"先读这些页"，降低上下文浪费与抓取失败率；
2. llms-full.txt 是可选伴生：生态中它常被用作更大的扩展索引，但只有在你能让它与实际想被 AI 消费的文档保持同步时才值得发布；维护不了就不发；
3. 传统爬取控制仍在 robots.txt：llms.txt不是搜索引擎/爬虫的替代品，canonical URL、sitemap、页面级元数据等机制照常生效。

最佳实践（Best Practices）

• 在正式域名上精确发布为/llms.txt；
• 保持简短与精选：优先列出最有用的指南、概念、参考与示例；
• 使用绝对 URL，并为每条链接配一句话描述，保证条目脱离上下文也自洽；
• 只链接公开、稳定的内容：返回 HTTP 200、无需登录；
• 若提供llms-full.txt，把它定位为可选伴生文件，并从llms.txt中链接它。

常见错误（Common Mistakes）

• 把llms.txt当作robots.txt、XML sitemap 或结构化数据的替代品；
• 把 sitemap 里所有页面原样倾倒，而不是精选最高信号的文档 URL；
• 列出营销页、定价页、登录流程，而非面向任务的文档页；
• 链接那些只有搜索、Tab 切换或客户端渲染完成后才可见的内容；
• 宣称llms.txt是搜索排名、AI Overviews 或聊天助手收录的必需条件——这属于无依据的说法，规则明确禁止。

实现要点：何时用、llms-full.txt 怎么配

• 适用场景：站点已有大量文档，且你能长期维护一份精选索引。小型宣传站（brochure sites）、落地页、简单营销站通常收益有限，不必多维护一个公开文件。
• llms-full.txt 定位：生态中常见的更大伴生文件，但可选；发布前提是能与你想让 AI 消费的文档保持同步。
• 可复制的 Next.js 最小实现（来自 references/rule.md）：

// app/llms.txt/route.ts export async function GET() { const body = `# Example Docs > Public documentation for Example product. ## Docs - [Getting Started](https://docs.example.com/getting-started): Setup and first steps. - [API Reference](https://docs.example.com/api): Request and response details. ## Optional - [Full Reference](https://docs.example.com/llms-full.txt): Expanded docs index. ` return new Response(body, { headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'public, max-age=3600' } }) }

注意：Front-End Checklist 的生产实现把Cache-Control提升到了max-age=86400（一天），因为内容来自构建期编译的内容集合，变化频率低、缓存收益更高。你可以根据自身内容的更新频率在 3600–86400 之间取舍。

生产实现的仓库级细节：目录结构与配置

• 路由目录即 URL：apps/web/app/llms.txt/route.ts位于app/llms.txt/目录，Next.js 会把它映射为站点根路径的/llms.txt，天然满足"根路径发布"要求；
• 站点与 MCP 地址集中配置：SITE_URL与MCP_SERVER_URL等来自 packages/config/src/routes.ts，默认值分别为https://frontendchecklist.io与https://mcp.frontendchecklist.io，可被NEXT_PUBLIC_SITE_URL/NEXT_PUBLIC_MCP_URL环境变量覆盖——这意味着llms.txt中的链接在部署环境间自动切换，无需手改文件；
• 链接由路由构建器统一生成：absoluteUrl/absoluteRuleUrl（packages/config/src/routes.ts）为/rules、/guides、/llms-full.txt等提供绝对 URL，保证llms.txt中全是绝对地址，符合"条目脱离上下文自洽"的要求。

与 MCP 的互补关系

有意思的是，Front-End Checklist 并没有让llms.txt孤军奋战。在 packages/mcp/SPEC.md 的设计原则中明确写着：

Complement /llms.txt- MCP for structured queries, existing endpoint for bulk context

也就是说：/llms.txt负责"批量上下文"（一次性给 AI 工具所有精选链接的概览），而 MCP Server（/api/mcp）负责"结构化查询"（get_rule、search_rules、check_rule等 11 个只读工具）。生产版llms.txt文件头部也直接嵌入了 MCP 入口信息与 VS Code 配置片段（见 apps/web/app/llms.txt/route.ts）。对 AI Agent 而言，这个组合提供了"先看索引、再精确查询"的完整路径——这也是文档型站点可以借鉴的双层架构：静态索引文件 + 结构化查询 API。

工具与验证（Tools & Validation）

发布后按以下清单验证：

• 在生产域名请求/llms.txt，确认返回 HTTP 200；
• 逐个抽查文件内列出的 URL，移除会重定向、404 或需要认证的链接；
• 将llms.txt与 sitemap 及站点文档信息架构（IA）对比，确认它突出的是最有用的公开文档而非简单复制全部链接；同时对照 llms.txt 约定检查整体结构是否符合规范；
• 若发布了llms-full.txt，确认它已被llms.txt链接，并被明确定位为"扩展伴生文件"；
• 参考 llmstxthub.com 这类公开目录对比真实世界的实现后再定义自己的文件结构；
• 审计大量现存站点时，可使用辅助工具npx -y @thedaviddias/mcp-llms-txt-explorer加速批量检查。

例外情况（Exceptions）

• 小型营销站、作品集、单页站点通常不需要llms.txt，良好的页面级结构已足够；
• 位于认证之后的私有文档，可能需要内部等效物而非公开的llms.txt；
• 如果文档平台已暴露干净、稳定、公开的文档索引，而团队又无法再维护一个文件，跳过llms.txt是合理决策。

标准与验证清单（Standards & Verification）

判定规则是否满足的标准：以 llms.txt 约定和 Google Search Central 关于 AI 功能的官方指南为最终标准，检查最终面向搜索的 HTML、元数据与爬取行为；实现通过后再将规则标记为已满足。

自动化检查：

• 请求生产域名的/llms.txt，确认从精确根路径返回 HTTP 200；
• 校验文件内每个 URL 都返回 HTTP 200 并解析到 canonical 的公开页面；
• 若存在llms-full.txt，请求/llms-full.txt并确认同样返回 HTTP 200。

人工检查：

• 确认文件围绕开发者/支持任务精选，而非通用站点导航；
• 确认最重要的文档页无需站内搜索框、隐藏 Tab 或登录即可理解；
• 确认爬取与索引规则仍通过robots.txt、canonical URL、sitemap 和页面级元数据管理。

关联规则：llms.txt 在 SEO 规则体系中的位置

在该仓库的规则体系中，llms.txt与四条规则关系最紧密（见 packages/content/rules/en/seo/llms-txt.mdx 的 frontmatter）：

• llm-parsability：聚焦页面级结构（单页对 LLM 的可解析性），llms.txt则是站点级的发现层（帮 LLM 找到该读哪页）；
• robots-txt：控制爬虫访问；llms.txt只是可选内容索引，不可替代；
• sitemap：XML sitemap 仍是搜索引擎的权威机器可读 URL 清单；llms.txt是面向 AI 文档发现的精选伴生；
• structured-data：结构化数据帮助单页表达语义，llms.txt帮助 AI 工具发现优先读哪些页。

这条"站点级发现（llms.txt）+ 页面级结构（llm-parsability）+ 爬取控制（robots.txt）+ URL 清单（sitemap）+ 语义表达（structured-data）"的协作模型，正是文档型站点构建 AI 可发现性时可以整体照搬的架构。

在仓库中继续深挖

本文涉及的规则与实现证据均可在仓库中直接验证：

• 规则本体：SKILL 形态见 skills/llms-txt/SKILL.md，完整正文见 skills/llms-txt/references/rule.md，MDX 源见 packages/content/rules/en/seo/llms-txt.mdx；
• 生产实现：/llms.txt 路由 与 robots.txt 路由；
• 站点/MCP 地址与路由构建器：packages/config/src/routes.ts；
• MCP 与 llms.txt 的互补设计：packages/mcp/SPEC.md。

SKILL 目录结构本身也值得注意：每个规则技能由SKILL.md（name、description、prompts 指令）与references/rule.md（完整规则正文转纯 Markdown）两部分组成，二者由 scripts/generate/generate-skills.ts 从规则 frontmatter 自动生成——这也解释了为什么 SKILL.md 末尾会指引读者"seereferences/rule.md"获取完整实现细节。

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist