Infrastructure — 缓存、错误、重定向

什么是 "Infrastructure"?

Infrastructure 组涵盖了决定智能体能否可靠地与你的源站交互的底层 HTTP 行为。这些都不属于特定协议 — 无论是提供 MCP 端点、OpenAPI 规范,还是仅有静态内容的站点,都适用。

HTTPS 重定向

智能体会跟随链接。如果 http://yourdomain.com 没有重定向到 https://yourdomain.com,落到 HTTP URL 上的智能体要么降级,要么直接失败。现代 AI 客户端通常会完全拒绝纯 HTTP。

修复方法: 从 http://yourdomain.com/* 返回 301 或 308,跳转到 HTTPS 上的同一路径。大多数平台(Cloudflare、Vercel、Heroku、build.io)会自动处理。如果是自托管,添加一个监听 80 端口并发出重定向的 nginx server 块。

Sitemap.xml

智能体通过 /sitemap.xml 发现你的 URL 范围。没有它,智能体能到达的路径就只有首页链接的或 llms.txt 中声明的那些 — 通常只是真实内容的一小部分。

修复方法: 在 /sitemap.xml 提供 XML 站点地图。Next.js、Hugo、Jekyll 和 Wordpress 这类框架会自动生成。手写示例:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url><loc>https://yourdomain.com/</loc></url>
  <url><loc>https://yourdomain.com/docs</loc></url>
</urlset>

缓存头

任何配置良好的服务器都至少在响应中输出 Cache-Control、ETag 或 Last-Modified 其中之一。没有这些,智能体无法判断该重新获取还是使用缓存副本 — 要么每次都重新下载(慢、贵),要么永远使用过期缓存(数据错误)。

修复方法: 大多数 Web 框架对静态文件默认会设置这些头。对动态响应,显式设置 Cache-Control:

// Express — 偶尔变化的内容
res.set('Cache-Control', 'public, max-age=3600');

// 不缓存的响应(同样满足检查):
res.set('Cache-Control', 'no-store');

no-store 也算有效的缓存头 — 它告诉智能体"不要缓存这个",这本身就是有用的信息。检查失败的情况是 *根本没有* 任何缓存头。

结构化错误 (JSON 404)

当智能体访问错误的 URL 时,带有导航、页脚、搜索框等的 HTML 404 页面会浪费 token,甚至会让困惑的智能体误以为收到了真正的内容。JSON 404 返回一个小巧、可解析的错误:

{ "error": "not_found", "path": "/wrong-url" }

修复方法: 在 404 处理器中使用内容协商。当客户端发送 Accept: application/json 时返回 JSON,否则返回 HTML。Express 示例:

app.use((req, res) => {
  res.status(404);
  res.format({
    'application/json': () => res.json({ error: 'not_found', path: req.path }),
    'text/html': () => res.send('<h1>404 Not Found</h1>'),
    default: () => res.json({ error: 'not_found', path: req.path }),
  });
});

这一改动对人类不可见(浏览器发送 Accept: text/html 收到 HTML),但对智能体却是革命性的(它们发送 Accept: application/json 就能拿到可解析的 JSON)。

速率限制头 (可选)

如果你的服务做了速率限制,通过 X-RateLimit-Remaining、X-RateLimit-Reset 或 Retry-After 暴露状态。达到限制的智能体可以等待正确的时间再重试,而不是直接失败。

这一项是可选的,因为大多数站点根本不做速率限制 — 只有 API 提供商和 SaaS 应用才会做。静态站点没有什么可暴露的。

为什么这些是必需的

今天许多站点的缓存头、结构化错误、站点地图和 HTTPS 重定向都在"无声地"失败 — 而这正是问题所在。每一项都代表了人类察觉不到、却让智能体真正受阻的摩擦点。把它们从可选提升为必需,体现的立场是:一个"agent-ready"的站点必须解决这些问题,而不只是处理协议相关的检查(MCP、OpenAPI、x402 等)。

agentgrade