智能体引擎优化（AEO）

AI 编程代理如何消费文档，与人类有着根本的不同——如果你仍然只为人类读者优化内容，那你正在让越来越多的受众对你的工具视而不见。文档、命令行界面（CLI）、模型上下文协议（MCP）、技能……AI 代理与之交互的接口生态正在不断扩展。

我一直在关注开发者门户中发生的一些变化，我认为这些变化值得更多关注。

工程师打开 Claude Code，要求它实现某个规范，然后按下回车键。代理会抓取你的一些文档。它可能会获取所需的内容，将其解析为原始文本，剥离 HTML，统计 token 数量，然后要么将其作为上下文使用，要么因为 token 数量超出其上下文窗口而静默丢弃。

你的分析系统记录下的一切毫无用处：滚动深度为零，页面停留时间为 400 毫秒，没有点击链接，没有完成教程，也没有与 UI 交互。你多年来优化的漏斗没有任何数据。

但代理确实在那里。它阅读了你的文档。而根据这些文档的结构方式，它要么成功完成了任务，要么因为内容过于冗长、结构混乱，或者被配置错误的 robots.txt 阻止，从而产生幻觉式的解决方案。

我开始将解决这一问题的学科称为面向代理引擎的优化。

什么是面向代理引擎的优化？

面向代理引擎的优化（AEO） 是指结构化、格式化和提供技术内容的方式，使 AI 编程代理能够真正使用这些内容，而不仅仅是供人类阅读。

我反复回到的一个类比是搜索引擎优化（SEO）。我们花了多年时间学习如何为搜索引擎爬虫和人类的点击模式进行优化。AEO 的理念相同，但服务对象不同：服务于自主获取、解析并推理你内容的 AI 代理。

事实证明，关键因素非常具体：

可发现性：代理能否在不渲染 JavaScript 的情况下找到你的文档？
可解析性：内容是否无需依赖视觉布局解释即可被机器读取？
Token 效率：内容是否能在不截断的情况下适应典型的代理上下文窗口？
能力信号传递：文档是否向代理说明了 API 的功能，而不仅仅是调用方法？
访问控制：你的 robots.txt 是否真的允许 AI 流量通过？

如果其中任何一项失败，代理要么完全跳过你的内容，要么生成细微但有误的输出。难点在于你可能永远不会知道，因为没有触发任何分析事件。

AI 代理实际上是如何阅读文档的

这里有必要说明行为上的差异，因为它比我最初预期的要大得多。

人类模式

人类开发者进入你的文档主页，导航到相关部分，快速浏览标题，阅读几段文字，可能在交互式控制台中运行代码示例，点击两三个内部链接，并在会话中花费 4 到 8 分钟。你的分析系统会捕获所有这些行为。

代理模式

最近的一项研究论文（《AI 编程代理的开发者体验》）研究了九种主流 AI 编程代理（包括 Claude Code、Cursor、Cline、Aider、VS Code 和 Junie）获取开发者文档时的 HTTP 流量。研究结果相当引人注目。

代理通常会将多页导航压缩为一次或两次 HTTP 请求。人类在文档层次结构中点击数分钟，代理则只发出一次 GET 请求，接收完整页面后继续前进。整个“用户旅程”的概念坍缩为一个服务器端事件。

实际后果是：所有客户端分析事件——滚动深度、页面停留时间、按钮点击、教程完成、链接跟随、表单交互——都变得不可见。代理直接绕过所有这些环节。

AI 流量的特征

该研究还识别出可用于在服务器日志中检测 AI 代理流量的独特行为特征：

代理	HTTP 运行时	预取行为	特征
Aider	Headless Chromium (Playwright)	按需 GET	完整的 Mozilla/Safari user-agent
Claude Code	Node.js / Axios	按需 GET	axios/1.8.4
Cline	curl	GET + OpenAPI/Swagger 扫描	curl/8.4.0
Cursor	Node.js / got	HEAD 探测 → GET	got (sindresorhus/got)
Junie	curl	顺序多页 GET	curl/8.4.0
OpenCode	Headless Chromium (Playwright)	按需 GET	完整的 Mozilla/Safari user-agent
VS Code	Electron / Chromium	按需 GET	带 Electron 标记的 Chromium 风格
Windsurf	Go / Colly	按需 GET	colly

