企业官网建设流程全解析

Firecrawl Web Agent（web-agent）是一个开源的 Web 数据智能体项目，专为结构化网络调研而优化。它基于 LangChain 的Deep Agents框架，让 AI 模型在"规划-执行-观察"循环中自主完成搜索、抓取、浏览器操作与结构化数据输出，无需人工写死任何抓取脚本。本文将带你从零看懂它的工作机制。

一、整体架构：五层堆叠的开源技术栈 🧱

web-agent 采用"逐层搭建"的设计，每一层都构建在下一层之上：

对普通用户来说，直接运行 Next.js 或 Express 模板即可获得开箱即用的 Web 调研 Agent；对开发者，则可以把agent-core作为库直接引入，获得对每个原语的细粒度控制。

二、核心机制：规划-执行-观察循环如何运转 🔁

整个智能体的"大脑"是编排器（Orchestrator），其入口在 agent-core/src/orchestrator/index.ts。它的工作流可以概括为五个步骤（源码中WORKFLOW_STEPS段定义了它）：

1. 规划（Plan）：判断任务类型，确定需要哪些数据；若用户提供了 URL，先查询站点导航手册；
2. 执行（Act）：调用 search、scrape、interact 等工具搜索、抓取、翻页；独立目标足够多时才派发并行子智能体；
3. 观察（Observe）：接收每次工具调用的返回结果，对照 schema 检查清单验证数据完整性；
4. 收敛（Finish）：调用formatOutput输出最终结果——"任务在 formatOutput 被调用之前永远不算完成"。

这个循环最多运行 50 步（maxSteps可配置），由stopWhen: stepCountIs(50)硬性约束，防止智能体无限打转。

系统提示词：一份写给 AI 的"作业守则"

编排器的行为很大程度上由 agent-core/src/orchestrator/prompts/system.md 塑造，其中几条设计非常值得学习：

• 事实必须可溯源：每条输出数据都必须来自本次会话实际抓取的页面，严禁用训练数据"脑补"；
• 完整性优先：要求"拿到全部数据，而不是样本"，抓取列表后必须自检"页面声称总数 vs 实际提取数"；
• 失败模式清单：专门列出"看到第一页就觉得够了""一个字段没找到就假设不存在"等典型偷懒模式，并逐条告诉模型"请反着做"；
• 工具降级策略：优先用带query参数的 scrape 做定向提取，只有登录墙、无限滚动等场景才动用成本更高的 interact（浏览器自动化）。

💡 提示词即产品。这份提示词本质上把"一个资深爬虫工程师的避坑笔记"翻译成了模型可执行的策略。

三、工具箱：五类核心工具的分工 🛠️

智能体可调用的工具在 agent-core/src/toolkit.ts 与 agent-core/src/tools.ts 中组装：

值得注意的是interact被额外包装了一层超时机制（见 agent-core/src/toolkit.ts），防止卡死的浏览器会话拖垮整个循环——这正是"执行"环节的工程化细节。

四、观察环节的"硬约束"：schema 校验门禁 🚦

"观察"不只是看模型怎么说，而是用代码强制校验。在 agent-core/src/agent.ts 中，formatOutput被包了两道门禁：

1. 数据收集门禁：如果任何数据工具（scrape/search/interact 等）还没返回过有效数据，直接拒绝formatOutput调用，并返回错误提示"先收集数据再输出"——从根上杜绝"拿着空壳数据交卷"；
2. Schema 修复门禁：当用户指定了 JSON schema，每次formatOutput都会先经过 agent-core/src/schema-validate.ts 校验，字段缺失或多出都会返回schema_mismatch错误，告诉模型缺了哪些字段、还剩几次修复机会（最多 3 次）。

这种"提示词软约束 + 代码硬约束"的双保险，是该项目结构化输出稳定性的关键。

五、并行扩展：spawnAgents 与子智能体 ⚡

当任务涉及 5 个以上互相独立的目标（比如同时调研 5 家公司的定价页），编排器会调用spawnAgents派发并行 worker，实现在 agent-core/src/worker/index.ts：

• 最多6 个worker 并行（maxWorkers），每个最多 30 步、5 分钟超时；
• worker 只拿到search、scrape、bashExec——没有 interact，因为浏览器会话太重，不适合并行；
• 每个 worker 的实时进度（步数、token、当前工具）通过workerProgress上报，UI 可以展示"每个小弟干到哪了"。

而用户自定义的专家型子智能体（如"定价分析师""财报分析师"）则定义在 agent-core/src/orchestrator/sub-agents.ts，每个子智能体可以拥有独立的模型、指令、工具子集和预加载技能。

官方示例 agent-core/examples/3-parallel-subagents.ts 展示了如何并行对比三款 AI 编码工具的价格与特性。

六、Skills 机制：按需加载的"站点操作手册" 📚

Skills 是本项目最有特色的设计之一。每个 Skill 是一个SKILL.md文件，存放在 agent-core/src/skills/definitions/，内置了 6 个：pricing-tracker（定价页提取）、e-commerce（电商抓取）、financial-research（财报调研）、deep-research、competitor-analysis、structured-extraction。

它的工作方式是渐进式加载，避免一次性塞爆上下文：

1. 系统提示词里只放每个技能的一行"目录"（见 agent-core/src/orchestrator/prompts/skills.md）；
2. 模型需要时才调用load_skill加载完整手册（工具实现在 agent-core/src/skills/tools.ts）；
3. 更妙的是lookup_site_playbook：每个技能目录下可放sites/子目录存放站点专属手册（如 financial-research/sites/sec-gov.md），按域名自动匹配，告诉模型该站点的 URL 模式、API 端点、翻页方式与坑点。

技能发现逻辑在 agent-core/src/skills/discovery.ts，支持用户传入自定义skillsDir，意味着你可以把自己的抓取经验沉淀为可复用的技能文件。

七、长任务保障：上下文压缩与失败恢复 🧹

长时间调研会让对话历史逼近模型的 token 上限。agent-core/src/orchestrator/compaction.ts 提供了自动压缩：

• 当输入 token 达到模型上限的75%时触发；
• 由另一个模型把完整对话压缩成结构化摘要（含"已抓取的 URL、已收集的数值、缺失字段、下一步精确动作"等 8 个板块）；
• 压缩失败也不中断任务，仅打印警告继续运行——压缩是"尽力而为的优化，而非正确性前提"。

配合 worker 的 5 分钟超时、404 不重试、/data/增量落盘等策略，整个循环具备了相当强的长任务韧性。

八、总结：这套架构教给我们什么 📌

如果你想动手体验，可以克隆仓库后运行模板：

git clone https://gitcode.com/gh_mirrors/weba/web-agent

然后按 README.md 中的两步命令安装 CLI 并生成项目，即可跑起一个属于自己的 Web 调研智能体。