agent 不报错才最吓人:自研编码工具半年,我踩了 10 个"看着正常"的运行时坑

agent 不报错才最吓人:自研编码工具半年,我踩了 10 个"看着正常"的运行时坑

前言

今年 6 月起,我给自己造一个 AI 编码工具:终端里跟大模型对话,它能读代码、改文件、跑命令、自己多轮干活(类似 Claude Code 的形态),底层接 DeepSeek。半年下来 359 次提交,129 次在修 bug。

修到后来我最大的体会是一句话:agent 出问题,八成不会报错。

听着有点反直觉。它照样流式输出、照样调工具、照样礼貌地说"完成了"------但根子上已经歪了。崩溃好查,安静地坏才难查。这篇文章就把这半年攒下的运行时坑挑 10 个最典型的讲透:每一个当时的表象都"看着正常",深挖下去全是问题。先上速览表:

# 表象(看着正常) 真相
坑一 工具"永远转圈"像死机 我忘了发"干完了"信号
坑二 输入框清空了 = 发出去了? 消息被两端静默吞掉
坑三 语气流畅地说"基本完成了" 活只干了一半(早收尾)
坑四 命令失败,模型说成功 输出像成功 ≠ 真成功
坑五 每个动作都正常 合起来 99 次工具调用
坑六 引导生效了,结果还是 0 命中 模型照抄出错形态
坑七 工具输出丰富、格式正常 目录是假的,谎言链三层
坑八 审批卡弹个不停,看着很安全 名字没对齐,安全在空转
坑九 长任务中途"记性变差" 压缩把任务锚点压碎了
坑十 无报错无卡顿,功能一切正常 账单在悄悄流血

坑一:工具"永远转圈"------不是模型死了,是我忘了喊"干完了"

表象很唬人:界面上某个工具一直显示"运行中...",对话像死机,等再久也没下文。第一反应:模型卡了?网络断了?

真相没那么玄。有两类工具(进出计划模式)不走正常执行流程,开始时我发了"开始了"信号,结束时却忘了发"干完了"信号。前端是个老实人:等不到结束信号,就一直转圈------模型那边早就说完了。

后来顺藤摸瓜,这类"静默故障"我一共修了七种,症状都一样(没输出/卡住),根因各不相同:有结束信号漏发的、有出错信息被去重逻辑吞掉的、有会话恢复后消息对不上账的、有状态标志没复位导致新输入被静默忽略的。

补信号只是表层,根治靠三件套:任何异常路径都要有兜底 catch ------错了也得给用户一个交代;会话恢复时对账补占位 ;状态复位放进 finally------保证失败路径也执行。

说白了,agent 的"卡死/没输出",先查事件流上哪句话没喊出来,别急着怪模型。

坑二:你发的消息,模型从来没收到

生成过程中你补充一句"顺便把测试也跑了",回车------输入框清空了,看着就是发出去了。等它干完,只字不提测试,按原计划收工。你会以为模型"没听懂",再发一次,还是没用。

真相是两端合谋的静默:生成中我的代码直接拒绝新输入,而前端先清空了输入框(给你"已发送"的假象),后端一看"忙着呢"直接 return(不吭一声)。你的消息在两端之间蒸发了------界面上没有痕迹,模型的世界里它从未存在过。

修法是把"拒绝"改成"排队":生成中的新输入先存起来,本轮干完在轮边界递给模型,它下一轮就能照办你的补充;万一排队也失败,至少弹一句"生成中,这条没发出去"。

"先清 UI 再调用"的模式里,被调方任何一声不吭的 return 都等于丢数据。界面给你的反馈,必须和真实发生的事一致。

坑三:活干到一半就说"完成了"------早收尾

模型拿到一个工具结果(比如后台编译还在跑,它只查到一半),就写上两句"基本完成了"结束对话。语气流畅、格式漂亮,看着就像一次正常的收工。

主循环有条硬规则------"模型回复里没有工具调用就收尾"。规则本身没错,但模型"不想再调工具"的原因可能是它以为活干完了。任务明明有五步,它走完两步就开始总结陈词。

深挖下去,这个坑我修了两次。第一次我加了个守护:检查结尾文本里有没有"已完成、搞定"这类关键词,没有就轻轻推它一把------往上下文里塞一张"任务可能还没完"的纸条(这就是 nudge,轻推)。结果翻车了:关键词表太窄,模型写"已简化完成""都已就位"就没命中 → 守护误判它没说完 → 拦下来让它继续 → 它又写一遍 → 再拦......用户看到的是连着三四个结尾,中间没有任何新消息。

第二次改用可度量的门槛:结尾文本少于 30 个字符才算"空手收尾"(拿到结果只蹦几个字就走),长总结一概放行。一下子就稳了。

判断模型"说完没说完",别猜语义------关键词正则永远列不全;用可度量的信号:长度、轮数、工具调用数。

