CRAWLER AGENT · AI 工程

一个抓取规则失效后,系统如何让它安全退役

用一个新闻网站改版的完整过程,讲清 Crawler Agent 如何识别可信失败、按版本累计、移除失效规则,并把历史交给下一次生成。

本文目录

在上一篇《一个“会学习”的新闻爬虫是怎样工作的》中,我们介绍了 Crawler Agent 如何为陌生网站生成、验证并保存抓取规则,让一次成功的探索可以被后续任务重复使用。这篇文章继续回答另一个同样重要的问题:已经保存的抓取能力失效以后,系统怎样及时停止使用它,又怎样避免误伤原本正常的规则。

即使没有读过上一篇文章,也不影响理解下面的内容。只需要先知道:Crawler Agent 会根据网址选择对应的抓取规则,再用规则指定的脚本读取新闻页面。

一个新闻爬虫今天能够正确读取文章,不代表它明天还能工作。新闻网站会换版式、换内容管理系统,也会把原来直接写在网页里的正文改成由浏览器加载。页面在人眼看来可能只换了字体和颜色,藏在背后的网页结构却已经完全不同。

假设 Crawler Agent 已经认识一家虚构媒体 daily.example.com。它保存了一条抓取规则:遇到 /news/ 下面的文章网址,就调用对应的正文提取脚本。脚本过去一直能找到标题和正文,网站改版以后却连续返回“找不到正文”。

如果系统什么都不做,这条失效规则仍会接收新任务,不断制造失败。如果第一次出错就删除规则,又可能把一次网络中断、网站临时维护或访问限制误认为代码已经损坏。

Crawler Agent 为此实现了一套组件退役机制。它不会凭一次失败做决定,而是先判断错误能不能明确归因给抓取组件,再按规则版本累计可信失败。达到阈值后,系统停止把新任务交给这个版本,同时保留旧代码、运行记录和诊断材料,为后续由 Agent——能够阅读页面并修改代码的 AI 助手——生成新版本留下依据。

这篇文章将沿着 daily.example.com 的改版过程,解释这套机制如何工作。文中的“退役”不是删除代码,也不是让 Agent 立即重写脚本,而是先把已经不可信的规则从正式抓取路径中安全地移开。

一个昨天正常的爬虫,为什么今天会失效

新闻页面通常包含标题、作者、时间、正文和图片,但不同网站保存这些内容的方式并不相同。有的网站把正文放在 <article> 标签中,有的网站使用标记页面样式的 CSS 类名,还有的网站把内容藏在页面中的结构化数据里。

站点脚本就是针对这些差异编写的“小型说明书”。例如,daily.example.com 的旧脚本可能认为正文总在 .story-body 中:

文章网址 → 找到 .story-body → 读取其中的段落 → 返回正文

网站改版后,正文可能被移到 .article-content。旧脚本并不知道这次变化,它仍然认真寻找已经不存在的 .story-body,最终只能报告正文缺失。

更危险的是脚本没有直接失败,而是把导航或推荐阅读当成正文。这样的结果表面上有很多文字,实际内容却是错的。系统因此需要一种止损办法:证据足以说明规则失效时,先停止使用它。

但“失败”本身不是足够的证据。目标网站可能暂时断网,服务器可能返回 503,访问频率过高可能得到 429,浏览器进程也可能恰好没有启动成功。这些问题都发生在抓取过程中,却不一定是站点脚本造成的。

真正困难的不是删除一行规则,而是判断失败责任、行动阈值,并在修改规则表时保护其他任务。

系统退役的到底是什么

理解退役之前,需要先区分三个容易混在一起的东西:组件脚本、匹配规则和规则版本。

Crawler Agent 中有两类组件脚本。正文提取脚本负责从一篇文章页面中读取标题、正文和时间,英文名称是 Extractor;网址查找脚本负责从栏目页中寻找某个时间范围内的文章网址,英文名称是 Discoverer。

脚本本身只是一个文件。系统还需要知道什么网址应该交给它,因此另外保存了匹配规则。可以把规则登记表想成一张分诊表:

daily.example.com/news/...  → daily-news 正文提取脚本
daily.example.com/world     → daily-world 网址查找脚本

一份脚本也可能被多条规则共享,因此系统不能因为其中一条规则出错,就让其他规则一起停止。

系统退役的是一个确定的规则版本。它的身份由三部分组成:组件种类、规则编号和版本编号。可以简化写成:

(正文提取脚本, daily-news, 版本 A)

规则编号说明“它是哪条规则”,版本编号说明“它是这条规则的哪一次实现”。同一个 daily-news 修复后可以发布版本 B。版本 A 的失败历史仍然存在,但不会污染版本 B 的新计数。

