跨国深谈← 返回←让 AI 智能体读懂你的开源库：文档优化实战清单

让 AI 智能体读懂你的开源库：文档优化实战清单

关联

人物 Christopher Burns

公司 C15T

概念 lead type · 智能体 · 智能体体验 · llms.txt · agents.md · WebMCP · node modules · Aura AI

Christopher Burns 是开源 cookie 横幅库 C15T(就是网站上那个 cookie 同意横幅)的创始人。他开场先自嘲:没有科学背景、不来自实验室,只是个”滑来滑去、点来点去、东西不好使”的普通开发者——“我只是在这个问题上比你们多折腾了一阵子”。

但折腾出了真结果:C15T 已有 300 万 NPM 下载量、45% 的月环比增长、2800 个网站在生产环境使用,从 Minlify 到 Zed 都在用。

这意味着获客逻辑变了:过去是 Collison 兄弟那种”把笔记本塞到你手里帮你装上 Stripe”的著名推广方式,如今”差不多就是一条提示词”。以前优化的是开发者体验,现在同一套基元正在变成**智能体体验**。

核心思路:没有万能工具,只有一条文档流水线

他的第一个判断是:没有任何单一工具能解决所有问题,“像蝙蝠侠的万能腰带,很多非常小的东西,各自针对不同领域”。他们把这些小工具都构建进 C15T,后来又抽象成一个独立开源框架(演讲中称为 lead type),做成一条”框架中立的文档流水线”:接收你的 .mdx 文件,运行一条生成命令,输出所有针对智能体体验优化的内容。其他开发者公司已在实现并看到类似效果。

下面是具体清单——从几乎人人都知道的,到大多数人还没做的。

第一层:llms.txt 和 llms-full.txt

问题一:文档有几百个页面,智能体怎么导航找到答案? 第一个解法是 llms.txt。

但研究中有个反直觉发现:不要自动生成,要手写。把它写成”你正试图把答案传达给 LLM”的样子——“大约 40 行优质内容,胜过 1000 行噪音”。

问题二:智能体不会”浏览”,只会”抓取”。 所以还需要 llms-full.txt:把它想象成一个站点地图,包含实际页面、链接、以及每个页面用途的简短描述,供 LLM 参考。

第二层:直接给智能体发 Markdown,别发 HTML

事情开始变复杂、也是当前大量优化集中的地方:HTML 很贵(token 意义上),为什么不直接把 Markdown 交给智能体? 可以,而且现在人人都开始做 “.md 后缀”——在正常网址末尾加 .md(比如 Next.js Quickstart 加 .md),加载后就进入 Markdown 版本。

但真正关键的一步大多数人没做:在网站 header 里声明存在 Markdown 替代版本。所有最好的文档网站(Minify、Vercel、C15T)都在 header 里放了这一行,等于告诉每个来访的智能体”这里有 Markdown 版”。

至于谁真的支持这个声明?”Perplexity、一些智能体,这些都还没有定论。”

另外 .md 文件要保证多种获取方式,因为不是所有智能体能力相同:

• 直接加 .md 后缀;
• 在 Next.js config 里加重定向:检测到请求 header 接受 markdown 时,不返回 HTML 而返回 markdown;
• 提供 URL 查询参数 mode=agent,给那些无法附加 header 标签的智能体用。

第三层:让智能体能向你的网站提问(WebMCP)

目前智能体只能抓取你的网页,无法向网站提问。方向是 WebMCP——还很早期,但他的工具已经向 WebMCP 暴露了三个工具:SearchDocs、GetPages、AskDocs,把文档上下文整合起来,智能体可以直接提问。他甚至认为未来会出现通过电子邮件通信的智能体,旧金山已有公司在做。

最重要也最不舒服的真相:智能体根本不访问你的网站

