## 什么是 llms.txt？

llms.txt 是在域名根目录（`/llms.txt`）提供的纯文本 Markdown 文件，用人类可读的散文向大语言模型描述你的服务。[OpenAPI](/kb/zh/openapi) 为机器提供结构化规范，[robots.txt](/kb/zh/robots-txt) 告诉爬虫该抓取什么，而 llms.txt 则以 LLM 已经最擅长处理的格式，向 LLM 提供它需要的*叙述性上下文*——让 LLM 理解你的服务做什么、代理何时应该使用它、哪些端点重要。

该规范由 Jeremy Howard（fast.ai、Answer.AI）于 2024 年 9 月提出。它有意做得很轻量：没有 schema 验证、没有 JSON 解析、没有版本控制。一个带有 H1 标题和单行摘要的 Markdown 文件。简单就是特性——任何人都可以在五分钟内编写一个，任何 LLM 都可以无需特殊工具读取它。

## 为什么 llms.txt 重要

浏览网络的 LLM 面临分诊问题。现代网站的单个页面可能有 200KB 的 HTML，大部分有意义的文本隐藏在代理的抓取器无法渲染的 JavaScript 之后。即使代理可以渲染 JS，信噪比也很差——导航、广告、Cookie 横幅和跟踪脚本占据了大部分字节。

llms.txt 正好相反：单个文档、纯文本、几 KB 大小、开门见山。代理获取 `https://example.com/llms.txt` 会得到：

- 服务是什么，一句话说清
- 重要的端点或页面列表
- 散文形式的认证/支付规则
- 代理可以复制的示例调用

这就是"代理必须自己搞清楚你的网站"和"代理可以一次获取就判断你的网站是否相关"的区别。对于希望被 ChatGPT、Claude、Perplexity 或任何检索增强系统引用的网站，llms.txt 是最便宜的可能 affordance。

## 工作原理

没有协议协商。代理像请求 `/robots.txt` 一样请求 `/llms.txt`，期望返回 `text/markdown` 或 `text/plain`，然后解析 Markdown。文件必须以 H1 标题开头；其他都是约定。

最小有效的 llms.txt：

```markdown
# 你的服务名称

> 服务功能的一行描述。

## 概述

你的服务是干什么的，2-3 句话。以代理会关心的用例开头，
而不是你公司的历史。

## 端点

- `GET /api/search?q=` — 搜索目录（免费）
- `POST /api/order` — 下订单（付费：x402）
- `GET /api/status` — 健康检查（免费）

## 认证

免费端点无需认证。付费端点返回带 x402 支付挑战的 HTTP 402。
在 Base 上用 USDC 结算。

## 示例

搜索鞋子：
  GET /api/search?q=shoes

下订单：
  POST /api/order {"sku": "ABC123", "qty": 1}
```

这就是全部规范。除了 H1 之外的标题都是可选的。项目符号列表、围栏代码块和链接都能工作，因为它们是 Markdown——代理使用它们已经在用的 Markdown 库来解析它们。

## llms.txt 与其他代理可读性文件对比

| 文件 | 用途 | 格式 | 谁读它 |
|---|---|---|---|
| `/llms.txt` | LLM 的叙述性上下文 | Markdown | LLM、浏览代理 |
| `/llms-full.txt` | 完整文本语料库，一个文件 | Markdown / 纯文本 | RAG 管道、嵌入式代理 |
| `/robots.txt` | 抓取权限 | 纯文本指令 | 爬虫、机器人 |
| `/sitemap.xml` | 爬虫的 URL 索引 | XML | 搜索引擎 |
| `/openapi.json` | 程序化 API 规范 | JSON/YAML | 代码生成器、API 客户端 |
| `/.well-known/mcp` | 工具服务器协议 | JSON-RPC | MCP 兼容代理 |

llms.txt 不替代任何这些——它在 robots.txt（机器指令）和 OpenAPI（机器规范）之间填补了空白，提供一层为需要推理你的网站用途的*语言*模型优化的内容。

## 配套：llms-full.txt

llmstxt.org 规范定义了一个可选的姊妹文件：[llms-full.txt](/kb/zh/llms-full-txt)。约定相同——Markdown、在根目录提供——但内容不同。llms.txt 是*目录*（带指针的简要概述）。llms-full.txt 是*语料库*（你的网站的完整连接文本内容放在一个文件中）。

为什么要两个？两类不同的消费者：

- **浏览代理**有限的上下文窗口，想要目录——根据 llms.txt 选择接下来获取什么。
- **非浏览代理**（RAG 管道、一次性检索、移动应用中嵌入的代理）想要语料库——一次摄取 llms-full.txt，然后无需更多 HTTP 请求即可回答问题。

如果可以，两个都发布。llms.txt 是营销门面；llms-full.txt 是知识库。

## 谁在发布 llms.txt

采用已经在 AI 基础设施、开发者工具和内容平台中广泛展开：

