说明 AI 代理可以如何通过 Raydo 官网发现文档、下载入口与设备授权流程。

Raydo 官网对 AI 代理公开的是一层较小但稳定的 Web Surface。它不是一个完整的公共自动化 API 平台，但提供了可发现的文档、桌面下载和设备授权入口。

代理在这里能发现什么

产品与使用文档：/docs
桌面版下载入口：/download，覆盖 macOS、Windows、Linux
联系入口：/contact，用于支持、合作和企业沟通
设备授权相关 API：/api/cloud/device-auth/*
Session 与 API Key 验证接口：/api/auth/* 与 /api/cloud/verify-key
Notion 桌面接力 OAuth 入口：/api/oauth/notion/*
OpenAPI 元数据：/openapi.json，覆盖当前公开和一方桌面端接入所需的 agent-facing API 面

发现入口

API Catalog

/.well-known/api-catalog
内容类型：application/linkset+json
用途：列出官网当前公开、且适合机器发现的 API 面与说明文档

OpenAPI 描述

/openapi.json
/swagger.json
用途：描述 Raydo Desktop 设备授权、文档搜索、Cloud Bridge、连接器 broker 等接口，并包含 operationId、安全方案与 JSON 错误结构

OAuth 授权服务元数据

/.well-known/oauth-authorization-server
/.well-known/openid-configuration
用途：描述 Raydo Desktop 当前使用的浏览器 Session 登录与设备授权流程

OAuth Protected Resource 元数据

/.well-known/oauth-protected-resource
用途：说明哪些受保护 API 需要 Bearer 凭证，以及相关 scope

MCP / WebMCP 发现入口

/.well-known/mcp
/.well-known/mcp/server-card.json
当浏览器支持 navigator.modelContext.provideContext() 时，官网页面会在加载时暴露站点级 WebMCP 工具
用途：让代理发现文档、下载、联系这些站点导航能力

LLM 与代理说明文件

/llms.txt
/llms-full.txt
/agents.md
用途：为代理提供简版和完整上下文、适用场景、集成边界、价格入口与推荐动作

Markdown 协商

对支持的官网营销页和文档页发送 Accept: text/markdown
返回内容类型：text/markdown; charset=utf-8
响应头会带上 Vary: Accept、Content-Signal、x-markdown-tokens
如果 Raydo 部署在启用了 Cloudflare Markdown for Agents 的区域后面，可以用平台原生转换进一步替换或增强这层应用侧兜底

Agent Skills 索引

/.well-known/agent-skills/index.json
/.well-known/agent-skills
用途：暴露官网当前提供的 agent-facing 技能和入口索引

A2A 与插件清单

/.well-known/agent-card.json
/.well-known/ai-plugin.json
用途：提供 A2A 风格的产品身份、技能、文档链接，以及 ChatGPT 兼容的 OpenAPI 插件元数据

官网当前真实存在的认证模式

Raydo 官网目前对外能真实说明的认证方式主要有两类：

1. 浏览器 Session 认证

/api/auth/[...all] 由 better-auth 提供，承载官网本身的登录与 Session 流程。

2. Raydo Desktop 设备授权流程

Raydo Desktop 使用的是设备式授权流程：

POST /api/cloud/device-auth/create 创建设备码与验证地址
用户在浏览器登录后通过 POST /api/cloud/device-auth/authorize 授权设备
桌面端通过 POST /api/cloud/device-auth/poll 轮询状态
桌面端通过 POST /api/cloud/device-auth/exchange 换取一次性交换结果
后续可通过 POST /api/cloud/verify-key 校验 Bearer API Key

这样可以让桌面端接入路径被发现，但不会错误宣称官网已经是一个完整的通用 OAuth 平台。

当前范围与边界

Raydo 官网不是通用公共 MCP 自动化后端
Raydo 官网现在发布的是一份有边界的 OpenAPI 描述，覆盖公开文档/搜索元数据以及 Raydo Desktop 一方接入流程
部分受保护 API 主要服务于 Raydo Desktop 与一方客户端，而不是任意第三方自动化
这些发现元数据应该被理解为能力提示，而不是默认授权

速率限制与 JSON 错误

公共发现文件、文档与 Markdown 文件可缓存 1 小时
客户端遇到 429 或 5xx 时应使用指数退避重试
API 错误会尽量使用 JSON envelope：

{
  "error": {
    "code": "api_route_not_found",
    "message": "See /openapi.json for supported public endpoints."
  }
}

代理接入