导语： Cloudflare 把 5000+ 页开发者文档按顶级目录拆成多个 llms.txt，再给每页挂一个 /index.md 兜底，自测代理取文档少耗 31% token、答对快 66%。

背景：代理在读 HTML，不是在读文档

Cloudflare 的开发者文档有 5000 多页。给这种体量的站配 llms.txt，最直觉的做法是生成一个巨型单文件——但这恰好是灾难的起点。

官方在复盘里描述了一个可复现的失败模式，叫 grep loop（grep 循环）：

1. 单文件 llms.txt 超出代理的即时上下文窗口，代理读不全；

2. 读不全就开始按关键词 grep，第一次搜不到精确细节；

3. 代理重新想、改写关键词、再搜一次；

4. 每一轮都产生新的"思考 token"和请求，最终响应更慢、总 token 更多、成本更高；

5. 更糟的是上下文被切碎，代理对整套文档的结构理解下降，答案开始跑偏——技术文档站最怕的"编参数"就是这么来的。

第二个痛点是格式。HTML 页面里塞满导航、侧边栏、脚本，一个普通页面转成纯文本，token 有一大半是噪音。2026 年 2 月 Cloudflare 测了 7 个代理，只有 Claude Code、OpenCode、Cursor 三个默认发 Accept: text/markdown 请求头，其余四个根本不会要 Markdown，只会一路抓 HTML。

所以这次改造要同时解决两件事：目录能不能进上下文，内容能不能拿到 Markdown。

落地清单

1. 文件位置：根 llms.txt 只做目录，按顶级目录分发

Cloudflare 的做法是每个顶级目录生成一个独立 llms.txt，根目录那份只负责指路。这是从 https://developers.cloudflare.com/llms.txt 抓取到的真实开头（2026-11-03 抓取，已截断展示）：

# Cloudflare Developer Documentation

Explore guides and tutorials to start building on Cloudflare's platform.

> Each product below links to its own llms.txt, which contains a full index of
> that product's documentation pages and is the recommended way to explore a
> specific product's content.

## Application performance

