后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载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.txtllms.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 domains root。核心流程如下路由挂载在 readthedocs/proxito/urls.py 的core_urls中llms.txt与llms-full.txt分别绑定到ServeLLMSTXT.as_view()后者通过{filename: llms-full.txt}参数区分文件名确定版本视图调用project.get_default_version()取得默认版本号再从project.versions中取出版本对象前置校验只有version.active and version.built默认版本已激活且已构建时才继续服务否则直接抛出Http404权限与缓存通过self.allowed_user(request, version)校验访问权限self.cache_response version.is_public决定响应是否可被 CDN 公开缓存私有版本返回private见测试test_llms_txt_private_version实际服务调用ServeDocsMixin._serve_docs(...)实现于 readthedocs/proxito/views/mixins.py以check_if_existsTrue先检查存储中是否存在该文件不存在则抛出StorageFileNotFound最终由视图转为 404。_serve_docs的内部逻辑会基于version.get_storage_path(media_typeMEDIA_TYPE_HTML)构造存储路径把文件名拼接到默认版本的 HTML 产物目录下再从构建媒体存储中读取文件内容返回。也就是说llms.txt本质上就是默认版本 HTML 构建产物中的一个普通静态文件只是被提升到了域名根路径来服务。测试用例确认的行为边界readthedocs/proxito/tests/test_full.py 中的一组测试完整锁定了该特性的行为测试场景预期结果test_custom_llms_txt默认版本激活且已构建提供llms.txt200x-accel-redirect指向/proxito/media/html/project/latest/llms.txtCDN-Cache-Control: publictest_custom_llms_full_txt同上请求llms-full.txt200重定向到/proxito/media/html/project/latest/llms-full.txttest_llms_txt_not_found存储中不存在该文件404test_llms_txt_private_version默认版本为私有版本200 但CDN-Cache-Control: private不进入公开缓存test_llms_txt_private_version_unauthorized_user私有版本且用户无权限401test_llms_txt_inactive_version默认版本未激活404test_llms_txt_unbuilt_version默认版本未构建404这组测试同时印证了文档中的仅当满足以下条件才提供服务的说明。启用 llms.txt 的三步流程使用该特性非常简单只需三步在文档源码中创建llms.txt文件按 llmstxt.org 规范编写内容通常包含站点标题、简介与核心页面清单配置你的文档工具让它把该文件包含进构建输出不同工具机制不同详见下文工具集成Read the Docs 会自动在域名根路径服务它触发一次新构建后即可通过https://your-project.readthedocs.io/llms.txt访问。服务的前提条件重要llms.txt文件只有在以下条件全部满足时才会被服务你的默认版本处于**激活active**状态默认版本已完成构建builtllms.txt文件存在于构建输出目录中。任何一条不满足访问/llms.txt都会得到 404——这一点与上面的测试用例完全对应。此外从源码实现看若默认版本为私有版本文件仍可正常服务但响应不会被 CDN 公开缓存且未授权用户会收到 401 响应。工具集成Sphinx 与 MkDocs 的接入方式不同文档工具生成llms.txt的方式不同以下是两个最主流工具的具体做法。SphinxSphinx 使用html_extra_path配置项将静态文件复制到最终的 HTML 输出目录。做法是创建llms.txt文件把它放在html_extra_path所指向的目录下html_extra_path中的每一项可以是文件或目录Sphinx 构建时会原样拷贝到输出目录触发构建后llms.txt即出现在 HTML 构建产物根目录Read the Docs 即可在/llms.txt提供服务。例如在conf.py中# conf.py html_extra_path [llms.txt, llms-full.txt]此外也可以使用sphinx-llm扩展在构建时从你的文档自动生成llms.txt文件省去手工维护清单的麻烦。MkDocsMkDocs 要求llms.txt位于docs_dir配置值所定义的目录中该目录是 MkDocs 的源文档目录默认为docs/在docs_dir目录内创建llms.txt例如docs/llms.txtMkDocs 构建时会将源目录中的文件复制到site_dir默认site/输出目录llms.txt因此进入构建产物根目录触发构建后即可通过/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.rstRead the Docs 通过 HTTP 内容协商Accept: text/markdown向请求方提供文档页面的 Markdown 版本该特性在所有托管域名上自动启用浏览器仍获得 HTML。llms.txt与之互补——前者是给 AI 的目录后者是给 AI 的正文Agent Skills见 docs/user/reference/agent-skills.rstRead 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属于构建产物的一部分不会脱离构建单独更新。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐OpenMetadata Stitch 管道连接器配置指南Host、Token 与元数据提取实战OpenMetadata Stitch 管道连接器配置指南Host、Token 与元数据提取实战 本文围绕 OpenMetadata 中 Stitch 管道后端文档Kingfisher规则库管理950内置规则的分类与使用Kingfisher规则库管理950内置规则的分类与使用 Kingfisher是一款功能强大的密钥检测工具提供950内置规则帮助用户发现并管理代码中的敏一条链接、零服务器存储FilePizza 让浏览器直接 P2P 传大文件一条链接、零服务器存储FilePizza 让浏览器直接 P2P 传大文件 FilePizza 是一个浏览器 P2P 文件传输工具。发送方和接收方各自打开网页上一篇如何让小爱音箱变身智能音乐中心3步配置指南下一篇解密Windows虚拟显示器如何用开源驱动扩展你的数字工作空间创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