除了编程代理外，AI 助手网页服务（如 ChatGPT、Claude、Google Gemini、Perplexity）在用户在聊天界面中共享 URL 时也会生成独特的特征，触发它们自己的服务器端获取。

一旦你知道要找什么，就可以开始在分析中细分 AI 代理流量。令我惊讶的是，我自己的日志中已经包含了大量此类数据。

Token 问题：你的文档可能对代理不可见

这可能是整个图景中最被低估的部分：Token 经济学。

代理没有无限的上下文空间。大多数代理的实际限制在 10 万到 20 万个 token 之间，上下文管理是每个任务中的活跃约束。论文中提到了一个具体例子：思科安全防火墙管理中心 REST API 快速入门指南（版本 10.0）包含 193,217 个 token——接近 718,000 个字符。仅此一份文档就可能消耗或超过大多数代理的全部可用上下文窗口。

当代理遇到过长的文档时，可能会发生以下几种情况——都不理想：

可能静默截断，丢失关键信息
可能完全跳过该文档，选择更短的替代品
可能尝试分块处理，但这会增加延迟和出错概率
可能退回到参数化知识——即编造内容

我认为这意味着 token 数量现在已成为文档的首要指标。如果你没有跟踪文档页面的 token 数量，就会错过代理用来决定是否尝试阅读内容的信号。

实用的 token 目标

以下是一些粗略的指导方针：

快速入门 / 入门页面：

AEO 栈：实际要构建的内容

AEO 不是一个单一的东西，而是一系列分层信号和标准。我一直将其视为从基础到表面的层级结构：

第一层：访问控制（`robots.txt`）

这是代理的第一步。在获取内容之前，许多代理会检查 robots.txt 以确定允许访问的内容。

配置错误的 robots.txt 如果阻止了已知的 AI 爬虫，将静默拒绝代理访问你的文档。没有流量，没有错误，也没有迹象表明出现问题。我曾见过这种情况导致团队对文档对代理不可见毫不知情。

实际操作步骤：

审计你的 robots.txt，确保没有意外阻止 AI 代理 user-agent
考虑明确允许已知的 AI 代理模式（Anthropic、OpenAI、Google、Perplexity 爬虫）
如果需要更精细的控制，请查看 agent-permissions.json——一种新兴规范，允许你声明性地指定允许哪些自动化交互、速率限制、首选 API 端点等

第二层：通过 llms.txt 发现

即使代理可以访问你的内容，它仍然需要找到正确的内容。这就是 llms.txt 发挥作用的地方。

我将 llms.txt 视为 AI 代理的站点地图。它是一个扁平的 Markdown 格式文件，托管在 yourdomain.com/llms.txt，提供你文档的结构化目录，包括描述，以便代理能够判断哪些内容相关，而无需爬取整个网站。

一个格式良好的 llms.txt 如下所示：

# YourProduct 文档 ## 入门 - [快速入门指南](/docs/quickstart)：5 分钟内安装并完成首次 API 调用 - [身份验证](/docs/auth)：OAuth 2.0 和 API 密钥认证模式 - [核心概念](/docs/concepts)：数据模型、实体和术语 ## API 参考 - [REST API 概览](/docs/api)：基础 URL、版本控制、分页、错误代码 - [用户 API](/docs/api/users)：用户管理的 CRUD 操作（12K tokens） - [事件 API](/docs/api/events)：事件流和 webhook 配置（8K tokens） ## MCP 集成 - [MCP 服务器](/docs/mcp)：用于直接代理集成的模型上下文协议服务器

一个好的 llms.txt 应具备：

描述告诉代理会发现什么，而不仅仅是页面名称
在有用时提供每页的 token 数量（使代理能够做出明智的上下文决策）
按任务组织，而非产品层次结构
自身控制在 5,000 tokens 以内（不应仅仅作为索引就耗尽预算）

第三层：通过 skill.md 传递能力信号

llms.txt 告诉代理东西在哪里。skill.md 则告诉代理你的产品实际上能做什么。

我认为这种区别比表面看起来更重要。与代理必须从文本文档中推断能力不同，skill.md 以声明方式呈现这些能力——将意图映射到端点和资源。

一个身份验证服务的 skill.md 可能如下所示：

---
name : auth-service
description : 处理用户身份验证、OAuth 2.0 流程和会话管理
---