退役版本 A 时,系统从正式规则表中移除它,使新任务不再命中;组件目录中的脚本、README 和测试样本保持原位。如果另一条活动规则仍然引用相同脚本,它可以继续工作。

退役更像从值班表中撤下一张不可靠的工作安排,同时保留完整档案。

为什么一次失败不能直接退役

回到 daily.example.com。第一次抓取失败时,我们只知道“这次没有得到文章”,还不知道为什么。

服务器无法连接、页面拒绝访问、请求超时或浏览器故障,都可能让任务失败;但只有页面成功交给脚本后仍找不到正文,或者输出不符合约定,才更像说明书本身出了问题。因为道路临时封闭就销毁说明书,显然过于武断。

Crawler Agent 没有根据错误消息中的几个词来猜责任,而是让错误携带两个稳定信息:错误类型说明发生了什么,发生阶段说明问题出现在哪里。系统还会结合当前运行的是正文提取脚本还是网址查找脚本进行判断。

例如,“找不到正文”只有在正文提取脚本实际解析页面的阶段发生,才是可累计的失败。如果同名错误出现在下载页面的阶段,或者被错误地用于网址查找脚本,系统不会接受它。

项目把允许累计的组合明确写在代码白名单中。只有错误类型、发生阶段和组件种类同时符合要求,失败次数才会增加。这比“所有失败都计数”保守得多,却能显著降低一次外部故障引发大批规则误退役的风险。

还有一条重要原则:无法确认来源的错误默认不计数。 普通的 Error 会被归入未知错误。组件如果包装了一个网络错误,却没有保留清楚的来源,也不能靠换一个外层名称获得退役资格。自动止损需要证据,而不是猜测。

哪些失败会被认为是组件自身的问题

当前代码允许累计的错误可以分为三组。

第一组是内容解析问题:

  • 正文提取脚本明确找不到文章正文。
  • 正文提取脚本明确找不到文章标题。
  • 提取内容受到菜单、广告等明显污染。
  • 网址查找脚本确认列表结构无法解析。

第二组是组件加载问题:

  • 组件脚本存在明确的语法错误。
  • 脚本缺少系统要求的导出函数,无法履行约定。

第三组是执行结果问题:

  • 能够明确归因给组件实现的执行错误。
  • 组件已经执行完成,但输出结构不符合统一格式。

下面这些失败则明确不进入计数:

情况 为什么不用于退役
域名解析、加密连接、连接中断或拒绝 目标网络或传输链路可能只是暂时异常
请求头或响应正文读取超时 不能证明解析规则已经失效
403、404、429 和 5xx 可能是权限、限流、临时故障或网址问题
响应过大或请求次数用尽 属于系统资源限制
浏览器启动或连接失败 属于运行环境故障
机器人挑战、登录或付费限制 需要访问能力,不等于页面规则错误
未知普通异常 缺少足够的责任证据
文章过短或文章类型不支持 可能是输入本身不适合当前任务

其中一个容易误解的例子是“文章过短”。短文章可能只是快讯,并不一定说明脚本坏了。因此当前实现会把它报告给调用者,却不会用它推动自动退役。

网址查找脚本返回空列表也不自动算失败。某个时间范围内本来就可能没有新文章。除非脚本能够明确判断列表结构已经无法解析,否则“没有找到文章”仍然被视为一次合法成功。

白名单不能识别所有情况,但它规定了清楚的边界:系统只对能可靠归因的组件缺陷采取行动。

失败次数是怎样累计的

退役计数只处理正式生产任务。Agent 工作区里的试运行不会进入生产计数,避免草稿代码影响正式规则。

每次正式执行完成后,运行队列会把结果交给统一入口。入口先检查运行编号:同一种组件的同一个结果即使被重复上报,也只处理第一次。这种性质叫作幂等,就像防止同一件商品被重复记账。

正文提取脚本还有一层网址去重。假设同一篇文章以两个形式被提交:

https://daily.example.com/news/a?utm_source=mail#comments
https://daily.example.com/news/a

系统会先整理网址,去掉页面片段和广告跟踪参数,再判断它们实际是同一篇文章。在当前失败累计轮次中,这个网址最多让计数增加一次。反复提交同一个坏页面,不能轻易把整条规则推到退役阈值。

有业务含义的查询参数会保留。例如 ?edition=2 可能真的代表另一种页面内容,不会被擅自当成完全相同的网址。

网址查找脚本的情况不同。同一个栏目页会被定时反复检查,如果每次新的运行都明确报告列表解析失败,这些独立运行可以分别计数。不过,同一个运行编号重复上报仍然只算一次。

