6.3 常见坑与排错速查：按症状对号入座

6.3 常见坑与排错速查：按症状对号入座

本节摘要：本节是工具节：把全书散落的坑位收进一张"症状到病因到处方"的速查表，配一条固定的诊断动线（先看死法、再看黑匣子、最后查环境）。撞坑时按表索骥，比重新翻五章快得多。

诊断动线先行

排错最大的浪费是"瞎试"——换个模型跑跑看、改改任务单再跑、把步数调大，三连之后问题还在，钱烧了三轮。固定的诊断动线能省掉大部分瞎试：第一步判死法（触顶终止还是"完成"但结果不对，3.3 的分类）；第二步读黑匣子（把最后几拍的模型思考与动作打出来，3.2 的回调）；第三步查环境（登录态、网络、页面在别的浏览器里能不能正常打开）。三步走完，症状大概率已经落进下面这张表。

速查表：六症状全收录

两个高发坑的现场还原

**坑一：绕圈现场。**轨迹显示模型连着五拍点击"索引 12"：

def 黑匣子(state):
    last = state.history[-1] if state.history else None
    if last:
        print("思考：", (last.model_thoughts or "")[:100])
        print("动作：", last.model_actions)

result = agent.run(max_steps=10, on_step_end=黑匣子)
​

思考：点击了索引12但弹窗没有关闭，页面状态与上拍相同，再点一次
动作： 点击元素 索引 12
（重复五拍）
​

读出来的真相：弹窗的关闭按钮实际不可点（浮层遮罩没移除），模型在"再试一次"的死循环里。处方不是调参，是把真相写进任务单——"若点击后页面无变化，不要重复点击，改为报告该按钮无响应"。模型的"再试一次"是善意默认，打破默认靠声明。

**坑二：静默漂移现场。**巡检任务连续三天"正常运行"，第四天价格列全是空值。回看轨迹发现页面改版后价格移进了懒加载区域，观察拍取不到，提取合同里 会员价 是可空字段——于是模型如实填了空，复核拍也如实通过。链条上每一步都"没错"，结果整体是错的。处方在 6.2 的校验器：价格列连续为空本身就是异常，程序层拦截，别让"如实"变成"静默"。

排错之外的三句忠告

第一句：改任务单要留版。任务单就是你的源代码，改前存底，出问题能回滚能对比——很多人改来改去最后忘了哪版是好使的。第二句：一次只改一个变量。温度、任务单、模型三样一起动，好了不知道谁的功，坏了不知道谁的过。第三句：记录环境指纹。同一天任务忽好忽坏，先查是不是站点灰度、网络出口变化——把"时间、出口、页面版本"记进运行日志，玄学秒变工程。

三个次高频坑，补全谱系

**坑七：提取结果带上下文噪音。**拿回来的列表里混着推荐位和广告位——任务单没写范围。处方：提取任务一律写清"仅取主列表区域，排除推荐与广告位"，一句话的事。**坑八：多标签页串台。**开了三个比价页，价格张冠李戴——切回与归属没写清。处方：任务单里给每个标签页起名（"原页面""竞品甲页"），并写明"每个价格必须标注来自哪个页面"。坑九：时区与日期陷阱。"今天"在模型与站点之间可能差一天（服务器时区、浏览器时区各说各话）。处方：任务单里给绝对日期，别依赖"今天"这种相对词；必须相对时，写明"以站点页面显示的日期为准"。

一张最小诊断记录模板

排错不是修完就完，每次诊断落三行字，攒下来就是团队的病历本：

日期：2026-08-29  任务：比价-店铺甲
症状：触顶终止，步数 12
死法与处方：观察拍缺目标元素（弹层未开）→ 任务单加"先点开筛选面板"
结果：次日重跑通过，步数 6
​

三行的价值在于"死法"一栏——它强制你把故障归到第 3 章的某一拍。季度末统计一次死法分布：集中在观察拍，说明任务单普遍缺侦察句；集中在复核拍，说明产出约定普遍含糊。分布本身就会告诉你，下一步该练哪块肌肉。

环境类坑三则：不在模型在机器

**坑十：代理与出口 IP。**任务时好时坏、报错多为超时——先查出口：公司代理切了线路、IP 被目标站限流，都会让智能体"看起来发疯"。诊断法：同一任务手动浏览器开与智能体开各跑一次，手动通智能体不通，基本就是出口问题。**坑十一：视口与响应式布局。**智能体看到的页面可能是移动端布局（视口小），元素位置与你的预期完全不同，"找不到按钮"其实是布局切了。处方：显式设置视口尺寸，让每次跑的都是同一个页面形态。**坑十二：系统字体与编码。**页面中文显示为方框时，视觉模式等于盲人摸象；文本提取也可能因编码错乱产出乱码。处方：服务器环境装齐中文字体库，一次装好终身受益。

三则的共性：症状出现在智能体身上，病因在机器环境里。排错动线的第三步"查环境"就是为它们准备的——先把机器环境钉死（视口固定、出口固定、字体齐全），再谈调任务单，顺序反了会白改一晚上的提示词。

把速查表用起来：一次完整的对号入座

拿一个组合症状演练一遍速查表用法：某巡检任务周三、周五连续失败，其余日子正常。第一步判死法——两次都是触顶；第二步读黑匣子——卡在"等待页面元素"；第三步查环境——周三周五是报表生成日，站点白天负载高。三条线索汇合，症状落进"等待失灵"行，处方取"错峰执行"。改到凌晨跑，连续一周全绿。这个案例的价值在于示范顺序：症状、死法、黑匣子、环境四条线索齐了再开药，而不是从表的第一行试到最后一行。

速查表覆盖不到的新症状，处理完之后按 6.2 的诊断记录模板落三行字，下次它就会出现在这张表里——速查表是活的，它长成的样子就是你们团队踩过的所有坑的形状。

下一节收尾全书：用指挥循环四拍当尺子，量一量这个赛道正在发生什么、哪些值得押注。