超越氛围编程以基础设施优先的检索扩展 AI 智能体

大多数开发者只要写出一条措辞得当的提示词，就能让 AI 智能体抓取单个页面。让 Claude 从某个 URL 里取出价格，粘贴一个链接，通常一轮就能拿到可用的结果。

但这套流程一旦越过原型阶段就会迅速失效，因为当你从一个页面扩展到一万个页面时，要对付的已经不是提示词，而是基础设施。在大规模检索测试中，同样的故障反复出现：

• 智能体把 CAPTCHA 页面当成真实内容来消费。
• 200 KB 的 HTML 负载让令牌用量爆炸。
• 重试让推理成本成倍增加。
• 前端改版悄无声息地破坏提取逻辑。
• 同样的 URL 被一遍又一遍地重复抓取。

大多数 AI 智能体故障，其实是披着提示词外衣的基础设施故障。本指南讲的不是如何写出更好的提示词，而是如何构建实时网络与模型之间的那一层：通过 Crawlbase Web MCP Server 获得规范化的 Markdown 检索结果，用熔断器在推理之前拒绝被污染的响应，并把 Cloud Storage 当作智能体的持久记忆。下文的每个示例，都能在配套代码仓库中找到可运行的版本。

AI 智能体为什么在规模化时崩掉

AI 智能体在规模化时失效，是因为公开网络嘈杂、不稳定，而且让语言模型直接处理的代价很高。现代网页不只是内容，它还包含 JavaScript 包、水合负载、分析脚本、重复的 DOM 树、Cookie 横幅以及框架状态。一个看起来很简单的定价页面，在任何规范化之前可能返回远超 200 KB 的原始 HTML，其中大部分与智能体真正需要的东西毫无关系。

不少智能体流水线仍然把整个响应原封不动地倒进上下文窗口，这会带来两个截然不同的基础设施问题。

令牌税是把无关的前端标记一路带进推理所付出的代价。每一个多余的检索字节，最终都会转化成令牌成本、延迟、重试开销和内存压力。上下文坍塌则是随之而来的推理故障：模型忙于处理标记而不是含义，于是丢失了语义焦点。

在实践中，这会造成一些孤立看来近乎滑稽、汇总起来却代价高昂的故障。智能体会从推荐轮播里提取价格，把 Cookie 横幅当成页面正文来总结，把水合 JSON 误认成商品数据，或者把 CAPTCHA 插页当成有效响应。

Markdown 为什么胜过原始 HTML

Markdown 能降低令牌用量并提升提取可靠性，因为它在保留语义结构的同时去掉了前端噪音。原始 HTML 携带着模型并不需要的 JavaScript 负载、CSS 类名、导航标记、跟踪脚本和框架产物。Markdown 保留下来的，恰恰是推理真正依赖的东西：标题、段落、列表、表格和链接。

具体的削减幅度因站点而异，但方向是一致的：同样的信息，负载少一个数量级。这会体现为更低的令牌成本、更快的推理、更干净的提取和更稳定的推理表现，而这一切都来自上下文窗口内信噪比的提升。

这正是 Web MCP Server 通过 crawl_markdown 提供规范化检索的原因，其背后的机制与 format=md 在 Crawling API 中所做的事情完全相同。既然规范化已经在上游完成，提示词就可以写得又短又具体：

Use crawl_markdown on https://example.com/pricing and return only:
plan names, monthly prices, and currency.
Do not paste raw HTML.
If the crawl fails, report the tool error.

底层原则是：模型永远不该直接消费任意的互联网响应，它消费的应该是规范化后的语义表示。

什么是智能体数据平面

智能体数据平面是互联网与 LLM 之间的基础设施层。大多数团队把注意力放在提示词、模型和智能体框架上，但在生产环境中，更大的瓶颈几乎总是检索可靠性。数据平面负责检索、验证、规范化、持久化和上下文治理，而且这一切都发生在任何一个字节抵达推理层之前。

没有这一层，智能体就直接面对不稳定的实时网页。演示效果很漂亮，衰退得也很快。

随着 AI 系统规模扩大，瓶颈会从提示词转向检索可靠性、记忆管理、上下文效率和确定性状态。这正是 Markdown 规范化、检索验证和持久化存储不再只是优化项，而开始成为架构本身的原因。

熔断器：在推理之前完成验证

熔断器的作用是把被污染的检索结果挡在上下文窗口之外，在生产级抓取中，这件事的分量比听上去更重，因为糟糕的检索结果通常比缺失的检索结果更糟。数据缺失会自己暴露出来，而糟糕的数据会被总结、被存储，还会被拿去行动。

配套的 circuit_breaker.py 模块在推理层之前实现了故障关闭式验证：

