代理发现

文档站默认为 AI 代理提供每页的 Markdown 表示、Markdown 站点地图与一组 /.well-known 发现文档,代理无需解析 HTML 就能找到并读取内容。本页列出全部端点、内容协商规则与 layer 的补充实现。
查看源码

代理发现层由 nuxt-agent-discovery 提供,layer 已完成配置,无需额外安装。它让 AI 代理以 Markdown 而不是 HTML 阅读文档,并通过标准位置的发现文档找到 MCP Server、llms.txt 与 Agent Skills。

端点

端点内容
/raw/**.md每个页面的 Markdown 表示
/sitemap.md全站页面的 Markdown 索引
/.well-known/api-catalogRFC 9727 linkset,列出站点发布的服务文档
/.well-known/mcp/server-card.jsonMCP 服务卡片,MCP 开启时提供
/.well-known/skills/index.jsonAgent Skills 索引,存在 Skill 时提供
/robots.txt为已知 AI 代理生成 Allow 分组与 Content-Signal

首页响应会附带 Link 头,指向上述发现文档,代理访问 / 即可获得完整清单。

Markdown 表示

内容协商

同一个页面 URL 在以下情况返回 Markdown(按顺序判定):

  1. URL 以 .md 结尾,如 /docs/getting-started.md
  2. Accept 请求头中 text/markdown 的权重不低于 text/html
  3. Accept 明确拒绝 text/html(text/html;q=0)且通配符允许 Markdown
  4. User-Agent 属于已知的 AI 代理(如 ClaudeBot、GPTBot)

单独的 */* 不算请求 Markdown,浏览器始终拿到 HTML。/_、/api/、/mcp、/.well-known/ 与静态资源不参与协商。响应带 Vary: Accept, User-Agent,CDN 会分别缓存两种表示。

Terminal
# 显式 .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 链接:

Terminal
curl https://docs.example.com/raw/index.md

Markdown 站点地图

/sitemap.md 按章节列出每个页面,链接指向对应的 Markdown 表示。layer 默认展开 /docs 下的一级目录,每个目录一个分组。分组标题由目录名推导,可用 labels 覆盖:

nuxt.config.ts
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:

Terminal
curl https://docs.example.com/.well-known/api-catalog

MCP 服务卡片

MCP 开启时提供 /.well-known/mcp/server-card.json,描述服务器地址、传输方式、是否需要认证,以及从 @nuxtjs/mcp-toolkit 实时读取的工具、资源与提示词清单:

server-card.json
{
  "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 中的名称、描述、版本与仓库在请求时补全:

字段来源
namesite.name,其次为 appConfig.seo.title
descriptionappConfig.seo.description
versionruntimeConfig.public.version
repositoryappConfig.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 错误。

Terminal
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 决定所有发现文档中的绝对地址。生产构建前请确认它是正式地址,见部署。
Copyright © 2024 - 2026