- [Cache / CDN](https://developers.cloudflare.com/cache/llms.txt): Make websites faster by caching content across our global server network
- [DNS](https://developers.cloudflare.com/dns/llms.txt): Deliver excellent performance and reliability for your domain
- [Load Balancing](https://developers.cloudflare.com/load-balancing/llms.txt): Maximize application performance and availability
- [SSL/TLS](https://developers.cloudflare.com/ssl/llms.txt): Encrypt your web traffic to prevent data theft and other tampering
- [Waiting Room](https://developers.cloudflare.com/waiting-room/llms.txt): Create a virtual waiting room to manage peak traffic

## Application security

- [Bots](https://developers.cloudflare.com/bots/llms.txt): Protect your domain from bad bot traffic
- [WAF](https://developers.cloudflare.com/waf/llms.txt): Filter incoming traffic and protect against web app vulnerabilities
- [Turnstile](https://developers.cloudflare.com/turnstile/llms.txt): Turnstile is Cloudflare's smart CAPTCHA alternative

三个细节值得抄：

• 链接指向的是子 llms.txt，不是页面 HTML。代理点进去拿到的是索引，不是渲染后的文档页。

• 每条 = 语义名 + URL + 一句描述。描述全部来自文档 frontmatter 里本来就有的 title / description，生成 llms.txt 时零额外人工成本。

• 一行一个产品，不嵌套。根文件只有几十行，任何代理都能一次性读完。

2. 每页 Markdown 兜底：/index.md + 两条 Cloudflare Rules

只有 3 个代理会主动要 Markdown，剩下的怎么办？Cloudflare 做了一个 URL 层面的兜底：任何页面 URL 后面加 /index.md，就直接返回该页的 Markdown。

关键是他们没有生成 5000 个静态 .md 文件，而是用两条规则动态实现（下方表达式按官方描述的参数复现，非后台截图原文）：

Rule 1  URL Rewrite（匹配 /index.md 结尾，改写回基础路径）
  When:  ends_with(http.request.uri.path, "/index.md")
  Then:  regex_replace(http.request.uri.path, "/index.md$", "")

Rule 2  Request Header Transform（注意匹配的是重写前的原始路径）
  When:  ends_with(raw.http.request.uri.path, "/index.md")
  Then:  set request header  Accept = "text/markdown"

顺序很重要：先按 /index.md 匹配到请求，再用 raw.http.request.uri.path（重写之前的原始路径）去补 Accept 头，最后才改写成真实页面路径。写成 http.request.uri.path 就会匹配不到，因为那时路径已经被剥掉了后缀。

这样做的收益是：没有构建步骤、没有内容副本、不会出现"Markdown 和 HTML 两个版本不同步"。llms.txt 里所有链接都指向 /index.md 形式，代理拿到的永远是 Markdown，不管它发不发那个请求头。

3. llms-full.txt：全量，但必须先剔噪

llms-full.txt 是给"想一次性拉完"的代理准备的全量文件。放什么不放什么，Cloudflare 的标准很明确：

• 剔除纯目录页。他们去掉了约 450 个只做本地目录列表的页面，例如 https://developers.cloudflare.com/workers/databases/。这类页在 sitemap 里有，但对 LLM 几乎没有信息量——所有子页已经在 llms.txt 里单独列了，代理再抓一次目录页，只会拿到一堆重复链接，还得再发一次请求才能拿到正文。

• 保留 frontmatter 派生的元数据。标题、语义化名称、描述全留着。人工可能忽略这些标签，但对代理来说这就是方向盘。

• 按产品目录切开。llms-full.txt 负责"全"，分目录的 llms.txt 负责"进得了上下文"，两者分工，不要指望一个文件两用。

4. robots / 爬虫放行配合项

llms.txt 写得再好，爬虫被拦就是零。Cloudflare 这边配了三层：

# robots.txt（Cloudflare 在 Agent Readiness 公告中给出的示例）
User-agent: *
Content-Signal: ai-train=no, search=yes, ai-input=yes
Sitemap: https://www.example.com/sitemap.xml

• Content-Signal：把"训练 / 推理输入 / 搜索展现"三件事拆开授权。想被 AI 引用但不想被拿去训练，就 ai-train=no, ai-input=yes。Cloudflare Radar 扫了 20 万个高访问域名，只有 4% 的站声明了 AI 使用偏好——这仍是个空位。

• Redirects for AI Training：识别 AI 训练爬虫，把 Wrangler v1、Workers Sites 这类废弃文档的抓取请求重定向走。人来查历史还能看到废弃横幅，LLM 只被喂最新写法，从源头上减少"代理推荐过时 API"。这一条最容易被忽略，但对文档站是刚需。

• HTML 里塞一句反悔提示：每个页面加一条只给模型看的隐藏指令——"STOP！这是 HTML 版，HTML 浪费上下文，请改取 Markdown 版：本页 URL + index.md，或发 Accept: text/markdown"。注意这句话在 Markdown 版本里会被删掉，否则代理会在 Markdown 里继续找 Markdown，形成递归。

结果

一句必须写清楚的限定：Cloudflare 这个 31% / 66% 是自测，不是第三方复现，而且对照的是"其他站点未优化的 llms.txt"，样本是单代理单任务类型。它能说明方向，不能当成 KPI 承诺。

另外，Cloudflare 自己的 isitagentready.com 检查器默认不检查 llms.txt，只查 robots.txt、Markdown 内容协商、API Catalog、MCP Server Card、Web Bot Auth 这些有明确机器契约的项。这个细节本身就是一个信号：llms.txt 至今仍是"作者主张"，不是被校验器承认的硬标准。

复盘

三条可以直接抄的配置项：

1. 根 llms.txt 只放目录，子文件按顶级目录切。判断标准：子文件能不能塞进一个上下文窗口。塞不进，就继续往下切。

2. 每条链接都写"语义名 + 一句描述"，描述从现有 frontmatter 自动派生，不要手写，也不要写成 - 这里 这种无描述裸链。

3. 给每页做 /index.md 兜底 + Accept: text/markdown 协商，覆盖那 4/7 不会主动要 Markdown 的代理。两条规则、零构建成本。

两条踩坑提醒：

1. 别把 5000 页塞进一个 llms.txt。后果不是"读得慢"，而是 grep loop：代理反复搜、上下文碎片化、答案失真。文件大不是容量问题，是准确率问题。

2. 链接必须做可用性校验。公开案例里就有站点在 llms.txt 放了 147 条链接，实测 8 条 404（Neuledge 对 React Aria 的 llms.txt 做的抓取验证，2026-04-16）。代理撞到死链后会退回训练记忆里编内容——这比没有 llms.txt 更糟。

标注

• llms.txt 版本：v1。2024-09-03 由 Jeremy Howard 在 llmstxt.org 提出，属社区提案；未获 W3C / IETF 标准化，也未被任何主流 LLM 厂商公开确认为抓取入口。Cloudflare 的实践证明它能降低 token 成本，但不能证明它提升了 AI 引用率。

• 来源：Cloudflare 官方博客《Introducing the Agent Readiness score. Is your site agent-ready?》（2026-04，中文转载：wpnews.pro）；llms.txt 原文抓取自 developers.cloudflare.com/llms.txt。

• 复盘时间：2026-11-03。

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