CrawlForge v5.0.4：实测全部 27 个 MCP 工具，修复 34 个缺陷

2026 年 8 月 20 日，我们在一天之内发布了四个补丁版本 — v5.0.1、v5.0.2、v5.0.3 和 v5.0.4 — 关闭了 34 个缺陷。它们没有一个来自用户的 bug 报告，全部来自一个更朴素的想法：把全部 27 个 MCP 工具 和每一个 CLI 子命令跑在真实的线上网站上，然后评判返回的内容 — 而不是退出码。

v5.0.0 从内部加固了代码库：一场由完整内部审计推动的七阶段整改。但审计读的是代码。它没法告诉你 GitHub 的未登录布局已经不再输出你的模板所依赖的标记，你的隐身引擎的上游包悄悄坏掉了，或者你的研究 agent 抓到了完全正确的页面、却声称自己无法访问互联网。这些只有真实流量才能告诉你。

于是我们就跑了真实流量 — 完整跑了三轮，每一轮发现的问题都在下一轮开始前修完。

目录

• v5.0.1 到 v5.0.4 都发布了什么
• 我们如何实测一个 MCP 服务器
• v5.0.1：13 项修复，其中一项是严重缺陷
• v5.0.2：真实页面标记上的内容质量
• v5.0.3：15 项修复，外加一个修好的隐身引擎
• v5.0.4：agent 工具终于能回答问题了
• agent 工具应该用哪个本地模型？
• 我需要改动什么吗？
• 如何升级
• 接下来的计划

v5.0.1 到 v5.0.4 都发布了什么

四个版本期间，单元测试套件从 914 个增长到 980 个 — 每个缺陷都在修复发布前先补上回归测试 — MCP 协议合规率全程保持 100%。没有任何工具 schema、输出结构或 credits 成本发生变化。四个版本都可以直接升级。

我们如何实测一个 MCP 服务器

每一轮都是一次全表面扫描：全部 27 个工具通过 MCP stdio 调用，每一个 CLI 子命令在真实 shell 中执行，对象是真实的线上网站 — 新闻首页、电商目录、GitHub 仓库、文档站点。随后由一组并行 agent 评判返回的结果：markdown 是干净的，还是焊在一起的文字？提取出的实体是真的吗？答案说的是页面此时此刻的内容吗？

最后那个问题正是关键。返回 HTTP 200 加一段看似合理的输出，是网页抓取工具出错最容易的方式，而单元测试和代码审计都看不见它。下面这些失败全部通过了 CI，其中几个已经连续通过了好几个版本。

v5.0.1：13 项修复，其中一项是严重缺陷

严重的那个：crawl_deep 可能拖垮整个服务器。 BFS 爬虫会为页面上的每一个链接重新解析整页 HTML — O(链接数 × 页面大小) 的同步 CPU。在链接密集的页面上，进程会把一个核心占满 13 分钟以上、内存达到数 GB，Node.js 事件循环陷入饥饿：所有并发 MCP 调用全部挂起，连优雅停机都无法执行。现在页面只解析一次，供所有链接复用。

同样在 crawl_deep：并发队列任务可能在任何一个注册之前就全部通过 max_pages 检查，导致爬取超出上限。现在上限是精确的。

第一轮其余的修复，快速过一遍：

• serp_rank 不再丢弃已付费的查询。 DataForSEO 对没有描述的自然结果会输出 snippet: null；输出 schema 要求字符串，把已经计费的响应整个丢弃。现在允许为 null。
• generate_llms_txt 尊重 analysisOptions.maxPages 和 maxDepth。 这些上限此前从未传到分析器。
• CLI stealth 每次默认调用都失败 — --engine 的默认值是 playwright，而这个值从 v4.0.0 起就不再被枚举接受。默认值现在是 chromium，playwright 保留为别名。
• CLI track 终于能跨调用比较了。 基线只存在于进程内存中，新的 CLI 进程（或重启后的 MCP 服务器）没有可比对象。基线现在会从最新的持久化快照恢复 — 同时修掉了一个自 v4.8.0 起潜伏的缺陷：存储的快照以 Buffer 形式返回，被一个字符串类型检查悄悄拒绝。
• monitor:stop 从不说实话。 成功时报告 stopped: false，未知的监控 id 则是静默无操作。两条路径现在都会先加载存储并报告真实结果。
• crawlforge init 有两个配置缺陷。 创作者机器不再需要 API key 就能生成配置。而生成的 MCP 配置调用的是 npx -y crawlforge@latest — 一个不存在的包。实际发布的包是 crawlforge-mcp-server，所以每一份 init 生成的配置在手工修改之前都是坏的。已修复，配置现在指向 crawlforge-mcp-server@latest。
• 变更快照存的是垃圾。 每次检测到变更都会写入一个空快照，因为变更记录携带的是 diff 分析而非内容。快照现在只存真实内容，恢复时会跳过空快照，此前被污染的存储也能恢复。

给自托管用户的一条环境提示：stealth_mode、scrape_with_actions 和 scrape 的 screenshot 格式需要安装 Playwright 浏览器 — npx playwright install chromium。

v5.0.2：真实页面标记上的内容质量

第一轮还标记了四个"调用成功、内容退化"的工具。四个都是真实网站上的标记问题：

