编程Agent在最近一年里已经从一个演示性质的新鲜事物变成了不少团队真正用来写脚本、修Bug、做重构的生产力工具。但实际用下来你会发现真正决定项目效率的往往不是模型本身有多强而是那些看起来很小的“修复动作”上下文被冲掉了怎么拉回来、依赖装错了怎么排查、日志看不到怎么办、批量任务跑到一半崩了怎么续。尤其是Ubuntu这类Linux开发环境里跑Agent编程的人越来越多环境、权限、路径、缓存这些细节会被成倍放大。这篇文章我直接整理11个我实测下来“投入很小但回报很高”的编程Agent修复技巧。它们不需要高端显卡不需要改一堆框架代码大多数只是调整提示词、检查环境、规范日志、做好回滚。适合已经上手Agent、但在真实项目里经常被小问题打断的人。我的核心判断是与其不断换更强的新工具不如先把你手头这套流程里最容易出问题的几个节点修好。1. 先把修复思维摆正Agent的问题往往藏在上下文和运行链路里很多人在使用编程Agent遇到问题时第一反应是“这个工具不行”或者“模型理解力不够”。但我排查过多次后发现真正导致失败的高频原因集中在三个地方需求边界不清、上下文太长被截断、运行环境不可见。这三类问题都不是模型能力问题而是使用方式问题。1.1 技巧1给Agent明确改动边界别让它自由发挥最典型的现象是你只想让Agent修一个函数的返回逻辑结果它顺手把整个模块的命名风格改了一遍还“贴心”地重构了另一个文件的公共方法。代码看起来更整洁了但评审成本也上来了甚至可能引入隐藏回归。修复方法很简单在每一轮Agent开始工作前用一两句话限定改动边界。我会在提示词里固定写清楚三个信息本次允许改动的文件、需要修改的关键函数、严禁触碰的范围。例如本次任务只允许修改 src/task_runner.py 中的 run() 和 retry() 函数。 不要修改其它文件。 如果发现需要改动其它文件先停下来说明原因等待确认。这个小改动为什么回报高因为Agent一旦明确知道“不能动什么”它的搜索范围、重构倾向都会收敛很多。省掉的不只是审查时间还有可能引入的新Bug。尤其是项目里有公共工具类、配置文件、数据库迁移脚本这类“碰一下就可能出大事”的模块边界约束几乎是必须的。1.2 技巧2第一次永远只建立基线不要直接要求最终效果很多人用Agent最大的误区是一上来就把最复杂的最终目标丢给它“把这个项目重构完并且保持所有接口兼容”。结果Agent跑了大半天报错一堆输出还和预期完全不一致。我的做法是第一轮永远只要求建立基线。所谓基线就是让Agent先把项目跑起来、执行现有测试、生成一个最简单的可用输出。比如你最终想做一个批量PDF转Markdown工具第一轮只让Agent读取一个PDF文件输出纯文本并打印成功日志第二轮再让它处理格式第三轮才加入批量。这样做有两个原因。第一基线能给你一个可对照的正确输出。后面Agent改坏了你能快速回退到基线状态而不是从头排查“到底是哪一步错了”。第二Agent修复代码时需要参照物。没有基线时它面对一堆报错只能靠猜有基线后它至少知道“之前这个逻辑是能跑的”。1.3 技巧3上下文被冲掉时重建最小上下文而不是重贴全部对话长会话里最常见的问题是Agent做到第10步时已经忘了第2步约定好的变量名或者忘了一个关键报错信息。尤其是在Ubuntu终端环境下命令输出、日志、文件列表会占用大量上下文窗口早期信息很容易被截断或压缩。遇到这种情况不要直接重贴全部历史对话。那样既浪费上下文又会把当前Agent的注意力搅乱。我一般会维护一个“会话摘要”文件每完成一个重要步骤就把当前状态写进去内容包含上次的结论、关键文件路径、当前待解决的问题、下一步目标。当Agent出现“记忆丢失”时只需要把摘要文件内容发过去再补一句“根据这份摘要继续”。这比滚动翻聊天记录高效得多也能避免Agent被早期无关输出带偏。提示在Linux环境里跑Agent时终端输出默认会占掉大量上下文。建议所有命令都加上“只输出错误和关键结果”的过滤别让Agent读几百行无关日志。2. 修复需求输入让Agent明确边界、基线和验收标准很多时候Agent不是能力不行而是它根本不知道“完成”的标准是什么。你问它“改好没有”它说“改好了”结果你一跑还是报错。原因往往是需求里只有“做什么”没有“做到什么程度算完成”。2.1 技巧4写清楚验收条件让Agent知道修好的标准我现在的做法是凡是让Agent修一个问题必须附带验收条件。验收条件不需要多复杂通常是几条“可执行、可检查”的结果完成标准 - python src/parse.py sample.pdf 能正常执行退出码为0。 - 生成文件 output/result.md 存在且大小大于0。 - 日志中不包含 ERROR 或 Traceback。 - 原始PDF页面数量保持不变。这样Agent在结束前会主动执行验证命令而不是凭感觉说“应该没问题”。对你自己来说验收也变得更机械、更可靠不是靠肉眼读代码而是靠命令输出判断。这里有一个细节验收条件要写成Agent能自己检查的形式不要写“结果正确”“质量好”“不能有Bug”这类模糊词汇。Agent无法判断“质量好”但它能判断“文件是否存在”“退出码是否为0”“测试是否通过”。2.2 技巧5让Agent把验证动作写进执行计划而不是口头保证只写验收条件还不够还要要求Agent把验证动作写进它的执行计划里。我见过很多次这种情况Agent给了代码说“可以跑”但我执行时发现连依赖都没装完。修复办法是要求Agent在最终交付时附带“验证输出”它必须实际运行过一次验证命令并把输出粘贴到结果里。比如验证方式 - 运行 pytest tests/test_parser.py -q - 运行 python scripts/generate_report.py --input sample.txt - 贴出最后一行输出作为证据判断标准很简单有验证输出才接受没有验证输出一律按“未完成”处理。这个规则会逼着Agent把任务闭环而不是交半成品。对于团队协作场景这也是一条很好用的纪律Agent提交的结果必须有日志、有输出文件、有可复现命令。2.3 为什么上游修复回报最高在需求输入阶段修改提示词看起来只是“多写两句话”但实际上影响的是后面所有轮次。每多跑一轮Agent成本就增加一轮而且越到后面上下文越混乱纠正方向的成本越高。这跟写程序里的“fail fast”是一样的道理在入口处拦截问题永远比在末端修补便宜。3. 修复环境与依赖把看不见的状态变成可检查的命令Agent编程和写文章不一样。文章写错了可以删掉重写代码跑不起来却往往卡在最底层的环境问题上。我遇到过很多次Agent给出的修复方案本身没问题但它的假设是错的它假设Python版本是3.10实际上机器上是3.8它假设依赖已经装好实际上虚拟环境都没激活它假设有GPU可用实际上驱动没装对。这类问题的可怕之处在于你看日志时看到的错误五花八门但根源往往只有一个环境状态和Agent预期不一致。3.1 技巧6把环境检查写成每个修复任务的起始步骤我要求Agent在修复任何问题之前必须先执行一组环境检查命令然后把结果贴出来充当“现场证据”。这组命令在Ubuntu下通常长这样node -v python --version pip --version nvcc --version echo $NODE_ENV echo $PYTHONPATH which python ulimit -n df -h /tmp不用所有命令都跑根据项目选重点。关键是让Agent基于真实环境做判断而不是默认“大家环境都一样”。这一步能避免大量无效修改。比如如果Agent看到python3是3.8而你项目里代码用的是3.10的新语法那它就不会浪费时间去改代码逻辑而是先提示你升级Python或切换虚拟环境。这会直接把问题的定位层级提高一整层。3.2 技巧7路径、权限和缓存是Ubuntu下最容易被忽略的故障源三个我经常遇到的高频故障源值得单独拿出来说。第一个是路径不一致。Agent可能在某个工作目录下创建了输出文件但它返回的路径是相对路径。任务结束后终端当前目录变了文件就找不到了。修复方法是让Agent每次输出结果时都附带pwd和ls -l 输出路径确保它说的路径真实存在。第二个是权限问题。Ubuntu下跑Agent时如果服务是用systemd或nginx跑的工作目录可能属于rootAgent进程没有写权限。常见表现是“任务没报错但输出目录是空的”。排查方式很简单id查看当前用户ls -l查看目录权限确认写入权限。第三个是缓存问题。包管理器缓存、模型缓存、临时目录缓存都可能导致Agent“看起来改了代码但运行的还是旧文件”。尤其是Python的__pycache__和npm的node_modules/.cache经常让人摸不着头脑。遇到诡异问题先让Agent清理缓存再重跑find . -name __pycache__ -type d -exec rm -rf {} 2/dev/null npm cache clean --force3.3 技巧8依赖问题用可重复执行的片段代替解释依赖冲突是Agent编程里最耗时间的一类问题。Agent为了修一个依赖可能会建议重装整个环境甚至执行sudo apt remove这种危险命令。我一般不允许Agent直接动系统级依赖而是要求它把依赖修复动作写成可重复执行的脚本。比如Agent发现项目依赖有冲突它应该做的不是手动改几个包的版本而是产出一份可复现的安装流程python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt pip freeze requirements.lock这个脚本的好处是第一任何一台Ubuntu机器都能按这个流程复现第二出问题时可以删掉虚拟环境重建不会留下不可控系统改动。判断标准也很简单Agent给出的每一步都必须能重复执行不能是“手动调一下试试”。4. 修复运行与日志保证出问题时你确实能看到问题Agent编程最让人崩溃的时刻不是它报错而是它报完错后你根本看不到完整的错误信息。终端一滚动日志就没了SSH断一下整个任务一起没了输出目录一堆文件也不知道哪个是最新结果。运行链路不修复Agent越能干你越难运维。4.1 技巧9强制日志落盘并把输出目录固定我要求所有Agent运行的命令都要带日志落盘并把日志放到固定目录。最简单的模板是这样mkdir -p logs python src/run_task.py logs/task_$(date %Y%m%d_%H%M%S).log 21这样做有两个好处第一Agent在后续轮次里可以直接读取日志文件来定位问题不用依赖它自己的“记忆”第二即使终端会话断开日志也还在服务器上你可以重新连上后继续排查而不是从头跑一遍。固定输出目录也很重要。我会在项目里规划好logs/、output/、tmp/三个目录并明确告诉Agent中间文件放tmp最终产物放output运行日志放logs。这会避免大量“文件到底写到哪了”的无效沟通。4.2 技巧10卡住时先看资源占用再改参数Agent任务卡住时很多人第一反应是加超时时间或者怀疑代码里死循环。但我实测下来最常见的卡住原因是资源耗尽。在Ubuntu下优先看这几个指标free -h df -h nvidia-smi top -o %CPU如果内存接近满可能是并发太高如果显存满可能是批次太大或模型太大如果磁盘满可能是日志或输出文件写爆了。先确认资源再决定改哪个参数。还有一点如果用SSH跑Agent编程最好给任务加上进程托管否则断连可能导致任务挂掉。我常用的方案是tmux或nohuptmux new -s agent-task python src/run_task.py这样即使本地电脑休眠服务器上的任务也不会中断。4.3 常见运行故障排查顺序遇到Agent运行异常我一般按固定顺序排查不跳步骤现象优先排查常用命令启动即报错Python/Node版本、入口文件路径node -v、python --version、ls -l src/main.py运行中卡死内存、磁盘、并发top -o %CPU、free -h、df -h输出为空输出目录、权限、输入文件路径pwd、ls -l output/、id输出不一致缓存、进程残留、依赖版本ps aux、find . -name __pycache__速度异常慢并发参数、GPU占用、网络等待nvidia-smi、iotop、lsof这套排查顺序的核心是先看现象再看输入再看资源最后才改代码逻辑。很多时候问题不在Agent写的代码里而在它运行的环境里。5. 修复批量任务单条能跑不等于全部能跑如果你的Agent只需要处理单个文件那很多问题不会暴露。但一旦进入批量化场景——批量转换PDF、批量处理图片、批量测试接口——新问题就会出现跑完第5个崩了、输出文件被覆盖、失败任务无法单独重试。5.1 技巧11批量任务要做错误隔离和失败记录我建议所有批量任务都按“逐条执行、记录结果、跳过失败、最后汇总”的方式设计。不管Agent是用Python还是Shell都应该做到单条任务失败时不能中断整批任务失败项必须被记录下来便于单独重跑。一个典型的Python批处理模板长这样import os import traceback inputs [a.pdf, b.pdf, c.pdf] success [] failed [] for item in inputs: try: print(f正在处理: {item}) # agent 在这里执行具体处理逻辑 process(item) success.append(item) except Exception as e: failed.append((item, str(e))) traceback.print_exc() continue with open(result_success.txt, w) as f: f.write(\n.join(success)) with open(result_failed.txt, w) as f: for item, err in failed: f.write(f{item}\t{err}\n) print(f成功 {len(success)} 条失败 {len(failed)} 条)判断标准很简单一批跑了100个文件即使20个失败也要把这20个失败原因单独列出而不是整个进程崩溃退出。之后再让Agent按失败列表单独重试效率会高很多。5.2 并发参数从1开始缓慢上调批量任务最容易踩的坑是一上来就搞高并发。Agent自己写代码时也有这个倾向看到多个独立文件就会想用ThreadPoolExecutor(max_workers10)。但在实际环境里高并发很可能瞬间打爆CPU或显存运行速度反而下降甚至把机器搞到无响应。我建议第一次跑批量任务时强制并发等于1。先记下三个数据单条任务耗时、内存峰值、输出是否正确。然后逐步提高并发每次加2到5观察资源占用是否在安全范围内。尤其是跑AI模型生成类任务时显存往往是第一瓶颈。并发数不是越高越好而是“显存够用的前提下尽可能高”。如果单次推理需要2GB显存你在一块8GB显卡上跑并发4加固态损耗可能就会崩。5.3 输出命名和断点续跑批量任务还有两个容易忽视的细节输出命名和断点续跑。如果10个文件都输出到同一个名字那最后只剩下最后一个文件的结果如果任务跑到一半中断重启后又要从头跑一遍。修复方式也很简单输出文件命名带输入文件名或序号output/result_001.md、output/result_002.md。给每个文件增加“已处理”标记下次运行时跳过已完成项。如果使用Redis或SQLite记录任务状态效果更好但不算必需。批量任务真正要做的不是“把Agent写得更聪明”而是把“任务队列、失败记录、输出一致性、断点续跑”这四件事做扎实。这四件事做好后Agent在批量场景里的稳定性会提升一个量级。注意如果你的Agent任务跑一次就要几分钟甚至几十分钟强烈建议先跑3条小样本确认输出格式、日志位置和错误重试逻辑都正常再开全量。不要抱着“先跑着看看”的心态启动长任务。6. 建立回滚与检查点避免Agent把工程越改越乱没有回滚机制的Agent编程就像在没有备份的情况下做数据库迁移哪一步都可能出错但你没有退路。我见过最惨的一次Agent修一个格式化问题时自动改动了一个配置文件里的默认端口然后整个服务起不来了。6.1 回滚链每次Agent动手前先留检查点我现在的习惯是无论让Agent改什么动手之前先建立检查点。最简单的方式是用Git哪怕项目本身没用Git也会临时git init一下。git add -A git commit -m before agent fix: $(date %Y%m%d_%H%M%S)如果Agent改坏了直接回滚git checkout -- .如果只是某个文件坏了可以只恢复那个文件git checkout -- src/config.py这个技巧看起来很基础但价值极高。有了回滚点你就敢让Agent大胆试没有回滚点你每让Agent动一次代码都提心吊胆一旦出错定位成本会非常高。6.2 检查点与任务拆解长任务要分成多个可验证阶段除了事前备份长任务也要拆阶段。我的做法是把一个大任务拆成多个有独立输出文件的阶段每个阶段结束后检查一次结果。比如准备数据把原始数据整理成中间格式输出data/prepared.json。执行转换读取中间格式生成报告输出output/report.md。验证结果检查输出文件是否完整生成校验日志。这样做的原因是Agent在长任务里越往后越容易偏离最初目标。每阶段都有输出文件至少你可以知道“它到底卡在哪一步”。单独重跑某一步也比整个任务推倒重来便宜得多。6.3 跑一个长期项目时我建议先固定这三件事如果你正在用Agent做一个超过一周的长期项目我建议先把三件事固定下来每轮Agent操作前建立Git检查点所有日志和输出目录固定每个任务都写验收条件。这三个习惯一旦养成大部分“Agent改出一个无法收拾的烂摊子”的问题都能被提前拦截。编程Agent确实能提高效率但它不是一颗万能药。它更像一个手脚很快、判断力有限的实习生只要需求清晰、环境稳定、有回滚保障它能干得不错一旦处于混乱状态它就会把混乱放大。这11个技巧的核心都指向同一个方向把不可控的部分拆成可控的小块。先让单条任务稳定跑通把环境、日志、回滚这三件基础设施打好再去考虑批量、并发和自动化调度。你会发现很多看起来很大的问题其实根本轮不到换工具来解决。