## 我能完成的事情
- 通过 OAuth 2.0 对用户进行身份验证（授权码、客户端凭证、PKCE）
- 颁发和验证 JWT 令牌
- 管理用户会话和刷新令牌轮换
- 与 SSO 提供商集成（SAML、OIDC）

## 必需输入
- 客户端 ID 和客户端密钥（来自开发者控制台）
- 重定向 URI（必须预先注册）
- 请求的范围（read:user、write:data、admin）

## 约束条件
- 速率限制：每分钟每个应用 1000 次令牌请求
- 令牌有效期：访问令牌 1 小时，刷新令牌 30 天
- 公共客户端必须使用 PKCE

## 关键文档
- [OAuth 2.0 指南]( /docs/oauth )：完整的流程详解及代码示例
- [令牌参考]( /docs/tokens )：令牌结构、声明、验证
- [Postman 集合]( /docs/postman )：即用型请求模板

这能让代理做出有意义的决策——不只是获取文档，而是在花费上下文预算进行全面阅读之前，理解你的 API 是否能满足用户的意图。

第四层：为代理解析而设计的内容格式

即使具备完美的发现和能力信号传递，实际内容仍需对代理可读。以下几点我发现很重要：

提供 Markdown，而不仅仅是 HTML。许多文档平台允许通过附加 .md 或查询参数访问原始 Markdown。使其可被发现。代理处理 Markdown 的 token 开销远低于 HTML（无标签噪音、无导航框架、无页脚冗余）。

为扫描而设计，而非阅读。代理不按线性阅读——它们解析结构：

使用一致的标题层次结构（H1 → H2 → H3，不跳跃）
每个部分开头说明结果，而非背景
代码示例紧跟其说明的声明之后
参数引用使用表格，而非散文式列表

消除导航噪音。侧边栏、面包屑和页脚链接在你的 HTML 中是噪音，在 Markdown/文本中也是噪音。避免将其包含在可解析内容路径中。

前置有用内容。任何页面的前 500 个 token 应回答：这是什么、它能做什么、我需要什么才能开始。代理对前言缺乏耐心。

第五层：Token 展示

这一点听起来简单，但杠杆效应出人意料：在文档页面展示 token 数量。理想情况下，既在 llms.txt 索引中，也在页面本身（作为元数据或页面标题）中展示。

这为代理提供了做出智能决策所需的信息：

“此页面为 8K tokens——我可以完整包含在上下文中”
“此页面为 150K tokens——我应该只获取相关部分”
“此页面超出我的上下文窗口——我将改用 llms.txt 中的摘要”

实现很简单：在服务器端统计字符数，除以约 4 估算 token 数量，并将其作为 meta 标签或 HTTP 响应头暴露。

第六层：“复制给 AI”

这更像是一个 UX 桥梁而非基础设施层，但我认为值得包含：复制给 AI 按钮。

当开发者在 IDE 中与 AI 助手协作，并希望将文档作为上下文包含时，他们目前从渲染的 HTML 中复制粘贴——包含导航噪音、页脚等所有内容。“复制给 AI”按钮可将干净的 Markdown 复制到剪贴板，虽然是小功能，但显著提高了代理接收到的上下文质量。

Anthropic、Cloudflare 等公司已经推出了此功能的变体。投入低，信号强。

AGENTS.md：新兴默认项

值得一提的是：AGENTS.md。

就像 README.md 成为人类开发者探索仓库的默认入口点一样，AGENTS.md 正成为 AI 代理的入口点。当编程代理打开项目时，它会查找根目录中的 AGENTS.md，并将其指令带入后续的每个任务。

我一直在单独撰写相关文章，但简单来说，一个好的 AGENTS.md 应包含：

项目结构和关键文件位置
指向相关 API 或服务文档的直接链接
可用的开发沙盒和测试环境
代理应了解的速率限制和约束
代码库的首选模式和约定
如果有，MCP 服务器的链接

Cisco DevNet 已将其作为开源项目的 GitHub 模板中的默认文件采用——新创建的项目会自动包含填充了特定项目内容、OpenAPI 文档链接、DevNet 沙盒和测试环境的 AGENTS.md。

监控 AI 引荐流量

你现在可以做的一件事：开始在分析中跟踪 AI 引荐流量。

以下引荐来源值得关注：

labs.perplexity.ai/referral
chatgpt.com/(none)
chatgpt.com/organic
link.edgepilot.com/referral
platform.openai.com/referral
perplexity/(not set)
claude.ai/referral
copilot.microsoft.com/referral
gemini.google.com/referral