对任何有开发者模块的人(NPM、cargo、Python),“令人不安的真相是,编码智能体实际上从不访问那个网站。它们实际访问的是 node_modules。” 它们读仓库、读 node_modules,带着过时的训练数据,试图从编译后的源码里搞清楚这个库能干什么。

解法是跟着 Vercel 这类思想领袖做:把打包好的 markdown 文档直接放进 node_modules,附带一个 agents.md 文件,内容大意是”有问题的话,所有文档都在这里,去 grep 它们”。

这一招效果出奇地真实:跨多个模型测试,相比去搜索网页、找工具、从代码库拉 markdown 文件,能节省近 50% 的 token。 如果你的库经常变动,node_modules 内置文档是非常有效的方案——智能体拿到的永远是和安装版本一致的文档。

这在不用任何 skills 的情况下就生效,也可以加一条 skill 明确说”先看 node_modules”。agents.md 里还可以写得更具体:“使用 C15T Next.js 库时,阅读打包好的文档,验证它们是否匹配,再继续。“

怎么检验你的网站对智能体是否友好

这个领域刚开始出现测试框架。Cloudflare 推出了一个,他最喜欢的是一个叫 Aura AI 的新工具:输入你的网站,它会给出优化建议。他乐意展示自家 59 分的成绩——“三周前它还要高得多”,因为评分标准一直在变,这本身就是这个领域”永远在变”的写照。

问答环节有网站代理公司问:从零建一个普通网站(不一定是开发者工具),该专注哪个方法?他的答案:第一是为每一个页面提供 .md 文件(很多 CMS 不是这样构建的,他自己甚至为此造了个自用 CMS);优先级是 llms.txt 第一、llms-full.txt 第二;即使你的系统没有 markdown,也推荐手动做这些文件。理由很直接:越来越多的网站访问者是智能体而不是真实人类,从 token 效率角度也该主动提供 markdown。

本集带走

• 手写 llms.txt,别自动生成:约 40 行优质内容胜过 1000 行噪音;配上 llms-full.txt 当”站点地图”(页面+链接+一句话用途)。
• 给每个页面提供 .md 版本,并在 header 里声明存在 Markdown 替代版;同时支持多种获取方式(.md 后缀、按 header 协商返回 markdown、mode=agent 查询参数)。
• 把打包好的文档直接放进 node_modules,附 agents.md:智能体实际读的是 node_modules 而不是你的网站——实测能省近 50% token,库频繁更新时尤其有效。
• 用 Aura AI / Cloudflare 的工具检测网站对智能体的友好度,但分数标准一直在变,持续跟进即可。
• 别追求完美:市场、智能体、LLM 永远在变,“你添加的每一件小事确实都很重要”。

真正有意思的是,我们从 wizards 安装我们的软件,变成了智能体安装它们
So what’s really funny is that we went from wizards installing our software to agents installing them
—— Christopher Burns · [03:34]

手写你的 LLMs.txt 是好得多的。
It is much better to write your LLMs.txt from hand.
—— Christopher Burns · [06:20]

从我们的测试来看,大约 40 行优质内容胜过 1,000 行噪音。
For about 40 good lines beats 1,000 lines of noise from our testing.
—— Christopher Burns · [06:33]

但事情开始变得非常复杂、也是我们现在看到大量优化的地方,是 HTML 很昂贵,为什么我们不能直接把 Markdown 交给智能体?
But where things are starting to get very complicated, and we’re seeing a lot of optimizations right now, is that HTML is expensive, and why can’t we just ship Markdown to the agents?
—— Christopher Burns · [07:07]

我们可以看到,在许多不同的模型之间,与试图搜索网页、找到正确的工具相比,能节省近 50% 的 token,不用从你的代码库中拉取 markdown 文件。
We can see that between many different models, almost 50% token saving on instead of trying to search the web, find the right tools, pulling the markdown files from your code base.
—— Christopher Burns · [11:22]

所以永远不要因为追求完美而卡住。
So never get caught with being perfect.
—— Christopher Burns · [14:00]