两类组件默认都在累计到 3 次可信失败时退役。几个例子最容易说明规则:

执行顺序 计数结果
文章 A 失败、文章 A 再失败、文章 B 失败 1 → 1 → 2
文章 A 失败、网络失败、文章 B 失败 1 → 1 → 2
文章 A 失败、文章 B 成功、文章 C 失败 1 → 0 → 1
同一栏目三次独立解析失败 1 → 2 → 3,网址查找规则退役
同一运行结果重复上报三次 只处理第一次

一次成功会把当前版本的失败次数清零,并开始新的累计轮次。之后同一个网址如果再次发生可信失败,可以在新一轮中重新计数。

非白名单失败既不增加,也不清零。也就是说,“连续可信失败”并不要求中间完全没有其他事件,它准确的含义是:从上一次成功开始,可信组件失败不断积累;网络故障等无法归因的结果保持中立。

关闭退役功能时,计数、累计轮次和退役状态都会冻结,但运行诊断仍然保存。重新开启后,系统从原有轮次继续,而不是偷偷丢掉之前的状态。

为什么必须按版本记录失败

假设 daily-news 的版本 A 已经失败两次。开发者修复脚本并发布版本 B。如果系统只按规则编号保存一个数字,版本 B 一上线就会继承那两次失败,再失败一次便立即退役。新代码几乎没有得到证明自己的机会。

Crawler Agent 因此把规则身份和实现版本分开。每个活动版本都有系统分配的版本编号,并在 SQLite(一种把数据保存在单个文件中的轻量数据库)中保存以下信息:

  • 当时完整的规则内容。
  • 组件目录内可执行文件的 SHA-256 摘要清单。SHA-256 是一种为文件内容生成固定指纹的算法。
  • 创建时间。
  • 如果由 Agent 生成,还会记录相关的 Agent 运行编号。

文件摘要可以理解为代码的“指纹”。路径不变而内容改变时,系统仍能发现数据库记录与磁盘实现已经不一致。

任务进入队列时,使用的版本编号就被固定下来,并随任务结果一起返回。它不能在执行结束后重新读取规则表,再猜测刚才运行的是哪个版本。

这个区别在并发环境中非常重要。版本 A 执行期间,版本 B 可能已经发布。如果 A 的结果晚到:

  • A 的第三次失败不能删除 B 的规则。
  • A 的一次成功不能清空 B 的失败计数。
  • A 的结果仍可保存为历史,但不能改变当前活动状态。

人工直接修改活动脚本同样会改变代码指纹。系统发现规则快照或文件摘要不一致时,会阻止继续沿用旧版本,并提示维护者执行:

bun run retirement:register

这个维护命令先备份状态,再为真正发生变化的规则登记新版本。新版本从零计数;没有变化的规则继续使用原版本。

第三次可信失败之后发生什么

假设 daily-news 版本 A 已经累计两次失败,文章 C 又明确报告正文缺失。系统不会直接打开以 JSON 文本格式保存的规则文件,删掉规则然后结束。退役需要同时更新规则文件和 SQLite,两者还可能被不同进程访问,因此操作必须分成受控步骤。

第一步是取得跨进程写入锁。Crawler Agent 使用一个独立的 SQLite 数据库承担这把锁。只要某个进程正在修改规则,其他进程就要等待;如果进程意外退出,操作系统会释放数据库事务持有的锁,不会永久卡住服务。

第二步是重新读取正式规则表。系统核对当前是否仍然存在相同的规则编号和版本编号,并再次检查规则快照与代码指纹。这个检查防止任务排队期间规则已经被替换,旧结果却试图删除新版本。

第三步是在一个 SQLite 事务中完成计数和记录。系统会:

  1. 确认这个运行编号没有处理过。
  2. 将可信失败次数从 2 增加到 3。
  3. 保存本次执行结果以及“为什么计数”。
  4. 写下一份待完成的规则修改意图。

修改意图包含文件修改前内容、目标内容、规则快照、触发运行、阈值和失败原因,相当于一张可以在中断后继续执行的操作清单。

第四步才是真正更新规则文件。系统先在同一目录创建临时文件,写入并刷新到磁盘,然后通过原子替换把它变成新的规则表。对其他读取者来说,文件要么是完整旧版本,要么是完整新版本,不会看到只写了一半的 JSON。

最后,系统在 SQLite 中记录不可变的退役事件,把版本状态标为已退役,并把操作意图标为完成。新的路由请求不再找到版本 A。

