PREFLIGHT — URL Routing for AI Agents

PREFLIGHT

AI Agent 访问 URL 前，请先询问我们该如何访问。

PREFLIGHT 为浏览器、研究和购物 Agent 提供路由智能。给定一个 URL，它会推荐最值得首先尝试的低成本路线：HTTP、BROWSER、MACHINE_ENDPOINT 或 AVOID。

长期目标是构建一张 Web 机器地图：不是 Web 上有什么，而是 机器应如何与这个目标交互？

在线服务

基础 URL：

https://preflight-api-production-01a2.up.railway.app

REST — 使用 Agent 即将访问的实际 URL：

GET /v1/check?url=<encoded-actual-destination-url>

例如，如果 Agent 即将查看产品、文档页面、文章、预订页面或 SaaS 网站，请先将该实际目标传给 PREFLIGHT。example.com 只是文档中的占位符；存在实际任务 URL 时，不应使用它。

远程 MCP：

https://preflight-api-production-01a2.up.railway.app/mcp

MCP 服务提供两个工具：

• preflight_check — 在获取陌生的实际 URL 或使用浏览器渲染该 URL 之前调用。
• preflight_feedback — 报告所选路线是否有效，以便 PREFLIGHT 改进未来的推荐。

工具调用意图示例：

打开当前任务中的 URL 前，使用 PREFLIGHT 判断普通 HTTP、浏览器、机器可读端点或暂不访问哪种方式最适合作为首选路线。

Agent 为什么应该调用 PREFLIGHT

先获取内容可能会造成浪费。目标页面可能可通过 HTTP 直接读取、需要浏览器渲染、提供更精简的机器端点、阻止自动化、要求身份验证／付费，或带有不适合获取的访问信号。PREFLIGHT 尝试在成本较高的步骤之前回答这个路由问题。

响应结合了直接探测信号、缓存的域名知识，以及足够有力的已观察路线反馈。响应内容可能包括状态、重定向、robots／访问提示、预计 token 数、JavaScript 外壳提示、结构化数据线索、机器端点、延迟、置信度、缓存时长和已学习的路线证据。

反馈循环

POST /v1/feedback
Content-Type: application/json
Authorization: Bearer <feedback-key>   # when protection is enabled

{
  "url": "https://merchant.example/product/123",
  "route": "BROWSER",
  "outcome": "success",
  "latencyMs": 840
}

PREFLIGHT 存储汇总后的成功／失败证据，而不存储页面内容或用户身份。URL 级学习至少需要 5 个样本且成功率达到 80%；域名级学习至少需要 10 个样本且成功率达到 85%。反馈绝不会覆盖当前由实时安全／访问／robots 信号得出的 AVOID 决策。

Agent 发现

• AGENTS.md 会明确告知编码／AI Agent 应在何时使用 PREFLIGHT。
• llms.txt 为大模型提供简洁、机器可读的说明、在线端点和使用规则。
• openapi.json 以 OpenAPI 3.1 格式公开 REST 操作，供工具导入器和生成的客户端使用。
• mcp.json 包含通用的远程 MCP 客户端配置。
• docs/AGENT-INTEGRATIONS.md 包含适用于浏览器、研究、购物、编码、MCP 和 REST Agent 的可复制粘贴集成模式。
• server.json 包含公开 Streamable HTTP 服务的官方 MCP Registry 元数据。
• /mcp 支持 MCP initialize、initialized notification、ping、tools/list 和 tools/call。
• 不使用 MCP 的客户端仍可使用普通 REST 端点。

搜索／发现概念：AI Agent URL 路由、浏览器 Agent 预检、选择 HTTP 还是浏览器、机器可读端点发现、减少 Agent 浏览所需的 token、Agent Web 路由、预获取路由智能、降低 AI 浏览器成本、爬取前先选路由、Agent URL 访问智能。

公开部署

GET /ready 用于验证数据目录是否可写。Railway 部署使用 /data；如需长期保留反馈，请在此处挂载持久卷。PREFLIGHT_FEEDBACK_KEY 可选用 bearer 方式保护反馈写入，同时保持路由检查公开。npm run smoke:live 会测试公开的路由／反馈流程。

真实场景基准测试

benchmarks/sites.json 包含跨类别的实时语料。运行 npm run benchmark。定时基准测试会记录路由、状态、延迟、Token 估算和机器端点，并保留机器可读报告以供趋势分析。

安全边界

PREFLIGHT 会拦截 localhost、私有/链路本地网络地址、包含凭据的 URL、非 HTTP 协议和不安全的重定向目标。端点发现和协商探测均通过同一安全防护 SSRF 的抓取层进行。MCP 会验证浏览器来源，路由反馈也无法放宽生效中的 AVOID 结果。

在本地运行

需要 Node.js 20+。

npm test
npm start

产品边界

PREFLIGHT 不是爬虫、浏览器集群、搜索引擎或网站所有者审计工具。它的职责更为明确：

输入真实 URL → 输出成本最低且可靠的机器路由。