如果你的产品提供 MCP server、A2A agent、OpenAPI 工具或 agent skill，AI 客户端在真正使用之前仍然要先回答两个问题：这个能力在哪里？它到底是什么？
ai-catalog.json
正是为这个发现问题而出现的方案。它是一份机器可读的能力目录，发布者通常把它放在自己域名下的
/.well-known/ai-catalog.json。文件列出产品提供的 AI 资源，并指向这些资源各自的原生描述文件。注册表可以抓取、索引这些目录，再把合适的能力返回给 agent。
但要先说清楚：这不是 Google 排名的新文件。AI Catalog 和后来的 Agentic Resource Discovery（ARD）解决的是 agent 如何发现、解析和验证能力，而不是承诺发布文件后就能提升 Google 排名、AI Overviews 展现或品牌引用。这个边界决定了正确的实施方式，也决定了后续应该如何衡量结果。
先说结论：它是 AI 能力的目录入口
AI Catalog 规范定义了一种带类型、可嵌套的 JSON 容器。每个条目通过 type
标识资源类型，并通过 url 指向原生元数据，或者直接用 data
内嵌元数据。目录可以描述不同协议，但不会取代这些协议本身。
AI Catalog 文档给出的最小结构大致如下：
{
"specVersion": "1.0",
"host": {
"displayName": "Example Tools"
},
"entries": [
{
"identifier": "urn:air:example.com:mcp:analytics",
"displayName": "Analytics assistant",
"type": "application/mcp-server-card+json",
"url": "https://example.com/mcp/server-card.json",
"description": "Reads approved analytics data for reporting tasks.",
"tags": ["analytics", "reporting"]
}
]
}这份文件的作用很具体：给兼容的客户端一个标准入口，让它知道发布者有哪些能力。AI Catalog 规范覆盖核心 schema、发现位置、不同一致性等级和可选的信任清单；它并不定义 MCP server 或 A2A agent 如何运行。调用、认证和行为仍然由各自的协议描述文件决定。
为什么需要它：先安装再使用无法无限扩展
现在很多 agent 集成仍然是“先安装，后使用”。开发者把 server URL 复制到配置文件，连接一个插件，或者把 agent card 硬编码进系统。只有几个可信工具时，这种方式没有问题；当团队拥有几百种能力，或者用户临时需要一个没有预装的能力时，维护成本就会迅速上升。
ARD 背后的实用观察是：发现和执行是两件不同的工作。目录帮助 agent 找到候选能力；原生资源描述文件告诉它如何连接；运行时协议才负责真正执行。把三层分开后，同一份目录可以同时列出 MCP server、A2A agent、OpenAPI 工具、skills 和子目录，而不需要把它们硬塞进同一种执行格式。
所以，AI catalog 也不等于商品 feed。商品 feed 为购物或库存决策描述商品；AI catalog 描述机器可以使用的能力，以及解析这些能力所需的元数据。一个 SaaS 产品可以同时发布两种数据，但它们解决的是两类不同的发现问题。
AI Catalog、ARD 和原生 card：三层关系
| 层级 | 它回答什么问题 | 常见资源 |
|---|---|---|
| 原生协议元数据 | 这个能力如何工作？ | MCP Server Card、A2A Agent Card、OpenAPI 文档或 skill 元数据 |
| AI Catalog | 这个发布者提供哪些能力？ | /.well-known/ai-catalog.json |
| ARD 注册表 | 哪个目录条目匹配当前请求？ | 类似 POST /search 的注册表搜索接口 |
Google 对 ARD 的介绍把 catalog 描述为发布者自己托管的能力清单，把 registry 描述为抓取和索引这些清单的搜索系统，同时增加让客户端在连接前验证发布者的信任层。Hugging Face 的参考实现也体现了这种分工：Discover 服务把搜索结果转换成 catalog 条目，但返回的资源仍然使用原生的 skill 或 MCP 表达方式。
这套架构也划定了证据边界。catalog 可以说明某个 endpoint 存在并标明类型，但它本身不能证明 endpoint 安全、可用、准确，或适合执行敏感任务。这些结论需要 endpoint 检查、认证策略、来源信息，以及在适用时使用签名的信任元数据。
一个目录条目应该写什么？
先写清楚让条目可识别的字段：
- 由发布者命名空间控制的稳定
identifier； - 人类可读的
displayName和简洁description； - 与原生协议一致的
type； url或内嵌的data，二者不要同时出现；- 描述真实能力的 tags 或 capability labels；
- 原生协议要求的 canonical endpoint 和文档地址。
AI Catalog
schema 要求核心身份和类型字段，示例使用类似 URN 的标识符。application/mcp-server-card+json、application/a2a-agent-card+json
和 application/ai-catalog+json
这样的类型字符串很重要，因为客户端需要据此判断接下来要抓取或解析什么。不要把营销分类写进
type，再期待客户端自己猜出协议。
描述应该写“能做什么”，而不是写口号。“帮助团队更聪明地工作”几乎不能帮助注册表完成匹配；“读取获得授权的 GA4 数据，并生成每周获客摘要”则说明了能力、数据边界和可能的用户意图。描述必须和真实权限及 endpoint 行为一致，因为过时元数据不是普通文案问题，而是发现链路中的故障。
安全发布流程
1. 盘点真实能力
列出目前可用的 endpoint、agent、skill 和文档，记录负责人、认证方式、支持的操作、数据敏感度、生命周期状态和原生元数据地址。不能访问或无人维护的实验项目不要放进公开目录。
这里的条件很重要：目录只有在条目描述真实可用资源时才有价值。一份包含已下线 endpoint 的静态清单，会让 agent 选中运行时必然失败的能力；一份过于宽泛的清单，则可能把原本只供内部使用的工具暴露给不该看到它的消费者。
2. 从唯一事实源生成 manifest
把能力元数据放在拥有 endpoint 的注册表或部署配置中，在发布阶段生成
ai-catalog.json，按照当前 schema 校验后与服务一起发布。不要让内容编辑者在每次 API 变更后再手工维护一份第二清单。
这和 sitemap 的原则一样：catalog 是有用的索引，不是业务数据库。endpoint 的原生 card 或 API 描述仍然是调用细节的权威来源；catalog 应该链接到它，并提供足够的上下文帮助完成发现。
3. 在稳定的 well-known 地址提供
把文件发布在：
https://example.com/.well-known/ai-catalog.json如果目录面向公开发现，应该让不带认证的请求能够成功获取它，返回正确的 JSON content type，使用 HTTPS，避免意外跳转到登录页，并确保 canonical host 可访问。如果目录本来就是私有的，就应该记录带认证的分发方式，不要假装公开注册表能够抓取它。
4. 单独验证信任和权限
发现不等于授权。客户端连接前要验证发布者身份、endpoint 来源、凭证、scope、速率限制、数据处理方式和版本。对于生产环境或高影响流程，应使用所选 ARD/AI Catalog 实现支持的信任与来源机制；涉及删除、付款或敏感数据时，仍应保留人工确认。
ARD 的介绍把加密验证放在“发现”和“运行时连接”之间。这是一个很实用的实现检查点：如果系统在验证发布者身份和访问范围之前就调用刚发现的 endpoint，那么 catalog 已经变成了不可信的命令入口。
5. 像维护 API 合约一样维护新鲜度
在 CI 中检查 well-known 地址、schema 合法性、链接的资源是否可访问，以及声明的协议类型是否仍然有效。条目出现 404、原生元数据发生不兼容变更，或能力下线但目录未更新时，都应触发提醒。必要时保留变更记录或版本字段，让消费者能区分元数据刷新和 endpoint 的破坏性变更。
ai-catalog.json 做不到什么
它不取代 SEO
Google 对 AI 搜索的官方说明仍然把普通技术 SEO、可抓取性、可索引性和有用内容放在基础位置。它没有说
ai-catalog.json 是 AI
Overviews 必需的文件，也没有说它是排名信号。用 catalog 暴露 agent 能力；用 HTML、结构化数据、sitemap 和清晰内容让公开产品在搜索中可理解。
它不取代 Schema.org Product
Product 结构化数据描述真实商品、报价、库存和其他商业事实，服务于搜索及其他消费者。AI catalog 描述能力 endpoint。一个产品有面向 agent 的 API 时，可能需要两层数据，但不能把其中一层伪装成另一层。
它不会让普通网站自动变得可调用
指向营销页面的 catalog 条目，不会自动变成 agent 工具。目标地址必须提供有文档的可访问接口，并定义认证、输入、输出、错误和限制。对于没有任何 agent 能力的宣传型网站，发布空目录或虚构目录几乎没有价值。
它不保证被发现或被使用
注册表可能还没有抓取你的目录；客户端可能只支持部分资源类型；匹配到的能力也可能输给更可信、更相关或维护更好的条目。应分别衡量目录可用性、注册表索引、成功解析和任务完成率，不能把“文件已经发布”直接算成采用率。
产品团队发布前检查清单
发布前逐项确认：
- 每个条目是否都指向真实且仍被支持的能力？
- identifier 是否稳定、唯一，并且属于发布者控制的域名命名空间？
type是否和原生协议元数据格式一致？- 公开目录是否能通过 HTTPS 被未认证客户端获取？
- 权限、数据边界和破坏性操作是否在其他文档中写清楚？
- catalog 是否自动生成、经过 schema 校验，并在部署中测试？
- 是否在调用前执行信任验证和授权检查？
- 监控和下线流程能否让 manifest 保持最新？
如果有多个答案是否定的，现在还不适合急着加文件。先把能力合约修好，再发布一份客户端能够安全理解的最小目录。
Resources / 参考资料
- AI Catalog specification：核心 schema、发现、conformance 和 trust manifest 概览。
- AI Catalog 文档与示例：工作组代码库和实现指南。
- Google Developers Blog：Announcing the Agentic Resource Discovery specification：catalog、registry、验证和运行时发现。
- Hugging Face：Agentic Resource Discovery：静态 catalog 与注册表搜索的参考实现细节。
- Google Search Central：AI Features and Your Website：为什么普通 SEO 仍是 Google AI 搜索功能的基础。
对于正在决定是否开放第一项 agent 能力的 SaaS 团队，更实际的顺序是：先发布一个准确条目，链接到原生协议文档，在执行前验证信任，并随着 endpoint 变化同步更新 manifest。技术 SEO 服务可以单独检查搜索入口，Evidence Loop 方法则可以帮助团队测试 agent 任务及其失败条件。这样，目录可用性、agent 完成率和搜索可见性会成为三个可以分别衡量的结果，而不是被混成一个承诺。