AI 智能体已成文档最大读者：HTML 是 31 倍的 Token 税

当一家公司的文档站点每月被 AI 爬虫抓取数万页、却只换回寥寥几个真人访客，文档的读者就不再只是人了。Jamdesk（隶属 Freestyle）近日发文指出，自 2024 年 5 月至 2025 年 5 月，AI 与搜索引擎爬虫流量整体增长 18%，其中 OpenAI 的 GPTBot 涨幅达 305%；Cloudflare 2025 年 7 月的统计更显示，Anthropic 的爬虫每带来 1 个真人访客，就抓取了约 38,000 个页面，OpenAI 的比例约为 1,100 比 1。机器正在以人类无法企及的规模「阅读」文档。

文档设计的人本主义已经失灵

过去二十年，文档团队的共识可以浓缩成一句话：「别让我思考」。快速入门、视频引导、侧边栏层层折叠，都是为了照顾人类稀缺而短暂的注意力。但对 AI 智能体而言，最稀缺的资源是上下文 token，而非注意力。智能体没有「点击侧边栏」或「输入搜索词」的概念，它们会冷启动直接抓取一个 URL，命中答案或重新抓取，没有中间态。把复杂度藏在「渐进式披露」里，对人类是友好，对智能体却是误导。

文章作者援引 Freestyle 同事 Ben Swerdlow 关于 API 设计的观点：智能体可以在一次会话里读完整个文档，训练数据里还残存着旧的鉴权流程和弃用的参数名，活文档是纠正这些「陈旧先验」的唯一机制。如果当下的事实没有被写下来且可被获取，智能体就会用旧版本。

上下文也会腐烂：别把所有内容塞进一页

不过，「让智能体读完一切」同样有代价。Chroma Research 在 2025 年 7 月测试了 18 个前沿模型，发现所有模型在输入长度增长时都会出现性能退化，并将这种现象命名为「context rot（上下文腐烂）」。换言之，提供海量内容并不等于提供高质量内容，文档结构依然重要。

HTML 是 31 倍的 Token 税

更直接的浪费发生在文件体积上。Jamdesk 团队对自己的 quickstart 页面做了对比实测：HTML 版本 225,527 字节，同内容的 Markdown 版本仅 7,246 字节，体积相差 31 倍。Vercel 2026 年的同源测试结果为 500 KB HTML 对 3 KB Markdown。多出来的字节全部是脚本、样式、导航与 hydration 负载——让网页在浏览器里漂亮，但对智能体来说是下载后即丢弃的 token。

更极端的案例来自七家文档平台的横向评测：某平台一个页面 HTML 高达 1,049,919 字节，真正可读文字只有 1,279 字节，因为内容只在 JavaScript 运行后才出现。对纯 HTTP 抓取者而言，这种文档就是一个无限旋转的加载圈。

把 Markdown 当成智能体的「正门」

文章给出的实践方向有三条：

• 为每个页面提供 Markdown 镜像：在 URL 末尾追加 .md，返回纯文本。Stripe 与 Jamdesk 均已在全站自动启用。
• 建立结构化入口：通过 llms.txt、每页 .md 端点，甚至 MCP（Model Context Protocol）服务器，让智能体有更多路径命中同一份内容。
• 把错误信息当作一等公民：智能体依赖显式信息，模糊的默认值和隐式知识会让它们猜错，这一点与 API 设计的「defaults are bad」原则一脉相承。

文章最后提醒：上述 HTML 与 Markdown 体积对比均可在公开 URL 上复测（测量日期 2026-07-16）。对正在被 AI 爬虫高频抓取的文档站点而言，是否要为智能体开一扇不走 31 倍弯路的小门，已经不再是选择题。