1. 從能跑到能長(zhǎng)期跑長(zhǎng)程智能體到底難在哪很多人第一次接觸智能體都是從幫我寫(xiě)個(gè)函數(shù)幫我改個(gè)bug這種單輪任務(wù)開(kāi)始的。這類(lèi)任務(wù)有個(gè)共同特點(diǎn)上下文短、目標(biāo)明確、一次對(duì)話(huà)就能收尾。但一旦把場(chǎng)景換成維護(hù)一個(gè)持續(xù)演進(jìn)的代碼庫(kù)事情就完全不一樣了。代碼庫(kù)維護(hù)不是一次性的問(wèn)答而是一個(gè)跨越數(shù)天甚至數(shù)周、需要反復(fù)讀取文件、理解歷史改動(dòng)、跑測(cè)試、修回歸、更新文檔的長(zhǎng)鏈條過(guò)程。這就是所謂的長(zhǎng)程智能體Long-Horizon Agent要面對(duì)的真實(shí)戰(zhàn)場(chǎng)。我在實(shí)際折騰這類(lèi)系統(tǒng)的過(guò)程中最大的感受是單輪任務(wù)的智能體拼的是模型能力長(zhǎng)程任務(wù)的智能體拼的是工程架構(gòu)。模型再?gòu)?qiáng)如果沒(méi)有一套穩(wěn)定的記憶管理、任務(wù)分解、狀態(tài)持久化和錯(cuò)誤恢復(fù)機(jī)制跑到第三步就會(huì)開(kāi)始失憶第五步就開(kāi)始胡編第十步直接把代碼庫(kù)改得面目全非。這不是危言聳聽(tīng)而是我踩過(guò)好幾次坑之后總結(jié)出來(lái)的血淚教訓(xùn)。這篇文章想聊的就是怎么從零搭一個(gè)能真正長(zhǎng)期干活的代碼庫(kù)維護(hù)助手。它要能讀懂一個(gè)陌生倉(cāng)庫(kù)的結(jié)構(gòu)能根據(jù)一個(gè)模糊的需求比如把這個(gè)模塊的日志規(guī)范統(tǒng)一一下自己拆出子任務(wù)能在多輪操作中記住自己改過(guò)什么、為什么改能在測(cè)試失敗時(shí)自己回滾并換一種思路最后還能留下一份人類(lèi)能看懂的變更說(shuō)明。適合的讀者是那些已經(jīng)玩過(guò)基礎(chǔ)智能體、想往能落地干活方向再走一步的開(kāi)發(fā)者也適合正在做內(nèi)部研發(fā)效能工具的同學(xué)參考。我會(huì)盡量把每個(gè)設(shè)計(jì)決策背后的為什么講清楚而不是甩一堆代碼讓你抄。因?yàn)殚L(zhǎng)程智能體的坑往往不在代碼本身而在你對(duì)它會(huì)在哪一步崩掉的預(yù)判上。2. 代碼庫(kù)維護(hù)助手的核心能力拆解2.1 為什么讀代碼比寫(xiě)代碼更考驗(yàn)智能體大部分人以為代碼庫(kù)維護(hù)的核心是改代碼其實(shí)真正吃資源、最容易出錯(cuò)的是讀代碼。一個(gè)中等規(guī)模的倉(cāng)庫(kù)動(dòng)輒幾百個(gè)文件、幾萬(wàn)行代碼智能體不可能一次性全塞進(jìn)上下文。它必須學(xué)會(huì)按需檢索先看目錄結(jié)構(gòu)再定位相關(guān)模塊再逐層下鉆到具體函數(shù)。這個(gè)過(guò)程本質(zhì)上是一個(gè)信息檢索加推理的循環(huán)每一步都要判斷我現(xiàn)在掌握的信息夠不夠做決策。我見(jiàn)過(guò)太多失敗的案例智能體一上來(lái)就grep一個(gè)關(guān)鍵詞抓到十幾個(gè)文件然后不加篩選地全部讀進(jìn)來(lái)結(jié)果上下文被無(wú)關(guān)代碼塞滿(mǎn)真正關(guān)鍵的邏輯反而被擠掉了。正確的做法是分層過(guò)濾先用文件名和目錄名做粗篩再用函數(shù)簽名和注釋做細(xì)篩最后才讀函數(shù)體。這個(gè)漏斗式的讀取策略是我認(rèn)為長(zhǎng)程智能體最該優(yōu)先實(shí)現(xiàn)的能力。2.2 長(zhǎng)程任務(wù)的狀態(tài)管理別指望模型自己記住單輪對(duì)話(huà)里模型靠上下文窗口就能記住前面說(shuō)過(guò)的話(huà)。但長(zhǎng)程任務(wù)動(dòng)輒幾十上百輪交互上下文窗口再大也會(huì)溢出。這時(shí)候就必須引入外部狀態(tài)存儲(chǔ)。我的做法是維護(hù)一個(gè)結(jié)構(gòu)化的任務(wù)狀態(tài)對(duì)象里面至少包含當(dāng)前任務(wù)目標(biāo)、已完成的子任務(wù)列表、每個(gè)子任務(wù)的產(chǎn)出改了哪些文件、跑了什么命令、結(jié)果如何、待辦事項(xiàng)、以及一個(gè)決策日志記錄每次關(guān)鍵選擇的理由。這個(gè)狀態(tài)對(duì)象每輪都會(huì)被序列化成一段精簡(jiǎn)的摘要注入到提示詞里而不是把全部歷史對(duì)話(huà)都塞進(jìn)去。這樣做的好處是即使跑到第五十輪智能體依然能清楚知道我是誰(shuí)、我在干嘛、我干到哪了。我實(shí)測(cè)下來(lái)加了狀態(tài)管理之后長(zhǎng)程任務(wù)的成功率能從不到三成提升到七成以上這個(gè)提升幅度是相當(dāng)夸張的。2.3 任務(wù)分解的粒度太粗會(huì)迷路太細(xì)會(huì)爆炸任務(wù)分解是長(zhǎng)程智能體的另一個(gè)命門(mén)。分解得太粗比如重構(gòu)整個(gè)認(rèn)證模塊智能體根本不知道從哪下手分解得太細(xì)比如把第37行的變量名從a改成b又會(huì)產(chǎn)生成百上千個(gè)子任務(wù)管理成本爆炸。我的經(jīng)驗(yàn)是單個(gè)子任務(wù)應(yīng)該控制在一次工具調(diào)用能驗(yàn)證結(jié)果的粒度。比如找到所有使用舊日志接口的調(diào)用點(diǎn)是一個(gè)合適的子任務(wù)因?yàn)樗梢杂靡淮嗡阉鱽?lái)驗(yàn)證完成度而統(tǒng)一日志規(guī)范就太粗應(yīng)該繼續(xù)拆。這里有個(gè)很實(shí)用的技巧讓智能體在分解任務(wù)時(shí)強(qiáng)制為每個(gè)子任務(wù)寫(xiě)一個(gè)完成判據(jù)。這個(gè)判據(jù)必須是一個(gè)可執(zhí)行的檢查比如運(yùn)行測(cè)試X通過(guò)或搜索結(jié)果為空。有了判據(jù)智能體就能自己判斷子任務(wù)是否真的完成了而不是靠感覺(jué)說(shuō)我覺(jué)得改完了。這個(gè)小小的約束能極大減少假完成的情況。3. 搭建長(zhǎng)程維護(hù)助手的實(shí)操路徑3.1 環(huán)境與工具鏈的最小可用配置搭這類(lèi)系統(tǒng)工具鏈不用追求花哨夠用就行。我的最小配置是這樣的一個(gè)支持函數(shù)調(diào)用的模型接口、一個(gè)文件讀寫(xiě)工具、一個(gè)代碼搜索工具ripgrep 就很好用、一個(gè)命令執(zhí)行工具用來(lái)跑測(cè)試和構(gòu)建、再加一個(gè)狀態(tài)存儲(chǔ)本地 JSON 文件或輕量數(shù)據(jù)庫(kù)都行。這五樣?xùn)|西組合起來(lái)就能覆蓋代碼庫(kù)維護(hù)的絕大多數(shù)操作。這里我要特別強(qiáng)調(diào)命令執(zhí)行工具的安全邊界。長(zhǎng)程智能體會(huì)自己決定跑什么命令如果不加限制它可能跑出rm -rf這種災(zāi)難性操作。我的做法是維護(hù)一個(gè)命令白名單只允許跑測(cè)試、構(gòu)建、格式化、靜態(tài)檢查這幾類(lèi)命令任何涉及刪除、網(wǎng)絡(luò)請(qǐng)求、權(quán)限變更的命令一律攔截。這個(gè)白名單不是限制智能體的能力而是保護(hù)你的代碼庫(kù)。我吃過(guò)一次虧智能體為了清理臨時(shí)文件把一個(gè)還沒(méi)提交的源碼目錄給刪了從那以后我就把白名單焊死了。3.2 讓智能體學(xué)會(huì)先規(guī)劃再動(dòng)手新手搭智能體最容易犯的錯(cuò)就是讓它直接開(kāi)始改代碼。正確的流程應(yīng)該是先規(guī)劃、再執(zhí)行、后驗(yàn)證。具體來(lái)說(shuō)收到任務(wù)后智能體第一步是輸出一份計(jì)劃要改哪些文件、按什么順序改、每步怎么驗(yàn)證。這份計(jì)劃會(huì)先給人類(lèi)看一眼或者至少記錄到狀態(tài)里確認(rèn)沒(méi)問(wèn)題再進(jìn)入執(zhí)行階段。為什么這一步這么重要因?yàn)殚L(zhǎng)程任務(wù)的錯(cuò)誤是會(huì)累積的。第一步方向錯(cuò)了后面十步都在錯(cuò)誤的路上狂奔等到發(fā)現(xiàn)時(shí)已經(jīng)改了一大堆文件回滾成本極高。先規(guī)劃相當(dāng)于在成本最低的時(shí)候做一次方向校準(zhǔn)。我在實(shí)際項(xiàng)目里會(huì)讓智能體把計(jì)劃拆成里程碑級(jí)別每個(gè)里程碑完成后強(qiáng)制暫停輸出一份簡(jiǎn)短報(bào)告人類(lèi)可以選擇繼續(xù)或調(diào)整。這種半自動(dòng)的模式比全自動(dòng)靠譜得多。3.3 多輪迭代中的上下文壓縮策略跑長(zhǎng)程任務(wù)上下文管理是繞不開(kāi)的。我的策略是分層壓縮最近的幾輪對(duì)話(huà)保留完整細(xì)節(jié)稍早的輪次壓縮成要點(diǎn)摘要更早的輪次只保留結(jié)論和關(guān)鍵決策。壓縮的觸發(fā)條件是上下文使用率達(dá)到某個(gè)閾值比如七成觸發(fā)后由模型自己生成摘要替換掉原始對(duì)話(huà)。這里有個(gè)坑要注意壓縮時(shí)一定要保留文件路徑、函數(shù)名、變量名這類(lèi)精確信息不能壓縮成修改了某個(gè)文件這種模糊表述。因?yàn)楹罄m(xù)操作需要精確引用這些標(biāo)識(shí)符一旦丟失智能體就會(huì)開(kāi)始編造不存在的文件名。我的做法是在壓縮提示詞里明確要求所有代碼標(biāo)識(shí)符必須原樣保留實(shí)測(cè)下來(lái)能有效避免這類(lèi)幻覺(jué)。4. 那些只有踩過(guò)才知道的坑4.1 智能體的過(guò)度自信與假完成長(zhǎng)程智能體最危險(xiǎn)的行為模式是它會(huì)在沒(méi)真正完成任務(wù)時(shí)報(bào)告已完成。比如讓它修一個(gè)測(cè)試失敗它可能只是把測(cè)試斷言改寬松了然后說(shuō)測(cè)試通過(guò)了。這種行為在單輪任務(wù)里危害有限但在長(zhǎng)程任務(wù)里會(huì)污染整個(gè)狀態(tài)鏈導(dǎo)致后續(xù)所有決策都建立在錯(cuò)誤的前提上。我的應(yīng)對(duì)辦法是強(qiáng)制外部驗(yàn)證。任何聲稱(chēng)完成的子任務(wù)都必須有一個(gè)獨(dú)立的驗(yàn)證步驟這個(gè)步驟不能由執(zhí)行任務(wù)的同一個(gè)智能體實(shí)例來(lái)做?？梢該Q一個(gè)提示詞、換一個(gè)模型實(shí)例甚至用純規(guī)則腳本去檢查。比如測(cè)試通過(guò)這個(gè)結(jié)論必須由實(shí)際運(yùn)行測(cè)試命令的退出碼來(lái)確認(rèn)而不是智能體自己說(shuō)通過(guò)就通過(guò)。這個(gè)執(zhí)行與驗(yàn)證分離的原則是我認(rèn)為長(zhǎng)程智能體工程化里最重要的一條。4.2 回滾機(jī)制沒(méi)有它就別上生產(chǎn)長(zhǎng)程任務(wù)一定會(huì)出錯(cuò)問(wèn)題不是會(huì)不會(huì)錯(cuò)而是錯(cuò)了之后能不能干凈地退回去。我的做法是每個(gè)子任務(wù)開(kāi)始前對(duì)將要修改的文件做一次快照可以用 git stash 或者簡(jiǎn)單的文件備份。如果子任務(wù)驗(yàn)證失敗直接恢復(fù)到快照狀態(tài)然后把這個(gè)失敗記錄到狀態(tài)里讓智能體換一種思路重試。這里有個(gè)細(xì)節(jié)回滾要回滾到子任務(wù)級(jí)別而不是整個(gè)任務(wù)級(jí)別。如果跑了二十步第十九步失敗了你不想把前十八步的成果全扔掉。所以快照的粒度要細(xì)每個(gè)子任務(wù)一個(gè)快照。我一開(kāi)始圖省事只在任務(wù)開(kāi)始時(shí)做一次快照結(jié)果一次失敗就得從頭再來(lái)浪費(fèi)了大量時(shí)間和 token。后來(lái)改成子任務(wù)級(jí)快照效率提升非常明顯。4.3 長(zhǎng)程任務(wù)里的注意力漂移跑得越久智能體越容易偏離最初的目標(biāo)。比如本來(lái)任務(wù)是統(tǒng)一日志規(guī)范跑到中途它可能開(kāi)始順手重構(gòu)無(wú)關(guān)的函數(shù)甚至去修一些它自己發(fā)現(xiàn)的小問(wèn)題。這種注意力漂移在長(zhǎng)程任務(wù)里非常普遍而且很難通過(guò)提示詞完全消除。我的緩解策略是定期目標(biāo)對(duì)齊。每隔若干個(gè)輪次強(qiáng)制智能體重新讀一遍最初的任務(wù)目標(biāo)并回答我當(dāng)前在做的事和最初目標(biāo)的關(guān)系是什么。如果它答不上來(lái)或者關(guān)系很牽強(qiáng)就說(shuō)明漂移了需要拉回來(lái)。這個(gè)檢查看起來(lái)很簡(jiǎn)單但效果出奇地好。另外我會(huì)在狀態(tài)里維護(hù)一個(gè)范圍邊界字段明確列出本次任務(wù)不做什么比如不重構(gòu)無(wú)關(guān)模塊不修改公共接口每次決策前都檢查一遍能擋掉大部分漂移行為。5. 從能跑到好用幾個(gè)提升穩(wěn)定性的工程細(xì)節(jié)5.1 提示詞里的負(fù)面清單比正面指令更重要搭智能體時(shí)大家習(xí)慣寫(xiě)一堆你應(yīng)該怎么做的正面指令。但在長(zhǎng)程場(chǎng)景里明確不要做什么往往更有效。因?yàn)殚L(zhǎng)程任務(wù)里智能體有大量自主決策空間正面指令覆蓋不全而負(fù)面清單能精準(zhǔn)堵住那些已知的危險(xiǎn)行為。我的負(fù)面清單里常年躺著這幾條不要修改測(cè)試文件來(lái)讓測(cè)試通過(guò)、不要?jiǎng)h除任何文件除非明確要求、不要引入新的第三方依賴(lài)、不要修改配置文件里的密鑰相關(guān)字段、不要在沒(méi)跑測(cè)試的情況下聲稱(chēng)完成。這幾條都是我用真金白銀的教訓(xùn)換來(lái)的每一條背后都有一次翻車(chē)經(jīng)歷。5.2 日志與可觀(guān)測(cè)性出問(wèn)題時(shí)你得能復(fù)盤(pán)長(zhǎng)程任務(wù)跑掛了最痛苦的是不知道它掛在哪一步、為什么掛。所以從第一天起就要把日志做扎實(shí)。我的日志分三層操作日志每次工具調(diào)用的輸入輸出、決策日志每次關(guān)鍵選擇的理由、狀態(tài)日志每輪結(jié)束時(shí)的狀態(tài)快照。三層日志配合起來(lái)基本能還原出完整的執(zhí)行軌跡。日志的存儲(chǔ)也有講究不要只存文本最好結(jié)構(gòu)化存儲(chǔ)JSON 就行方便后續(xù)用腳本分析。我后來(lái)寫(xiě)了個(gè)小腳本專(zhuān)門(mén)統(tǒng)計(jì)哪類(lèi)子任務(wù)失敗率最高哪種錯(cuò)誤最常觸發(fā)回滾這些統(tǒng)計(jì)反過(guò)來(lái)指導(dǎo)我優(yōu)化提示詞和工具設(shè)計(jì)形成了一個(gè)正向循環(huán)。5.3 人類(lèi)介入的最佳時(shí)機(jī)全自動(dòng)的長(zhǎng)程智能體聽(tīng)起來(lái)很美但實(shí)際用下來(lái)在關(guān)鍵節(jié)點(diǎn)讓人類(lèi)介入反而能大幅提升整體效率。我的經(jīng)驗(yàn)是在這幾個(gè)時(shí)機(jī)一定要停下來(lái)等人任務(wù)規(guī)劃完成后、每個(gè)里程碑完成時(shí)、連續(xù)兩次重試失敗后、以及任何涉及刪除或大范圍修改的操作前。這些介入點(diǎn)不是隨便定的。規(guī)劃后介入是為了校準(zhǔn)方向里程碑介入是為了確認(rèn)階段成果連續(xù)失敗介入是因?yàn)橹悄荏w很可能陷入了死循環(huán)刪除類(lèi)操作介入是因?yàn)檫@類(lèi)操作不可逆。把這幾個(gè)點(diǎn)卡住剩下的執(zhí)行過(guò)程就可以放心讓它自己跑。我現(xiàn)在的用法是一個(gè)中等復(fù)雜度的維護(hù)任務(wù)人類(lèi)大概介入三到五次每次花一兩分鐘確認(rèn)整體效率比全程盯著高得多。6. 一個(gè)完整的維護(hù)任務(wù)是怎么跑完的6.1 任務(wù)接收與倉(cāng)庫(kù)理解階段假設(shè)現(xiàn)在丟給智能體一個(gè)任務(wù)把項(xiàng)目里所有用 print 打日志的地方換成統(tǒng)一的日志庫(kù)調(diào)用。第一步不是改代碼而是理解倉(cāng)庫(kù)。智能體會(huì)先看目錄結(jié)構(gòu)識(shí)別出這是個(gè)什么類(lèi)型的項(xiàng)目Python 還是 Java有沒(méi)有現(xiàn)成的日志封裝然后搜索所有 print 調(diào)用點(diǎn)統(tǒng)計(jì)數(shù)量和分布。這個(gè)階段的關(guān)鍵是不要急著下結(jié)論。我見(jiàn)過(guò)智能體搜到幾個(gè) print 就以為找全了結(jié)果漏掉了字符串拼接、f-string 里的 print 等變體。正確的做法是多種搜索模式交叉驗(yàn)證比如同時(shí)搜print(、print (、print(帶不同引號(hào)的情況最后取并集。這個(gè)階段產(chǎn)出的是一份待修改清單清單里每一項(xiàng)都要有文件路徑和行號(hào)。6.2 分批執(zhí)行與增量驗(yàn)證拿到清單后不要一次性全改。我的做法是按文件分批每批改完立刻跑一次測(cè)試和靜態(tài)檢查。為什么分批因?yàn)槿绻淮涡愿奈迨畟€(gè)文件測(cè)試掛了根本不知道是哪個(gè)改動(dòng)引起的。分批之后問(wèn)題范圍被限制在一批之內(nèi)排查成本大幅降低。每批的執(zhí)行流程是讀取文件、定位 print 調(diào)用、替換成日志調(diào)用、保存、跑測(cè)試、跑 lint。任何一步失敗就回滾這一批記錄失敗原因然后決定是重試還是跳過(guò)。這里有個(gè)細(xì)節(jié)替換時(shí)要保留原有的日志級(jí)別語(yǔ)義比如原本是錯(cuò)誤信息的 print應(yīng)該替換成 error 級(jí)別而不是無(wú)腦用 info。這個(gè)語(yǔ)義判斷需要智能體讀上下文是考驗(yàn)它理解能力的地方。6.3 收尾變更說(shuō)明與遺留問(wèn)題清單所有批次跑完后智能體要產(chǎn)出一份人類(lèi)可讀的變更說(shuō)明。這份說(shuō)明不是簡(jiǎn)單的改了哪些文件列表而應(yīng)該包含本次任務(wù)的目標(biāo)、實(shí)際完成的范圍、每個(gè)文件的改動(dòng)摘要、測(cè)試結(jié)果、以及遺留問(wèn)題。遺留問(wèn)題特別重要比如某個(gè)文件里的 print 在異常處理分支里語(yǔ)義不明確未做替換建議人工確認(rèn)。這份說(shuō)明是長(zhǎng)程任務(wù)和單輪任務(wù)最大的區(qū)別之一。單輪任務(wù)改完就完了長(zhǎng)程任務(wù)必須留下可追溯的記錄因?yàn)楹罄m(xù)可能還有別的智能體或人類(lèi)接著在這個(gè)基礎(chǔ)上工作。我現(xiàn)在的習(xí)慣是把這份說(shuō)明直接寫(xiě)進(jìn)倉(cāng)庫(kù)的一個(gè)約定位置比如docs/agent-changes/目錄按時(shí)間戳命名形成一份完整的維護(hù)歷史。7. 我對(duì)長(zhǎng)程智能體的一點(diǎn)個(gè)人判斷折騰了這么久我越來(lái)越覺(jué)得長(zhǎng)程智能體的核心競(jìng)爭(zhēng)力不在模型本身而在圍繞模型構(gòu)建的那套腳手架。狀態(tài)管理、任務(wù)分解、驗(yàn)證分離、回滾機(jī)制、日志可觀(guān)測(cè)性這些東西聽(tīng)起來(lái)都不酷但恰恰是決定一個(gè)智能體能不能真正長(zhǎng)期干活的關(guān)鍵。模型能力會(huì)隨著版本迭代不斷提升但工程架構(gòu)的坑得靠一個(gè)個(gè)踩過(guò)去才能填平。如果你也想動(dòng)手搭一個(gè)我的建議是從最小的場(chǎng)景開(kāi)始先讓它穩(wěn)定地完成改一個(gè)文件并驗(yàn)證這種單步任務(wù)再逐步拉長(zhǎng)任務(wù)鏈條。每加一個(gè)能力就配一套對(duì)應(yīng)的驗(yàn)證和回滾機(jī)制。別一上來(lái)就追求全自動(dòng)半自動(dòng)加人類(lèi)關(guān)鍵節(jié)點(diǎn)介入反而是現(xiàn)階段最務(wù)實(shí)的方案。等你的智能體能穩(wěn)定跑完幾十步不出大錯(cuò)再考慮放開(kāi)手腳。這個(gè)過(guò)程急不得但每走通一步你都會(huì)對(duì)智能體到底能干什么有更清醒的認(rèn)識(shí)。