你还应监控我之前提到的 HTTP 特征——axios/1.8.4、curl/8.4.0、got (sindresorhus/got)、colly——以捕获没有引荐来源的直接代理流量。

建立适当的 AI 流量细分将为你提供领先指标，判断这些工作是否真的产生了影响。

对开发者体验的更广泛影响

我想后退一步，因为我认为 AEO 指向的不仅仅是技术清单。

在 Web 历史的绝大部分时间里，开发者门户都是围绕人类认知模式设计的：渐进式披露、视觉层次、交互式示例、引导式教程。所有这些都假设人类在每个步骤都在场。

在一个以代理为主的世界里，许多这些假设不再成立：

视觉层次无关紧要——代理读取文本，而非布局
渐进式披露变成障碍——代理想要一次性获得所有信息
交互式示例失去价值——除非有静态/API 等效物
用户旅程坍缩——多章节教程变成单次上下文加载

这并不意味着以人为本的设计不再重要。人类仍然阅读文档。但他们越来越多地在 AI 助手的上下文中阅读——这意味着代理通常是直接消费者，即使人类是最终受益者。

未来的最佳文档可能需要同时服务两个受众：对人类来说可扫描且结构良好，对代理来说机器可读且 token 高效。

AEO 审核清单

如果我今天要评估文档网站的代理就绪度，我会检查以下内容：

发现

llms.txt 存在于根目录，包含所有文档的结构化索引
robots.txt 没有意外阻止已知的 AI 代理 user-agent
agent-permissions.json 定义了自动化客户端的访问规则
AGENTS.md 存在于代码仓库中，并链接到相关文档

内容结构

文档页面可作为干净的 Markdown 提供（而不仅仅是渲染的 HTML）
每页在前 200 词中明确说明结果
标题一致且层次正确
代码示例紧跟其散文描述之后
参数引用使用表格，而非嵌套散文

Token 经济学

每篇文档页面的 token 数量被跟踪
没有单页超过 30,000 tokens 且无分块策略
token 数量在 llms.txt 中为关键页面公开
token 数量作为页面元数据提供（meta 标签或 HTTP 头）

能力信号传递

skill.md 文件描述每个服务/API 的功能，而不仅仅是调用方法
每个技能包括：能力、必需输入、约束、关键文档链接
如有适用，提供 MCP 服务器用于直接代理集成

分析

在网页分析中细分 AI 引荐来源
监控服务器日志中的已知 AI 代理 HTTP 特征
建立 AI 与人工流量的比率基准

UX 桥梁

文档页面提供“复制给 AI”按钮
Markdown 源可通过 URL 约定访问（例如附加 .md）

工具

为了帮助自动化部分检查，我发布了 agentic-seo——一个轻量级审计工具，用于扫描你的网站以发现 AEO 机会。它检查 llms.txt、robots.txt 代理阻止、token 数量、Markdown 可用性等。可将其视为代理就绪度的标识。

从哪里开始

如果你看着这份清单想知道从何入手，我推荐以下顺序：

审计你的 robots.txt——只需十分钟的工作，防止代理静默锁定
添加 llms.txt——几小时的工作，立即提升可发现性
测量并展示 token 数量——周末项目，高杠杆效应
为你的前 3 个 API 编写 skill.md——从代理最可能调用的开始
添加“复制给 AI”按钮——投入低，信号强
设置 AI 流量监控——为你提供数据以证明其他工作的价值

总结

SEO 教会我们优质内容不够——你必须让它以符合时代流量模式的方式被发现。我认为 AEO 是同样的教训，只是服务对象不同。

AI 编程代理已经是文档流量的重要且不断增长的部分。它们的行为与人类读者有根本不同。大多数开发者门户尚未为此做好准备。

在这里率先行动的团队可能会获得真正的优势：他们的 API 将是代理推荐的、成功集成的、反复使用的对象。而那些没有这样做的团队，将看到文档质量与实际代理任务成功率之间的差距越来越大——这是一种难以调试的静默故障模式。

好消息是，为代理构建内容往往也能让文档对人类更好。这些学科的交集多于分歧。

从 llms.txt 开始。发布一个 skill.md。审计你的 robots.txt。测量你的 token。大部分工作只需周末即可完成，回报已经显现。