补齐接口发现信息，让代理找到网站能力

有 REST API、有 MCP server，也给页面准备了 Markdown，AI agent 就能顺利使用你的产品吗？Fuxux 团队原本这么想，结果在 Cloudflare 的 agent-readiness 扫描中只拿到 33/100，属于 Level 1。他们花了一天补齐发现入口和元数据，升到了 87/100、Level 5。

这次改造最有参考价值的，是它暴露了一个常见缺口：功能已经存在，机器却找不到入口、说明和登录方式。但分数也有边界，作者最后主动留下两项不通过，因为它们涉及真实的产品取舍。

API 已经能用，为什么 agent 还是找不到

Fuxux 是社交媒体排程产品。扫描前，它已有有效的 robots.txt、sitemap 和 Markdown 页面，满足内容读取的基本条件，缺的是机器可读的服务指引。

网页导航适合人浏览，agent 如果只请求首页，很难从大量 HTML 链接里判断哪个是 API 文档、哪个是 MCP 入口。作者先用 RFC 8288 的 Link 响应头，把这些资源直接列出来：

Link: </.well-known/api-catalog>; rel="api-catalog",
      </openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json",
      </docs>; rel="service-doc"; type="text/html",
      </.well-known/mcp/server-card.json>; rel="describedby"; type="application/json",
      </llms.txt>; rel="describedby"; type="text/plain"

注意每一项的 rel：它让客户端知道目标资源的用途。团队使用 Next.js，在 next.config.ts 的 headers() 中增加一项配置，覆盖 / 和各语言首页。

接着是 RFC 9727 定义的 /.well-known/api-catalog。它用 JSON 的 linkset 列出 REST API 和 MCP server，再用 anchor、service-desc、service-doc 关联服务、描述文件和文档，响应类型为 application/linkset+json。

首页响应头负责指路，目录负责把服务组织起来。两者解决的是不同层次的发现问题。

已有文件也可能不合格。扫描器找到了他们的 /.well-known/mcp.json，却因为缺少 serverInfo.name 或顶层 name 判定失败。作者补上 name: "com.fuxux/mcp"、version: "1.3.0" 和 serverInfo，保留旧字段，并在 /.well-known/mcp/server-card.json 提供同一份描述。

其中，transport.type 为 streamable-http，端点是 https://www.fuxux.com/api/mcp；认证声明包括 required: true、oauth2、bearer，以及指向 OAuth 资源元数据的 protected_resource_metadata。发现服务之后，客户端还需要知道连接方式和认证要求。

找到入口之后，还得知道怎么用

OpenAPI 描述接口，Agent Skills 则用 SKILL.md 教 agent 如何使用产品。团队已有面向 ChatGPT plugin 和 ClawHub 的两份技能文件，这次主要补发现索引。

示例索引采用 schema 0.2.0，技能名为 social-media-posts，类型是 skill-md，文件位于 /.well-known/agent-skills/social-media-posts/SKILL.md。索引还携带 sha256 摘要，方便客户端识别文件变化。

他们实际踩过一个小坑：先计算摘要，构建又改变了换行符，最终下载到的文件便无法通过校验。

摘要必须根据最终对外提供的精确字节计算。

另一个入口是 ARD（Agentic Resource Discovery）的 /.well-known/ai-catalog.json。它集中列出域名下可用的 MCP server、OpenAPI 描述和 agent，还能通过 representativeQueries 写明资源适合处理的请求，例如明早 9 点向 Instagram 和 LinkedIn 排程、本周有哪些待发布内容、TikTok 发布为何失败。

这些示例补充的是使用意图，不能替代接口定义。

团队还尝试了 WebMCP，让浏览器中的 agent 调用页面注册的工具。考虑到它仍处于草案阶段、支持的浏览器较少，他们只开放产品概览和价格两个只读工具，内容复用已有 Markdown：

const ctx = document.modelContext ?? navigator.modelContext;
if (!ctx || typeof ctx.registerTool !== "function") return; // most browsers today
for (const tool of TOOLS) {
  try {
    ctx.registerTool(tool, { signal: controller.signal });
  } catch {
    // an older draft of the API: leave the page alone
  }
}

