---
title: "代理发现"
description: "文档站默认为 AI 代理提供每页的 Markdown 表示、Markdown 站点地图与一组 /.well-known 发现文档，代理无需解析 HTML 就能找到并读取内容。本页列出全部端点、内容协商规则与 layer 的补充实现。"
canonical_url: "https://docs.mhaibaraai.cn/docs/ai/agent-discovery"
---
# 代理发现

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

代理发现层由 [`nuxt-agent-discovery`](https://github.com/benjamincanac/nuxt-agent-discovery) 提供，layer 已完成配置，无需额外安装。它让 AI 代理以 Markdown 而不是 HTML 阅读文档，并通过标准位置的发现文档找到 [MCP Server](https://docs.mhaibaraai.cn/docs/ai/mcp)、[llms.txt](https://docs.mhaibaraai.cn/docs/ai/llms-txt) 与 [Agent Skills](https://docs.mhaibaraai.cn/docs/ai/skills)。

## 端点

| 端点 | 内容 |
| --- | --- |
| `/raw/**.md` | 每个页面的 Markdown 表示 |
| `/sitemap.md` | 全站页面的 Markdown 索引 |
| `/.well-known/api-catalog` | [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) 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（按顺序判定）：

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 会分别缓存两种表示。

```bash [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 开头，随后是正文，站内链接全部转为绝对地址：

```md
---
title: "简介"
description: "..."
canonical_url: "https://docs.example.com/docs/getting-started"
---
```

正文中的 MDC 组件在输出前由 layer 转换为纯 Markdown（见下文 [layer 的补充](#layer-%E7%9A%84%E8%A1%A5%E5%85%85)），代码示例、表格与组件 API 都以普通 Markdown 呈现。指向章节而不是页面的路径会 302 跳转到该章节的第一篇。

### 首页

`/raw/index.md` 由 layer 自己生成，而不是输出落地页的组件标记。内容包括站点标题与简介、`## Resources for Agents` 发现清单（与 `Link` 头同源）以及站点与 GitHub 链接：

```bash [Terminal]
curl https://docs.example.com/raw/index.md
```

## Markdown 站点地图

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

```ts [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：

```bash [Terminal]
curl https://docs.example.com/.well-known/api-catalog
```

### MCP 服务卡片

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

```json [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` 中的名称、描述、版本与仓库在请求时补全：

| 字段 | 来源 |
| --- | --- |
| `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 错误。

```bash [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 文档](https://github.com/benjamincanac/nuxt-agent-discovery#configuration)。

> [!NOTE]
> 
> site.url
> 
>  决定所有发现文档中的绝对地址。生产构建前请确认它是正式地址，见
> 
> 部署
> 
> 。


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
