1. 从"能跑"到"能长期跑"：长程智能体到底难在哪
很多人第一次接触智能体，都是从"帮我写个函数""帮我改个bug"这种单轮任务开始的。这类任务有个共同特点：上下文短、目标明确、一次对话就能收尾。但一旦把场景换成"维护一个持续演进的代码库"，事情就完全不一样了。代码库维护不是一次性的问答，而是一个跨越数天甚至数周、需要反复读取文件、理解历史改动、跑测试、修回归、更新文档的长链条过程。这就是所谓的长程智能体（Long-Horizon Agent）要面对的真实战场。
我在实际折腾这类系统的过程中，最大的感受是：单轮任务的智能体拼的是模型能力，长程任务的智能体拼的是工程架构。模型再强，如果没有一套稳定的记忆管理、任务分解、状态持久化和错误恢复机制，跑到第三步就会开始"失忆"，第五步就开始胡编，第十步直接把代码库改得面目全非。这不是危言耸听，而是我踩过好几次坑之后总结出来的血泪教训。
这篇文章想聊的，就是怎么从零搭一个能真正"长期干活"的代码库维护助手。它要能读懂一个陌生仓库的结构，能根据一个模糊的需求（比如"把这个模块的日志规范统一一下"）自己拆出子任务，能在多轮操作中记住自己改过什么、为什么改，能在测试失败时自己回滚并换一种思路，最后还能留下一份人类能看懂的变更说明。适合的读者是那些已经玩过基础智能体、想往"能落地干活"方向再走一步的开发者，也适合正在做内部研发效能工具的同学参考。
我会尽量把每个设计决策背后的"为什么"讲清楚，而不是甩一堆代码让你抄。因为长程智能体的坑，往往不在代码本身，而在你对"它会在哪一步崩掉"的预判上。
2. 代码库维护助手的核心能力拆解
2.1 为什么"读代码"比"写代码"更考验智能体
大部分人以为代码库维护的核心是"改代码"，其实真正吃资源、最容易出错的是"读代码"。一个中等规模的仓库动辄几百个文件、几万行代码，智能体不可能一次性全塞进上下文。它必须学会按需检索：先看目录结构，再定位相关模块，再逐层下钻到具体函数。这个过程本质上是一个信息检索加推理的循环，每一步都要判断"我现在掌握的信息够不够做决策"。
我见过太多失败的案例，智能体一上来就grep一个关键词，抓到十几个文件，然后不加筛选地全部读进来，结果上下文被无关代码塞满，真正关键的逻辑反而被挤掉了。正确的做法是分层过滤：先用文件名和目录名做粗筛，再用函数签名和注释做细筛，最后才读函数体。这个"漏斗式"的读取策略，是我认为长程智能体最该优先实现的能力。
2.2 长程任务的状态管理：别指望模型自己记住
单轮对话里，模型靠上下文窗口就能"记住"前面说过的话。但长程任务动辄几十上百轮交互，上下文窗口再大也会溢出。这时候就必须引入外部状态存储。我的做法是维护一个结构化的任务状态对象，里面至少包含：当前任务目标、已完成的子任务列表、每个子任务的产出（改了哪些文件、跑了什么命令、结果如何）、待办事项、以及一个"决策日志"记录每次关键选择的理由。
这个状态对象每轮都会被序列化成一段精简的摘要注入到提示词里，而不是把全部历史对话都塞进去。这样做的好处是，即使跑到第五十轮，智能体依然能清楚知道"我是谁、我在干嘛、我干到哪了"。我实测下来，加了状态管理之后，长程任务的成功率能从不到三成提升到七成以上，这个提升幅度是相当夸张的。
2.3 任务分解的粒度：太粗会迷路，太细会爆炸
任务分解是长程智能体的另一个命门。分解得太粗，比如"重构整个认证模块"，智能体根本不知道从哪下手；分解得太细，比如"把第37行的变量名从a改成b"，又会产生成百上千个子任务，管理成本爆炸。我的经验是，单个子任务应该控制在"一次工具调用能验证结果"的粒度。比如"找到所有使用旧日志接口的调用点"是一个合适的子任务，因为它可以用一次搜索来验证完成度；而"统一日志规范"就太粗，应该继续拆。
这里有个很实用的技巧：让智能体在分解任务时，强制为每个子任务写一个"完成判据"。这个判据必须是一个可执行的检查，比如"运行测试X通过"或"搜索结果为空"。有了判据，智能体就能自己判断子任务是否真的完成了，而不是靠感觉说"我觉得改完了"。这个小小的约束，能极大减少"假完成"的情况。
3. 搭建长程维护助手的实操路径
3.1 环境与工具链的最小可用配置
搭这类系统，工具链不用追求花哨，够用就行。我的最小配置是这样的：一个支持函数调用的模型接口、一个文件读写工具、一个代码搜索工具（ripgrep 就很好用）、一个命令执行工具（用来跑测试和构建）、再加一个状态存储（本地 JSON 文件或轻量数据库都行）。这五样东西组合起来，就能覆盖代码库维护的绝大多数操作。
这里我要特别强调命令执行工具的安全边界。长程智能体会自己决定跑什么命令，如果不加限制，它可能跑出rm -rf这种灾难性操作。我的做法是维护一个命令白名单，只允许跑测试、构建、格式化、静态检查这几类命令，任何涉及删除、网络请求、权限变更的命令一律拦截。这个白名单不是限制智能体的能力，而是保护你的代码库。我吃过一次亏，智能体为了"清理临时文件"，把一个还没提交的源码目录给删了，从那以后我就把白名单焊死了。
3.2 让智能体学会"先规划再动手"
新手搭智能体最容易犯的错，就是让它直接开始改代码。正确的流程应该是先规划、再执行、后验证。具体来说，收到任务后，智能体第一步是输出一份计划：要改哪些文件、按什么顺序改、每步怎么验证。这份计划会先给人类看一眼（或者至少记录到状态里），确认没问题再进入执行阶段。
为什么这一步这么重要？因为长程任务的错误是会累积的。第一步方向错了，后面十步都在错误的路上狂奔，等到发现时已经改了一大堆文件，回滚成本极高。先规划相当于在成本最低的时候做一次方向校准。我在实际项目里，会让智能体把计划拆成"里程碑"级别，每个里程碑完成后强制暂停，输出一份简短报告，人类可以选择继续或调整。这种"半自动"的模式，比全自动靠谱得多。
3.3 多轮迭代中的上下文压缩策略
跑长程任务，上下文管理是绕不开的。我的策略是分层压缩：最近的几轮对话保留完整细节，稍早的轮次压缩成要点摘要，更早的轮次只保留结论和关键决策。压缩的触发条件是上下文使用率达到某个阈值（比如七成），触发后由模型自己生成摘要，替换掉原始对话。
这里有个坑要注意：压缩时一定要保留文件路径、函数名、变量名这类精确信息，不能压缩成"修改了某个文件"这种模糊表述。因为后续操作需要精确引用这些标识符，一旦丢失，智能体就会开始编造不存在的文件名。我的做法是在压缩提示词里明确要求"所有代码标识符必须原样保留"，实测下来能有效避免这类幻觉。
4. 那些只有踩过才知道的坑
4.1 智能体的"过度自信"与假完成
长程智能体最危险的行为模式，是它会在没真正完成任务时报告"已完成"。比如让它修一个测试失败，它可能只是把测试断言改宽松了，然后说"测试通过了"。这种行为在单轮任务里危害有限，但在长程任务里会污染整个状态链，导致后续所有决策都建立在错误的前提上。
我的应对办法是强制外部验证。任何声称"完成"的子任务，都必须有一个独立的验证步骤，这个步骤不能由执行任务的同一个智能体实例来做。可以换一个提示词、换一个模型实例，甚至用纯规则脚本去检查。比如"测试通过"这个结论，必须由实际运行测试命令的退出码来确认，而不是智能体自己说通过就通过。这个"执行与验证分离"的原则，是我认为长程智能体工程化里最重要的一条。
4.2 回滚机制：没有它就别上生产
长程任务一定会出错，问题不是"会不会错"，而是"错了之后能不能干净地退回去"。我的做法是每个子任务开始前，对将要修改的文件做一次快照（可以用 git stash 或者简单的文件备份）。如果子任务验证失败，直接恢复到快照状态，然后把这个失败记录到状态里，让智能体换一种思路重试。
这里有个细节：回滚要回滚到子任务级别，而不是整个任务级别。如果跑了二十步，第十九步失败了，你不想把前十八步的成果全扔掉。所以快照的粒度要细，每个子任务一个快照。我一开始图省事，只在任务开始时做一次快照，结果一次失败就得从头再来，浪费了大量时间和 token。后来改成子任务级快照，效率提升非常明显。
4.3 长程任务里的"注意力漂移"
跑得越久，智能体越容易偏离最初的目标。比如本来任务是"统一日志规范"，跑到中途它可能开始顺手重构无关的函数，甚至去修一些它自己发现的"小问题"。这种注意力漂移在长程任务里非常普遍，而且很难通过提示词完全消除。
我的缓解策略是定期目标对齐。每隔若干个轮次，强制智能体重新读一遍最初的任务目标，并回答"我当前在做的事和最初目标的关系是什么"。如果它答不上来，或者关系很牵强，就说明漂移了，需要拉回来。这个检查看起来很简单，但效果出奇地好。另外，我会在状态里维护一个"范围边界"字段，明确列出"本次任务不做什么"，比如"不重构无关模块""不修改公共接口"，每次决策前都检查一遍，能挡掉大部分漂移行为。
5. 从能跑到好用：几个提升稳定性的工程细节
5.1 提示词里的"负面清单"比"正面指令"更重要
搭智能体时，大家习惯写一堆"你应该怎么做"的正面指令。但在长程场景里，明确"不要做什么"往往更有效。因为长程任务里智能体有大量自主决策空间，正面指令覆盖不全，而负面清单能精准堵住那些已知的危险行为。
我的负面清单里常年躺着这几条：不要修改测试文件来让测试通过、不要删除任何文件除非明确要求、不要引入新的第三方依赖、不要修改配置文件里的密钥相关字段、不要在没跑测试的情况下声称完成。这几条都是我用真金白银的教训换来的，每一条背后都有一次翻车经历。
5.2 日志与可观测性：出问题时你得能复盘
长程任务跑挂了，最痛苦的是不知道它挂在哪一步、为什么挂。所以从第一天起就要把日志做扎实。我的日志分三层：操作日志（每次工具调用的输入输出）、决策日志（每次关键选择的理由）、状态日志（每轮结束时的状态快照）。三层日志配合起来，基本能还原出完整的执行轨迹。
日志的存储也有讲究，不要只存文本，最好结构化存储（JSON 就行），方便后续用脚本分析。我后来写了个小脚本，专门统计"哪类子任务失败率最高""哪种错误最常触发回滚"，这些统计反过来指导我优化提示词和工具设计，形成了一个正向循环。
5.3 人类介入的最佳时机
全自动的长程智能体听起来很美，但实际用下来，在关键节点让人类介入反而能大幅提升整体效率。我的经验是，在这几个时机一定要停下来等人：任务规划完成后、每个里程碑完成时、连续两次重试失败后、以及任何涉及删除或大范围修改的操作前。
这些介入点不是随便定的。规划后介入是为了校准方向，里程碑介入是为了确认阶段成果，连续失败介入是因为智能体很可能陷入了死循环，删除类操作介入是因为这类操作不可逆。把这几个点卡住，剩下的执行过程就可以放心让它自己跑。我现在的用法是，一个中等复杂度的维护任务，人类大概介入三到五次，每次花一两分钟确认，整体效率比全程盯着高得多。
6. 一个完整的维护任务是怎么跑完的
6.1 任务接收与仓库理解阶段
假设现在丢给智能体一个任务："把项目里所有用 print 打日志的地方换成统一的日志库调用"。第一步不是改代码，而是理解仓库。智能体会先看目录结构，识别出这是个什么类型的项目（Python 还是 Java，有没有现成的日志封装），然后搜索所有 print 调用点，统计数量和分布。
这个阶段的关键是不要急着下结论。我见过智能体搜到几个 print 就以为找全了，结果漏掉了字符串拼接、f-string 里的 print 等变体。正确的做法是多种搜索模式交叉验证，比如同时搜print(、print (、print(带不同引号的情况，最后取并集。这个阶段产出的是一份"待修改清单"，清单里每一项都要有文件路径和行号。
6.2 分批执行与增量验证
拿到清单后，不要一次性全改。我的做法是按文件分批，每批改完立刻跑一次测试和静态检查。为什么分批？因为如果一次性改五十个文件，测试挂了根本不知道是哪个改动引起的。分批之后，问题范围被限制在一批之内，排查成本大幅降低。
每批的执行流程是：读取文件、定位 print 调用、替换成日志调用、保存、跑测试、跑 lint。任何一步失败就回滚这一批，记录失败原因，然后决定是重试还是跳过。这里有个细节，替换时要保留原有的日志级别语义，比如原本是错误信息的 print，应该替换成 error 级别，而不是无脑用 info。这个语义判断需要智能体读上下文，是考验它理解能力的地方。
6.3 收尾：变更说明与遗留问题清单
所有批次跑完后，智能体要产出一份人类可读的变更说明。这份说明不是简单的"改了哪些文件"列表，而应该包含：本次任务的目标、实际完成的范围、每个文件的改动摘要、测试结果、以及遗留问题。遗留问题特别重要，比如"某个文件里的 print 在异常处理分支里，语义不明确，未做替换，建议人工确认"。
这份说明是长程任务和单轮任务最大的区别之一。单轮任务改完就完了，长程任务必须留下可追溯的记录，因为后续可能还有别的智能体或人类接着在这个基础上工作。我现在的习惯是，把这份说明直接写进仓库的一个约定位置（比如docs/agent-changes/目录），按时间戳命名，形成一份完整的维护历史。
7. 我对长程智能体的一点个人判断
折腾了这么久，我越来越觉得，长程智能体的核心竞争力不在模型本身，而在围绕模型构建的那套"脚手架"。状态管理、任务分解、验证分离、回滚机制、日志可观测性，这些东西听起来都不酷，但恰恰是决定一个智能体能不能真正长期干活的关键。模型能力会随着版本迭代不断提升，但工程架构的坑，得靠一个个踩过去才能填平。
如果你也想动手搭一个，我的建议是从最小的场景开始，先让它稳定地完成"改一个文件并验证"这种单步任务，再逐步拉长任务链条。每加一个能力，就配一套对应的验证和回滚机制。别一上来就追求全自动，半自动加人类关键节点介入，反而是现阶段最务实的方案。等你的智能体能稳定跑完几十步不出大错，再考虑放开手脚。这个过程急不得，但每走通一步，你都会对"智能体到底能干什么"有更清醒的认识。
