代理发现
代理发现层由 nuxt-agent-discovery 提供,layer 已完成配置,无需额外安装。它让 AI 代理以 Markdown 而不是 HTML 阅读文档,并通过标准位置的发现文档找到 MCP Server、llms.txt 与 Agent Skills。
端点
| 端点 | 内容 |
|---|---|
/raw/**.md | 每个页面的 Markdown 表示 |
/sitemap.md | 全站页面的 Markdown 索引 |
/.well-known/api-catalog | RFC 9727 linkset,列出站点发布的服务文档 |
/.well-known/mcp/server-card.json | MCP 服务卡片,MCP 开启时提供 |
/.well-known/skills/index.json | Agent Skills 索引,存在 Skill 时提供 |
/robots.txt | 为已知 AI 代理生成 Allow 分组与 Content-Signal |
首页响应会附带 Link 头,指向上述发现文档,代理访问 / 即可获得完整清单。
Markdown 表示
内容协商
同一个页面 URL 在以下情况返回 Markdown(按顺序判定):
- URL 以
.md结尾,如/docs/getting-started.md Accept请求头中text/markdown的权重不低于text/htmlAccept明确拒绝text/html(text/html;q=0)且通配符允许 Markdown- User-Agent 属于已知的 AI 代理(如
ClaudeBot、GPTBot)
单独的 */* 不算请求 Markdown,浏览器始终拿到 HTML。/_、/api/、/mcp、/.well-known/ 与静态资源不参与协商。响应带 Vary: Accept, User-Agent,CDN 会分别缓存两种表示。
# 显式 .md 地址
curl https://docs.example.com/docs/getting-started.md
# 通过 Accept 协商
curl -H 'Accept: text/markdown' https://docs.example.com/docs/getting-started
# 以代理身份访问
curl -A 'ClaudeBot/1.0' https://docs.example.com/docs/getting-started
部署到 Vercel 时,预渲染页面在边缘完成协商;其他平台与 pnpm dev 由 Nitro 中间件处理,行为一致。
文档格式
返回内容以 frontmatter 开头,随后是正文,站内链接全部转为绝对地址:
---
title: "简介"
description: "..."
canonical_url: "https://docs.example.com/docs/getting-started"
---
正文中的 MDC 组件在输出前由 layer 转换为纯 Markdown(见下文 layer 的补充),代码示例、表格与组件 API 都以普通 Markdown 呈现。指向章节而不是页面的路径会 302 跳转到该章节的第一篇。
首页
/raw/index.md 由 layer 自己生成,而不是输出落地页的组件标记。内容包括站点标题与简介、## Resources for Agents 发现清单(与 Link 头同源)以及站点与 GitHub 链接:
curl https://docs.example.com/raw/index.md
Markdown 站点地图
/sitemap.md 按章节列出每个页面,链接指向对应的 Markdown 表示。layer 默认展开 /docs 下的一级目录,每个目录一个分组。分组标题由目录名推导,可用 labels 覆盖:
export default defineNuxtConfig({
agentDiscovery: {
sitemap: {
markdown: {
expand: ['/docs'],
labels: { 'getting-started': 'Getting Started', 'ai': 'AI' }
}
}
}
})
XML 站点地图仍由 @nuxtjs/sitemap 生成,/raw/** 不会进入其中。
发现文档
API 目录
/.well-known/api-catalog 返回 application/linkset+json,把 MCP 端点、llms.txt、Skills 与文档首页组织为 linkset:
curl https://docs.example.com/.well-known/api-catalog
MCP 服务卡片
MCP 开启时提供 /.well-known/mcp/server-card.json,描述服务器地址、传输方式、是否需要认证,以及从 @nuxtjs/mcp-toolkit 实时读取的工具、资源与提示词清单:
{
"serverInfo": {
"name": "my-docs",
"title": "my-docs MCP Server",
"documentation": "https://docs.example.com/docs/ai/mcp",
"version": "1.0.0",
"repository": "https://github.com/owner/repo"
},
"endpoints": [{ "type": "streamable-http", "url": "https://docs.example.com/mcp" }],
"authentication": { "required": false }
}
端点取自 aiChat.mcpPath(默认 /mcp),文档地址取自 mcp.browserRedirect。serverInfo 中的名称、描述、版本与仓库在请求时补全:
| 字段 | 来源 |
|---|---|
name | site.name,其次为 appConfig.seo.title |
description | appConfig.seo.description |
version | runtimeConfig.public.version |
repository | appConfig.github.url |
robots.txt
@nuxtjs/robots 生成的 robots.txt 中会为每个已知 AI 代理加入 Allow 分组,并添加 Content-Signal: search=yes, ai-train=yes, ai-input=yes。这份代理列表与内容协商共用。
错误页
代理或命令行请求不存在的页面时,404 响应体是 Markdown,附带首页、站点地图等恢复链接;浏览器与 fetch() 仍收到原本的 HTML 或 JSON 错误。
curl https://docs.example.com/docs/not-found
layer 的补充
layer 只实现模块无从得知的部分:
- MDC 转换:
server/plugins/agent-discovery.ts在agent-discovery:document钩子中把 MDC 组件转为纯 Markdown,ComponentProps等组件 API 会展开为带注释的 TypeScript 接口 - 服务卡片元数据:同一插件在
agent-discovery:mcp-server-card钩子中补全serverInfo - 首页:
server/routes/raw/index.md.get.ts接管/raw/index.md - 配置:
nuxt.config.ts的agentDiscovery块设置站点地图分组与 Skills 目录,siteUrl与siteName留空,由你的site.url、site.name决定
需要调整时,直接在项目的 nuxt.config.ts 中覆盖 agentDiscovery,或在 server/plugins/ 中注册同样的钩子。全部选项见 nuxt-agent-discovery 文档。
site.url 决定所有发现文档中的绝对地址。生产构建前请确认它是正式地址,见部署。