過去半年我一直在折騰 AI 編碼代理從最早把整個(gè)項(xiàng)目往上下文窗口里硬塞到后來學(xué)會(huì)給 AI“劃重點(diǎn)”這中間的差距大概就是新手和老司機(jī)的距離。所謂 Context Mode說到底就是一套上下文管理范式——它告訴編碼代理什么時(shí)候該調(diào)取哪些代碼、哪些對話該記住、哪些細(xì)節(jié)可以壓縮歸檔而不是讓 AI 每一次都從頭猜你的項(xiàng)目長什么樣。這篇文章我從實(shí)際踩坑出發(fā)聊聊我理解的 Context Mode 到底是什么、為什么要重構(gòu)上下文管理、以及落地時(shí)怎么配置、有哪些坑。內(nèi)容針對用過 Cursor、Claude Code、Aider 這類工具的開發(fā)者也適合在大模型應(yīng)用層做 Agent 開發(fā)的工程師?？赐昴阒辽倌芑卮鹨粋€(gè)問題當(dāng) AI 編碼代理面對十萬級代碼庫時(shí)它是怎么保證不亂、不忘、不改錯(cuò)的。1. 為什么要重構(gòu)上下文管理從“塞滿窗口”說起1.1 上下文窗口的物理限制與 AI 編碼代理的雄心先說個(gè)現(xiàn)實(shí)現(xiàn)在主流模型的上下文窗口GPT-4 級別大概 128K tokensClaude 的窗口能做到 200K 級別。聽著很大對吧但你要真把一個(gè)中型項(xiàng)目塞進(jìn)去試試——我手頭一個(gè)接近三十萬行的后端倉庫按每行代碼平均吃掉 15 到 20 個(gè) token 粗算整個(gè)倉庫的 token 量在 450 萬到 600 萬之間。也就是說哪怕給一個(gè) 200K 窗口的模型也只夠放下倉庫十分之一的內(nèi)容這還沒算對話歷史、工具輸出、系統(tǒng)指令這些開銷。AI 編碼代理的尷尬就在這它想在代碼庫里穿梭、改 bug、加功能但它的“工作記憶”只有那么點(diǎn)大。更麻煩的是上下文窗口不是越大越好——窗口越大模型對中間內(nèi)容的注意力越容易渙散檢索精度也會(huì)跟著下降實(shí)測在長上下文里找一條具體的配置項(xiàng)有時(shí)候還不如小窗口專注模式來得準(zhǔn)。所以真正的問題不是“窗口多大”而是“窗口里裝什么”。1.2 沒有上下文管理時(shí)AI 代理的典型翻車現(xiàn)場我最初用 AI 改代碼時(shí)方式是簡單粗暴的把所有相關(guān)的文件一股腦塞進(jìn)對話里。結(jié)果就是一連串熟悉又崩潰的場面。最典型的是“越改越倒退”。我讓 AI 在一個(gè)訂單服務(wù)里加一個(gè)超時(shí)重試功能它改了服務(wù)類卻忘了配套的配置項(xiàng)在另一個(gè)模塊里結(jié)果編譯報(bào)錯(cuò)我提醒它看配置文件它理解了又因?yàn)樵谏舷挛睦锓搅艘粋€(gè)舊版本的接口定義把新邏輯寫成了舊簽名。整個(gè)過程和翻聊天記錄找前任約會(huì)地點(diǎn)一樣——信息不全的時(shí)候AI 只能靠猜。還有“上下文漂移”的問題。一個(gè)會(huì)話聊到第 30 輪之后前面確定過的技術(shù)約束、代碼風(fēng)格約定、禁止修改的文件清單全部慢慢淡出模型的注意力。模型會(huì)禮貌地說“好的我記住不改這個(gè)文件了”然后在第 40 輪得意洋洋地把那個(gè)文件改了個(gè)底朝天。這類問題的根源不是模型智商不夠而是沒有任何一層機(jī)制在幫忙管理“什么該出現(xiàn)在上下文里”。模型的注意力是平等的不會(huì)因?yàn)槟惆选敖垢暮诵闹Ц赌K”這句話寫在了最前面它就真的能一字不落記住。這時(shí)候就需要一套約束機(jī)制主動(dòng)幫模型規(guī)劃上下文——這就是 Context Mode 存在的理由。2. Context Mode 的核心設(shè)計(jì)范式分層、檢索、預(yù)算2.1 分層的上下文架構(gòu)把上下文拆成幾個(gè)“抽屜”我自己實(shí)踐下來Context Mode 的第一步是把上下文空間從“一個(gè)平面”改成“多個(gè)抽屜”。模型不會(huì)自己分抽屜但我們可以用工程手段給它規(guī)整出來。我用過一套四層結(jié)構(gòu)實(shí)測效果不錯(cuò)全局層項(xiàng)目的技術(shù)棧、目錄結(jié)構(gòu)、編碼規(guī)范、關(guān)鍵業(yè)務(wù)約束。這層約等于新員工入職培訓(xùn)幾個(gè)核心事實(shí)就能說清楚。域?qū)赢?dāng)前改動(dòng)所屬的業(yè)務(wù)領(lǐng)域知識(shí)比如支付模塊的接口約定、訂單模塊的狀態(tài)機(jī)定義。按模塊劃分用的時(shí)候才拉進(jìn)來。任務(wù)層當(dāng)前任務(wù)直接涉及的文件、類、函數(shù)簽名、調(diào)用鏈。這是模型真正動(dòng)手改代碼時(shí)要看的“施工圖紙”。瞬時(shí)層最近幾輪對話中的具體內(nèi)容比如報(bào)錯(cuò)信息、用戶最新需求、剛剛修改完的代碼片段。為什么要把上下文拆成四份而不是一份因?yàn)檫@樣就能精確控制每個(gè)抽屜的“容量預(yù)算”。全局層永遠(yuǎn)常駐但很小幾千 token 就能裝下域?qū)邮菕攸c(diǎn)放不追求全量任務(wù)層是動(dòng)態(tài)變化的AI 每走一步相關(guān)文件集合都在更新。我在一個(gè)訂單服務(wù)重構(gòu)項(xiàng)目里落實(shí)這套結(jié)構(gòu)時(shí)全局層放了一張項(xiàng)目結(jié)構(gòu)圖和三條技術(shù)約束域?qū)臃帕擞唵螤顟B(tài)機(jī)文檔任務(wù)層動(dòng)態(tài)追蹤當(dāng)前修改涉及的文件。調(diào)好之后AI 的“森林和樹葉”終于分清了它對全局方向有把握又不至于在細(xì)節(jié)里迷失。2.2 按需加載與檢索增強(qiáng)不讓模型背著一整個(gè)倉庫跑分層的下一步是解決“內(nèi)容從哪來”的問題。一個(gè)三十萬行的倉庫不可能每一項(xiàng)都提前寫進(jìn)上下文。Context Mode 的第二個(gè)范式是按需加載結(jié)合檢索增強(qiáng)。具體做法是先把整個(gè)代碼庫做一次 embedding 索引建語義檢索通道。代理接到任務(wù)后先通過檢索找到“最相關(guān)的 5 到 15 個(gè)文件”再把它們的完整內(nèi)容注入上下文。相當(dāng)于給模型配了一個(gè)只借書不搬圖書館的助手。這里有個(gè)很反直覺的經(jīng)驗(yàn)——檢索不要太依賴“語義相似”。純向量檢索最大的坑是模型在找“重試機(jī)制怎么實(shí)現(xiàn)”檢索系統(tǒng)匹配到的文章可能全是關(guān)于“熔斷”的因?yàn)檫@兩個(gè)概念在語義空間里挨得很近。我后來在檢索層疊加了“符號檢索”機(jī)制優(yōu)先索引函數(shù)名、類名、變量名這些符號級信息再配合語義向量。比如搜“OrderService.retry”直接定位到符號再補(bǔ)充語義聯(lián)想命中率上了幾個(gè)臺(tái)階。按需加載的另一個(gè)要點(diǎn)是滿載還是部分加載的取舍。對于核心修改文件直接整文件進(jìn)上下文最穩(wěn)但對那些只是路徑指向、配置引用的輔助文件完全可以只加載關(guān)鍵片段。我有一個(gè)實(shí)踐標(biāo)準(zhǔn)如果模型需要修改這個(gè)文件的代碼就整文件進(jìn)如果只是“看一眼”或“理解調(diào)用關(guān)系”只加載相關(guān)函數(shù)體和簽名。2.3 上下文預(yù)算的量化分配每個(gè)任務(wù)吃多少 token按賬單管理Context Mode 第三個(gè)核心范式是我認(rèn)為最容易被忽略但也最關(guān)鍵的把 token 當(dāng)預(yù)算管起來。很多開發(fā)者習(xí)慣一次性把上下文塞到接近窗口上限結(jié)果就是模型的行為變得詭異——回答變慢、邏輯渙散、早期的指令失效。我給自己的項(xiàng)目定了一套預(yù)算分配策略系統(tǒng)指令與全局層占總預(yù)算的 5%約 2K tokens域?qū)颖尘爸R(shí)10%約 4K tokens任務(wù)層文件內(nèi)容40%約 16K tokens對話歷史與工具輸出30%約 12K tokens冗余預(yù)留15%約 6K tokens總量控制在 40K 到 60K 之間而不是頂著窗口上限。為什么留冗余因?yàn)槟Ｐ驮谏纱a時(shí)輸出本身也占用上下文。如果輸入就把窗口撐滿生成到一半就會(huì)被迫截?cái)嗷蛘唛_始“忘事”。實(shí)際的預(yù)算計(jì)算可以用這樣一筆賬假設(shè)一個(gè)修改任務(wù)涉及 6 個(gè)文件平均每個(gè)文件約 250 行按每行 16 個(gè) token 算任務(wù)層大約 6 × 250 × 16 24K tokens加上系統(tǒng)指令和域?qū)又R(shí)起步就有 30K 左右。這種情況下我再?zèng)Q定對話歷史最多保留多少輪——超過的部分做摘要壓縮而不是無腦保留原文。這個(gè)“做預(yù)算”的動(dòng)作就是上下文管理和普通 prompt engineering 的分水嶺。3. 實(shí)操過程給 AI 編碼代理配置 Context Mode3.1 一個(gè)真實(shí)的項(xiàng)目場景重構(gòu)電商訂單超時(shí)處理拿一個(gè)我上個(gè)月實(shí)際跑過的場景來拆解一個(gè)電商后端項(xiàng)目核心服務(wù)是訂單模塊技術(shù)棧是 Java Spring Boot Redis RabbitMQ。任務(wù)內(nèi)容是“給訂單超時(shí)未支付增加自動(dòng)取消機(jī)制并補(bǔ)償庫存”。這個(gè)項(xiàng)目大概有 200 個(gè) Java 文件、總計(jì) 18 萬行代碼模型窗口按 128K 算。如果不做上下文管理直接讓 AI 上手它要么挑幾個(gè)文件瞎猜要么干脆說“這個(gè)范圍太大了我處理不了”。我按四層結(jié)構(gòu)規(guī)劃了上下文內(nèi)容全局層注入的是項(xiàng)目架構(gòu)圖一個(gè)簡版訂單服務(wù)、庫存服務(wù)、MQ 消息隊(duì)列的關(guān)系三條約束——“禁止直接修改庫存服務(wù)的核心扣減邏輯”“所有對外接口保持 RESTful 風(fēng)格”“數(shù)據(jù)庫表結(jié)構(gòu)變更需要有遷移腳本”。域?qū)幼⑷氲氖怯唵螤顟B(tài)機(jī)的完整定義待付款、已支付、已取消、已完成以及超時(shí)處理的相關(guān)業(yè)務(wù)規(guī)則——比如超時(shí)窗口是 30 分鐘取消訂單后要發(fā)消息給庫存服務(wù)。任務(wù)層是動(dòng)態(tài)變化的。我讓代理從搜索“OrderService”類開始然后追蹤它看到的調(diào)用鏈逐步把支付回調(diào)、庫存接口、MQ 生產(chǎn)者消費(fèi)者這幾個(gè)文件加入上下文。這個(gè)過程里不用手動(dòng)挑文件靠檢索模塊自動(dòng)完成。3.2 上下文裁剪的具體操作步驟這里分享一下我在工具里實(shí)際執(zhí)行的裁剪流程你可以直接照著做第一步列白名單。把“必須進(jìn)上下文的文件”列出來優(yōu)先選當(dāng)前任務(wù)的入口類、核心業(yè)務(wù)邏輯類、配置類、最近改動(dòng)過的文件。我這次選了 8 個(gè)文件其中 5 個(gè)是任務(wù)直接相關(guān)的類3 個(gè)是配置和接口定義。第二步列索引名單。第二個(gè)名單是“不需要進(jìn)上下文但可能被檢索到的文件”。這些文件不預(yù)先加載只進(jìn)入語義索引等模型需要的時(shí)候再檢索加載。我把庫存服務(wù)的遠(yuǎn)程接口、MQ 的配置常量、工具類都?xì)w到了這一類。第三步壓縮對話歷史。如果這個(gè)任務(wù)需要多輪對話我的策略是每 10 輪做一次歷史摘要把“已確認(rèn)的方案”“已修改的文件”“待解決的問題”三條記錄成結(jié)構(gòu)化信息注入上下文替換掉冗長的原始對話。第三步非常關(guān)鍵。你可以想象一個(gè)改了 20 輪的代碼任務(wù)原始對話記錄可能有 2 萬 token其中一半是早期試錯(cuò)的過程。把這些過程壓縮成三行“事實(shí)摘要”既省預(yù)算又減少干擾。壓縮完成之后AI 記得住的全部是有效信息而不是“第三輪的時(shí)候用戶說那樣做不行第五輪又說其實(shí)試一下也行”。3.3 一個(gè)可直接套用的配置模板下面是一個(gè)我在 Cursor 和 Claude Code 上都跑過的配置思路不是某個(gè)工具的官方配置項(xiàng)而是通用的“上下文管理策略”描述你自己按工具語法翻譯一下就能用[全局上下文] - 項(xiàng)目結(jié)構(gòu)樹僅目錄級深度不超過3層 - 技術(shù)棧聲明Java 17, Spring Boot 3.x, Redis, RabbitMQ - 綁定規(guī)則禁止修改文件inventory-core/*, payment-core/* - 日志與錯(cuò)誤處理規(guī)范 [域上下文] - 模塊: order-service - 狀態(tài)機(jī)定義: PENDING - PAID - COMPLETED; PENDING - CANCELLED (30min) - 外部依賴接口: inventory-api, payment-api - 相關(guān)文檔: order-flow.md, mq-events.md [任務(wù)上下文] - 目標(biāo): 實(shí)現(xiàn)超時(shí)自動(dòng)取消 庫存補(bǔ)償 - 入口文件: OrderController, OrderService, OrderTimeoutHandler - 依賴文件: InventoryClient, MQProducer, OrderRepository - 約束: 不改變訂單表結(jié)構(gòu); 補(bǔ)償邏輯要冪等 [歷史管理] - 每10輪對話執(zhí)行一次摘要化 - 摘要內(nèi)容: 已確認(rèn)方案 / 已修改文件 / 待解決問題這套模板的思路抽象出來就是“全局 域 任務(wù) 歷史”四個(gè)象限。全局層是所有任務(wù)共用的域?qū)影茨K切換任務(wù)層是動(dòng)態(tài)的歷史層是定期壓縮的。配置成這個(gè)樣子之后AI 編碼代理的表現(xiàn)會(huì)有質(zhì)的提升——至少不會(huì)出現(xiàn)改了 A 模塊卻把 B 模塊的配置刪掉這種低級事故。4. 踩坑實(shí)錄與排查技巧4.1 上下文碎片化AI“失憶”的真正原因我遇到過最隱蔽的問題是 AI 在對話中期開始“失憶”但它不是完全失憶而是把不同來源的信息搞混了。比如它明明在上下文里看到了“訂單超時(shí) 30 分鐘”卻在生成代碼時(shí)寫成了 300 分鐘看到“補(bǔ)償庫存要冪等”卻生成了不做任何判斷的重復(fù)扣減調(diào)用。排查了半天原因出在上下文的排列方式上。我把域?qū)又R(shí)放在了很前面任務(wù)層文件放在了后面中間隔了很長的對話歷史。模型在處理長上下文時(shí)對中間部分的關(guān)注度天然偏低結(jié)果就是它永遠(yuǎn)記得前面的狀態(tài)機(jī)定義也記得最后看到的任務(wù)代碼但對兩者的關(guān)聯(lián)關(guān)系理解得不夠牢固。解決方法很簡單把“當(dāng)前任務(wù)最重要的約束”復(fù)制一份放到對話最末尾緊挨著模型即將生成代碼的位置。這有點(diǎn)像是給 AI 貼一張便利貼在顯示器邊框上——不是所有信息重要而是讓重要信息出現(xiàn)在它眼前。如果在任務(wù)開始時(shí)和對話結(jié)束前各聲明一次“超時(shí)時(shí)間是 30 分鐘補(bǔ)償必須冪等”失憶問題幾乎絕跡。4.2 壓縮過度導(dǎo)致的信息失真如何保住關(guān)鍵細(xì)節(jié)歷史摘要壓縮是一個(gè)兩難。壓得狠省了上下文但容易丟關(guān)鍵細(xì)節(jié)壓得松信息是保住了可歷史又一次占滿了預(yù)算。我踩過一個(gè)大坑我寫了一個(gè)摘要腳本自動(dòng)把每 10 輪對話壓成三行結(jié)果第 18 輪時(shí)用戶說過一句“注意退款邏輯里涉及優(yōu)惠券的按比例退還”這句關(guān)鍵業(yè)務(wù)規(guī)則沒有被摘要腳本識(shí)別為“重要信息”被省略了。結(jié)果 AI 在后續(xù)生成退款邏輯時(shí)完全沒處理優(yōu)惠券部分業(yè)務(wù)測試直接失敗。這個(gè)問題的教訓(xùn)是摘要壓縮不能只靠“長度”標(biāo)準(zhǔn)還要靠“業(yè)務(wù)關(guān)鍵性”標(biāo)準(zhǔn)。我后來改了摘要策略除了壓縮對話外還額外維護(hù)一張“事實(shí)清單”專門記錄對話中出現(xiàn)的硬性數(shù)字、業(yè)務(wù)規(guī)則、禁止事項(xiàng)。每次摘要時(shí)先掃描事實(shí)清單里有沒有新增的硬約束有就無條件保留。這個(gè)習(xí)慣幫我躲過了好幾次線上事故。還有一種替代方案是“分層摘要”保留最近 5 輪對話的完整原文更早的對話才做摘要。最近的 5 輪往往包含當(dāng)前最新狀態(tài)全文保留的代價(jià)小、收益大。再往前的壓成摘要也不心疼。4.3 檢索誤召回與工具鏈整合時(shí)的協(xié)作沖突Context Mode 依賴檢索時(shí)檢索的“誤召回”是一個(gè)讓人頭疼的問題。有一次我讓 AI 找“取消訂單需要調(diào)用的所有服務(wù)”結(jié)果檢索系統(tǒng)召回了十來個(gè)文件里面有訂單模塊的、有支付模塊的、有物流模塊的看起來每個(gè)都沾點(diǎn)邊但真正需要的只有 3 個(gè)。AI 把這 10 個(gè)文件全部塞進(jìn)上下文后反而因?yàn)椤靶畔⑦^載”開始行差踏錯(cuò)——它甚至打算改物流模塊的接口。解決誤召回的辦法是給檢索結(jié)果打分過濾先按符號命中過濾一批再做語義排序最后只保留符號命中和語義排名前五的交集。這套機(jī)制可以從根上削減“看著相關(guān)但實(shí)際無關(guān)”的文件進(jìn)入上下文。工具鏈整合的沖突是另一個(gè)維度。我在同一個(gè)項(xiàng)目里同時(shí)用了代碼補(bǔ)全類工具、對話類代理、本地編譯檢測工具它們各自維護(hù)自己的索引和上下文判斷結(jié)果出現(xiàn)了一個(gè)尷尬的場景對話代理已經(jīng)修改了接口簽名代碼補(bǔ)全工具還在按舊簽名提示編譯檢測工具報(bào)錯(cuò)但代理看不到報(bào)錯(cuò)信息因?yàn)樗鼪]把編譯結(jié)果納入上下文。后來我把工具鏈做了“主從分層”對話代理作為唯一入口代碼補(bǔ)全工具的提示全部關(guān)閉編譯檢測輸出重定向到代理的上下文中。雖然犧牲了一部分補(bǔ)全工具的便利性但換來的是上下文的一致性——所有決策都基于同一份信息這個(gè)收益是實(shí)打?qū)嵉摹?. 這套范式后續(xù)還能擴(kuò)展到哪里分享兩個(gè)我自己在嘗試的擴(kuò)展方向供你參考。一個(gè)是多 Agent 協(xié)作場景下的上下文隔離與共享。當(dāng)拆成多個(gè)代理分別負(fù)責(zé)調(diào)研、編碼、測試時(shí)每個(gè)代理的 Context Mode 應(yīng)該隔離到什么程度我的實(shí)驗(yàn)方案是調(diào)研代理的輸出只保留結(jié)論不保留過程編碼代理的輸入只接收“調(diào)研結(jié)論 約束清單”不接收原始代碼搜索日志測試代理再獨(dú)立看編碼結(jié)果。通過這種方式每個(gè)代理的上下文都相對干凈不會(huì)互相污染。另一個(gè)是上下文在任務(wù)中斷后的“恢復(fù)”問題。AI 編碼代理經(jīng)常會(huì)遇到長任務(wù)被打斷的情況比如編譯不過、用戶插話、工具崩潰。重新啟動(dòng)后原來的上下文已經(jīng)丟失。我現(xiàn)在的做法是每個(gè)任務(wù)開始時(shí)就生成一份“任務(wù)快照”里面包含目標(biāo)、當(dāng)前進(jìn)度、已修改文件清單、下一步計(jì)劃。任務(wù)恢復(fù)時(shí)先把快照灌進(jìn)上下文再補(bǔ)充必要的文件內(nèi)容。這個(gè)快照機(jī)制本質(zhì)上就是把 Context Mode 從“對話時(shí)的動(dòng)態(tài)管理”變成“持久化的任務(wù)資產(chǎn)”。我在實(shí)際使用中體會(huì)最深的還是那句老話——AI 編碼代理的上限不在于模型的智商而在于你喂給它的信息質(zhì)量和信息結(jié)構(gòu)。Context Mode 不是某個(gè)工具的隱藏開關(guān)而是一套設(shè)計(jì)哲學(xué)承認(rèn)上下文窗口有限所以主動(dòng)分層承認(rèn)模型注意力會(huì)漂移所以反復(fù)強(qiáng)調(diào)關(guān)鍵事實(shí)承認(rèn)長對話會(huì)失憶所以定期做摘要。你只要能把這套邏輯想明白不管底層模型換了幾代關(guān)于“如何給 AI 劃重點(diǎn)”的這套手藝永遠(yuǎn)是有效的。