完成退役后,系统会尝试导出方便阅读的历史文件。这个导出结果可以根据 SQLite 重建,因此即使导出偶然失败,也不会反过来把已经提交的退役操作变成失败。

整个过程可以压缩成下面这条路线:

第 3 次可信失败
→ 核对当前规则和版本
→ 保存操作意图
→ 原子更新规则表
→ 提交退役事件
→ 导出历史资料

写到一半进程退出怎么办

规则表是 JSON 文件,状态和历史保存在 SQLite 中。普通数据库事务无法把一个外部文件也包进来。如果更新文件后程序崩溃、数据库还没来得及提交,就可能出现两边状态不同的问题。

Crawler Agent 没有把文件写入假装成数据库事务,而是用持久化操作日志解决中断恢复。每次退役或发布都先保存操作意图,再修改文件,最后提交数据库状态。

服务启动、读取受管理规则或准备下一次写入时,会检查有没有仍为“待处理”的操作。恢复程序比较文件当前内容与操作意图中的两个版本:

  • 文件还是修改前内容,说明写入尚未完成,可以继续。
  • 文件已经是目标内容,说明文件写入完成,只需补齐数据库状态。
  • 文件既不是修改前内容,也不是目标内容,说明可能有人工或其他程序同时修改过。

第三种情况不能凭猜测覆盖。系统会报告规则冲突并阻止受影响的路由,让维护者先确认哪份内容才是正确的。

在多文件操作中,系统会先检查所有目标文件,再开始继续写入。这样能避免第一个文件已经修改,走到第二个文件才发现冲突,留下更难处理的半完成状态。

这套设计不追求永不中断,而是让中断后的系统知道做到哪一步,也不覆盖未知修改。

旧文件为什么不删除

版本 A 退役以后,daily-news 的活动规则从登记表中消失,但它的脚本目录仍留在原位。当前实现不会把目录移动到 deprecated/,也不会自动删除其中的脚本、README 或样本。

保留旧文件首先是为了排障。数据库能够说明发生了哪些错误,旧代码则能说明当时系统具体做了什么。两者结合,开发者或 Agent 才能判断问题是选择器过时、页面类型变化,还是原规则覆盖范围太宽。

第二个原因是脚本可能被共享。假设普通新闻和专题新闻使用两条不同网址规则,但恰好复用一份解析脚本。只退役普通新闻规则时,直接移动或删除目录会让仍然有效的专题规则一起损坏。只从登记表中精确移除目标规则版本,就不会产生这种连带影响。

第三个原因是旧文件提供了清楚的发布边界。自动生成的新实现必须使用一个未占用目录,不能原地覆盖已经发布的组件。系统检查主机名、网址摘要和编号候选来分配目录,遇到冲突就选择新的名称。

代价也很明确:旧目录和历史文件会持续增长。当前项目没有自动垃圾回收,也不会替维护者决定旧资料应该保留多久。磁盘清理需要以后单独设计保留期限、引用检查和恢复策略,不能顺手塞进退役动作里。

退役后会立即让 Agent 修复吗

不会。退役负责停止继续使用已经不可信的版本,生成负责研究陌生或当前无法处理的页面。这是两个独立动作。

版本 A 退役后,系统不会立即在后台启动一个“修复工人”。下一次请求访问 daily.example.com/news/d 时,因为规则已经被移除,路由会得到“没有匹配规则”的结果。

只有同时满足以下条件,请求才会进入 Agent 生成流程:

  1. 这次请求明确允许使用 Agent。
  2. 系统总开关允许 Agent 工作。
  3. 对应的正文提取或网址查找生成功能已经开启。
  4. 当前用量限制和生成队列允许开始任务。

Agent 随后在独立工作区研究页面、读取相关历史并编写新组件。新实现必须通过验证程序,发布时只能增加本次允许的规则和文件,不能修改无关规则,也不能选择旧版本编号。

发布程序不会把工作区中的整份旧规则表覆盖到主目录,而是计算这次新增的部分,再与当前正式规则表合并。即使 Agent 的工作区创建得较早,也不能借旧快照把已经退役的版本重新放回来。

新规则获得新的系统版本和从零开始的计数。如果未来它再次发生可信失败,也可以独立退役,不会被旧版本的状态永久阻止。

这样责任更清楚:退役只做可靠止损,生成继续接受开关、预算、验证和发布规则的约束。

旧失败怎样帮助下一次生成

不立即修复不等于丢掉失败现场。SQLite 是退役事实的来源,系统还会把这些记录导出成更适合程序和 Agent 阅读的历史文件。

历史先按照组件种类和目标域名整理。例如,新的正文提取任务访问 daily.example.com 时,工作区会得到与这个域名相关的正文提取历史,而不是复制整个项目所有网站的失败日志。