关键是第二行的能力检测，以及注册时的 try。浏览器不支持或草案接口不兼容时，页面仍可正常运行。原文没有提供这些工具被实际调用的次数。

有些检查是在声明权限，有些是在验证信任

robots.txt 中的 Content-Signal: search=yes, ai-input=yes, ai-train=yes，分别表达允许搜索展示、作为 AI 回答输入和用于训练；示例作用范围是 User-Agent: *。

作者全部选择 yes，理由是希望助手了解并推荐 Fuxux。但这是他们的业务选择，不能从扫描得分推导出其他网站也应照抄。内容许可声明也不等于技术上的访问控制。

DNS-AID 则让 agent 通过 DNS 查询发现服务。作者添加的记录是 _mcp._agents.fuxux.com. HTTPS 1 www.fuxux.com. alpn="h2" port=443，扫描器仍然报错，因为找到了记录，却未验证 DNSSEC。

他们的 DNS 托管在 Cloudflare，域名注册在 GoDaddy，需要完成两步：先在 Cloudflare 的 DNS → Settings 开启 DNSSEC，再把 DS 记录交给注册商，字段包括 key tag、algorithm 13、digest type 2 和 digest。

约 20 分钟后，cloudflare-dns.com 返回 AD: true，Discoverability 才变成 4/4。这是作者这次操作的观察结果，不能当成所有域名的生效时限。

最后两项，团队决定保留失败。

第一项是根路径的 OAuth Protected Resource Metadata。团队已提供 RFC 9728 元数据，authorization_servers 为 ["https://www.fuxux.com"]，但 resource 指向 MCP URL。按作者描述，扫描器期待它指向站点 origin，而 Claude 和 ChatGPT 目录审核都要求精确匹配 MCP URL。他们选择维持已经上线的目录兼容性。

第二项是 auth.md，它用于让 agent 自行注册账户。Fuxux 每发布一条 X 帖子都有实际成本，试用限制又依赖每人一次、邮箱和银行卡检查。开放自动开户会改变原有假设，团队因此暂不实现。

我的判断

这篇最值得借鉴的是发现链路的排查方法，87 分本身只能证明通过了更多扫描检查。

作者给出了分数变化和具体修改，但没有提供改造前后的 agent 调用成功率、推荐曝光或新增用户数据。因此，「更容易被发现」有明确的实现依据，「因此带来业务增长」仍缺证据。一天从 33 分升到 87 分，也有团队早已具备 API、MCP 和 Markdown 内容的前提。

这些入口的成熟程度还不相同。文中既有带 RFC 编号的规范，也有草案格式、WebMCP 和实际客户端兼容要求。维护时需要核对目标客户端，不能只追扫描器。

对于已有接入方的服务，直接提供明确的端点和认证文档仍然实用；发现目录增加的是让陌生客户端自行找到服务的机会。是否需要同时维护这么多入口，要看真实接入需求。

我赞同作者保留两项失败的取舍。尤其当评分建议与已上线客户端发生冲突时，应先查清兼容范围。原文对 OAuth 冲突只给出他们的审核经历，尚不足以认定哪一种解释普遍正确。

能拿来做什么

• 如果你负责已有 REST API 或 MCP 的 Next.js 站点，先检查首页响应是否能把客户端引到描述文件和文档，再考虑通过 headers() 添加 Link，以及补齐 /.well-known/api-catalog。
• 如果 Node 服务发布 MCP 描述或技能文件，把最终部署产物作为检查对象，核对字段、内容类型和路径，并在构建完成后计算 sha256。
• 如果准备试用 WebMCP，可以参考作者从只读信息查询开始的做法，加入能力检测和失败容错，再根据实际客户端使用情况决定投入。
• 把内容许可、自动注册和认证元数据分别评审。先确认训练许可、账户成本和现有客户端要求，再决定哪些检查值得通过。