坑四:成功幻觉------命令明明失败了,模型说成功了

最吓人的一种。工具输出里有点内容,模型就当它成功了,接着干下一步------以为测试过了就开始提交,以为依赖装好了就开始打包。全程自信满满,逻辑连贯,像一个正常工作的 agent。

两种变体我都踩过。第一种:跑命令的工具只把屏幕输出给模型看,不带退出码 ------模型看着输出像成功就判成功,但输出像不像成功,和成没成功是两回事。第二种更冤:超时、异常这类失败,错误文案是自由文本,我的另一段代码靠"输出前缀像不像成功"来猜成败------猜错了方向,把失败判成了成功。

修法是让机器判,别让模型读心:命令结果强制带退出码哨兵,没有哨兵一律按失败算(宁可错杀);成败判定收敛到一个出口,统一产出结构化的结果。

喂给模型的事实必须机器可判定。一个含混的成功,会让它错上加错且毫不自知。

坑五:模型把搜索工具当字典查------每个动作都正常,合起来是灾难

观察一次中等需求的执行过程:读文件、搜代码、改一点、再看一眼、再搜......每个动作单拎出来都完全正常------agent 就该这么干活嘛。但一次任务下来工具调了 99 次,合理值是它的三分之一,token 烧了三倍。

我对这几个月的真实执行记录做了行为统计:20% 的轮次是浪费的------同一参数重复调用(387 次)、同一关键词反复搜索(347 次)、改一处看一眼来回跑(98 次)。模型没有"我刚才查过这个"的习惯,它每次都当作第一次。

修法两招,都不靠打断。一是提示词里立规矩:"先读全再动手,别把搜索当字典查""批量规划改动,一次成型"。二是运行时轻推(nudge):同一文件第 3 次读、同一搜索词第 2 次搜时,往上下文尾部塞一张纸条------"这个你刚查过,答案在历史里"。不打断、不重试、不惩罚,就像旁边同事轻轻拍你一下;改完代码的文件自动重置计数(改后重读是合法的)。

单看每个动作都对、合起来就是灾难------这类问题要看统计才能发现,盯单次执行永远看不出来。

坑六:你给它语法名,它照抄出错形态

网页抓取失败后,我在失败提示里写了一句引导:"可以试试 web_search,用 site: 语法"。模型立刻照做了------引导生效了,但结果还是 0 命中,然后它连着空转两轮、调了 5 次工具,最后得出"索引里没有这个内容"的错误结论。

模型把失败的完整 URL 整条塞进了 site: 后面(site:zhuanlan.zhihu.com/p/37196599)------而 site: 只能接域名。它不是理解了引导,是逐字模仿 :引导里没有示例,它就拿最近上下文里最显眼的素材(那条失败的 URL)现场造了一个形。我做了 A/B 对照:正确写法 site:域名 标题词,首条结果就是目标。

修法:给模型的引导必须带可照抄的模板 ------"现场拼好的前缀 + 留空位"(site:${域名} 页面标题关键词),比解释语法有效十倍。守门测试同时钉住两个形态:输出必须含正确形态、不得含已知误用形态。

模型是照抄高手,不是语法学员。你给语法名,它造形;你给示例,它复刻。

坑七:工具骗了模型,模型再骗你------一条三层谎言链

让 agent 去看某个外部目录,它列出一大堆文件------输出丰富、格式正常,看起来一切顺利。然后它开始全盘递归搜索,撞墙之后郑重其事地告诉你:"这里没有这个仓库。"

查出来是工具的错:list_dir 有个参数被静默忽略 了,工具没报错,而是"好心"地兜了底------把当前工作区的目录树返回给了模型。模型不知道目录是错的,拿着假地图认认真真推理,得出假结论,再一本正经汇报给你。

整条谎言链三层:工具好意容错(说谎源头)→ 模型基于假信息推理(传谎)→ 输出假结论(用户被骗)。最讽刺的是,每一层单看都"工作正常"------工具返回了数据,模型给出了结论。

修法是工具层禁止静默兜底:参数没收到就显式报错,宁可让模型看到失败,不可给它一份好心替换的假数据。配套把"找仓库的正确路线"作为示例钉进引导(见坑六)。

工具层的好意容错是谎言的源头。显式的失败好过静默的替换------模型读得到错误原文就能自愈,读不到假数据只能自嗨。

坑八:一百多次审批点击,不是安全,是 bug

一次浏览器自动化任务,审批卡一张接一张弹,逐张手点------真机数过,一百多次。当时的直觉:工具危险,审批多说明系统在认真把关。

解锁名单明明配了,为什么每次都拦?查出来是名字对不上 :审批环节里用的工具名是一种写法(裸名 mcp_call),解锁名单里登记的是另一种(完整名 mcp__服务__工具)。链条上每一环各自都"正常",唯独名字没对齐 → 名单永远匹配不上 → 每次必弹卡。安全系统看起来在尽职,其实在空转。

