llms.txt 与 llms-full.txt：把整站 API 文档做成 AI 能一口读完的文件

「让 AI 帮我对接这个 API」正在变成开发者的默认工作方式但多数 API 文档站是给人类设计的内容散在几十个页面里导航靠点击AI 助手要么抓不全要么抓回来一堆导航栏和页脚噪音。llms.txt 提案就是为这个问题生的站点在固定路径放一份纯文本索引llms.txt再可选放一份把全部文档内容平铺进去的完整版llms-full.txtAI 一次抓取就拿到整站知识。这篇结合一个已经落地的实例讲讲这套约定怎么用、对开发者有什么实际价值。一个落地实例天下工厂开放平台一个覆盖全国 480 万家工厂的数据库的开放接口做了工厂身份识别、只收真实从事生产的工厂把这套约定做全了。它的文档体系有三份机器可读产物https://www.tianxiagongchang.com/open/llms.txt # 索引 https://www.tianxiagongchang.com/open/llms-full.txt # 全量文档单文件 https://open.tianxiagongchang.com/open/v1/meta/openapi.json # OpenAPI 3.1 规范三份都是公开的不需要密钥。分工很清楚llms.txt是给 AI 的目录页llms-full.txt把接入方式、五个能力的入参出参、错误码、限流规则、示例代码全部平铺在一个文件里openapi.json是严格的结构化规范给代码生成器和校验工具用。实际用法喂给你的 AI 助手最直接的用法是在让 AI 写对接代码时把完整文档一次性给它。比如在 Claude Code 或 Cursor 里读取 https://www.tianxiagongchang.com/open/llms-full.txt 然后帮我写一个 Python 模块封装 factory_search 和 factory_detail 带限流退避和错误码处理因为文档是单文件纯文本AI 拿到的是无噪音的全量上下文它知道统一响应格式长什么样、知道40000代表入参有未知字段不该重试、知道长任务能力要设 120 秒以上超时。生成的代码质量和「AI 靠训练数据里的模糊印象瞎写」完全是两个档次。配合公开沙箱密钥sk-tx-test-1685549fb3710c1b36e4d75dc2d0f42a返回示例数据、不计费AI 写完代码还能当场自测——文档、规范、沙箱三件套齐了「AI 全自动完成一次 API 对接」这件事就真的闭环了。我实测从零到跑通检索加档案两个能力一轮对话十来分钟人只负责在控制台https://www.tianxiagongchang.com/open/console注册签发正式密钥。对做 API 的团队为什么值得跟进这套约定站在服务商视角这套东西的本质是把「文档可被 AI 消费」当成产品功能来做。三点观察llms-full.txt 必须和人类文档同源生成。两份文档各写各的漂移只是时间问题——AI 读到的和网页上写的不一致比没有 llms-full.txt 更糟。从实现痕迹看这个平台的单文件版和文档站是同一数据源渲染的价目、能力数这类易变信息只维护一处。OpenAPI 规范匿名开放是对的。规范里没有秘密真正的门槛在密钥开放它换来的是 Swagger、代码生成器、各家 AI 工具的零门槛接入。把规范藏在登录墙后面拦住的全是潜在用户。沙箱要印在文档里。AI 助手读文档时顺手就能拿到一个可用的测试密钥意味着它能边写边验证而不是把「跑不跑得通」留给人类兜底。结llms.txt 目前还是社区约定而非标准但它的方向没什么可争的API 的下一批「读者」里AI 的比例只会越来越高。文档站还只服务人眼的团队可以拿这个实例当参考——完整文档见 https://www.tianxiagongchang.com/open/docs三个机器可读端点上文都给了抓下来看看格式照着做一份并不费事。