Cloudflare Markdown for Agents：AI 工作流的新选择

在 AI 驱动的内容处理日益普及的今天，如何让网络内容更容易被 AI 系统理解和处理，成为了一个关键问题。Cloudflare 最近推出的 "Markdown for Agents" 功能为这个问题提供了一个优雅的解决方案——AI 代理和自动化工具现在可以通过发送 Accept: text/markdown HTTP 请求头，将任何 Cloudflare 托管的网页直接转换为 Markdown 格式返回。这是让网络内容对 AI 系统更友好的重要一步。

本文将深入探讨这个功能的工作原理、适用场景，以及它与客户端工具（如 Web2MD）在哪些方面互补，哪些方面仍然不可替代。

什么是 Cloudflare Markdown for Agents？

Cloudflare Markdown for Agents 是 Cloudflare 边缘网络提供的一项内容转换服务。启用该功能后，Cloudflare 托管的网站可以响应包含 Accept: text/markdown 请求头的 HTTP 请求，返回页面的 Markdown 版本而非传统的 HTML 格式。

这个功能利用了 HTTP 内容协商（Content Negotiation）机制——一个标准的 HTTP 特性，允许客户端和服务器就最适合的内容格式达成一致。当 AI 代理、爬虫或自动化脚本需要获取网页内容时，它们可以明确表示"我更喜欢 Markdown 格式"，而 Cloudflare 会在边缘节点自动完成转换。

主要特性

适用范围：Cloudflare Pro、Business 和 Enterprise 计划的用户可以启用此功能
启用方式：通过 Cloudflare Dashboard 或 API 一键开启
响应格式：返回 content-type: text/markdown 响应头
Token 计数：包含 x-markdown-tokens 响应头，显示预估的 token 数量
元数据支持：支持 Content-Signal 头提供额外的页面元数据

这项功能专为 AI 代理、内容聚合器和自动化流水线设计，目的是减少 HTML 解析的复杂性，降低发送给 OpenAI 和 Anthropic 等大语言模型（LLM）的 token 消耗，并提供更结构化的内容格式。

工作原理：HTTP 内容协商

理解 Cloudflare Markdown for Agents 的关键在于掌握 HTTP 内容协商的工作机制。

传统的 HTTP 请求

在传统的 HTTP 请求中，浏览器或客户端发送请求，服务器返回 HTML：

curl https://example.com/blog/post

响应：

<!DOCTYPE html>
<html>
<head><title>Blog Post</title></head>
<body>
  <article>
    <h1>My Blog Post</h1>
    <p>This is the content...</p>
  </article>
</body>
</html>

使用 Markdown for Agents

当 AI 代理发送带有 Accept: text/markdown 请求头的请求时：

curl -H "Accept: text/markdown" https://example.com/blog/post

Cloudflare 在边缘节点拦截这个请求，获取原始的 HTML 响应，将其转换为 Markdown 格式，然后返回：

# My Blog Post

This is the content...

响应头包含：

content-type: text/markdown; charset=utf-8
x-markdown-tokens: 1450

关键点：原始服务器完全不知道这个转换过程——它仍然生成和返回 HTML。所有的转换工作都由 Cloudflare 的边缘网络透明地处理。这意味着网站开发者不需要修改任何后端代码，只需在 Cloudflare 控制面板中启用该功能即可。

技术实现指南

通过 Cloudflare Dashboard 启用

登录 Cloudflare Dashboard
选择你的域名
导航至速度 → 内容优化
找到 Markdown for Agents 选项
切换开关启用该功能

启用后，你的网站立即开始支持 Markdown 内容协商，无需重启或等待。

在 Cloudflare Workers 中使用

如果你正在构建 AI 代理或自动化工具，可以在 Cloudflare Workers 中轻松集成：