def evaluate(
    result: CrawlResult,
    *,
    max_body_chars: int = DEFAULT_MAX_BODY_CHARS,
    expect_markdown: bool = True,
) -> CircuitDecision:

    if result.http_status != 200:
        return CircuitDecision(False, f"HTTP status {result.http_status}")

    if result.cb_status and result.cb_status != "200":
        return CircuitDecision(
            False,
            f"Crawlbase cb_status={result.cb_status}"
        )

    if not result.body.strip():
        return CircuitDecision(False, "empty body")

    if expect_markdown and not result.content_type.startswith("text/markdown"):
        return CircuitDecision(
            False,
            f"expected markdown, got {result.content_type}"
        )

    if len(result.body) > max_body_chars:
        return CircuitDecision(
            False,
            f"body exceeds {max_body_chars} chars"
        )

    return CircuitDecision(True, "ok")

这个函数就是公开网络与上下文窗口之间的一道防火墙。它不会信任每一个响应，而是在任何内容抵达模型之前，先检查传输状态、Crawlbase 的 cb_status、空响应体、内容类型和负载大小。请注意，cb_status 是 Crawlbase 状态响应头的现用名称；较旧的代码和教程可能仍然把它叫作 pc_status。

这一点之所以重要，是因为反爬系统很少会大张旗鼓地报错。一个请求可以在传输层成功，返回的却是 CAPTCHA 页面、拒绝访问文档、挑战插页或空的水合外壳。除非检索层先把它们拒之门外，否则模型会对这些内容自信地展开推理。

没有熔断器，生产环境的故障链条完全可以预见：

1. 目标站点返回一个 CAPTCHA 页面。
2. 智能体把这段 HTML 当成真实内容。
3. 提取流水线存下被污染的数据。
4. 监控系统报告出从未发生过的变化。
5. 重试循环让令牌成本和抓取成本同时成倍增加。

一次糟糕的检索就足以污染整条多智能体工作流，这正是验证应当发生在推理之前而不是之后的原因。可运行的版本参见熔断器实现。

存储为什么胜过重复抓取

生产级智能体应当先查询记忆，再查询互联网。大多数智能体教程把网络当成无状态的，真实系统承担不起这种做法。反复重新抓取同样的 URL 会推高令牌开销、削弱检索稳定性、产生前后不一的输出，还会增加毫无收益的抓取成本。

这正是 Crawlbase Cloud Storage 在架构中赢得一席之地的地方。摄取流水线用 store=true 保存规范化的 Markdown 快照，而不是每次运行都重新处理实时页面：

params = {
    "token": token,
    "url": url,
    "format": "md",
    "md_readability": "true",
    "store": "true",
}

其结果是一套基于 rid 的检索工作流：智能体之间交换的是引用，而不是完整负载。系统不再在每一跳都把大文档塞进模型，而是持久化规范化后的 Markdown、检索元数据、rid 引用和令牌估算值，等到某个步骤真正需要内容时，再通过 storage_get 按引用取回。

还有一项容易被忽略的好处：确定性。由于前端改版、A/B 测试、个性化以及日常的 DOM 变动，实时互联网是非确定性的。基于存储的快照给了你一份固定的推理输入，而这正是"可以调试的流水线"和"只能旁观的流水线"之间的分水岭。

完整的工作流参见配套的存储优先摄取脚本。

不必重新处理全部内容的变更检测

持久化存储让变更检测的成本大幅下降，因为系统比较的是规范化后的快照，而不是把整张网页重新塞回模型。配套的 change_detection.py 脚本会把存储中的 Markdown 与一次新的规范化抓取结果做对比，而这个对比过程刻意做得很平淡：

prev_hash = hashlib.sha256(previous.encode("utf-8")).hexdigest()
curr_hash = hashlib.sha256(current.encode("utf-8")).hexdigest()

如果两个哈希值一致，脚本就报告 UNCHANGED 并停下。不会跑总结环节，不会触发下游推理，也不会消耗任何令牌。这正是这个模式的全部意义：最便宜的推理步骤，是那个你从未执行的步骤。可运行的版本就是变更检测实现。

配套的数据平面代码仓库

配套代码仓库展示了这些模式如何在同一条检索流水线中协同工作。这套工作流不会把原始网页送进模型，而是在推理之前先验证响应，把页面转换成规范化的 Markdown，保存快照以备后续检索，并以确定性的方式把存储内容与实时内容做对比。支撑它的是三个模块：

• circuit_breaker.py 负责故障关闭式的检索验证。
• ingest.py 负责存储优先的 Markdown 摄取。
• change_detection.py 负责快照对比与监控工作流。

重要的不是这些脚本，而是它们的形态：一批 URL 进入，熔断器拒掉那些本就不该抵达模型的内容，通过检查的部分被规范化成 Markdown 并存储起来，之后智能体按引用读取小片段，而不是重新抓取。智能体应当基于经过验证、规范化并持久化的检索结果来推理，而不是基于任意的互联网响应。

把 Web MCP Server 接入 Claude

Web MCP Server 可以直接接入 Claude Desktop 或 Claude Code。AI 与 MCP 文档和 Claude 集成指南更详细地介绍了安装配置、Cloud Storage 工作流以及各项检索工具。Claude Desktop 的配置很简短：

{
  "mcpServers": {
    "crawlbase": {
      "type": "stdio",
      "command": "npx",
      "args": ["@crawlbase/mcp@latest"],
      "env": {
        "CRAWLBASE_TOKEN": "YOUR_TOKEN",
        "CRAWLBASE_JS_TOKEN": "YOUR_JS_TOKEN"
      }
    }
  }
}

