企业官网建设流程全解析

• 后端
• 文档

Read the Docs 原生支持在项目域名的顶层路径（/llms.txt与/llms-full.txt）托管自定义的llms.txt文件，为 AI 助手与语言模型提供关于你文档库的结构化元信息。本文将以仓库文档 docs/user/reference/llms-txt.rst 为核心骨架，结合 proxito 服务层的源码实现 与 完整测试用例，讲解该特性的工作原理、启用条件、Sphinx/MkDocs 两种主流工具的接入方式，以及如何用重定向实现对版本服务的精细控制。

什么是 llms.txt，为什么文档项目需要它

llms.txt是一个面向 LLM 友好的内容标准（规范由 llmstxt.org 维护），它允许文档作者提供一个自定义文件，该文件：

• 向 AI 模型提供关于你文档的结构化信息；
• 帮助 AI 理解项目的结构与内容组织；
• 为 AI 消费提供更聚焦、更精炼的文档视图。

与搜索引擎抓取整站 HTML 不同，AI 代理通常希望先读取一个"目录文件"来快速定位最相关的页面，再按需深入。llms.txt正是扮演这个"给 AI 看的目录"的角色：它把文档的站点地图、核心页面链接与说明浓缩为纯文本，让模型在有限的上下文预算内快速建立对项目的整体认知。

Read the Docs 支持从你的文档构建产物中直接托管自定义的llms.txt文件，无需额外配置服务端，只需在文档源码中创建该文件并让构建工具把它放进输出目录即可。

工作原理：文件从默认版本的构建产物中服务

llms.txt文件将从你项目的**默认版本（default version）**中服务，访问地址固定为：

https://your-project.readthedocs.io/llms.txt

之所以固定挂在域名顶层而非版本化路径（如/en/latest/）下，是因为llms.txt按规范必须位于站点的顶级路径，因此 Read the Docs 必须选定一个版本去其中查找该文件——默认版本就是最合理的选择。

如果你同时提供了llms-full.txt（llms.txt 规范中的完整版文件，通常包含更全的页面清单），Read the Docs 会按同样的规则从以下地址服务：

https://your-project.readthedocs.io/llms-full.txt

源码视角：ServeLLMSTXT 视图的完整服务链路

在仓库源码中，这个功能由 readthedocs/proxito/views/serve.py 中的ServeLLMSTXTBase视图实现，其注释明确写道："Serve llms.txt files from the domain's root"。核心流程如下：

1. 路由挂载：在 readthedocs/proxito/urls.py 的core_urls中，llms.txt与llms-full.txt分别绑定到ServeLLMSTXT.as_view()，后者通过{"filename": "llms-full.txt"}参数区分文件名；
2. 确定版本：视图调用project.get_default_version()取得默认版本号，再从project.versions中取出版本对象；
3. 前置校验：只有version.active and version.built（默认版本已激活且已构建）时才继续服务，否则直接抛出Http404；
4. 权限与缓存：通过self.allowed_user(request, version)校验访问权限，self.cache_response = version.is_public决定响应是否可被 CDN 公开缓存（私有版本返回private，见测试test_llms_txt_private_version）；
5. 实际服务：调用ServeDocsMixin._serve_docs(...)（实现于 readthedocs/proxito/views/mixins.py），以check_if_exists=True先检查存储中是否存在该文件，不存在则抛出StorageFileNotFound，最终由视图转为 404。

_serve_docs的内部逻辑会基于version.get_storage_path(media_type=MEDIA_TYPE_HTML)构造存储路径，把文件名拼接到默认版本的 HTML 产物目录下，再从构建媒体存储中读取文件内容返回。也就是说，llms.txt本质上就是默认版本 HTML 构建产物中的一个普通静态文件，只是被提升到了域名根路径来服务。

测试用例确认的行为边界

readthedocs/proxito/tests/test_full.py 中的一组测试完整锁定了该特性的行为：

这组测试同时印证了文档中的"仅当满足以下条件才提供服务"的说明。

启用 llms.txt 的三步流程

使用该特性非常简单，只需三步：

1. 在文档源码中创建llms.txt文件：按 llmstxt.org 规范编写内容，通常包含站点标题、简介与核心页面清单；
2. 配置你的文档工具，让它把该文件包含进构建输出：不同工具机制不同，详见下文"工具集成"；
3. Read the Docs 会自动在域名根路径服务它：触发一次新构建后，即可通过https://your-project.readthedocs.io/llms.txt访问。

服务的前提条件（重要）