- **Anthropic** 在 [docs.anthropic.com/llms.txt](https://docs.anthropic.com/llms.txt) 发布 llms.txt，列出开发者文档的每个页面。
- **Cloudflare** 在 [developers.cloudflare.com/llms.txt](https://developers.cloudflare.com/llms.txt) 为 Workers 和平台文档发布。
- **Stripe** 为 API 参考发布。
- **Vercel、Mintlify、Netlify、Supabase 和 Fly.io** 都为其开发者文档发布 llms.txt。
- **许多开源项目**通过文档生成器自动发布 llms.txt（Mintlify 和 Docusaurus 都有插件）。

出现的模式：文档平台为其*文档*发布 llms.txt，产品网站为其*API 表面*发布 llms.txt。两者都有用——首次发现产品的代理读取营销 llms.txt，然后在需要集成详情时深入文档 llms.txt。

## 如何在你的服务中添加 llms.txt

### 1. 决定代理需要知道什么

跳过代理不需要的一切：你的公司故事、设计哲学、营销文案。从服务*做什么*和有哪些端点开始。如果你不能用一句话写出摘要，那你的服务太宽泛了——拆分它。

### 2. 创作文件

将 `/llms.txt` 创建为纯 Markdown。必需：第一行的 H1 标题和块引用摘要。推荐：一个"端点"部分、一个"认证"部分和 2-3 个示例请求。整个文件保持在 10KB 以下。

### 3. 在根目录提供

文件必须在 `/llms.txt`——不是 `/.well-known/llms.txt`，不是 `/docs/llms.txt`。代理直接探测根目录。大多数静态站点托管允许你将文件放在 `public/` 或 `static/` 中并按原样提供。

设置 `Content-Type: text/markdown` 或 `text/plain`。一些代理会拒绝 `application/octet-stream`。

### 4. 从首页链接

在 HTML head 中添加 `rel="alternate"` 链接，以便代理和爬虫发现它：

```html
<link rel="alternate" type="text/markdown" href="/llms.txt" title="LLM 友好的描述">
```

### 5. 也发布 llms-full.txt

将文档页面连接成 `/llms-full.txt` 上的单个 Markdown 文件。大多数文档生成器可以发出此文件。如果手动处理，遍历 Markdown 源并用 H1 分隔符连接的构建步骤就足够了。

## 常见错误和调试

- **文件作为 HTML 提供。** 静态主机有时将文本文件包装在它们的模板中。检查 `curl https://your-domain.com/llms.txt` 是否返回原始 Markdown，而不是包含它的 HTML 页面。
- **首行缺少 H1。** 规范要求文档以 `#` 开头。以块引用、frontmatter 或 HTML 注释开头的文件在期望 H1 的解析器中失败。
- **内容协商覆盖。** 一些服务器向浏览器返回 HTML，向代理返回 Markdown——但如果 `Accept` 头错误，代理会得到 HTML。直接提供文件；不要将其门禁在内容协商之后。
- **过时的 llms.txt。** 作者发布一次文件，从不更新。按计划重新获取的代理看到过时的端点。将 llms.txt 视为构建产物——API 更改时重新生成。
- **太长。** 超过 50KB 的文件被一些代理截断。如果你的 llms.txt 这么长，你实际上想要 llms-full.txt——拆分为目录和语料库。

agentgrade 的扫描器直接探测 `/llms.txt`，并检查文件是否存在、以 H1 开头、是否有非平凡的内容。

## 常见问题

### llms.txt 和 robots.txt 一样吗？

不。robots.txt 是给*爬虫*的指令（它们可以获取哪些 URL）。llms.txt 是给 LLM 的*上下文*（你的服务是什么以及如何使用它）。一个网站可以并且应该发布两者。

### 搜索引擎读取 llms.txt 吗？

一些非正式地读取。Google 没有正式承诺任何事情。主要消费者是 LLM 驱动的工具——ChatGPT 浏览、带 Web 搜索的 Claude、Perplexity、Cursor 的 @web——它们在总结或引用你的服务时检索 llms.txt。

### 我应该手写 llms.txt 还是生成它？

手写顶级 llms.txt——它很短（10-50 行），编辑判断很重要。从你的文档构建管道生成 llms-full.txt——它很长且机械化。

### 如果我的服务有付费端点呢？

用散文描述支付（"付费端点返回带 x402 支付挑战的 HTTP 402"）。不要尝试在 llms.txt 中编码支付元数据——那是 [x402](/kb/zh/x402) 和 [OpenAPI](/kb/zh/openapi) `x-payment-info` 的用途。

### llms.txt 取代 OpenAPI 吗？

不。OpenAPI 是严格的机器规范——代码生成器直接消费它。llms.txt 是叙述性的——LLM 读取它以理解意图。两者都发布：OpenAPI 用于工具链，llms.txt 用于上下文。

### llms.txt 与 SKILL.md 有何不同？

[SKILL.md](/kb/zh/skills) 是*指令性的*——代理遵循的剧本，用于执行任务。llms.txt 是*描述性的*——关于服务用途的上下文。SKILL 存在于代理运行时（Claude Code、Cursor 等）内，告诉代理*如何操作*。llms.txt 位于你的网站上，告诉*任何* LLM *你是什么*。

### 文件必须是 Markdown 吗？

规范说是 Markdown。实际上，纯文本也可以——大多数 LLM 无论如何都会忽略 Markdown 语法。但 Markdown 是推荐格式，因为标题给出了代理可以用来跳到相关部分的结构。

### 发布 llms.txt 会帮助我的 SEO 吗？

间接地。传统搜索引擎不会根据 llms.txt 的存在对页面进行排名。但 AI Overviews、Perplexity、ChatGPT 搜索和 Bing 的生成式答案越来越多地引用来源——清晰、结构良好的 llms.txt 让你成为更可引用的来源。这就是 GEO（生成式引擎优化），随着 LLM 驱动的搜索一起出现的 AEO 相关实践。

## 规范成熟度

**社区标准。** 由 Jeremy Howard 于 2024 年 9 月在 [llmstxt.org](https://llmstxt.org/) 定义。没有正式的治理机构，但被主要 AI 基础设施提供商（Anthropic、Cloudflare、Stripe、Vercel）和文档平台（Mintlify、Docusaurus）广泛采用。规范简短稳定——预计不会有破坏性变更。

## 了解更多

- [llmstxt.org](https://llmstxt.org/) — 规范
- [llms-full.txt](/kb/zh/llms-full-txt) — 完整内容配套
- [Anthropic llms.txt](https://docs.anthropic.com/llms.txt) — 参考实现
- [Agent Readiness](/agent-readiness) — llms.txt 如何融入更广阔的格局


## 交叉引用 {#cross-references}

如果你的站点同时提供 OpenAPI、MCP、SKILL.md、x402、A2A 或 WebMCP，请在 `llms.txt` 中提及它们。llms.txt 的目的就是成为代理为了解你的服务而读取的*唯一文档* —— 如果读完它仍然不知道你有付费 API 或 MCP 端点，代理就只能去碰运气探测 well-known 路径，而大多数代理不会这么做。

好的交叉引用是带有代理可获取的 URL 的一行项目：

- `POST /api/order` — 下单（通过 x402 付费 —— 见 `/.well-known/x402.json`）
- MCP 服务器: `/mcp`
- 用于 RAG 的完整语料: `/llms-full.txt`
- OpenAPI 规范: `/openapi.json`
- SKILL.md（代理操作手册）: `/skill.md`
- A2A 代理卡片: `/.well-known/agent.json`
- WebMCP 清单: `/.well-known/webmcp.json`

不需要专门的章节 —— 正文中的提及也算数。AgentGrade 的扫描会为你站点公开的每个资源发出一个可选子检查：如果扫描器检测到你的 `/mcp` 端点但 `llms.txt` 中从未出现 "mcp" 一词，就会以软失败的方式标出这个缺口。

这些都是可选检查：它们不会降低你的总分，但会标出 llms.txt 对正在阅读它的代理而言*未能发挥应有作用*的地方。


## 什么算作有意义的内容 {#meaningful-content}

llms.txt 规范只要求一个 H1，但仅有标题的文件无法教给代理任何东西。AgentGrade 的 *Meaningful content* 检查会确认文件至少具备三种结构信号之一，让代理有可执行的依据：

1. **Markdown 链接列表** — 至少三条 `- [标题](url)` 形式的条目。这是 Anthropic、Stripe、Cloudflare、Vercel、Mintlify 等大多数平台 llms.txt 采用的文档目录形态。每个链接都把代理指向它能够获取并阅读的真实内容。
2. **围栏代码块** — 任何用三个反引号包围的内容。`curl` 示例、示例 JSON 响应、展示如何认证的代码片段。这是 API 表面形态：一个文件用可工作的示例描述一个服务。
3. **命名的操作区段** — 像 `## Endpoints`、`## API`、`## Routes`、`## Authentication`、`## Examples`、`## Usage` 或 `## Quick Start` 这样的 H2 标题。这些名称表明"这是给代理的操作内容"，而非营销文案。

三者中**任一**满足即可通过。结构良好的 llms.txt 大多至少满足两项。

### 什么会失败

伪装成 llms.txt 的营销页脚：十五行，但没有 markdown 链接，没有代码块，没有操作区段。读取它的代理只知道 Acme 存在 —— 但找不到可以跳转的目标。*Meaningful content* 检查失败。

### 为什么链接很重要

llms.txt 是一个路由文件，不是内容文件（内容文件是 [llms-full.txt](/kb/llms-full-txt) 的职责）。它的工作是把代理指向它接下来应该获取的 URL。像 `- 关于` 这样的纯文本条目只给代理一个没有 URL 的标签 —— 它无法追踪。像 `- [关于](/about) — 公司信息` 这样的 markdown 链接则提供 URL 加上一行描述，让代理可以判断该页面是否值得获取。

此检查失败时最简单的修复方法：把纯文本条目变成 markdown 链接，或者加一个围栏示例展示代理如何调用你的服务。