export default {
  async fetch(request, env, ctx) {
    const url = 'https://example.com/blog/post';

    // 发送带 Markdown Accept 头的请求
    const response = await fetch(url, {
      headers: {
        'Accept': 'text/markdown'
      }
    });

    // 检查是否收到 Markdown 响应
    const contentType = response.headers.get('content-type');
    if (contentType && contentType.includes('text/markdown')) {
      const markdown = await response.text();
      const tokenCount = response.headers.get('x-markdown-tokens');

      console.log(`收到 Markdown 内容，预估 ${tokenCount} 个 token`);

      // 可以直接将 Markdown 发送给 AI 模型
      return new Response(markdown, {
        headers: {
          'Content-Type': 'text/markdown',
          'X-Token-Count': tokenCount
        }
      });
    }

    return response;
  }
}

Python 自动化脚本

对于使用 Python 的数据科学家和 AI 工程师：

import requests

def fetch_markdown(url):
    """从支持 Markdown for Agents 的网站获取 Markdown 内容"""
    response = requests.get(
        url,
        headers={
            'Accept': 'text/markdown',
            'User-Agent': 'MyAI-Agent/1.0'
        }
    )

    content_type = response.headers.get('content-type', '')

    if 'text/markdown' in content_type:
        markdown_content = response.text
        token_count = response.headers.get('x-markdown-tokens')

        return {
            'content': markdown_content,
            'tokens': int(token_count) if token_count else None,
            'success': True
        }
    else:
        return {
            'content': None,
            'tokens': None,
            'success': False,
            'message': '网站不支持 Markdown for Agents'
        }

# 使用示例
result = fetch_markdown('https://example.com/blog/post')

if result['success']:
    print(f"成功获取 Markdown 内容")
    print(f"Token 数量：{result['tokens']}")
    print(f"内容预览：{result['content'][:200]}...")
else:
    print(f"失败：{result['message']}")

Node.js 示例

const axios = require('axios');

async function fetchAsMarkdown(url) {
  try {
    const response = await axios.get(url, {
      headers: {
        'Accept': 'text/markdown'
      }
    });

    const contentType = response.headers['content-type'];

    if (contentType && contentType.includes('text/markdown')) {
      return {
        success: true,
        markdown: response.data,
        tokenCount: response.headers['x-markdown-tokens']
      };
    } else {
      return {
        success: false,
        message: '网站不支持 Markdown 响应'
      };
    }
  } catch (error) {
    return {
      success: false,
      message: error.message
    };
  }
}

// 批量处理多个 URL
async function processUrls(urls) {
  const results = await Promise.all(
    urls.map(url => fetchAsMarkdown(url))
  );

  results.forEach((result, index) => {
    if (result.success) {
      console.log(`${urls[index]}: ${result.tokenCount} tokens`);
    } else {
      console.log(`${urls[index]}: ${result.message}`);
    }
  });
}

适用场景

Cloudflare Markdown for Agents 在以下场景中特别有用：

1. AI 代理流水线

当你的 AI 代理需要自动化地爬取和处理多个页面时，直接请求 Markdown 可以跳过复杂的 HTML 解析步骤。这不仅简化了代码，还减少了处理时间和计算资源消耗。

# 传统方式：需要解析 HTML
from bs4 import BeautifulSoup

html = fetch_html(url)
soup = BeautifulSoup(html, 'html.parser')
text = soup.get_text()  # 质量往往不理想

# 使用 Markdown for Agents：直接获取结构化内容
markdown = fetch_markdown(url)  # 已经是干净的 Markdown

2. RAG（检索增强生成）系统

在构建 RAG 系统时，文档质量直接影响 AI 的回答质量。Markdown 格式比纯文本保留了更多结构信息（标题、列表、链接），比 HTML 更简洁，是理想的中间格式。

// RAG 工作流示例
async function addToVectorDB(url) {
  const { markdown, tokenCount } = await fetchAsMarkdown(url);

  // 将 Markdown 分块
  const chunks = splitMarkdown(markdown, 500);

  // 生成嵌入向量并存储
  for (const chunk of chunks) {
    const embedding = await generateEmbedding(chunk);
    await vectorDB.insert({
      content: chunk,
      embedding: embedding,
      source: url
    });
  }
}

3. 内容监控和变更追踪

