1. 從一次上下文崩潰說起為什么長(zhǎng)會(huì)話里的編碼代理會(huì)“失憶”如果你用 AI 編碼代理跑過稍微大一點(diǎn)的項(xiàng)目大概率遇到過這種場(chǎng)景前 30 輪對(duì)話里它還記得你的目錄結(jié)構(gòu)、命名規(guī)范、某個(gè)工具函數(shù)的簽名到了第 50 輪你讓它改一個(gè)之前已經(jīng)討論過的模塊它開始一本正經(jīng)地胡說八道把utils/date.ts里的函數(shù)搬到services/下面或者干脆重新發(fā)明一個(gè)你已經(jīng)寫好的工具。這不是模型變笨了而是上下文窗口被壓縮機(jī)制“動(dòng)過刀”了。我把它叫做“腦葉切除術(shù)”——當(dāng)會(huì)話 token 數(shù)逼近上限平臺(tái)側(cè)會(huì)觸發(fā)上下文壓縮把早期對(duì)話摘要化、截?cái)嗷踔林苯觼G棄。對(duì)于閑聊這沒什么但對(duì)于一個(gè)需要持續(xù)記住項(xiàng)目狀態(tài)、文件結(jié)構(gòu)、接口約定的編碼代理來說這等于把它的長(zhǎng)期記憶切掉了一大塊。你還在按原來的約定跟它協(xié)作它卻已經(jīng)換了一個(gè)“人格”。這個(gè)項(xiàng)目要解決的問題很具體讓 AI 編碼代理在長(zhǎng)會(huì)話中對(duì)抗上下文壓縮保持對(duì)項(xiàng)目關(guān)鍵狀態(tài)的記憶連續(xù)性。核心思路借鑒了兩個(gè)東西——Unix 的init.d服務(wù)管理模型以及電影《記憶碎片》里那種“用外部載體對(duì)抗短期記憶缺失”的敘事結(jié)構(gòu)。前者提供了一套“開機(jī)自舉、按需拉起、狀態(tài)可查”的機(jī)制后者提供了一種“把關(guān)鍵事實(shí)寫下來、每次操作前先讀一遍”的工作范式。適合誰(shuí)來參考如果你滿足下面任意一條這篇內(nèi)容對(duì)你就直接有用一是用 AI 代理做中大型項(xiàng)目重構(gòu)會(huì)話經(jīng)常超過幾十輪二是自己搭過基于 API 的編碼助手被上下文管理折磨過三是單純好奇“怎么讓一個(gè)會(huì)失憶的助手依然可靠地干活”。下面我會(huì)把整套設(shè)計(jì)思路、關(guān)鍵實(shí)現(xiàn)、踩過的坑和排查方法完整拆開講。2. 整體設(shè)計(jì)思路用 init.d 的自舉模型對(duì)抗記憶丟失2.1 為什么選“服務(wù)自舉”而不是“加大上下文”最直覺的方案是換更大的上下文窗口或者把壓縮閾值調(diào)高。我試過治標(biāo)不治本。原因有兩個(gè)第一窗口再大也有上限項(xiàng)目一大照樣溢出第二即使不溢出超長(zhǎng)上下文里的信息密度會(huì)被稀釋模型對(duì)早期關(guān)鍵信息的注意力本來就會(huì)衰減。這就像你往一個(gè)房間里不斷堆東西堆到一定程度找任何一件東西都變難了。所以我換了個(gè)思路不指望模型自己記住而是讓它在每次需要的時(shí)候能主動(dòng)“查”到。這正好對(duì)應(yīng) Unix 的init.d模型——系統(tǒng)啟動(dòng)時(shí)不需要把所有服務(wù)都塞進(jìn)內(nèi)存而是通過一套約定好的腳本目錄按需啟動(dòng)、查詢狀態(tài)、重啟服務(wù)。代理也一樣它不需要把整個(gè)項(xiàng)目歷史背在腦子里只需要知道“去哪里查、怎么查、查完怎么用”。具體來說我把項(xiàng)目里那些“代理必須始終知道”的信息抽出來固化到一組外部文件里形成一套類似init.d的目錄約定。代理在每次關(guān)鍵操作前先執(zhí)行一個(gè)“自舉腳本”把這些文件讀進(jìn)來重建工作記憶。這樣即使平臺(tái)側(cè)把早期對(duì)話壓縮掉了代理也能通過這套機(jī)制把關(guān)鍵狀態(tài)“拉回來”。2.2 《記憶碎片》范式把“記憶”外化成可重復(fù)讀取的載體《記憶碎片》里主角的做法很極端但很有效他記不住新發(fā)生的事于是把關(guān)鍵信息紋在身上、拍成照片、寫成紙條每次行動(dòng)前先看一遍。這個(gè)范式遷移到編碼代理上核心就一句話——不要依賴對(duì)話歷史作為唯一記憶載體把關(guān)鍵事實(shí)寫成代理每次都會(huì)讀的文件。我落地時(shí)把它拆成三層第一層是“紋身”項(xiàng)目級(jí)的不可變約定比如目錄結(jié)構(gòu)、命名規(guī)范、技術(shù)棧版本。這些寫在PROJECT_CONTRACT.md里代理每次自舉必讀。第二層是“照片”當(dāng)前任務(wù)的動(dòng)態(tài)狀態(tài)比如“正在重構(gòu)哪個(gè)模塊”“已經(jīng)改了哪些文件”“下一步要做什么”。寫在TASK_STATE.md里隨任務(wù)推進(jìn)更新。第三層是“紙條”臨時(shí)的、一次性的上下文比如某個(gè)函數(shù)的當(dāng)前實(shí)現(xiàn)、某次報(bào)錯(cuò)的完整堆棧。這些放在SCRATCH.md里用完即棄。關(guān)鍵在于這三層文件不是給人看的文檔而是給代理讀的“記憶載體”。它們的格式、位置、讀取時(shí)機(jī)都是被自舉腳本嚴(yán)格約定的代理不需要“想起來”去讀而是流程強(qiáng)制它讀。2.3 方案選型的取舍為什么不直接用向量庫(kù)或 RAG有人會(huì)問為什么不搞一套向量檢索把歷史對(duì)話存進(jìn)去需要時(shí)檢索出來我實(shí)際對(duì)比過對(duì)于編碼代理這個(gè)場(chǎng)景向量庫(kù)有幾個(gè)硬傷一是檢索結(jié)果不可控你沒法保證它一定召回“那個(gè)函數(shù)簽名”而編碼場(chǎng)景對(duì)精確性要求極高二是引入額外依賴調(diào)試鏈路變長(zhǎng)出問題很難定位是檢索錯(cuò)了還是模型理解錯(cuò)了三是延遲每次操作前檢索一遍交互體驗(yàn)會(huì)變差。而基于文件的自舉方案本質(zhì)上是“確定性檢索”——文件路徑和內(nèi)容是固定的代理讀到的就是寫進(jìn)去的沒有召回率問題。代價(jià)是需要人工維護(hù)這些文件的結(jié)構(gòu)但換來的是可預(yù)測(cè)、可調(diào)試、零額外依賴。對(duì)于個(gè)人開發(fā)者和小團(tuán)隊(duì)這個(gè)取舍是劃算的。3. 核心細(xì)節(jié)解析自舉腳本、狀態(tài)文件與讀取時(shí)機(jī)3.1 自舉腳本的設(shè)計(jì)代理的“開機(jī)第一件事”自舉腳本是整個(gè)機(jī)制的入口。它的職責(zé)很簡(jiǎn)單按固定順序讀取那三層記憶文件拼裝成一段結(jié)構(gòu)化的“工作記憶摘要”注入到當(dāng)前對(duì)話的最前面。我用的是 shell 腳本加一個(gè)輕量的模板拼接核心邏輯大概是這樣#!/usr/bin/env bash # bootstrap.sh - 代理自舉腳本 # 按約定順序讀取記憶文件輸出結(jié)構(gòu)化工作記憶 CONTRACT.agent/PROJECT_CONTRACT.md STATE.agent/TASK_STATE.md SCRATCH.agent/SCRATCH.md echo WORKING MEMORY BOOTSTRAP echo echo --- [LAYER 1: CONTRACT] --- cat $CONTRACT 2/dev/null || echo (empty) echo echo --- [LAYER 2: TASK STATE] --- cat $STATE 2/dev/null || echo (empty) echo echo --- [LAYER 3: SCRATCH] --- cat $SCRATCH 2/dev/null || echo (empty) echo echo END BOOTSTRAP 這個(gè)腳本本身不復(fù)雜復(fù)雜的是它背后的約定代理在每次開始一個(gè)新任務(wù)、或者感覺上下文可能被壓縮之后必須先跑一遍這個(gè)腳本。我在系統(tǒng)提示里明確寫了這條規(guī)則并且用“如果你不確定當(dāng)前項(xiàng)目狀態(tài)先執(zhí)行 bootstrap”這樣的措辭反復(fù)強(qiáng)化。注意自舉腳本的輸出要控制長(zhǎng)度。我一開始把整個(gè)PROJECT_CONTRACT.md都塞進(jìn)去結(jié)果每次自舉就吃掉幾千 token反而加速了壓縮。后來改成只讀“契約摘要”部分完整契約放在文件里按需查閱。3.2 三層記憶文件的格式約定文件格式直接決定了代理能不能高效讀取。我踩過的坑是一開始用自由格式的 Markdown結(jié)果代理每次讀進(jìn)來的理解都不太一樣有時(shí)候把注釋當(dāng)成了指令。后來我改成半結(jié)構(gòu)化的格式用固定的標(biāo)題和鍵值對(duì)穩(wěn)定性好了很多。PROJECT_CONTRACT.md的結(jié)構(gòu)大概是這樣# PROJECT CONTRACT (IMMUTABLE) ## STACK - language: TypeScript 5.x - runtime: Node 20 - test: vitest - package-manager: pnpm ## STRUCTURE - src/components: UI 組件每個(gè)組件一個(gè)目錄 - src/services: 業(yè)務(wù)邏輯禁止直接操作 DOM - src/utils: 純函數(shù)必須有單元測(cè)試 ## NAMING - 組件文件: PascalCase.tsx - 工具函數(shù): camelCase.ts - 常量: UPPER_SNAKE_CASE ## FORBIDDEN - 禁止在 services 層引入 React - 禁止使用 any - 禁止跳過測(cè)試直接提交TASK_STATE.md是動(dòng)態(tài)的我要求代理在每次完成一個(gè)子任務(wù)后更新它# TASK STATE ## CURRENT - task: 重構(gòu)用戶認(rèn)證模塊 - phase: 提取 token 校驗(yàn)邏輯 - last-file: src/services/auth/verify.ts ## DONE - [x] 梳理現(xiàn)有認(rèn)證流程 - [x] 提取 token 解析函數(shù) ## NEXT - [ ] 提取 token 校驗(yàn)函數(shù) - [ ] 補(bǔ)充單元測(cè)試 - [ ] 更新調(diào)用方 ## BLOCKERS - 無(wú)SCRATCH.md則是用完即清的臨時(shí)區(qū)代理可以往里寫任何它覺得“這次需要記住但下次不一定需要”的東西。3.3 讀取時(shí)機(jī)的判斷什么時(shí)候該自舉這是整個(gè)機(jī)制里最需要經(jīng)驗(yàn)的部分。自舉太頻繁浪費(fèi) token 和交互輪次自舉太少代理已經(jīng)失憶了才補(bǔ)救為時(shí)已晚。我總結(jié)了幾條觸發(fā)規(guī)則新任務(wù)開始時(shí)必讀不管上下文看起來多完整新任務(wù)一律先自舉。連續(xù)對(duì)話超過 20 輪后每 5 輪自舉一次這是我實(shí)測(cè)下來壓縮開始變得明顯的臨界區(qū)間。代理出現(xiàn)“記憶模糊”信號(hào)時(shí)立即自舉比如它開始問“你之前說的那個(gè)文件叫什么來著”或者引用了不存在的路徑。執(zhí)行破壞性操作前必讀刪除文件、批量重命名、改公共接口之前先自舉確認(rèn)當(dāng)前狀態(tài)。實(shí)操心得我在系統(tǒng)提示里加了一條“如果你對(duì)當(dāng)前項(xiàng)目狀態(tài)有任何不確定先執(zhí)行 bootstrap 再繼續(xù)”這條規(guī)則救了我很多次。代理主動(dòng)自舉的成本遠(yuǎn)低于它基于錯(cuò)誤記憶干活的成本。4. 實(shí)操過程從零搭一套抗壓縮的代理工作流4.1 初始化項(xiàng)目記憶目錄第一步是在項(xiàng)目根目錄建一個(gè).agent/目錄把三層記憶文件的模板放進(jìn)去。我建議用腳本初始化避免每次手動(dòng)建mkdir -p .agent touch .agent/PROJECT_CONTRACT.md touch .agent/TASK_STATE.md touch .agent/SCRATCH.md然后把bootstrap.sh放到.agent/下并賦予執(zhí)行權(quán)限。接著在.gitignore里決定哪些文件要版本控制——我的做法是PROJECT_CONTRACT.md和TASK_STATE.md納入版本控制SCRATCH.md忽略因?yàn)樗桥R時(shí)的。4.2 把自舉規(guī)則寫進(jìn)系統(tǒng)提示這一步是成敗關(guān)鍵。代理不會(huì)自動(dòng)知道要去讀這些文件你必須在系統(tǒng)提示里用明確的、可執(zhí)行的指令告訴它。我的系統(tǒng)提示里相關(guān)部分大概是這樣你是一個(gè)編碼代理工作在一個(gè)可能發(fā)生上下文壓縮的長(zhǎng)會(huì)話環(huán)境中。 在以下情況你必須先執(zhí)行 .agent/bootstrap.sh 并閱讀其輸出 1. 開始任何新任務(wù)之前 2. 連續(xù)對(duì)話超過 20 輪后每 5 輪執(zhí)行一次 3. 當(dāng)你對(duì)項(xiàng)目結(jié)構(gòu)、命名規(guī)范、當(dāng)前任務(wù)狀態(tài)有任何不確定時(shí) 4. 執(zhí)行刪除、重命名、修改公共接口等破壞性操作之前 執(zhí)行 bootstrap 后以輸出內(nèi)容為準(zhǔn)重建你的工作記憶。 如果 bootstrap 輸出與你的對(duì)話記憶沖突以 bootstrap 輸出為準(zhǔn)。最后那句“以 bootstrap 輸出為準(zhǔn)”很重要。壓縮后的對(duì)話記憶可能是錯(cuò)的但文件是可信的必須明確優(yōu)先級(jí)。4.3 一次完整的任務(wù)執(zhí)行記錄我拿一個(gè)真實(shí)的重構(gòu)任務(wù)走一遍流程你能看到自舉是怎么嵌入的。任務(wù)是“把認(rèn)證模塊里的 token 校驗(yàn)邏輯抽成獨(dú)立函數(shù)”。第 1 步任務(wù)開始代理自舉。它執(zhí)行bootstrap.sh讀到契約里的“services 層禁止引入 React”“工具函數(shù)必須有測(cè)試”讀到任務(wù)狀態(tài)里的“當(dāng)前在提取 token 校驗(yàn)邏輯”讀到 scratch 為空。基于這些它確認(rèn)了工作目錄和約束。第 2 步代理讀取目標(biāo)文件。它打開src/services/auth/verify.ts看到當(dāng)前的校驗(yàn)邏輯內(nèi)聯(lián)在login函數(shù)里。它沒有直接改而是先更新TASK_STATE.md把 phase 改成“提取 token 校驗(yàn)函數(shù)”。第 3 步代理執(zhí)行提取。它新建src/services/auth/validateToken.ts把邏輯搬過去然后在原文件里 import 新函數(shù)。這一步它遵守了契約里的命名規(guī)范camelCase 文件名。第 4 步代理補(bǔ)充測(cè)試。因?yàn)槠跫s里寫了“工具函數(shù)必須有單元測(cè)試”它自動(dòng)去src/services/auth/__tests__/下建了測(cè)試文件。這一步如果沒有契約約束它很可能會(huì)跳過。第 5 步代理更新狀態(tài)。它把TASK_STATE.md里的 DONE 加一條NEXT 里劃掉“提取 token 校驗(yàn)函數(shù)”phase 改成“補(bǔ)充單元測(cè)試”。第 6 步會(huì)話繼續(xù)了 30 多輪中間平臺(tái)觸發(fā)了一次壓縮。代理在第 35 輪時(shí)感覺要改調(diào)用方它主動(dòng)執(zhí)行了 bootstrap重新讀到契約和最新狀態(tài)確認(rèn)了“調(diào)用方在src/pages/Login.tsx”然后準(zhǔn)確地去改了那個(gè)文件。如果沒有自舉它很可能已經(jīng)忘了調(diào)用方在哪。這個(gè)流程跑下來最直觀的感受是代理的行為變得可預(yù)測(cè)了。它不再依賴“運(yùn)氣好沒被壓縮”而是有一套確定的機(jī)制把關(guān)鍵狀態(tài)拉回來。4.4 參數(shù)與閾值的選擇依據(jù)上面提到的“20 輪”“5 輪”這些數(shù)字不是拍腦袋來的。我做過一組粗略的測(cè)試在典型的中等復(fù)雜度項(xiàng)目里對(duì)話輪次和 token 消耗大致是線性關(guān)系每輪平均消耗 800 到 1500 token取決于代碼塊大小。當(dāng)總 token 逼近窗口的 70% 到 80% 時(shí)壓縮開始明顯影響早期信息的保真度。按每輪 1000 token 估算20 輪大約消耗 2 萬(wàn) token對(duì)于 32k 窗口來說已經(jīng)過半所以我把 20 輪設(shè)為第一個(gè)警戒線。至于“每 5 輪自舉一次”是因?yàn)樽耘e本身消耗大約 500 到 1000 token太頻繁會(huì)加速消耗。5 輪一次是在“記憶新鮮度”和“token 成本”之間取的平衡。你可以根據(jù)自己的窗口大小和每輪 token 消耗調(diào)整公式大概是自舉間隔 窗口大小 × 0.3 / 每輪平均 token。5. 常見問題與排查技巧實(shí)錄5.1 代理不執(zhí)行自舉怎么辦這是最常見的問題。原因通常有三個(gè)一是系統(tǒng)提示里的指令不夠明確代理把它當(dāng)成了“建議”而不是“規(guī)則”二是自舉腳本路徑不對(duì)代理執(zhí)行失敗后就放棄了三是代理在壓縮后連“要自舉”這件事都忘了。針對(duì)第一個(gè)原因我把指令從“你可以執(zhí)行 bootstrap”改成了“你必須執(zhí)行 bootstrap”并且加了“如果輸出與記憶沖突以輸出為準(zhǔn)”的優(yōu)先級(jí)聲明。針對(duì)第二個(gè)我在腳本里加了容錯(cuò)路徑不存在時(shí)輸出明確的錯(cuò)誤信息而不是靜默失敗。針對(duì)第三個(gè)這是最棘手的——如果代理連自舉規(guī)則都忘了那就沒轍了。我的應(yīng)對(duì)是在每個(gè)任務(wù)的第一個(gè)用戶消息里手動(dòng)帶上“先執(zhí)行 bootstrap”的提醒相當(dāng)于人工兜底。5.2 自舉輸出太長(zhǎng)反而加速壓縮前面提過這個(gè)坑。解決辦法是分層讀取自舉時(shí)只讀契約的“摘要區(qū)”和任務(wù)狀態(tài)的“當(dāng)前區(qū)”完整內(nèi)容放在文件里代理需要時(shí)再單獨(dú)讀。我在PROJECT_CONTRACT.md頂部加了一個(gè)## SUMMARY區(qū)只放最關(guān)鍵的 5 到 10 條約束自舉腳本只讀這個(gè)區(qū)。5.3 狀態(tài)文件被代理改亂代理有時(shí)候會(huì)“過度更新”狀態(tài)文件把一些不該記的東西寫進(jìn)去或者格式改得亂七八糟。我的應(yīng)對(duì)是給狀態(tài)文件定一個(gè)嚴(yán)格的模板并且在系統(tǒng)提示里寫明“只允許在指定區(qū)塊內(nèi)追加或修改不允許改變文件結(jié)構(gòu)”。另外TASK_STATE.md納入版本控制后改亂了我可以直接git diff看它改了什么必要時(shí)回滾。5.4 常見問題速查表問題現(xiàn)象可能原因排查方法解決手段代理引用不存在的文件路徑上下文壓縮導(dǎo)致記憶錯(cuò)亂讓它執(zhí)行 bootstrap 后重新確認(rèn)強(qiáng)化自舉觸發(fā)規(guī)則代理跳過測(cè)試直接改代碼契約約束被壓縮丟失檢查 bootstrap 是否讀到契約把測(cè)試要求寫進(jìn)契約摘要區(qū)自舉后行為仍不對(duì)狀態(tài)文件本身是錯(cuò)的人工檢查 TASK_STATE.md修正狀態(tài)文件并回滾錯(cuò)誤操作自舉腳本執(zhí)行失敗路徑或權(quán)限問題手動(dòng)跑一遍腳本看報(bào)錯(cuò)修正路徑加容錯(cuò)輸出token 消耗過快自舉太頻繁或輸出太長(zhǎng)統(tǒng)計(jì)每輪 token 消耗調(diào)整自舉間隔精簡(jiǎn)輸出5.5 幾個(gè)我踩過的坑第一個(gè)坑是把契約寫得太細(xì)。一開始我把所有編碼規(guī)范都塞進(jìn)契約結(jié)果自舉一次就吃掉大量 token。后來我只保留“代理容易違反且后果嚴(yán)重”的約束比如“禁止 any”“services 層禁止引入 React”其他細(xì)節(jié)讓它按常規(guī)習(xí)慣來。第二個(gè)坑是狀態(tài)文件更新滯后。代理有時(shí)候干完活忘了更新TASK_STATE.md導(dǎo)致下次自舉讀到的是舊狀態(tài)。我的應(yīng)對(duì)是在系統(tǒng)提示里把“完成任務(wù)后更新狀態(tài)”設(shè)為強(qiáng)制步驟并且在自舉腳本里加了一個(gè)檢查如果狀態(tài)文件的修改時(shí)間早于最近一次代碼提交就輸出警告。第三個(gè)坑是過度依賴自舉。有一段時(shí)間我讓代理每輪都自舉結(jié)果交互變得很慢而且 token 消耗翻倍。后來我改成按需觸發(fā)體驗(yàn)好了很多。這個(gè)機(jī)制的定位是“保險(xiǎn)”不是“日常操作”別把它用成每輪必跑的儀式。6. 把這套機(jī)制遷移到你的工作流這套東西的核心其實(shí)不是那幾個(gè)腳本而是一個(gè)觀念轉(zhuǎn)變不要把 AI 代理的記憶當(dāng)成理所當(dāng)然要像對(duì)待一個(gè)會(huì)失憶的協(xié)作者一樣給它準(zhǔn)備好外部記憶載體。Unix 的 init.d 給了我們“按需自舉”的模型《記憶碎片》給了我們“關(guān)鍵事實(shí)外化”的范式兩者結(jié)合就能讓代理在長(zhǎng)會(huì)話里保持可靠。遷移到你的項(xiàng)目時(shí)我建議從最小可用版本開始先建一個(gè)PROJECT_CONTRACT.md只寫 5 條最重要的約束再建一個(gè)TASK_STATE.md只記當(dāng)前任務(wù)和下一步然后寫一個(gè)最簡(jiǎn)單的 bootstrap 腳本把這兩個(gè)文件拼起來輸出。跑幾個(gè)任務(wù)感受一下代理在壓縮后的表現(xiàn)有沒有改善再?zèng)Q定要不要加第三層 scratch 和更復(fù)雜的觸發(fā)規(guī)則。最后分享一個(gè)我最近在用的技巧在TASK_STATE.md里加一個(gè)## HANDOFF區(qū)專門寫給“下一個(gè)自舉的代理”看。當(dāng)我知道這次會(huì)話可能要結(jié)束了我會(huì)讓代理把當(dāng)前進(jìn)度、未解決的問題、下一步建議寫進(jìn) HANDOFF 區(qū)。下次新會(huì)話開始時(shí)代理自舉讀到 HANDOFF就能無(wú)縫接上。這個(gè)技巧把“抗壓縮”延伸到了“跨會(huì)話”實(shí)測(cè)下來很穩(wěn)。