1. 从一次翻车说起为什么 Agent 光有循环还不够去年冬天我接手了一个内部工具链的自动化改造目标很朴素让一个基于大模型的 Agent 自己去读代码仓库、定位一个已知的构建失败、改掉它、跑测试、提交。听起来就是标准的“感知—决策—执行”循环我一开始也确实是这么搭的一个 while 循环把工具调用结果塞回上下文再让模型决定下一步。第一天跑得挺顺第二天开始出问题——它开始重复读同一个文件第三次、第四次上下文越滚越长最后在一次工具调用里返回了一个巨大的日志直接把窗口撑爆模型开始胡言乱语改了一个根本不存在的函数。那次翻车让我意识到一件事Agent 循环本身只是骨架真正决定它能不能干活的是循环外面那一圈东西。后来我把这套外围机制统称为 Harness也就是“挽具”——它不负责思考它负责让思考这件事能稳定、可验证、可长时间地跑下去。这个标题里的几个词其实是一条完整的链路Agent 循环是心脏上下文是血液沙箱是手术台验证是术后检查长时运行是能不能撑过一台大手术。缺任何一环Agent 都只是个玩具。这篇东西我想按我自己踩坑的顺序把这五个部分拆开讲清楚。适合谁看如果你已经写过最基础的 tool-calling 循环但发现它一上真实任务就崩那这篇就是写给你的。如果你还没写过循环也能看懂因为我会把每个概念用生活化的方式讲一遍。核心关键词我会反复提到Agent 循环、上下文管理、沙箱隔离、验证机制、长时运行这五个是 Harness 工程的五根柱子。2. Harness 工程的整体设计思路拆解2.1 为什么我把 Harness 和 Agent 本体分开看很多人第一次接触 Agent脑子里想的是“模型 工具 Agent”。我早期也这么认为直到我发现同一个模型、同一套工具换一个外围框架成功率能差出好几倍。这说明能力不全在模型里很大一部分在外围。我把这个外围叫 Harness它包含五件事怎么组织循环、怎么管理上下文、在哪执行、怎么判断对错、怎么撑住长时间。打个比方模型是一个很有天赋但记性有限、手还容易抖的实习生。Agent 循环是给他派活的流程上下文是他的工作台沙箱是他操作的车间验证是质检长时运行是排班制度。你光招个聪明实习生不给他工作台、不给他车间、不质检、不排班他干两天就乱了。Harness 工程做的就是这四件“不性感但致命”的事。我坚持把 Harness 独立出来设计还有一个很现实的原因它可测试、可替换、可复用。模型会换、工具会加但 Harness 的骨架相对稳定。你把循环、上下文、沙箱、验证做成独立模块换模型的时候只动一小块而不是推倒重来。这是工程化的基本盘。2.2 五个模块的职责边界与耦合关系我画不出图这里也不打算画但可以用一张表把职责说清楚。这张表是我实际项目里模块划分的简化版每个模块我只写它“必须负责”的事超出范围的一律不接。模块核心职责不该管的事与其他模块的接口Agent 循环驱动“决策—执行—观察”的节奏控制终止条件不负责上下文裁剪策略向上下文模块要历史向沙箱要执行结果上下文管理决定每一步给模型看什么、丢什么、压缩什么不负责判断任务是否完成从循环接收新事件输出给模型沙箱提供隔离、可复现、可回滚的执行环境不负责决定执行什么接收循环下发的动作返回结构化结果验证判断一次动作或整个任务是否达标不负责修复只负责判定接收沙箱产物向循环反馈信号长时运行处理中断、恢复、状态持久化、资源回收不负责单步逻辑包裹整个循环管理生命周期这张表最关键的一列是“不该管的事”。我见过太多项目把上下文裁剪逻辑写进循环里结果循环代码膨胀到几百行改一处崩三处。边界清晰比功能强大更重要这是 Harness 工程的第一原则。2.3 一个反直觉的取舍宁可循环笨一点新手容易把循环写得很“聪明”根据任务类型走不同分支、内置各种启发式规则、提前判断该不该调用某个工具。我早期也这么干后来全删了。原因是循环越聪明越难调试越难和模型的能力解耦。当模型升级后你那些启发式规则反而成了拖累。我现在的做法是循环尽量笨只做四件事——把当前状态交给模型、拿到动作、交给沙箱执行、把结果交给验证和上下文。所有“聪明”都下沉到上下文管理和验证里因为那两块是可独立测试的。循环笨了出问题时我能快速定位是模型的问题、上下文的问题还是沙箱的问题而不是在一堆分支里猜。3. Agent 循环的核心细节与实操要点3.1 循环的四种终止条件缺一个都会挂最朴素的循环是“模型不再调用工具就停”。我实测下来只靠这一条十次里有三次会卡死或者无限循环。我现在固定用四种终止条件任何一个触发就停模型显式给出最终答案最理想的情况模型说“我完成了”并给出结论。达到最大步数我一般设 30 到 50 步看任务复杂度。超过就强制停交给人工或上层逻辑。连续无进展检测如果连续三步的动作和观察结果高度相似比如反复读同一个文件判定卡死停。预算耗尽token 预算或时间预算任一超限就停。这四条里第三条最容易被忽略但它是救命的。我踩过的坑就是模型陷入“读文件—发现不对—再读同一个文件”的死循环光靠最大步数要等 50 步才停浪费大量预算。无进展检测我用的是动作指纹加结果指纹的相似度简单但有效。提示最大步数不要设太大。我一开始设 100结果一次卡死烧掉的钱够我跑一周正常任务。后来改成 30配合无进展检测反而更稳。3.2 动作解析为什么我不让模型直接输出 JSON早期我让模型直接输出 JSON 格式的工具调用结果被各种格式错误折磨少个引号、多个逗号、字段名拼错。后来我改成让模型输出一种更宽松的格式再由解析层做容错。具体做法是模型输出“工具名 参数块”参数块允许用自然语言描述解析层负责把它规整成结构化调用。这个改动的收益很大。模型在宽松格式下的成功率明显高于严格 JSON因为严格格式对 token 级错误零容忍而宽松格式给了容错空间。解析层我写了几条规则字段名做模糊匹配、参数值做类型推断、缺失的必填参数用默认值兜底并记录警告。这套下来格式导致的失败率从两位数降到个位数百分比。3.3 循环里的状态机别用裸 while裸 while 循环在简单场景够用但一旦涉及重试、回滚、人工介入就会变成一团乱麻。我现在的循环内部是一个显式状态机状态包括IDLE、THINKING、ACTING、OBSERVING、VERIFYING、RETRYING、DONE、FAILED。每个状态只做一件事状态转移有明确条件。这么做的直接好处是可观测。我可以在任意时刻打印当前状态知道 Agent 卡在哪一步。另一个好处是可干预人工介入时我可以把状态从RETRYING手动推到DONE或者注入一条修正指令。裸 while 做不到这些因为你根本不知道它现在处于什么阶段。4. 上下文管理Agent 的记性和注意力4.1 上下文不是越长越好这是个陷阱我见过一种说法“上下文窗口越大Agent 越强”。这话对了一半。窗口大确实能塞更多信息但塞进去的信息越多模型的注意力越分散。我做过对比同一个任务把完整历史塞进去 vs 只塞关键历史后者的成功率反而更高因为模型不会被无关的中间步骤干扰。这就像你让一个人干活桌上堆满了他之前所有的草稿纸他反而找不到当前要用的那张。上下文管理的核心不是“装得多”而是“装得准”。我现在的基本原则是当前任务相关的信息必须全历史过程信息按需保留无关信息坚决丢。4.2 三层上下文结构我实际用的组织方式我把上下文分成三层每层有不同的保留策略系统层任务目标、约束条件、可用工具说明。这层几乎不变始终保留。工作层当前正在处理的子任务、最近几步的动作和观察。这层滚动更新只保留最近 N 步。归档层更早的历史压缩成摘要后保留。摘要由模型生成只保留结论和关键决策。三层之间的信息流动是有规则的工作层满了最老的几步压缩进归档层归档层超过阈值最老的摘要再压缩一次。这样上下文总量可控同时关键信息不丢。我实测下来这套结构能让长任务在固定窗口下稳定跑几十步而不爆。4.3 压缩的时机和粒度踩过的坑压缩最怕两件事压太早关键信息还没用上就没了压太晚窗口已经爆了。我现在的做法是按 token 占用比例触发而不是按步数。当上下文占用达到窗口的 70% 时开始压缩压到 50% 停。这个区间是试出来的70% 留了缓冲50% 保证有足够空间继续跑。粒度上我不用“每步都压”而是按子任务边界压。一个子任务完成就把这个子任务的过程压成一段摘要。这样摘要的语义完整不会把一件事拆成两半。早期我按固定步数压结果经常把一次工具调用和它的结果分开模型看到结果却看不到调用直接懵了。注意压缩摘要一定要让模型自己生成不要用规则截断。规则截断会丢语义模型生成的摘要至少保留了“发生了什么、结论是什么”。4.4 上下文里的“负样本”要不要留这是个有意思的问题。Agent 走错路的过程要不要留在上下文里我一开始全留想着让模型“记住教训”。结果发现模型经常被错误路径带偏反复回到错误方向。后来我改成错误路径只保留结论性的“此路不通”不保留具体过程。比如“尝试用方案 A 修复失败原因是 X”而不是把方案 A 的每一步都留着。这个改动让 Agent 的“回头率”明显下降。模型知道哪些路走不通就够了不需要重温走错的全过程。这跟人一样你记住“那条路堵”不需要记住堵车的每一秒。5. 沙箱让 Agent 的手不抖、可回滚5.1 为什么必须隔离一次真实的教训我早期图省事让 Agent 直接在宿主机上跑命令。有一次它执行了一个清理命令参数写错删掉了一个不该删的目录。虽然那个目录有备份但那次之后我彻底改了所有 Agent 的执行动作必须在隔离环境里。这不是洁癖是底线。隔离的好处不只是安全还有可复现。同一个任务在干净的沙箱里跑结果稳定在脏的宿主机上跑结果取决于环境状态根本没法调试。我现在要求沙箱每次任务开始时是干净状态任务结束后销毁中间的所有改动都在沙箱内。5.2 沙箱的三种隔离级别与选型我实际用过三种隔离级别各有适用场景级别隔离方式启动速度适用场景我的使用建议进程级独立进程 资源限制快纯计算、无文件系统改动轻量任务首选容器级独立文件系统 网络隔离中需要装依赖、改文件大多数任务用这个虚拟机级完整系统隔离慢高风险、需内核操作谨慎任务才用选型逻辑很简单按任务的风险和依赖需求选。改代码、跑测试这种容器级足够纯文本处理进程级就行涉及系统级操作的才上虚拟机。我见过有人一律用虚拟机结果启动慢到没法用也见过一律用进程级结果文件被改乱。按需选别一刀切。5.3 沙箱内的文件系统快照与回滚回滚是沙箱最被低估的能力。Agent 改错了怎么办如果沙箱支持快照直接回滚到上一个检查点比重跑一遍快得多。我的做法是在每个子任务开始前打一个快照子任务失败就回滚成功就保留。这样即使某个子任务搞砸了也不会污染前面的成果。快照的粒度要控制好。太细快照开销大太粗回滚损失大。我按子任务边界打快照一个子任务通常几步到十几步这个粒度实测最舒服。回滚时我只回滚文件系统不回滚上下文——上下文里保留“这次尝试失败了”的记录让模型知道别再试。5.4 沙箱与循环的接口设计沙箱和循环之间的接口我坚持用结构化结果而不是裸的 stdout。每次执行返回一个对象包含退出码、标准输出、标准错误、耗时、资源占用、是否超时。循环拿到这个对象再决定下一步。为什么不用裸 stdout因为裸文本没法可靠解析。我早期让循环去 grep stdout 里的关键字判断成功失败结果被各种格式变化搞崩。结构化结果让判断逻辑稳定也让验证模块有干净的输入。这个接口设计看起来是小事但它决定了整个 Harness 的可维护性。6. 验证机制怎么知道 Agent 干对了6.1 验证的三个层次动作、子任务、整体验证不是一步是三层。动作级验证看单次工具调用是否成功退出码、返回格式子任务级验证看一组动作是否达成子目标比如“修复了这个函数”整体级验证看整个任务是否完成比如“构建通过且测试全绿”。三层缺一不可。我早期只做动作级验证结果 Agent 每一步都“成功”但整体任务失败——因为它做的每一步都对方向却错了。加上子任务级和整体级验证后这种“局部正确、全局错误”的情况大幅减少。验证层次的设计本质是给 Agent 提供不同粒度的反馈信号。6.2 用测试作为验证最可靠但也最贵如果任务有现成的测试那测试就是最好的验证。跑一遍测试通过就是通过不通过就是不通过没有歧义。但测试的问题是贵——跑一次可能几十秒到几分钟Agent 如果每步都跑测试时间成本爆炸。我的折中方案是子任务级用轻量验证整体级用测试。子任务级用静态检查、语法检查、快速单元测试整体级才跑完整测试套件。这样既保证了反馈及时又保证了最终质量。实测下来这个分层让总耗时降了一半以上质量没降。6.3 没有测试怎么办启发式验证的设计很多任务没有现成测试比如写文档、改配置。这时候只能靠启发式验证。我常用的几种格式校验JSON 能不能解析、YAML 合不合法、引用完整性引用的文件存不存在、链接通不通、一致性检查改动前后有没有矛盾、模型自评让另一个模型判断结果是否合理。模型自评要慎用因为它容易“自我感觉良好”。我的做法是让自评模型只看结果不看过程并且给它明确的评判标准而不是笼统地问“好不好”。标准越具体自评越可靠。比如“这个配置文件的字段是否都符合给定的 schema”比“这个配置写得好不好”有用得多。6.4 验证失败后的反馈怎么给模型验证失败后反馈的质量决定了 Agent 能不能自我修正。我踩过的坑是只告诉模型“失败了”不告诉它为什么失败。结果模型瞎猜越改越错。后来我要求验证模块输出结构化的失败原因哪一层失败、失败的具体位置、期望值 vs 实际值。比如不是“测试失败”而是“子任务 3 的单元测试失败函数 X 的返回值期望 5 实际 3”。这种反馈模型一看就知道往哪改。反馈的粒度越细修正的成功率越高。这是验证模块和上下文模块的接口也是整个 Harness 里最影响 Agent 自我修正能力的一环。7. 长时运行让 Agent 撑过一场马拉松7.1 长时运行的真实挑战不是慢是断短任务跑几分钟长任务可能跑几小时甚至跨天。长时运行最大的挑战不是性能是中断。网络抖一下、进程被重启、预算临时超限任何一个小意外都可能让几小时的工作白费。我早期没做持久化一次任务跑到第 80 步进程崩了全部重来那种感觉不想再体验第二次。长时运行的核心是状态持久化 断点恢复。每一步的状态都要落盘恢复时能从最近的检查点继续。这不是可选项是长任务的必需品。我现在要求所有可能跑超过 10 分钟的任务都必须支持断点恢复。7.2 检查点设计存什么、多久存一次检查点存三样东西上下文状态三层结构、沙箱快照引用、循环状态当前状态机的状态、步数、预算消耗。这三样齐了就能完整恢复。存多久一次我的经验是按步存但异步。每步结束后触发一次异步落盘不阻塞主循环。这样既保证恢复点足够新又不拖慢执行。同步落盘我试过每步多几百毫秒几十步下来就是十几秒的额外开销不划算。提示检查点文件要带版本号。我有一次改了上下文结构结果旧检查点恢复不了只能从头跑。加了版本号后至少能检测到不兼容并给出明确提示。7.3 资源回收与预算控制长时运行最容易失控的是资源。token 越用越多、沙箱越开越多、临时文件越堆越大。我现在的做法是每个检查点做一次资源审计统计当前 token 消耗、活跃沙箱数、磁盘占用超过阈值就触发清理或告警。预算控制我分两级软预算触发告警和降级比如减少验证频率硬预算直接终止任务并保存状态。软硬结合既不会因为一点超支就停也不会无限烧下去。这个设计让我在长任务里能睡个安稳觉不用担心一觉醒来账单爆炸。7.4 长时运行的可观测性日志、指标、追踪长任务出问题时没有可观测性就是抓瞎。我要求三样东西结构化日志每步一条带步数、状态、耗时、结果摘要、关键指标步数、token 消耗、成功率、重试次数、追踪 ID贯穿整个任务方便串联。日志我坚持结构化不用纯文本。纯文本日志在长任务里根本没法查结构化日志可以直接过滤、聚合、告警。指标我接了一个简单的时序存储能看到任务随时间的健康度。追踪 ID 让我能把一次任务的所有日志串起来看定位问题快很多。8. 常见问题与排查技巧实录8.1 循环卡死三种典型表现和排查路径卡死是最高频的问题我总结成三种表现表现可能原因排查方法解决反复读同一文件无进展检测缺失看动作指纹是否重复加无进展检测步数暴涨但无输出上下文爆了模型乱答看上下文占用比例加压缩触发停在某状态不动状态机转移条件缺失打印当前状态补转移条件排查顺序我固定为先看状态机当前状态再看上下文占用最后看最近几步的动作指纹。这个顺序能覆盖八成卡死情况。剩下两成通常是模型本身的问题换模型或调提示词。8.2 上下文爆窗口预防比补救重要上下文爆窗口的补救很麻烦因为一旦爆了模型已经开始乱答你得回滚重来。所以重点是预防。我的预防措施有三条压缩阈值设 70%、每步检查占用、子任务边界强制压缩。这三条下来我最近半年没再遇到爆窗口。如果真的爆了补救办法是回滚到上一个检查点手动触发一次压缩再继续。不要试图在爆了的上下文上继续跑模型的状态已经不可信了。8.3 沙箱污染为什么你的结果不可复现沙箱污染的表现是同一个任务跑两次结果不一样。原因通常是沙箱没清理干净或者任务之间共享了状态。我的排查方法是跑两次对比沙箱的文件系统差异。有差异就是污染。解决很简单每次任务开始前强制清理沙箱任务结束后销毁。如果任务需要保留状态用显式的持久化卷而不是让沙箱自己留着。我见过有人为了“省启动时间”复用沙箱结果调试了一整天最后发现是上一个任务的残留文件在捣乱。8.4 验证误判假阳性和假阴性验证误判有两种假阳性明明错了说对了和假阴性明明对了说错了。假阳性更危险因为它让错误溜过去。假阴性更烦人因为它让 Agent 反复重试正确的东西。假阳性通常来自验证太宽松比如只检查退出码不检查输出。解决是加严验证多层校验。假阴性通常来自验证太严格或环境问题比如测试依赖了不稳定的外部服务。解决是隔离验证环境去掉不稳定依赖。我现在的原则是宁可假阴性多一点也不要假阳性因为假阴性最多浪费点时间假阳性会交付错误结果。8.5 长任务恢复失败检查点不兼容的坑恢复失败最常见的原因是检查点不兼容——代码改了旧检查点读不了。我的解决办法是检查点带 schema 版本恢复时先校验版本不匹配就明确报错而不是静默失败。静默失败最坑你以为恢复了其实状态是错的跑出来的结果全是垃圾。另一个坑是检查点存了但没存全恢复时缺东西。我的做法是恢复后做一次完整性校验上下文三层是否齐全、沙箱快照是否可访问、循环状态是否合法。校验不过就不恢复从头跑至少结果可信。9. 我在实际项目里的一些体会这套 Harness 工程我迭代了大概大半年从最开始一个两百行的裸循环到现在五个模块分工明确。最大的体会是Agent 的能力上限由模型决定但能力下限由 Harness 决定。模型再强Harness 不行任务照样崩模型一般Harness 扎实任务反而能稳定完成。另一个体会是别追求一步到位。我一开始想设计一个完美的 Harness结果卡在设计阶段很久。后来改成先用最笨的版本跑起来遇到问题再加模块反而进展快。上下文管理是第三个版本才成型的验证机制是第四个版本长时运行是最后加的。每个模块都是被真实问题逼出来的不是设计出来的。最后分享一个小技巧给 Harness 本身写测试。循环的终止条件、上下文的压缩逻辑、沙箱的清理、验证的判定这些都可以单元测试。我一开始觉得 Harness 是“胶水代码”不用测结果每次改都提心吊胆。后来补了测试改起来放心多了。Harness 是 Agent 的地基地基值得测。