重启 Claude 之后，这些检索工具就会出现在模型环境里：crawl_markdown 用于规范化抓取，另外还有 storage_get、storage_list 和 storage_bulk_get，用于读取你已经抓取过的内容。同一套基础设施模式，既能在 Claude 里交互式使用，也能通过 Python 流水线在运维层面使用，这正是把它们放进数据平面而不是塞进提示词的意义所在。

能够规模化的生产模式

少数几条规则，就把能在生产环境活下来的检索系统，和那些只擅长演示的系统区分开了。

默认使用 Markdown

把原始 HTML 当成兜底选项，而不是默认的推理格式。大多数页面携带的前端噪音远多于内容，而这些噪音只会增加令牌成本，不会提升提取质量。Markdown 保留语义、丢掉杂乱，让推理更快、更便宜，也更稳定。

故障时关闭

糟糕的检索结果比没有检索结果更糟。CAPTCHA 页面、软封锁或渲染失败都可能返回 HTTP 200，同时把毒素喂给模型。在边界处就拒绝可疑的检索结果，而不是指望模型自己察觉。

先查询记忆

在重新抓取之前先查存储。反复获取同样的页面会带来令牌开销、不稳定的输出和重复的抓取成本。持久化快照让智能体基于一份固定的输入推理，而不是一份不断变动的输入。

强制执行上下文预算

上下文窗口是一种带价签的基础设施资源。庞大的负载会同时推高成本、延迟和推理的不稳定性，所以要在内容进入窗口之前就给负载大小设上限，而不是等账单来了再说。

把检索与推理分开

验证和规范化属于模型的上游。把流水线拆成 retrieval、validation、normalization、persistence 和 reasoning，你会得到干净的故障隔离、更稳定的输出，以及一个规模化之后真的能调试的系统。

真正能规模化的东西

氛围编程足以让一个智能体在单个页面上跑通。难的部分从这里开始：同一套工作流要在成千上万个页面上持续运行，而且无人看管。到那一步，问题就不再是如何给模型写提示词，而是如何不再给它喂进嘈杂、不稳定或昂贵的检索结果。

可靠的系统往往会收敛到同一组选择：用 Markdown 而不是原始 HTML，用存储而不是无状态抓取，用熔断器而不是盲目重试，用确定性快照而不是实时浏览，以及在推理之前先做验证。随着智能体规模扩大，它们越来越不像聊天机器人，而更像分布式系统，瓶颈也随之转移到检索可靠性、记忆架构、规范化、持久化和令牌治理上。

如果你正朝这个方向构建系统，我们关于用 Web MCP Server 搭建 AI 智能体工作流和构建 AI 研究数据集的实操教程，展示了同一套数据平面在具体任务中的应用。下一代 AI 系统不会只由更好的提示词来定义，它会由更好的检索基础设施来定义。

常见问题

AI 智能体为什么在抓取大量页面时会失败？

小型演示之所以有效，是因为模型在暗中弥补了嘈杂的检索结果。当抓取量上去之后，智能体开始消费超大的 HTML 负载、CAPTCHA 页面、重复的前端标记和不稳定的实时响应，从而导致上下文坍塌、令牌成本膨胀和提取结果前后不一。故障出在数据平面，不在提示词。

对 AI 智能体来说，Markdown 为什么比 HTML 更好？

Markdown 在保留语义结构的同时去掉了大部分前端噪音，从而降低令牌用量、上下文污染、推理延迟和提取的不稳定性。同一个页面，以原始 HTML 计要花掉 50K+ 令牌，换成 Markdown 通常只需几千个令牌，而且上下文窗口内的信噪比更好。

AI 基础设施里的熔断器是什么？

它是一道在内容抵达 LLM 之前运行的验证关卡。它会拒绝 HTTP 错误、非 200 的 cb_status 值、空响应体、非预期的内容类型和超大负载，让被污染的检索结果永远不会成为推理输入。策略是故障时关闭：当一个响应看起来不对劲，就直接丢弃，而不是拿去总结。

智能体为什么应该使用存储而不是重新抓取页面？

持久化存储带来确定性的检索、历史对比、可重放的工作流、更低的抓取成本和更低的令牌用量。智能体之间交换的是 rid 引用而不是完整文档，只有当某个步骤需要时才去取内容。生产级智能体应当先查询记忆，再查询互联网。

什么是智能体数据平面？

智能体数据平面是互联网与 LLM 之间的基础设施层。它负责检索、验证、规范化、持久化和上下文治理，而且 AI 系统越是越过原型阶段往上扩展，它就越重要。

NZ

Neil Zamora

高级架构师 · Crawlbase

Crawlbase 高级架构师，专注大规模爬取背后的系统：代理轮换、反机器人韧性，以及隐藏这些复杂性的 API。

IK

Ian Kalvin

技术支持工程师 · Crawlbase

Crawlbase 技术支持工程师，从生产环境抓取与代理配置中真正出问题的第一线写作。