ard.json

智能体资源发现 (ARD) 是一种用于对智能体资源进行编目的规范。ard.json 清单描述了网域中的智能体资源（例如 MCP 服务器、A2A 智能体和智能体技能），以便 AI 智能体和注册服务能够找到这些资源。

Lighthouse 审核的工作原理

发现流程：审核会根据 ARD 规范 (§5.1) 中的发现机制查找清单：

  • 正在检查 robots.txt 中是否存在 Agentmap: 指令。
  • 正在扫描 HTML，查找 <link rel="ard" href="..."> 标记。
  • 正在检查 HTTP Link: <...>; rel="ard" 标头响应。
  • 正在从已知端点 /.well-known/ard.json 提取。

如果主要发现失败，Lighthouse 会检查旧版路径（例如 rel="ai-catalog" 或 /.well-known/ai-catalog.json）。虽然此处找到的内容仍会经过验证，但系统会发出警告，因为标准 ARD 客户端没有义务支持已弃用的路由。

验证规则：使用 ARD v0.91 一致性套件的 JavaScript 端口执行验证，测试以下条件：

一致性和验证错误：

  • 语法和架构：清单是有效的 JSON，与 ARD 清单架构匹配，并且每个条目都与 ARD 条目架构匹配。Lighthouse 不会提取或验证条目指向的工件（例如，url 处的 MCP 服务器卡片）。
  • 必填字段：清单包含一个 entries 数组，每个条目都包含 identifier、displayName 和 type。
  • 网域锚定 URN：每个 identifier 都遵循 urn:air:<publisher>:<namespace>:<name> 格式。
  • 位置定义：每个条目都只定义 url 或内嵌 data，绝不会同时定义两者或两者都不定义。
  • 信任清单结构：如果包含 trustManifest，则它是一个具有 identity 属性的对象。

最佳实践警告：

  • 代表性查询：每个条目都有一个 representativeQueries 数组，其中包含 2-5 个示例查询。注册表会根据这些信息构建搜索索引，因此不包含这些信息的条目不会显示在搜索结果中。（如果存在，则必须是字符串数组；任何其他内容都是错误。）
  • 媒体类型：type 必须是格式正确的媒体类型。Lighthouse 会针对已弃用的类型（例如，application/mcp-server+json 到 application/mcp-server-card+json）、缺少参数或包含额外参数的标准类型以及 application/* 之外无法识别的类型发出警告。允许使用自定义 application/* 类型。
  • 集合：标记顶级 collections 字段。它不再是 ARD 的一部分，会被忽略；模型层次结构现在位于 entries 中。
  • 旧版端点：标记仅通过旧版 ai-catalog 位置找到的清单。
  • 损坏的广告位置：标记在其他位置找到清单时无法加载的任何广告位置（Agentmap:、rel="ard" 或 rel="ai-catalog" 链接，或 Link 标头）。

不需要：

  • specVersion 和其他额外的顶级字段不会影响得分。
  • capabilities 为选答题，不计分。如果您的资源公开了命名的工具或技能，请考虑列出这些工具或技能（例如 ["WeatherTool", "ForecastTool"]），以便注册表可以根据这些工具或技能进行过滤，而无需提取完整工件。如果包含，则必须是字符串数组。

解读结果表

如果清单整体存在问题，“元素”列会显示 Root。对于条目问题，它会显示条目的 displayName，回退到其 identifier，如果两者都不可用，则显示 Entry #n。一个架构问题可能会出现两次，一次出现在 Root 下，另一次出现在条目下，这与官方一致性测试的输出一致。

了解您的得分

审核结果会通过以下方式反映：

  • 通过 (1)：清单已找到，且没有任何错误或警告。
  • 部分得分 (0.9)：清单有效，但至少有一条最佳实践警告。
  • 失败 (0)：任何一致性错误，例如 JSON 格式错误、违反架构、URN 无效，或者 url/data 均存在或均不存在。如果清单已通告（通过 robots.txt、rel="ard" 或 rel="ai-catalog" 链接或 Link 标头），但无法加载，则审核也会失败。
  • 不适用：未通过任何方法找到清单。这不会影响您的 Lighthouse 得分。

解决方法

如需通过审核，请按照以下可行的步骤操作：

  1. 请通过 /.well-known/ard.json 提供清单，或使用 rel=ard 关联清单。如果您使用的是 ai-catalog.json 或 rel=ai-catalog，请改用新名称。
  2. 修复审核表中列出的所有错误，使清单与 ARD 架构相匹配。
  3. 为每个条目提供一个 urn:air:... 标识符，以及 url 或 data 之一。
  4. 在type中使用标准 ARD 媒体类型（如果适用）。
  5. 为每个条目添加 2 到 5 个representativeQueries，即可获得满分。