如果你需要跟踪某个网站的内容变更（比如竞品分析、价格监控、新闻追踪），Markdown 格式更容易进行差异比对：

import hashlib
from difflib import unified_diff

def monitor_content_changes(url):
    # 获取当前内容
    current = fetch_markdown(url)['content']
    current_hash = hashlib.md5(current.encode()).hexdigest()

    # 与上次保存的内容比对
    previous = load_previous_content(url)

    if previous and previous['hash'] != current_hash:
        # 生成差异报告
        diff = unified_diff(
            previous['content'].splitlines(),
            current.splitlines(),
            lineterm=''
        )
        send_alert(url, '\n'.join(diff))

    # 保存当前版本
    save_content(url, current, current_hash)

4. API 驱动的内容聚合

如果你在构建内容聚合平台或 RSS 替代品，直接获取 Markdown 可以大大简化内容标准化流程：

async function aggregateContent(sources) {
  const articles = [];

  for (const source of sources) {
    const { markdown, tokenCount } = await fetchAsMarkdown(source.url);

    articles.push({
      title: extractTitle(markdown),
      content: markdown,
      source: source.name,
      tokens: tokenCount,
      timestamp: new Date()
    });
  }

  return articles;
}

局限性深度分析

尽管 Cloudflare Markdown for Agents 是一个创新功能，但它有一些重要的局限性需要理解：

1. 仅限 Cloudflare 生态

这是最明显的限制。该功能只适用于：

使用 Cloudflare 作为 CDN 或 DNS 的网站
网站所有者已启用该功能
Pro、Business 或 Enterprise 计划（免费计划不支持）

据统计，虽然 Cloudflare 为超过 20% 的网站提供服务，但这仍然意味着互联网上绝大多数网站无法使用这个功能。你无法强制一个未启用该功能的网站返回 Markdown。

2. 需要网站所有者主动启用

即使网站使用了 Cloudflare，所有者也必须主动在控制面板中启用 Markdown for Agents。许多网站管理员可能：

不知道这个功能的存在
没有意识到其价值
出于某些原因选择不启用

这意味着你不能假设任何 Cloudflare 站点都支持 Markdown 响应。

3. 压缩响应的兼容性问题

在某些配置下，Cloudflare 的 Markdown 转换不支持 gzip 或 brotli 压缩的响应。这可能导致：

响应体积更大
传输时间更长
在高流量场景下的带宽成本增加

4. 仅限 HTML 内容

该功能只转换 HTML 网页。它不支持：

PDF 文档
Word 文档
图片或视频页面
API JSON 响应
其他非 HTML 内容类型

如果你需要从 PDF 或其他格式提取内容，仍然需要专门的工具。

5. 静态 HTML 限制

Cloudflare 的转换基于服务器返回的静态 HTML。它无法处理：

JavaScript 动态渲染的内容
需要用户交互才显示的内容
懒加载的元素
客户端路由的单页应用（SPA）

这意味着许多现代 Web 应用的内容可能无法正确转换。

6. 转换质量不一致

Markdown 转换的质量高度依赖于源 HTML 的结构：

语义化良好的 HTML → 高质量 Markdown
混乱的 HTML 结构 → 质量不佳的 Markdown
过度使用 <div> 和 <span> → 丢失结构信息

开源工具如 Turndown 和 Mozilla Readability 也面临类似的挑战。你无法控制转换算法，只能接受 Cloudflare 提供的结果。

服务端 vs 客户端：互补而非竞争

Cloudflare 的服务端方案和 Web2MD 这样的客户端工具并不是竞争关系，而是互补的：