llms.txt文件只有在以下条件全部满足时才会被服务：

• 你的默认版本处于**激活（active）**状态；
• 默认版本已完成构建（built）；
• llms.txt文件存在于构建输出目录中。

任何一条不满足，访问/llms.txt都会得到 404——这一点与上面的测试用例完全对应。此外，从源码实现看，若默认版本为私有版本，文件仍可正常服务，但响应不会被 CDN 公开缓存，且未授权用户会收到 401 响应。

工具集成：Sphinx 与 MkDocs 的接入方式

不同文档工具生成llms.txt的方式不同，以下是两个最主流工具的具体做法。

Sphinx

Sphinx 使用html_extra_path配置项将静态文件复制到最终的 HTML 输出目录。做法是：

1. 创建llms.txt文件；
2. 把它放在html_extra_path所指向的目录下（html_extra_path中的每一项可以是文件或目录，Sphinx 构建时会原样拷贝到输出目录）；
3. 触发构建后，llms.txt即出现在 HTML 构建产物根目录，Read the Docs 即可在/llms.txt提供服务。

例如在conf.py中：

# conf.py html_extra_path = ["llms.txt", "llms-full.txt"]

此外，也可以使用sphinx-llm扩展，在构建时从你的文档自动生成llms.txt文件，省去手工维护清单的麻烦。

MkDocs

MkDocs 要求llms.txt位于docs_dir配置值所定义的目录中（该目录是 MkDocs 的源文档目录，默认为docs/）：

1. 在docs_dir目录内创建llms.txt（例如docs/llms.txt）；
2. MkDocs 构建时会将源目录中的文件复制到site_dir（默认site/）输出目录，llms.txt因此进入构建产物根目录；
3. 触发构建后即可通过/llms.txt访问。

如果想自动生成，可以使用mkdocs-llmstxt插件，它能在构建时根据你的导航结构自动生成llms.txt。

两种方式殊途同归：只要最终llms.txt出现在默认版本 HTML 构建产物的根目录，Read the Docs 就会自动在域名顶层路径提供服务。

备选方案：用精确重定向控制版本

默认情况下，llms.txt固定从默认版本服务。如果你希望把它挂在某个特定版本的路径下（例如/en/latest/llms.txt），可以通过创建一条**精确重定向（exact redirect）**实现：

/llms.txt -> /en/latest/llms.txt

这样你可以：

• 更精确地控制由哪个版本提供该文件；
• 在默认版本与目标版本不一致时依然保持根路径可用；
• 结合llms-full.txt使用同样的规则。

重定向的完整配置方法见 用户指南：如何在文档项目中配置自定义 URL 重定向，配置入口在项目仪表盘的Admin > Redirects页面，选择"Exact redirect"类型后填写 From URL 与 To URL 即可。需要注意，重定向规则在保存后立即生效，多个规则匹配同一 URL 时列表顺序在前的规则优先。

与其他 AI 协作特性的关系

llms.txt是 Read the Docs 面向 AI 生态的一组特性之一，与它并列的还有：

• Markdown for AI agents（见 docs/user/reference/markdown-for-agents.rst）：Read the Docs 通过 HTTP 内容协商（Accept: text/markdown）向请求方提供文档页面的 Markdown 版本，该特性在所有托管域名上自动启用，浏览器仍获得 HTML。llms.txt与之互补——前者是"给 AI 的目录"，后者是"给 AI 的正文"；
• Agent Skills（见 docs/user/reference/agent-skills.rst）：Read the Docs 官方提供的 Agent Skills 集合，帮助 AI 代理正确使用 Read the Docs API 与配置。

三者共同构成了一套"让 AI 高效、准确地消费文档"的完整方案，而llms.txt承担的是入口与导航的角色。

验证与排障建议

上线后建议用以下命令验证服务是否正常：

# 查看 HTTP 状态与响应头 curl -i https://your-project.readthedocs.io/llms.txt # 检查 llms-full.txt curl -i https://your-project.readthedocs.io/llms-full.txt

常见排障思路（均可在仓库测试 readthedocs/proxito/tests/test_full.py 中找到对应场景）：

• 返回 404：依次检查默认版本是否激活、是否已构建、llms.txt是否真的进入了构建产物根目录（可在 Read the Docs 构建日志或产物下载中确认）；
• 返回 401：默认版本为私有版本且当前访问未授权，属于预期行为；
• 内容未更新：确认重新触发构建后默认版本产物已刷新，llms.txt属于构建产物的一部分，不会脱离构建单独更新。

• 后端
• 文档