• analyze_content 永远返回零个实体。 分析器调用了一个 NLP 方法，而它需要一个我们从未安装的插件；抛出的异常中止了整个提取，一个静默的 catch 返回空结果 — 尽管人物、地点、组织的提取在底层一直正常。日期现在使用核心库的标签匹配，"Apple and Microsoft announced record earnings in California" 能产出你预期的实体。
• extract_structured 静默漏掉价格字段。 字面选择器 .price 无法匹配 price_color 这样的类名。语义表现在包含 [itemprop="price"] 和 [class*="price"]。
• generate_llms_txt 不产出页面清单。 子串匹配把 "S-api-ens" 归类为 API 链接，而一个误报就足以压制整个站点地图回退。API 检测现在使用词边界，未分类的站点始终渲染 ## Pages 列表。
• scrape_template 在 GitHub 上返回 null 的 watchers 和空的 topics。 GitHub 未登录的 React 布局删掉了旧选择器针对的标记。新选择器读取当前布局，经典布局的选择器保留为回退。

v5.0.3：15 项修复，外加一个修好的隐身引擎

第二轮走得更深，又找到十五个，其中三个是结构性的：

agent 工具不再编造答案。 前言行过滤、按来源分配的合成上下文预算加相关性排序、明确的反编造规则，以及"提示词中点名的网站一定优先抓取"的保证。

Camoufox 引擎自 v5.0.0 起就悄悄坏了。 Camoufox 的 ESM 入口是一个坏掉的 esbuild 打包产物，加载直接失败 — 这也让 deep_research 的反爬回退在没有任何可见错误的情况下失效。修复改用 CJS 加载、使用真实的 Camoufox() API，并用 viewport: null 创建上下文来绕开 playwright-core 与 Firefox 的协议不匹配。

计划监控任务现在持久化到 ~/.crawlforge/monitors。 它们以前写入相对于进程启动位置的 ./monitors 目录，所以 monitor:list、monitor:stop 和 cron 工作流只在那个确切目录下才有效。旧存储会自动迁移。

其余十二项是遍布整个表面的内容质量修复：track_changes 的相似度收敛到 [0,1] 并带真实基线统计、batch_scrape 的 markdown 保留 span 和 small 的内容、extract_text 剥离 noscript 块、localization 里法语日期格式化为 DD/MM/YYYY、抽取式摘要包含首句、analyze_content 返回真实主题、scrape_with_actions 尊重滚动坐标并报告 scrolledTo、llms.txt 链接获得真实页面标题，等等 — 仅这个版本就新增了约 50 个回归测试。

v5.0.4：agent 工具终于能回答问题了

第三轮只剩一个硬缺陷，也是当天最有意思的 bug。

agent 工具会抓到完全正确的页面 — HTTP 200、证据已记录 — 然后回答 "I'm unable to access the internet"（我无法访问互联网）。三个相互耦合的原因，每一个都被验证过单独修复并不够：

1. 文本扁平化摧毁了结构。 页面文本用一个空白正则折叠，把相邻的块级元素焊成一个字符串：一个排行榜列表变成了 "1.Story title329 points"。新的扁平化器在折叠前先标记块级元素边界，这样每个表格行、每个列表项都能作为独立的一行存活。
2. 来源排序无视你的意图。 合成来源纯粹按与提示词的词汇重叠度排序，于是一篇碰巧包含任务用词的泛泛文章可能排在提示词明确点名的网站前面。种子 URL 和提示词点名的网站现在带有固定的优先级加成，高于任何词汇重叠得分。
3. 小型本地模型拒绝完全正常的输入。 合成提示词现在明确说明来源已经抓取完毕，并禁止以"无法浏览网页"为由拒答。

三处都就位后，agent — 通过 MCP stdio 实时运行 — 能说出 Hacker News 当前真实的第一名文章。这就是今后每个版本都必须跨过的端到端标准。

v5.0.4 还修复了 CLI search 无视 crawlforge setup 存储的 API key 的问题：密钥在 import 时从环境读取，早于 CLI 密钥解析钩子的运行。现在改为在调用时解析。

agent 工具应该用哪个本地模型？

如果你用本地 Ollama 模型运行 agent 工具，合成工作中有一个发现值得照做。在真实的约 13KB 多来源合成提示词上，llama3.2 — 代码默认值 — 依然失败，而 qwen2.5:3b（同为 3B 大小）、mistral:7b 和 gemma3:12b 全部成功。

出于生态兼容性，默认值仍是 llama3.2，但如果本地的 agent 回答质量下降，就切换：

export OLLAMA_DEFAULT_MODEL=qwen2.5:3b

我需要改动什么吗？

不需要。四个版本都是补丁：没有任何工具 schema、输出结构或 credits 成本变化，工具总数仍为 27 个，价格不变。v5.0.0 的 Node.js 最低版本 >= 20.16.0 仍然适用。

一个例外：如果你在 v5.0.1 之前运行过 crawlforge init，而你的 MCP 客户端配置调用的是 crawlforge@latest，那份配置从来就没生效过 — 重新运行 crawlforge init，或把它改为 crawlforge-mcp-server@latest。

如何升级

npm install -g crawlforge-mcp-server@latest

新用户：

npm install -g crawlforge-mcp-server
npx crawlforge init

已有 MCP 客户端的用户只需触发一次 /mcp 重连。四个版本逐缺陷的完整记录在 changelog 和 releases 页面。

接下来的计划

全表面实测现在是发布流程的一部分，而不是一次性活动：今后每个版本发布前，全部 27 个工具都会针对真实网站跑一轮实测。v5.0.0 顺延的方向 — 带 OAuth 的托管远程端点、监控即服务、持久会话 — 仍在其后排队。

长期有效的邀请依然成立：如果某个工具返回的内容与页面上的实际内容不符，那正是我们想听到的 bug。

准备好试试了吗？免费开始，赠送 1,000 credits — 然后运行 npx crawlforge init 注册 MCP 服务器。参阅完整文档，或阅读 v5.0.0 发布文章了解这些版本所依托的那次大修。