| 特性 | Cloudflare Markdown for Agents | Web2MD（客户端工具） | |------|-------------------------------|---------------------| | 支持范围 | 仅限启用该功能的 Cloudflare 站点 | 任意网站，无限制 | | 需要网站配合 | 是——必须由站长启用 | 否——完全客户端处理 | | 登录态支持 | 有限——仅支持无状态认证 | 完整——使用浏览器会话和 Cookie | | JavaScript 渲染 | 否——仅处理静态 HTML | 是——捕获完全渲染后的 DOM | | 配置复杂度 | 需要 API 集成和错误处理 | 浏览器扩展——一键操作 | | 批量处理 | 出色——可并发请求多个 URL | 适中——逐页处理 | | 最佳用途 | 大规模自动化、后端流水线 | 交互式研究、需要登录的内容 | | Token 计数 | 通过 x-markdown-tokens 响应头 | 内置（Pro 版本） | | 费用 | 包含在 Cloudflare 付费计划中 | 免费版 + Pro 版可选 | | 可靠性 | 依赖 Cloudflare 服务可用性 | 依赖浏览器和本地环境 | | 隐私性 | 内容经过 Cloudflare 边缘节点 | 完全本地处理 |

何时使用 Cloudflare 方案

你的目标网站明确支持该功能
你需要批量处理大量 URL
内容不需要登录即可访问
你在构建后端服务或自动化流水线
你需要预估 token 数量来控制成本

何时使用客户端工具（如 Web2MD）

目标网站不使用 Cloudflare 或未启用该功能
内容需要登录后才能访问
页面使用 JavaScript 动态渲染内容
你需要交互式地探索和提取内容
你关注隐私，不希望内容经过第三方服务器
你需要处理复杂的单页应用

混合策略：最佳实践

在生产环境中，最优方案是结合两者优势：

async def get_markdown(url, use_browser_fallback=True):
    """
    智能获取 Markdown：优先尝试服务端，失败后回退到客户端
    """
    # 步骤 1: 尝试 Cloudflare Markdown for Agents
    result = await try_cloudflare_markdown(url)

    if result['success']:
        return {
            'content': result['markdown'],
            'method': 'cloudflare',
            'tokens': result['tokens']
        }

    # 步骤 2: 如果失败且允许回退，使用浏览器方式
    if use_browser_fallback:
        browser_result = await fetch_with_browser(url)
        return {
            'content': browser_result['markdown'],
            'method': 'browser',
            'tokens': estimate_tokens(browser_result['markdown'])
        }

    raise Exception(f"无法从 {url} 获取 Markdown 内容")

实用建议和最佳实践

1. 始终检查响应类型

不要假设请求一定会返回 Markdown：

const response = await fetch(url, {
  headers: { 'Accept': 'text/markdown' }
});

const contentType = response.headers.get('content-type');

if (!contentType || !contentType.includes('text/markdown')) {
  console.warn(`${url} 不支持 Markdown，返回了 ${contentType}`);
  // 实现回退逻辑
}

2. 监控 Token 消耗

使用 x-markdown-tokens 响应头在发送给 AI 模型前预估成本，也可以使用 OpenAI 开源的 tiktoken 库在本地验证 Token 计数：

def process_with_cost_control(url, max_tokens=4000):
    result = fetch_markdown(url)

    if result['tokens'] > max_tokens:
        print(f"警告：内容过长 ({result['tokens']} tokens)，考虑分块处理")
        return split_content(result['content'], max_tokens)

    return result['content']

3. 实现优雅降级

async function robustFetchMarkdown(url) {
  try {
    // 尝试 Cloudflare 方式
    const response = await fetch(url, {
      headers: { 'Accept': 'text/markdown' },
      timeout: 5000
    });

    if (response.headers.get('content-type').includes('text/markdown')) {
      return await response.text();
    }
  } catch (error) {
    console.log('Cloudflare 方式失败，回退到客户端转换');
  }

  // 回退到其他方法
  return await convertHtmlToMarkdown(url);
}

4. 验证转换质量

自动化验证 Markdown 输出是否包含预期内容：

def validate_markdown(markdown, url):
    checks = {
        'has_title': bool(re.search(r'^#\s+.+', markdown, re.MULTILINE)),
        'has_content': len(markdown.strip()) > 100,
        'has_structure': bool(re.search(r'^#{2,}\s+', markdown, re.MULTILINE)),
        'not_error_page': '404' not in markdown.lower()[:200]
    }

    if not all(checks.values()):
        print(f"警告：{url} 的 Markdown 质量可能有问题")
        print(f"检查结果：{checks}")

    return checks

