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