一句话结论：llms.txt 本身不保证 AI 会高频来读，但把它和页面上的 Markdown alternate 链接、llms-full.txt 分块三件事一起做对，代理读文档时踩空的死链能从每任务 2.23 条降到 0.11 条。

背景：文件挂出去了，代理照样点空

Mintlify 在 2026 年 7 月 17 日发布的基准测试，戳破了一个流行假设：站点根目录放一个 llms.txt，AI 代理就会顺着它优雅地读文档。实测 20 个文档站、5 类问题、4 种获取格式，共 2,400 次运行，结果是代理经常拿到 llms.txt 之后转去点里面的相对链接，而链接指向的是渲染后的 HTML 页面或干脆 404——它以为自己在读 Markdown 源，实际在读一堆导航栏和脚本。

同一时间段，Ahrefs 对 137,210 个域名的抽查给出了另一面：28% 的域名有 llms.txt，其中 97% 零请求。剩下 3% 约 1,100 个站点承接了约 22,000 次请求，96% 来自各类 bot，GPTBot 占 4.51%、ClaudeBot 0.8%、OAI-SearchBot 0.74%。SE Ranking 另做 30 万域名统计，有 llms.txt 的占 10.13%，与搜索/AI 可见度之间没有可测的相关性。

两组数据合起来说明一件事：llms.txt 不是开关，是接口。写了不等于被读，被读不等于读对。

落地清单：三件事一起改

1）文件位置与路由

• /llms.txt 放根目录，纯文本 + text/markdown（或 text/plain）响应头，不要走 SPA 路由，不能让 CDN 把它回退成 index.html。这是最常见的"200 但内容是 HTML"车祸现场。

• /llms-full.txt 放全量正文，供需要一次抓完的代理使用；超过 100,000 字符就按 Mintlify 2026 年 9 月 1 日那份报告的做法分块——按导航树切段，每段一个 URL，段头给出摘要和三五个关键链接，代理可以按需只取一段。

• 页面级配套：在每个文档页的 <head> 注入指向该页 Markdown 源的链接，这是 llms.txt v2 修订（2026 年 8 月 10 日）里补的部分，比只在根目录挂一个总表更有用。

<link rel="alternate" type="text/markdown" href="/docs/api/auth.md" />
<link rel="describedby" type="text/markdown" href="/llms.txt" />

2）llms.txt 原文结构（照这个骨架填，别自创字段）

规范结构只有四类元素：H1 站名、一段 blockquote 摘要、若干 H2 分节、分节下的链接列表。多余的元数据字段代理基本不解析。

# Acme Docs

> Acme 支付网关的开发者文档。REST + Webhook，SDK 覆盖 Node/Python/Go。

## 核心概念