每次 Agent 工作区创建时,系统准备一个固定入口:

.agent-context/component-history/index.json

索引列出相关退役事件,并让原规则确实能匹配当前网址的记录排在前面。每条记录可以包含规则版本、退役原因、最近三次执行、最近一次已经保存的成功结果,以及仍然可以取得的诊断材料。

为了避免把无限增长的日志全部复制进工作区,当前实现最多提供 12 个诊断文件,每个文件不超过 2 MiB(约 2 MB)。不存在、已经删除或超出范围的材料会被明确标记为不可用,而不是留下一个看似有效、实际打不开的路径。

Agent 的提示词只告诉它历史索引在哪里,不把大量旧正文和日志直接塞进提示词。这样既控制上下文长度,也让 Agent 根据当前问题按需阅读。

这些历史仍然是不可信数据。旧页面内容或日志里可能包含误导文字,不能被当成新的操作指令。历史目录会在 Agent 开始工作前纳入可信基线;如果 Agent 修改它或试图把它发布出去,发布检查会拒绝这次变更。

保留历史的目标不是让 Agent 继承旧对话,也不是保证下一版一定正确。它只是把“上次为什么失败、当时运行了什么”变成可查证材料。新脚本最终能否进入正式规则表,仍由真实试运行和验证结果决定。

这套机制还有哪些边界

退役机制减少了误杀风险,却不能证明所有判断都绝对正确。理解边界,才能正确使用它。

第一,白名单依赖错误归因准确。如果网站返回 HTTP 200,也就是用状态码表示请求成功,但正文其实是一张“请稍后再试”的错误页,脚本可能把问题报告为正文缺失。系统看到的是一个可累计错误,实际原因却可能在上游。

第二,正文提取失败按规范化网址去重。如果一条规则实际只覆盖两个有效网址,而默认阈值是 3,这两个网址无论重试多少次,在同一轮中都只能贡献两次计数。规则可能长期无法自动达到阈值。这是防止单页误杀带来的直接取舍。

第三,网址查找脚本的空列表仍被视为成功。某个栏目即使因为页面变化而悄悄返回空结果,只要脚本没有明确识别解析失败,计数就会清零。当前没有额外的业务质量判断来证明“空列表是否合理”。

第四,当前没有失败时间窗口、计数衰减、退役前观察期、全局故障熔断或退役速率限制。如果多个站点同时出现同类问题,系统不会自动判断是否是一次平台级事故。

第五,保存的版本摘要只覆盖组件自己的执行文件。共享库、运行时和依赖没有完整快照,因此历史材料适合排障,却不保证能够精确重放当时的全部环境。

最后,项目没有独立的自动修复程序,也没有旧目录垃圾回收。Agent 可以读取历史并生成替代实现,但仍可能产生有缺陷的代码,发布过程不能跳过验证。

这些边界并不否定退役机制的价值。它们说明这套系统选择了一个保守目标:在证据明确时停止继续使用坏规则,同时避免把临时外部故障轻易变成永久配置变化。

可以迁移到其他 Agent 系统的原则

Crawler Agent 处理的是新闻抓取规则,但它面对的问题并不只属于爬虫。任何允许 Agent 生成并长期复用程序组件的系统,都会遇到版本失效、错误归因、自动停用和历史保存。

这套实现有五条值得迁移的原则。

  1. 只根据能够明确归因的证据自动淘汰组件。 网络失败、环境失败和未知错误不应该因为发生次数多就被解释成代码缺陷。
  2. 把组件名称和实现版本分开。 新版本从零开始,旧任务的迟到结果只能进入旧历史,不能影响当前实现。
  3. 隔离生产执行和验证执行。 草稿代码的试运行不应改变正式组件的健康状态。
  4. 修改正式配置前保存操作意图。 文件和数据库无法共享一个事务时,要让中断后的恢复过程有据可查,并拒绝覆盖无法确认的第三种状态。
  5. 让退役负责止损,让生成负责恢复能力。 两个动作分别接受自己的权限、预算和验证约束,比一个“失败后立即自动修复”的黑盒更容易控制。

从表面看,组件退役只是累计三次失败后删除一条规则。真正让它可靠的,是删除之前的一系列克制:区分责任、按网址去重、固定版本、抵抗重复结果、协调并发写入、保存恢复意图,以及保留失败现场。

一个能够生成代码的系统,不仅要知道怎样获得新能力,也要知道什么时候停止相信旧能力。安全退役所做的,正是把这种“不再信任”变成一套能够检查、恢复和继续演进的工程流程。