1. 工作原理与部署前提
siseo Agent Gateway 由两部分组成：边缘 Markdown 层与 WebMCP 工具层。边缘 Markdown 层运行在 Cloudflare Worker 中，当请求头包含 `Accept: text/markdown` 或来自已验证的 AI 爬虫时，返回与 HTML 事实一致的精简 Markdown；WebMCP 工具层通过页面脚本向浏览器内智能体注册结构化工具。
据 Surfer 2026 趋势报告，边缘 Markdown 可将博客页从约 16,180 tokens 降至 3,150 tokens，结构化工具调用可将智能体单次交互开销从 2,000+ tokens 降至 20-100 tokens。部署前请确认站点已接入 Cloudflare，且 HTML 正文在服务端渲染输出。
- 1在控制台「出海独立站专席 → Agent Gateway」中绑定站点域名，系统会生成 Worker 脚本与 WebMCP 工具定义。
- 2在 Cloudflare 控制台创建 Worker，并为需要的路径（如 `/blog/*`、`/products/*`）配置路由。
- 3部署后使用 `curl -H "Accept: text/markdown"` 验证 Markdown 输出，并确认响应头包含 `Vary: Accept`。
- 4在页面模板中引入 WebMCP 注册脚本，在支持预览的 Chrome 版本中验证工具是否可被发现。
2. Cloudflare Worker 边缘 Markdown 示例
以下示例通过 `Accept` 请求头与 AI 爬虫 User-Agent 判断是否返回 Markdown。Markdown 由源站预生成的 `.md` 版本提供（例如 Next.js 在构建时输出），以保证与 HTML 的事实一致性。生产环境建议结合 IP 段或反向 DNS 校验 AI 爬虫身份，避免仅依赖 UA 字符串。
务必设置 `Vary: Accept` 响应头，防止 CDN 把 Markdown 版本缓存后返回给普通浏览器；同时保留 `Link: <...>; rel="canonical"` 指向 HTML 页面，避免 Markdown 版本被当作独立页面索引。
const AI_CRAWLER_UA = /(GPTBot|ChatGPT-User|OAI-SearchBot|ClaudeBot|Claude-User|PerplexityBot)/i;
export default {
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url);
const accept = request.headers.get("Accept") ?? "";
const ua = request.headers.get("User-Agent") ?? "";
const wantsMarkdown =
accept.includes("text/markdown") || AI_CRAWLER_UA.test(ua);
if (!wantsMarkdown || request.method !== "GET") {
return fetch(request);
}
// 源站在构建时为每个页面输出同路径的 index.md（内容与 HTML 事实一致）
const mdPath = url.pathname.replace(/\/$/, "") + "/index.md";
const mdResponse = await fetch(new URL(mdPath, url.origin).toString(), {
cf: { cacheTtl: 3600, cacheEverything: true },
});
if (!mdResponse.ok) {
return fetch(request); // 无 Markdown 版本时回退到 HTML
}
const headers = new Headers(mdResponse.headers);
headers.set("Content-Type", "text/markdown; charset=utf-8");
headers.set("Vary", "Accept, User-Agent");
headers.set("Link", "<" + url.toString() + '>; rel="canonical"');
headers.set("X-Agent-Gateway", "siseo");
return new Response(mdResponse.body, { status: 200, headers });
},
};3. WebMCP 工具注册示例（预览 API）
WebMCP 目前处于预览阶段（Chrome 146 起提供预览支持），`navigator.modelContext` 的接口名称、参数结构与权限模型可能随规范演进而调整，以下代码仅用于演示思路，请以 Chrome 与 W3C 社区组发布的官方规范为准，并始终先做特性检测。
建议首批只注册只读工具，例如商品规格查询与库存查询；涉及加购、下单等写操作时，必须在工具实现中要求用户显式确认，并在服务端做好鉴权与限流。
// ⚠️ 预览 API：接口可能变化，请以官方 WebMCP 规范为准
type ModelContextLike = {
registerTool?: (tool: {
name: string;
description: string;
inputSchema: Record<string, unknown>;
execute: (input: Record<string, unknown>) => Promise<unknown>;
}) => void;
};
const modelContext = (navigator as Navigator & { modelContext?: ModelContextLike })
.modelContext;
if (modelContext?.registerTool) {
modelContext.registerTool({
name: "get_product_specs",
description: "查询当前商品的规格参数、价格区间与认证信息（只读）",
inputSchema: {
type: "object",
properties: { sku: { type: "string", description: "商品 SKU" } },
required: ["sku"],
},
async execute(input) {
const res = await fetch("/api/agent/specs?sku=" + encodeURIComponent(String(input.sku)));
return res.json();
},
});
modelContext.registerTool({
name: "check_inventory",
description: "查询指定 SKU 在目标国家的库存与预计发货时间（只读）",
inputSchema: {
type: "object",
properties: {
sku: { type: "string" },
country: { type: "string", description: "ISO 3166-1 国家代码，如 US" },
},
required: ["sku", "country"],
},
async execute(input) {
const qs = new URLSearchParams({ sku: String(input.sku), country: String(input.country) });
const res = await fetch("/api/agent/inventory?" + qs.toString());
return res.json();
},
});
}4. 配置项与上线验证
Agent Gateway 的行为可在控制台或 Worker 环境变量中调整。上线后建议在服务器日志与 Gateway 调用日志中持续观察 AI 爬虫抓取量、Markdown 命中率与 WebMCP 工具调用次数，并与 AI 引荐流量变化对照分析。
- 1执行 `curl -s -H "Accept: text/markdown" https://你的域名/blog/示例文章` 确认返回 Markdown 且事实与 HTML 一致。
- 2执行普通浏览器请求，确认仍返回 HTML 且未命中 Markdown 缓存。
- 3在支持 WebMCP 预览的 Chrome 中打开商品页，确认工具可被发现且返回结构化结果。
- 4在控制台开启 Gateway 告警，当 Markdown 回源失败率超过 5% 时通过 Webhook 通知。
| 配置项 | 默认值 | 说明 |
|---|---|---|
| MARKDOWN_PATHS | /blog/*,/docs/*,/products/* | 启用边缘 Markdown 的路径模式，逗号分隔 |
| AI_UA_ALLOWLIST | GPTBot,ClaudeBot,PerplexityBot | 按 UA 返回 Markdown 的 AI 爬虫列表，建议配合 IP 校验 |
| MD_CACHE_TTL | 3600 | Markdown 版本边缘缓存秒数，内容更新后可通过 Webhook 清除 |
| WEBMCP_TOOLS | get_product_specs,check_inventory | 注册到 navigator.modelContext 的工具列表 |
| WEBMCP_WRITE_ENABLED | false | 是否允许写操作工具（加购 / 下单），开启后强制用户确认 |