修法三连:审批链所有环节统一用同一个名字;解锁名单支持通配(一条规则解锁一个服务的全部工具);同一张票里你批过的工具记住,不再重复问。一百多次点击降到 23 次。

审批弹得多 ≠ 安全。每一次"多余的确认"都在训练用户无脑点"允许"------那才是真的危险。

坑九:跑长任务,agent 中途"失忆"了

一个跨多轮的长任务,跑到后半段,agent 开始重复问已经确认过的事情,或者丢掉早先定下的约束("别动那个文件"------它动了)。看着像模型不行、记性差。

上下文窗口有限,超过阈值会把旧对话压缩 成一段摘要。问题出在压缩这个动作上。我做了对照实验:把摘要里的叙述 丢掉,任务质量显著退化(模型会暴力翻检归档捞回原文);把实体索引 丢掉,反而没大事(它不依赖索引也能检索)。也就是说,压缩丢的不是文字,是任务的锚点:早先的约束、只有对话里才存在的事实(比如"完成后把结果写成追溯码 X"),这些没落在任何文件里,一压缩就蒸发。

修法两件:一是摘要槽做成双段------实体索引由代码从原文确定性提取,永远不过模型的脑子(不会在压缩中被改写),叙述部分才允许模型自己收敛;二是任务里最要命的事实,刻意写成"对话独有交付物"------明说它只存在于本次对话、不在任何文件里,并要求"全部完成后再交付",防它提前交差。

长任务中途行为变形,先查压缩记录,再看模型。锚点要在设计上就压不碎。

坑十:最安静的坑------账单在流血,一切看着正常

没有报错、没有卡顿、没有功能异常,助手每天干一样的活。唯一的变化是账单悄悄涨了。一查:新会话的缓存命中率只有 15%------绝大部分固定开销在按原价反复计算。

做了四组对照实验才发现,缓存的最小结算单位不是逐字,而是"前面一整块固定内容"(工具说明书 + 系统提示词,约 1.1 万 token)打包成一块------块里哪怕差一个字节,整块作废按原价重算。而我的代码往这块的尾部塞了会变的东西:回复语言、技能列表、记忆目录......技能刷新一下、语言变一下,整块全失。

就像整箱优惠:拆过封就不算整箱价------而我每隔几分钟拆一次封。

修法:把"要稳定的"钉死(目录按名字排序、注入内容字节级一致),把"会变的"全部挪到块的后面去。改完同一台机器重跑同一问题,命中率 15% → 99.8%。

不报错的坑里最贵的一种:连症状都没有,只有账单。成本类问题要靠指纹取证(同一份前缀两次请求的命中差),盯功能测试永远发现不了。

结语

聊到这,标题那句话就落地了:agent 不报错,才是最吓人的。

回头看,这 10 个坑没有一个是"模型不够聪明"。模型把它看到的信息全接住了------包括我递过去的那份错的。转圈是我没发信号,吞消息是我让界面撒了谎,幻觉是我没给退出码,照抄是我没给示例,弹卡是名字没对齐,失忆是我压缩丢了锚点,烧钱是我把会变的塞进了缓存块。

做 agent 这半年,我的工作重心慢慢从"调教模型"挪到了"修管道":信号发全、事实可判、失败显式、锚点压不碎。模型是那个永远认真干活的部分,管道才是会悄悄撒谎的部分。

完整踩坑台账(14 章、按主题索引,含上面每个坑的修复细节和更多环境类坑)在仓库:deepseeker-code → docs/经验汇总.md。踩了同款坑欢迎来 issue 交流。

相关推荐
鲸鹏芯海微电子科技上海有限公司13 分钟前
手机直连卫星,射频前端到底要解决什么?
前端·后端
FungLeo14 分钟前
FengCMS · PHP+MySQL 升级实录 · Web 入口收敛:Apache/Nginx 白名单挡住配置、安装 SQL、上传脚本直连
前端·mysql·php·安全加固·fengcms
用户9860239656118 分钟前
Gemini Tool Retrieval:工具越来越多,Agent 如何按需读取参数说明?
人工智能
Jvav练习生23 分钟前
别再让Agent互相传话:多Agent协作的3个致命错误(附120行可运行代码)
agent
用户19172912708327 分钟前
Agent 工具面裁剪:动态暴露与渐进披露(附 Python 代码)
人工智能
AI前端工程狮29 分钟前
我给 MCP 长任务加进度条,五步只显示了一步
javascript·人工智能·程序员
费曼学习法29 分钟前
12 个工具调用改成并发,耗时从 94 秒掉到 23 秒:DeepSeek 并行调用工程细节
前端
TsingtaoAI30 分钟前
VeyForge:构建具身智能的AI 3D资产与Sim-to-Real数据引擎
人工智能·机器学习
修炼的dance34 分钟前
qpdf四个结构开关逐个开,只有对象流明显省
前端