5. 缓存策略

合理缓存 Markdown 响应以减少重复请求：

const markdownCache = new Map();

async function getCachedMarkdown(url, ttl = 3600000) {
  const cached = markdownCache.get(url);

  if (cached && Date.now() - cached.timestamp < ttl) {
    return cached.content;
  }

  const markdown = await fetchAsMarkdown(url);

  markdownCache.set(url, {
    content: markdown,
    timestamp: Date.now()
  });

  return markdown;
}

未来展望

Cloudflare Markdown for Agents 代表了让网络内容对 AI 更友好的重要趋势。我们可以期待：

更多 CDN 提供商跟进：其他边缘网络服务商可能推出类似功能
标准化努力：可能会出现关于内容协商的行业标准
质量改进：转换算法会不断优化，处理更复杂的 HTML 结构
格式扩展：未来可能支持 JSON、YAML 等其他 AI 友好格式
成本优化：更准确的 token 计数和内容压缩技术

但无论技术如何发展，客户端工具仍然有其不可替代的价值——特别是在处理需要登录、JavaScript 渲染或不受开发者控制的任意网站时。

结论

Cloudflare Markdown for Agents 是 AI 时代网络内容分发的一个创新解决方案。它通过标准的 HTTP 内容协商机制，让 AI 代理能够直接获取符合 CommonMark 规范的 Markdown 格式内容，简化了从"网页"到"AI 可理解的文本"的转换流程。

然而，它的适用范围有明确的边界：仅限 Cloudflare 托管且启用该功能的网站，无法处理 JavaScript 渲染的动态内容，也不支持需要登录的场景。

这正是为什么像 Web2MD 这样的客户端工具依然不可或缺。两者各有优势：

Cloudflare 方案：适合大规模、自动化的后端流水线
客户端工具：适合任意网站、交互式内容提取

最优策略是根据具体场景选择合适的工具，或者在生产环境中实现两者结合的混合方案——优先尝试服务端转换，失败后回退到客户端处理。

无论你选择哪种方式，Markdown 作为 AI 内容消费的通用格式这一趋势已经非常明确。掌握这些工具和技术，将让你在 AI 驱动的内容处理工作流中更加高效。

需要从任意网站获取 Markdown——而不仅限于 Cloudflare 站点？试试 Web2MD——一键将任何网页转换为干净、AI 友好的 Markdown。支持 JavaScript 渲染、登录态和复杂的单页应用。

Cloudflare Markdown for Agents：AI 工作流的新选择

Cloudflare Markdown for Agents：AI 工作流的新选择

什么是 Cloudflare Markdown for Agents？

主要特性

工作原理：HTTP 内容协商

传统的 HTTP 请求

使用 Markdown for Agents

技术实现指南

通过 Cloudflare Dashboard 启用

在 Cloudflare Workers 中使用

Python 自动化脚本

Node.js 示例

适用场景

1. AI 代理流水线

2. RAG（检索增强生成）系统

3. 内容监控和变更追踪

4. API 驱动的内容聚合

局限性深度分析

1. 仅限 Cloudflare 生态

2. 需要网站所有者主动启用

3. 压缩响应的兼容性问题

4. 仅限 HTML 内容

5. 静态 HTML 限制

6. 转换质量不一致

服务端 vs 客户端：互补而非竞争

何时使用 Cloudflare 方案

何时使用客户端工具（如 Web2MD）

混合策略：最佳实践

实用建议和最佳实践

1. 始终检查响应类型

2. 监控 Token 消耗

3. 实现优雅降级

4. 验证转换质量

5. 缓存策略

未来展望

结论

Related Articles

研究人员、写作者与 AI 用户的 5 个实用 Markdown 工作流

Obsidian Web Clipper vs Web2MD：网页转 Markdown 哪家强

AI驱动的学术研究：从网页资料到论文级分析