- [认证](https://docs.acme.dev/auth.md): API Key 与 OAuth2 两种方式，必须带 X-Acme-Key
- [幂等与重试](https://docs.acme.dev/idempotency.md): 所有 POST 支持 Idempotency-Key，24 小时去重

## 接口参考

- [创建支付单](https://docs.acme.dev/api/payments-create.md): POST /v2/payments，必填 amount、currency、reference
- [查询支付单](https://docs.acme.dev/api/payments-get.md): GET /v2/payments/{id}
- [Webhook 事件](https://docs.acme.dev/api/webhooks.md): payment.succeeded / payment.failed / refund.created

## 可选

- [更新日志](https://docs.acme.dev/changelog.md)
- [完整文档包](https://docs.acme.dev/llms-full.txt)

要点三条：链接一律指向 .md 源而不是渲染页；每条链接后面用冒号跟一句话说明，代理靠这句话判断要不要点；"可选"分节放低优先级内容，不少实现正是按这个分节决定截断位置。

3）llms-full.txt 放什么、不放什么

放：接口参数表、错误码、鉴权流程、版本迁移说明。 不放：定价数字（代理会当成事实转述，过两周就是幻觉源）、内部工单链接、带 token 的示例请求、构建时间戳。

价格这类内容改成"见定价页"的链接，让代理取实时页面，比在 Markdown 里埋一个会过期的数字安全得多。

4）robots 与爬虫放行

llms.txt 生效的前提是爬虫进得来。三件事逐项核对：

# 1. 文件本身是否可直连、是否被中间层改写
curl -sI https://docs.acme.dev/llms.txt | sed -n '1p;/content-type/Ip;/cf-cache-status/Ip'

# 2. robots 里是否误伤 AI 爬虫（GPTBot / ClaudeBot / OAI-SearchBot / PerplexityBot）
curl -s https://docs.acme.dev/robots.txt   # 确认没有 User-agent: * + Disallow: / 的全局封杀

# 3. 边缘层是否按 UA 或路径二次拦截（Cloudflare AI Crawl Control 之类）
curl -s -o /dev/null -w '%{http_code}\n' -A 'GPTBot' https://docs.acme.dev/llms.txt
curl -s -o /dev/null -w '%{http_code}\n' -A 'ClaudeBot' https://docs.acme.dev/llms.txt

第三条特别值得做。EZY.ai 的 83 站 12 周对照实验（2026 年 4 月 27 日至 7 月 19 日）里有个反直觉结果：部署了 llms.txt 的站，OpenAI 类爬虫只来了 7 次，未部署的对照组来了 3,990 次；ClaudeBot 是 9 次对 3,120 次。也就是说决定抓取量的是爬虫策略和站点权重，不是 llms.txt 的有无。同一实验里 Meta-ExternalAgent 在部署组反而是 193 次、对照组 172 次——UA 层面的放行差异足以把结论整个翻转。

结果：能测到的和测不到的

以上均为发布方自述数据，非第三方复现。

定性观察：改完之后，代理问答里"参数写错、把 v1 接口当 v2 用"这类问题不再复现；同时 Lighthouse 的 Agentic Browsing 审计（Chrome 150+ 的实验性类别）在补齐 Markdown alternate 链接后不再因为缺 llms.txt 被扣分。需要注意的是 Google 官方在 2026 年 7 月 10 日的表述仍是"既不损害也不帮助"排名，把它当抓取友好度工程，不要当排名手段。

复盘：三条可以直接抄，两条别踩

可以直接抄的配置项：

1. llms.txt 与 llms-full.txt 都走静态文件直出，响应头 text/markdown; charset=utf-8，并把 CDN 回退规则里这条路径排除掉。

2. 每个文档页 <head> 加 rel="alternate" type="text/markdown"，链接指到同路径的 .md，别指到 /llms-full.txt。

3. llms-full.txt 超过 100,000 字符就按导航树分块，段首给摘要 + 3 条关键链接，代理命中率明显高于一个巨型文件。

踩坑提醒：

1. 文件写了但 robots 里 User-agent: * 还是 Disallow: /，或者边缘 WAF 把 GPTBot 当恶意 UA 拦了——表现为 llms.txt 全是 200，日志里零请求。

2. 在 llms-full.txt 里塞价格、库存、内部路径。这些是会过期的状态，代理会原样转述给用户，过两周就是可验证的错误答案。

标注：llms.txt v2（2026 年 8 月 10 日修订，补 <link rel="alternate" type="text/markdown"> 与 rel="describedby"）。规范为作者主张，未被任何 LLM 厂商官方确认为抓取标准。数据来源：Mintlify 基准（2026-07-17）与分块报告（2026-09-01）、Ahrefs 域名抽查、EZY.ai 83 站 12 周对照、SE Ranking 30 万域名统计，经 primores.org/blog/does-llms-txt-work（2026 年 6 月 16 日发布，11 月 4 日更新）汇总核对；Google 官方口径见其 2026-07-10 更新说明。本文数据为发布方自述，非第三方复现。复盘时间 2026-11-08。

标签：llms.txt、AI可见度、AIWO、结构化暴露、开发者文档