前一阵我在整理自己调过的编码代理日志时发现一个特别扎心的现象那些最终跑废的任务往往不是在某一条命令上突然爆掉而是有一条漫长的“滑坡”轨迹——先是理解偏差执行偏离接着连续几次费力不讨好的修复最后彻底绕回原点。这篇题为《Failure as a Process: An Anatomy of CLI Coding Agent Trajectories》的论文几乎就是在给这类现象做病理切片。论文标题翻译过来是“失败作为一个过程CLI编码代理轨迹的解剖”它不满足于数一数代理输没输出正确结果而是把完成编码任务时留下的每一次命令调用、每一个文件改动、每一段自我纠错行为全部摊开来看。如果你也写过或者长期用基于命令行的编码代理又想知道这些家伙到底是怎么一步步把事情搞砸的这篇论文值得认真读一遍。这篇论文真正触动我的地方在于“失败”被重新定义成了一个可以追踪、可以分类、可以干预的过程而不是一个板上钉钉的终局。我写这篇文章除了拆解论文的思路也会把自己在代理调优、轨迹日志采集、失败预警方面的一些实操经验放进来力求看完能直接对着自己的工具链做一次体检。1. 这篇论文在研究什么从结果失败转向过程失败1.1 核心命题失败不是孤立事件而是一条完整路径过去我们评判一个编码代理干得好不好标准极其朴素跑测试过了就是成功没过就是失败。这种“结果导向”当然有它的价值但问题在于它把失败这件事压缩成了一个点状事件丢失了所有中间信息。论文标题里的“Failure as a Process”说白了就是要把失败重新拉长成一个连续的时间序列去看看失败究竟是从哪一步开始酝酿的。我过去也犯过同样的错误。有一阵子我在调一个自动修 bug 的脚本每次只关心“最后一次运行测试是否通过”结果发现同一个 Agent 昨天能修好问题 A今天就修不好问题 B而且我根本说不清这两次的行为差异在哪里。后来我强迫自己把完整的 shell 历史、每轮 prompt、每次文件 diff 都保留下来才开始意识到绝大多数失败是有前兆的只是在最终结论出来之前没人愿意去细看。论文提出的“过程”概念我认为包含三层含义。第一失败有起点它往往不是一个动作造成的而是某个早期决策埋下的隐患。第二失败有路径不同路径之间有明显的形态差异比如反复重试、长距离绕路、过早收敛到错误方案。第三失败有结构它可以通过轨迹特征被建模和预测而不是随机散落的噪声。这套认知上的转变是整篇论文最核心的贡献。1.2 为什么偏偏是 CLI 编码代理的轨迹如果把研究对象换成普通聊天机器人或者换成图形界面下的自动化操作“轨迹解剖”的难度会大很多。CLI 编码代理之所以被论文选中是因为它天然具备“过程可观测”的属性。在命令行环境下代理的几乎每个行为都会落到具体的文本记录上执行了哪条命令、切到了哪个目录、读到了什么报错、改动了哪些文件、测试的退出码是多少。这些信息是结构化、可重放、可运算的。相比之下图形界面里的鼠标点击和屏幕像素变化要转换成有意义的动作标签就费劲得多。CLI 代理的工作流通常是以“observation-action”循环展开的一轮又一轮像极了实验里的试次记录非常适合用来做轨迹层面的量化分析。还有一个不可忽略的因素是交互协议的规范性。CLI 编码代理面向的是一整套成熟的开发者工具链shell、git、编译器、测试框架、调试器。这些工具本身就会输出稳定的状态信息等于代理的每一步行动都自带“仪器读数”。论文能对一个代理的行为轨迹做解剖靠的正是这层标准化观测基础。看到这里你应该能明白这篇论文不是随便选了个对象而是挑了一个最适合把“失败过程”概念落地实证的场景。2. 轨迹研究的基本框架怎么记录、怎么标注、怎么归因2.1 任务池与环境沙箱的设计既然要研究“CLI coding agent trajectories”第一步就是得有足够多、足够真实的轨迹数据。按这类轨迹研究的常见做法论文需要的任务池通常覆盖多种编码场景修一个具体的测试失败、实现一个小功能、重构一段有坏味道的代码、查找并修复某个依赖问题。任务难度要有梯度太简单会让轨迹太短体现不出失败过程太难又会让代理从头到尾都处于失控状态同样不适合分析。环境沙箱的设计在实操层面非常关键。我记得自己刚开始做这类实验时直接让代理在一个带真实 git 历史的仓库里跑结果它一不小心就把分支搞乱了。后来学乖了所有实验都在隔离的容器里进行代理能访问的文件系统、网络权限、环境变量都被严格控制。论文在这一点上应该也是类似处理任务规定完成后会人为清理掉无关上下文只给代理一个干净的工作目录和一段任务描述。超时和资源限制也是硬约束比如最多调用多少次命令、最多运行多少轮超过即算失败。任务设计还有个容易被忽略的细节代理是否有机会“发现问题本身”。很多编码任务描述很明确比如“修复某函数返回错误的问题”代理只需要定位并修复但真实世界里需求往往是含糊的代理必须先理解期望状态再判断现状与之的差距。在研究轨迹时这两类任务会呈现出非常不同的失败模式所以论文大概率会把它们分开标注和统计。作为一个读论文的人我觉得这点尤其值得留意——它决定了整套失败分类框架能不能推广到你的真实业务场景。2.2 轨迹中的最小动作单元与观测空间解剖轨迹得先定义什么是轨迹上的一个“切片”。以我自己的数据采集经验来看最自然的切分单位是一轮“动作行使”。代理先读一段上下文产生一次意图然后执行一个外部动作——可能是发起一条命令、写入一段文件内容、或者查询某份文档。这次动作执行后工具环境会产生返回结果包括标准输出、错误信息、退出码、文件变更摘要等这些观察又会进入代理的上下文影响它的下一步动作。如果要用表格来描述一条最小轨迹记录单元我一般会整理成这样字段内容示例作用step12记录推进顺序phase修复阶段判断当前处在任务哪个环节action_typeshell_command / file_edit / grep_search区分动作类别commandpytest tests/test_login.py -x还原执行现场cwd/repo/src检查代理是否在正确路径工作exit_code1快速判断动作成败observation_hashf3a91c判断是否看到过相同报错diff_summary修改 login.py 第42行追踪文件变化reasoning_excerpt“可能是 token 过期导致”追溯决策依据duration_ms1200评估动作成本我在自己的项目里会把上面这些字段按 JSON 格式一行行追加到日志文件里后续随时可以加载成 DataFrame 做轨迹级分析。论文在轨迹记录层面应该做的事与此类似只是规模会大得多。观测空间的定义越细致失败归因才能越准确否则你去解释“代理为什么失败”时手上只有一堆残缺的命令记录根本无从下手。2.3 失败标签体系从“失败结果”到“失败痕迹”有了原始轨迹还需要一套统一的“失败语言”给轨迹打标签。论文标题里的“Anatomy”一词意味着它要像解剖学那样给不同器官命名定位。我认为一套合格的失败标签体系至少要覆盖四个维度失败发生在哪个阶段、失败的直接触发因素、失败的过程形态、失败对后续任务的影响。我常把失败阶段分成计划阶段、探索阶段、执行阶段和验证阶段。计划阶段失败表现为代理在动手前就抱定了错误方向探索阶段失败表现为搜索不到关键信息或者读文件时反复扑空执行阶段失败表现为命令写错、依赖缺失、编译不过验证阶段失败表现为测试命令虽然执行了但根本没有覆盖到目标逻辑。触发因素则包括信息不足、状态误判、工具误用、上下文遗忘等。过程形态是我个人最关注的部分循环、漂移、早停、震荡每种形态都会留下完全不同的轨迹指纹。这个标签体系显然不可能完全由机器自动完成需要结合规则、模型标注和人工复核。论文研究里一旦涉及人工标注就要面对主观偏差的问题因此我猜测他们应该设计了一套互斥且详尽的标签定义并且用多人交叉标注来验证一致性。对我们这种想学方法论的人来说不需要照搬整套标签库关键是要明白一个道理给失败分类时不要只写“失败原因”还要写“失败形态”和“失败路径”。这样不同的轨迹才能放在一起做形态学对比也能帮你识别出那些“虽然测试没能跑通但过程其实已经接近正确”的情况。3. 从轨迹里看到的三个关键失败规律3.1 偏离预期命令执行与任务目标出现分裂我观察过大量编码代理轨迹后发现一个反复出现的拐点代理开始执行一些和任务目标没有直接关系的命令。它明明要修一个登录接口的校验逻辑却花大量时间在编译另一个无关模块或者一遍遍读取某个只读配置文件。这种“行为漂移”初看无害但它会污染上下文窗口稀释代理对核心目标的注意力后续再想拉回来就难了。在论文的语境里这种漂移应该会被标记为“探索/执行的不匹配”。从轨迹数据上去识别它最直接的方法是看工作目录和命令作用对象的“主题一致性”。比如解析一条命令涉及的文件路径计算它与任务描述里关键实体的语义相关性一旦相关性掉到阈值以下就记录一个“偏离点”。我还用过更简单的代理指标一条轨迹里有超过 30% 的命令访问的是从未在任务描述里出现过的目录那基本可以判定它开始“散步”了。这种偏移是怎么发生的呢拿我自己的经验看最常见的原因是代理在某个中间探索环节发现了一个有趣的问题比如看到一段测试代码里的老 bug于是顺手开始研究。它没有意识到“完成当前任务”才是目标而不是“修复所有看到的代码问题”。论文把失败当过程处理就能精准捕捉到这种“任务目标感”逐步流失的时机——这比只看终局测试结果有用多了。3.2 伪修复自我纠错为何常常原地打转如果说偏离预期是“往错的方向跑”那么伪修复就是“在原地踏步”。轨迹分析里最让人头痛的形态之一是代理在收到错误反馈后并没有真正分析失败根因而是选择换一种措辞把同样的事情再做一遍。比如测试用例报出断言错误它不去打印中间变量、不去检查输入数据而是把同一个测试函数重跑三遍再比如 API 调用报超时它不做重试策略调整而是直接再发一次相同的请求。论文里如果对这种“伪修复”做了定量分析应该会发现它在失败轨迹中占比极高而且非常消耗预算。我自己也有过深刻教训某次让代理排查一个偶发性的数组越界问题它在十轮对话中重复执行了八次同样的压测命令每次只是把文件路径从相对路径改成绝对路径本质上没有任何新信息进入决策循环。要识别伪修复轨迹字段里的“重试前命令”和“重试后命令”对比是个好抓手。我们可以计算两条命令的文本相似度以及它们涉及的参数是否真的变化如果相似度极高且没有引入新的观测信息就标记为“表面修复”。更严谨一点可以把每次报错的文本哈希存下来如果代理连续好几轮处理的都是同一个错误哈希说明它并没有真正推进问题拆解。这个字段在自建实验里非常好用也对论文里“失败是过程”的论证形成了量化支撑。3.3 震荡与收敛失败轨迹的形态学如果把轨迹画成图你会发现失败轨迹往往不是一条斜向下的直线而是一条剧烈震荡的曲线。代理在多个方案之间反复横跳刚修好模块 A 的编译错误去验证时又发现模块 B 被它改坏了回到模块 B 重新修改结果模块 A 的测试又开始失败。这种“拆东墙补西墙”的震荡模式是过程中失败最典型、也最可预测的表现。我习惯用三个数值描述一撮轨迹的形态重复动作占比、有效动作占比、方案切换频率。重复动作占比是指执行过的命令或者读取过的文件在当前轨迹里是否重复出现过有效动作占比是说有多少动作真实改变了系统状态比如产生了文件 diff、新的测试输出、新的报错信息方案切换频率则是观察代理在最近 N 轮里是否主动改变过解决思路。你可以把这三项做成滚动窗口比如每 5 步计算一次一旦“重复动作占比 0.5”且“有效动作占比 0.25”这条轨迹就大概率要滑向失败。当然震荡和探索是有区别的。健康的探索也会出现频繁换方向但每一次换方向都会带回新的观测信息失败的震荡则是不断回到原点只是把理由换了个说法。论文把轨迹当作解剖对象之后我觉得最重要的产出之一就是能把这些“形态病征”标准具象化让后人看轨迹时不再只是凭感觉说“这个 Agent 好笨”而是能指出它在哪一个时刻开始陷入无效循环。4. 把论文方法迁移到自己的编码代理中轨迹日志与预警规则4.1 自建轨迹日志的字段设计读完论文别只停留在“学到了一个概念”的层面我建议你把它的思路落地成一套自己的轨迹记录体系。这不需要什么重量级基础设施只需要在你的 Agent 外层套一层轻量日志中间件把每轮交互的要点落盘即可。我实际在用的日志 schema 大概长这样{ task_id: fix-login-validation, step: 7, timestamp: 2025-01-04T10:23:41Z, phase: verification, action_type: shell_command, command: python -m pytest tests/test_login.py::test_login_success -x, cwd: /home/agent/repo, exit_code: 1, stdout_tail: AssertionError: expected 200, got 422, stderr_tail: , files_modified: [app/routes/login.py], diff_summary: added length check for password field, reasoning_excerpt: 密码长度不足尝试直接加一个 max length 校验, context_window_usage: 0.83, duration_ms: 1520, is_retry: true, similar_to_previous_command: 0.91 }不要小看similar_to_previous_command这个字段它就是判定伪修复的利器。我一般在每次动作后把当前命令和上一条命令做一次文本相似度计算如果超过 0.8 就自动打标。这样过完一个任务拿出日志一看“理论上应该推进 30 步其实 20 步都花在重试同一件事上”的情况一目了然。还有一个字段我觉得特别实用context_window_usage。CLI 编码代理最常见的死法之一就是上下文被无效输出、重复历史、超大日志填满最后模型既想不起来最初目标也提取不出关键线索。把每轮上下文占用率记录下来你可以清楚看到代理是在“高压工作”还是“低效灌水”。这比统计 token 总消耗更直观。4.2 基于轨迹的失败预警规则有了结构化轨迹日志下一步就是做预警。论文的目标是理解失败我们则可以更进一步把失败过程识别做成实时监控在代理真正把任务跑废之前人工介入。下面这份预警规则是我在实际调试点位里反复打磨出来的不能说多高级但非常实用。红灯信号判定方式阈值建议处理建议无效重试循环相邻命令相似度 0.9且退出码未变化连续出现 3 次终止当前方案强制改写行动策略工作目录漂移命令里出现与任务无关的路径某无关目录访问次数 5注入提醒把上下文拉回任务目标同一文件反复修改用 file_edit 类型动作统计同一路径修改次数同一文件修改次数 6中断操作要求先梳理变更 diff上下文占用告急每轮记录 context_window_usage超过 0.85 且仍在上升抽取关键信息清空历史细节验证空转连续 N 次运行同一测试命令且结果相同超过 3 次要求代理先加日志/打印再测这不是什么天网系统只是一组可配置的规则引擎。我实际使用下来最有效的是第一条“无效重试循环”它直接帮我发现了 Agent 的“假努力”倾向而“同一文件反复修改”在重构类任务里特别准几乎每次出现都意味着代理没有真正理解现有代码结构只是在自己改过的地方反复打补丁。4.3 实操示例一次典型的失败轨迹复盘为了让你更直观地理解“轨迹复盘”怎么做我拿一个模拟项目的典型失败案例来说。某次任务要求代理给一个命令行工具增加“批量导出 CSV”的功能任务描述里给了输入输出格式的样例。代理的前五步相对正常先读取主入口文件的代码结构再查了一下现有导出相关模块然后创建了一个新函数框架。到第六步时它第一次执行了一个简单的单元测试发现测试文件里根本没有批处理相关的用例于是它开始尝试自己构造测试数据。真正的拐点在第九步代理创建了一个临时的测试数据生成脚本这个脚本开始频繁产生 JSON 格式化错误的报错。它的应对方式是不断在脚本里加 try-except而不是去检查数据结构本身。到了第十二步它已经连续四次修改同一个临时脚本却始终没动目标入口文件。我用前面提到的预警规则去扫发现“同一文件反复修改”次数早已超过阈值而且 cwd 还停留在临时目录。这时候我做了一次人工介入把它拉回主入口文件让它重新读了一遍需求描述。它立刻意识到自己偏了但代价是已经消耗了 40% 的上下文预算。最终任务虽然勉强完成但代码质量并不理想。事后我把这个轨迹存成日志并在复盘日记里写下一句话失败不是从第十一步开始的而是从第九步创建无关脚本时就开始了。这就是“失败作为过程”的真实写照。5. 研究的边界与争议5.1 任务选取与生态差异论文对 CLI 编码代理轨迹的研究再怎么细致也要面对“外部效度”的问题。CLI 编码代理的测试环境通常是定义良好的仓库、确定的依赖版本、清晰的验收条件。真实软件工程里需求会变、团队协作会引入噪音、技术债会层层叠加现有代码库的混乱程度远高于任何实验环境。因此论文得出的某些失败规律在高度真实的大型项目里可能体现得没那么明显甚至会有新的失败模式冒出来。这并不是说研究没有价值。恰恰相反一个能在一万条干净轨迹上复现的规律至少说明这个规律不是偶然它是否适用所有场景本来就需要更多生态研究去验证。我觉得读这篇论文时应该把它当作方法论模板而不是把里面每一条结论都当成圣经。你可以拿它的分析思路去分析自己项目里的轨迹那才是最有价值的迁移。5.2 轨迹标注与评价的主观性“失败标签怎么打才客观”这个问题在论文研究里绕不开。同一个轨迹A 标注者可能觉得代理“过早放弃”B 标注者可能觉得代理“知难而退是合理的”。尤其是在一些模糊边界比如代理在某个方案上投入了很多步但最终放弃这种过程算失败还是策略调整不同人的判断会差很多。我看到这类研究时通常会特别留意作者有没有报告“标注一致性”。如果他们报了 Kappa 系数或者多人仲裁流程说明这个标签体系经受了严格推敲。如果没报那后续基于标签下的一切统计结论都要留几分怀疑。对我们自己构建 Agent 评估体系来说也是一样的道理别让单个人的判断成为标准的唯一来源至少找两个熟悉业务的人独立看轨迹再对齐。5.3 模型迭代带来的时效性挑战需要坦白说任何关于 Agent 失败模式的实证结论都面临“模型进步太快”的诅咒。可能论文里总结的伪修复高频现象在下一代模型中因为训练数据的改变就大幅缓解了可能那些震荡型失败在推理能力更强的模型那里变得不那么典型。这也是很多 Agent 研究的困境之一。但论文的价值并不因此归零。轨迹分析的方法论本身是持久的如何记录、如何标注、如何计算轨迹特征、如何判断过程健康度这些框架不会因为模型版本升级而失效。我现在读这类论文已经很少去背“结论数字”而是把注意力放在它们的实验设计和分析工具上。毕竟模型是流动的而研究失败过程的方法可以沉淀下来。6. 面向开发者的行动清单与避坑指南6.1 使用 CLI 编码代理时的三个好习惯第一个好习惯每次让代理开始任务之前明确要求它先输出一段“行动计划”包括准备读取哪些文件、预期改动哪个模块、用什么命令验证结果。这个要求会让代理在动手前先形成目标感也为你后续看轨迹提供对齐坐标。我把它叫作“先写药方再抓药”实测能减少不少开局漂移。第二个好习惯给自己设定“观察窗”。不要等代理跑完整个任务才去看它在做什么而是每十轮左右切到轨迹日志里快速扫一眼有没有红灯信号。现在很多 Agent 框架都自带实时日志哪怕没有你也可以用最简单的tail -f盯住输出。人工介入越早救回来的概率越高。第三个好习惯限制代理的“重试预算”。不要让它无限重试同一个失败动作在提示词里直接写清楚“同一测试最多运行三次超过后必须换思路”。这个约束看起来简单却能让代理在行动时更有意识地引入新信息而不是把失败动作再做一遍。6.2 构建编码代理时最常踩的五个坑在动手搭建自己的 CLI 编码代理时有几个坑我几乎每次都会看到别人踩自己也踩过。第一个坑是日志里不记 stderr。很多开发者在记录命令时只记 stdout遇到问题就抓瞎因为真正的报错全在标准错误流里。务必把 stdout 和 stderr 分开保存并附上退出码。第二个坑是上下文管理“只留最新几轮”。这看起来省 token但会让代理丢失对早期决策的记忆很多失败正是从这种记忆断层开始的。正确做法是输出一份持续更新的“任务状态摘要”包含已完成动作、当前假设、失败尝试列表。第三个坑是允许代理直接修改公共分支。一次失控的命令就可能把仓库搞乱而且一旦发生轨迹日志里记录的“agent 行为”就会混入大量人为恢复的痕迹。所有实验和自动化操作都要在独立分支或容器里进行。第四个坑是等任务彻底结束再做评估。过程性指标的价值在于“实时可见”。如果日志系统只支持事后离线分析你就永远失去了人工介入的机会。把失败预警尽量前置运行时就能看到指标滚动更新。第五个坑是不区分“探索信息”和“决策依据”。代理可能会读一堆无关文件其中只有一小部分是真正支撑下一步行动的。轨迹日志里如果不把这两类信息区分开复盘时就会觉得所有动作都是合理的看不出明显的决策盲区。6.3 给评估体系加点“过程思维”最后想聊一下评估体系的改造。如果你的团队现在还在用“最终测试通过率”做唯一指标我强烈建议引入几项过程指标无效动作占比、平均返工次数、任务目标相关性、首次正确提交时间。这些指标不需要完全替代结果指标只需并行观测一段时间你大概率会发现结果指标误导你的地方。举个例子。一个代理任务最终测试通过率是 80%看起来很厉害但如果轨迹分析显示这些通过的任务平均要经过 7 次返工每次返工都是对同一文件的反复修改那么这个“80% 通过”背后的成本其实高得吓人。换个角度另一个代理通过率只有 60%但它的轨迹流畅、返工少、上下文利用率高只要给它多一轮机会通过率可能马上追平。只看结果指标你会永远选错优化方向。把“失败当作过程”来对待本质上就是一种更精细的观察方式。我自己读完这篇论文后做的一件小事是在每次跑完编码代理任务后固定生成一份“失败轨迹体检报告”把前面说的那些红灯指标全部汇总。很多曾经要凭感觉判断的问题现在一眼就能看懂而且还能顺着轨迹找到最初的那个偏离点。如果你也长期被某个 Agent 的“神操作”气得头疼建议你试试从记录第一条命令开始回到失败发生之前去找到它的轨迹源头。