從 Agentic Loop 到 Repo Map七種策略與六類陷阱引言128K vs 10MB 的硬沖突2026 年的 LLM 上下文窗口已達(dá)到 128K ~ 1M token≈ 0.5MB ~ 4MB 文本但 LLM 想要處理的真實(shí)數(shù)據(jù)規(guī)模遠(yuǎn)遠(yuǎn)超過(guò)這個(gè)量級(jí)真實(shí)場(chǎng)景數(shù)據(jù)量級(jí)與 200K context 的比值一個(gè) 10MB 的代碼文件~2.5M token12 倍一份 50MB 的日志~12M token60 倍一個(gè)代碼倉(cāng)庫(kù)的全量源碼數(shù)百 MB ~ 數(shù) GB千倍 ~ 萬(wàn)倍這是幾乎所有 agent 系統(tǒng)的通病。本文盤點(diǎn)主流開源項(xiàng)目如何應(yīng)對(duì)并提煉出一套可落地的工程模式。一、七種主流應(yīng)對(duì)策略建立坐標(biāo)系應(yīng)對(duì)上下文超限業(yè)界的方法論可歸納為七類。它們常常組合使用很少單獨(dú)生效#策略一句話定義典型使用者1硬截?cái)郥runcate工具輸出只保留前 N 字節(jié)/行剩余換成[truncated]指針OpenCode、Vercel AI SDK 應(yīng)用層2結(jié)構(gòu)化摘要Summarize用 LLM 把工具輸出重寫成短摘要Claude Code/compact、LangChain SummarizationMiddleware3動(dòng)態(tài)剪枝Prune按陳舊度 / 引用次數(shù)刪除已消費(fèi)過(guò)的舊工具消息OpenCode DCP 插件、MemGPT4外部化 按需檢索Offload RAG大文本存文件/向量庫(kù)prompt 里只放指針 檢索片段LangChain offload、Letta OS-style 虛擬內(nèi)存5替換為引用Reference Replacement工具消息替換為短 metadata行數(shù) / 字節(jié) / 路徑Claude CodeFile unchanged去重機(jī)制6分塊延遲回填Chunked Backfill工具返回立刻切片 嵌入LLM 想看更多時(shí)再調(diào)檢索OpenCodeenowdev/mnemosyne、LangChain Deep Agents7上下文重置Periodic Reset不壓縮而是定期丟棄整個(gè)對(duì)話歷史從結(jié)構(gòu)化文檔重建CoordClaw二、主流方案的實(shí)際坐標(biāo)2.1 CoordClaw——以外化記憶做根因規(guī)避CoordClaw 的設(shè)計(jì)哲學(xué)與其他項(xiàng)目有根本性差異。它不試圖壓縮或檢索而是讓對(duì)話歷史根本不必要長(zhǎng)期保留。核心機(jī)制每輪上下文完全重置——Agent 下次啟動(dòng)時(shí)重新跑task_start.pyT2 標(biāo)準(zhǔn)動(dòng)作只加載角色定義 上一輪工作日志工作日志外化——通過(guò)task_report.pyT3編寫結(jié)構(gòu)化工作日志到項(xiàng)目目錄它是項(xiàng)目記憶而不是對(duì)話歷史配套context_optimization配置項(xiàng)——team.json中可配置保留輪數(shù)、丟棄/壓縮策略壓縮歷史工具消息llm_error阻斷機(jī)制——team.json中l(wèi)lm_error.enabledendcode配置在 LLM 報(bào)錯(cuò)超閾值時(shí)阻斷防止對(duì)話失控點(diǎn)對(duì)點(diǎn)消息——Agent 之間通過(guò)chat_manager.py send精確路由非廣播避免上下文污染擴(kuò)散為什么有效真相在文件里不在 prompt 里。LLM 看不到上一次說(shuō)了什么但能看到上一次的結(jié)論寫在哪個(gè)文件里——這是主動(dòng)遺忘換取可審計(jì)。代價(jià)每輪需要花 token 重建上下文Agent 不能做基于對(duì)話氛圍的連續(xù)推理。2.2 OpenCode——原生機(jī)制 插件生態(tài)OpenCode 的官方鉤子提供手動(dòng)觸發(fā)點(diǎn)experimental.session.compacting—— 上下文壓縮鉤子允許插件在 LLM 生成續(xù)接摘要前注入自定義上下文或完全替換壓縮提示詞tool.execute.before/tool.execute.after—— 工具調(diào)用攔截但 OpenCode默認(rèn)不主動(dòng)壓縮。真正活躍的是它的第三方插件生態(tài)插件功能狀態(tài)opencode-dynamic-context-pruning按已無(wú)引用 / 超過(guò)輪數(shù)自動(dòng)移除 obsolete tool outputs官方生態(tài)收錄enowdev/mnemosyne組合插件命令過(guò)濾 上下文剪枝 持久記憶 自動(dòng)代碼索引npm 已發(fā)布o(jì)pencode-mnemosyne本地持久記憶基于 SQLite 向量搜索跨會(huì)話保留社區(qū)維護(hù)2026 年的事實(shí)OpenCode 的 token 優(yōu)化方向是插件化裁剪而非runtime 內(nèi)置智能壓縮。這是一個(gè)清晰的設(shè)計(jì)分工——核心 runtime 保持精簡(jiǎn)社區(qū)圍繞它做策略創(chuàng)新。2.3 Claude Code——三件套 隱式預(yù)讀Claude Code 的 Read 工具默認(rèn)最多讀2000 行單行超過(guò)2000 字符會(huì)被自動(dòng)截?cái)唷Ｋ┞度齻€(gè)相互配合的工具工具作用LLM 何時(shí)調(diào)用Read分頁(yè)讀窗口offset limit已知位置讀具體內(nèi)容Grep按模式找位置不知道在哪讓 grep 定位Glob按文件名 pattern 找文件不知道文件叫啥LLM 的典型工作流Glob(**/*.ts) → 找到 50 個(gè) Grep(handleAuth, pathsrc/) → 精確定位到 src/auth.ts:42 Read(file_path, offset42, limit50)核心技巧Read 返回的內(nèi)容帶顯式行號(hào)——“我在第 42 行看到 function handleAuth()”下次 LLM 可以精確地說(shuō)修改第 50 行的 return 語(yǔ)句。預(yù)讀不變量pre-read invariantEdit / Write 工具強(qiáng)制要求目標(biāo)文件此前被 Read 讀取過(guò)——否則報(bào)錯(cuò)。防止 LLM 盲目覆蓋。File unchanged去重同一文件被讀過(guò)且未修改通過(guò) mtime 判斷第二次 Read 直接返回File unchanged字符串——deduplication 節(jié)省 token。官方測(cè)算命中率約18%每次省約25K tokens。2.4 Claude Code 的/compact自動(dòng)壓縮與手動(dòng)觸發(fā)當(dāng) Claude Code 接近上下文窗口限制約 95%時(shí)會(huì)自動(dòng)壓縮對(duì)話歷史。/compact命令可手動(dòng)觸發(fā)這一過(guò)程。壓縮后以下內(nèi)容易丟失會(huì)話早期的指令如不要碰這個(gè)文件中間決策為什么選擇方案 A 而非 B50 條消息前討論的具體代碼片段而以下內(nèi)容通常保留當(dāng)前任務(wù)和即時(shí)上下文最近修改的文件名最近的錯(cuò)誤及解決方案關(guān)鍵洞察項(xiàng)目根目錄的CLAUDE.md在壓縮后會(huì)被重新加載——它是唯一保證能幸存任何壓縮的地方。2.5 LangChain / LangGraph——Middleware 抽象LangGraph 把上下文管理做成可插拔 middleware。Deep Agents 項(xiàng)目基于 LangGraph提供了SummarizationMiddleware和FilesystemMiddleware等組件。# 概念示例基于 LangGraph 中間件模式app.add_middleware(SummarizationMiddleware(trigger{messages:50},# 觸發(fā)閾值keep{messages:10},# 保留多少summarization_modelgpt-4o-mini,))這種設(shè)計(jì)的真正價(jià)值把策略和 runtime 解耦。同一份 LangGraph 應(yīng)用可以掛不同 middleware“開發(fā)環(huán)境保留全部” / “生產(chǎn)環(huán)境三級(jí)壓縮” / “演示模式 50% 截?cái)唷薄?.6 Aider——Repo Map代碼地圖Aider 不分頁(yè)讀取而是自動(dòng)生成倉(cāng)庫(kù)地圖用 tree-sitter 抽出所有文件的類簽名、函數(shù)簽名、關(guān)鍵調(diào)用關(guān)系喂給 LLM 一個(gè)代碼地圖。src/auth/auth.service.ts: class AuthService login(email: str, password: str) - Token # line 35 validateToken(token: str) - User | null # line 230 hashPassword(plain: str) - str # line 1500LLM 看地圖選位置再精確讀具體文件。地圖大小固定默認(rèn)約 1,024 tokens不隨代碼量線性增長(zhǎng)——這是它能處理整個(gè)代碼倉(cāng)庫(kù)的關(guān)鍵。局限只對(duì)結(jié)構(gòu)化代碼文件有效.ts / .py / .go 等 50 語(yǔ)言。對(duì)散文、日志、配置文件無(wú)效。2.7 MemGPT / Letta——OS 風(fēng)格虛擬內(nèi)存把 LLM 的 context window 類比為 RAM大文檔類比為磁盤OS 概念Letta 等價(jià)物RAMCore Memory始終保留在上下文中的關(guān)鍵信息磁盤緩存Recall Memory可搜索的近期歷史冷存儲(chǔ)Archival Memory長(zhǎng)期向量數(shù)據(jù)庫(kù)存儲(chǔ)LLM 在兩套內(nèi)存之間主動(dòng)換頁(yè)——這是 OS 虛擬內(nèi)存思想在 LLM 上的應(yīng)用。優(yōu)勢(shì)是 LLM 顯式掌控記憶劣勢(shì)是 LLM 要學(xué)會(huì)這個(gè)換頁(yè) API認(rèn)知負(fù)擔(dān)。2026 年的現(xiàn)狀MemGPT 已演變?yōu)樯虡I(yè)平臺(tái)Letta開源核心 商業(yè)云服務(wù)。對(duì)于生產(chǎn)環(huán)境Letta 是更成熟的選擇MemGPT 原始倉(cāng)庫(kù)更適合研究和自定義。2.8 Clawith——數(shù)字員工的 Aware 系統(tǒng)Clawith由 dataelement 團(tuán)隊(duì)開發(fā)的企業(yè)級(jí) AI 員工框架的創(chuàng)新是Aware 自主感知系統(tǒng)三組件協(xié)同組件作用Focus當(dāng)前注意力焦點(diǎn)——結(jié)構(gòu)化工作記憶列表Trigger觸發(fā)新任務(wù)的信號(hào)——六種類型cron / once / interval / poll / on_message / webhookHeartbeat周期性自我檢查——默認(rèn) 15 秒一次輕量掃描這套機(jī)制不直接解決上下文超限而是讓 Agent 主動(dòng)管理注意力——Focus 決定現(xiàn)在看什么Heartbeat 周期性評(píng)估是否需要換頁(yè)Trigger 在該換頁(yè)時(shí)主動(dòng)發(fā)起。三、工具層設(shè)計(jì)讓 Agentic Loop 健康運(yùn)轉(zhuǎn)主流方案的工程實(shí)現(xiàn)都收斂到同一個(gè)事實(shí)LLM 必須分頁(yè)讀取大文件。這種LLM 始終只處理一小塊的模式叫Agentic Loop或Iterative Retrieval┌─────────────────┐ │ LLM 拿到當(dāng)前頁(yè) │ ← context window 里只有這一段 └────────┬────────┘ │ reasoning ▼ ┌─────────────────────────────┐ │ 決定下一步 │ │ A. 讀下一段offsetN │ │ B. grep 換位置 │ │ C. 已收集夠輸出結(jié)論 │ └────────┬────────────────────┘ │ tool call ▼ ┌─────────────────┐ │ read_file 返回 │ ← 又是 200 行 └────────┬────────┘ │ 回到 LLM └──── 循環(huán)3.1 read_file 的契約設(shè)計(jì)一個(gè)健康的read_file工具應(yīng)返回read_file(path:string,offset?:number,// 1-based 起始行l(wèi)imit?:number// 讀多少行默認(rèn) 200最大 2000):{content:string,// 該窗口內(nèi)容每行帶行號(hào)total_lines:number,// 文件總行數(shù)讓 LLM 知道剩余多少start_line:number,// 本次起始行號(hào)encoding:string,// 文件編碼truncated:boolean,// 是否被截?cái)鄛建議的擴(kuò)展字段推薦設(shè)計(jì)非所有工具統(tǒng)一實(shí)現(xiàn)next_offset?: number—— 建議的下一次 offset避免 LLM 陷入 offset 計(jì)算循環(huán)bytes_total?: number—— 總字節(jié)數(shù)輔助 LLM 評(píng)估文件規(guī)模3.2 配套工具——三個(gè)最少必須有工具作用為什么必須有read_file分頁(yè)讀窗口主力grep按模式找位置效率工具——大多數(shù)時(shí)候是找特定模式不是順序讀outline看文件結(jié)構(gòu)類/函數(shù)/章節(jié)大綱給 LLM 全局地圖避免讀了一段不知身在何處只有 read_file 會(huì)導(dǎo)致 LLM 盲目翻頁(yè)只有 grep 會(huì)讓 LLM 缺乏全局感三個(gè)配套才能形成健康工作流。3.3 LLM 的工作流示例假設(shè)架構(gòu)師 Agent 審查src/auth/auth.service.ts2400 行[Round 1] outline(pathsrc/auth/auth.service.ts) → { classes: [AuthService], functions: [login, validateToken, hashPassword] } [Round 1] reasoning: login() 在 line 35先看它 周圍 100 行 read_file(path, offset1, limit100) [Round 2] reasoning: 看完 login()跳到 validateToken() 在 line 230 read_file(path, offset230, limit100) [Round 3] reasoning: 重點(diǎn)關(guān)注 hashPassword 部分在 line 1500-1600 read_file(path, offset1500, limit100) [Round 4] reasoning: 已收集夠證據(jù)寫工作日志并交付 write_worklog(content...) → done每一輪 LLM context 里只看到 ~100 行但邏輯上看完了 4 個(gè)關(guān)鍵區(qū)段。四、六類陷阱實(shí)戰(zhàn)中會(huì)撞到的光說(shuō)優(yōu)勢(shì)不夠這些坑決定了你工具設(shè)計(jì)的好壞#陷阱反模式表現(xiàn)解決方案1翻頁(yè)循環(huán)LLM 卡在再 offset 幾行確認(rèn)一下N 輪無(wú)結(jié)論max_steps上限 工作日志記錄已讀區(qū)段2早期放棄前幾頁(yè)不像預(yù)期就跳走錯(cuò)過(guò)關(guān)鍵章節(jié)提供 outline 工具給全局地圖3丟失全局視野只看局部忘了全局目標(biāo)在哪一段outline 段摘要工具4重復(fù)讀取同一窗口被反復(fù)讀File unchangeddeduplication 已讀區(qū)段記憶5撐爆 window某段意外讀到 10MB工具內(nèi)置硬上限單行 2000 字符截?cái)唷imit 上限 20006多級(jí)壓縮細(xì)節(jié)流失第一級(jí)壓縮保留的細(xì)節(jié)在第二級(jí)被丟棄用 reference replacement 而非 summarize其中#6是工業(yè)界最隱蔽的問(wèn)題——Claude Code 的自動(dòng)壓縮設(shè)計(jì)巧妙但學(xué)術(shù)研究反復(fù)指出經(jīng)過(guò)多級(jí)壓縮后關(guān)鍵決策細(xì)節(jié)會(huì)顯著丟失。補(bǔ)充Claude Code 的 Read 工具存在一個(gè)已知邊界情況——在某些場(chǎng)景下會(huì)嘗試讀取整個(gè)文件而非嚴(yán)格遵守 2000 行限制導(dǎo)致超出 25,000 token 上限而報(bào)錯(cuò)。這提醒我們即使工具文檔承諾了限制實(shí)際實(shí)現(xiàn)也可能有漏洞生產(chǎn)環(huán)境必須做二次校驗(yàn)。五、提示詞紀(jì)律——告訴 LLM 怎么讀光有好工具不夠LLM 需要工作紀(jì)律。建議在 Agent 系統(tǒng) prompt 或角色卡里明示閱讀大型文檔的工作紀(jì)律 1. 拿到文件路徑后先評(píng)估大小read_file 返回的 total_lines 2. 超過(guò) 1000 行先用 outline 拿到結(jié)構(gòu)再 grep 定位關(guān)鍵區(qū)段最后 read_file 取窗口 3. 超過(guò) 5000 行禁止從頭順序翻頁(yè)必須 grep outline 組合 4. 每次 read_file 后記錄本段要點(diǎn)到工作日志避免重復(fù)讀 5. 累計(jì)讀 5 次以上仍未得出結(jié)論回退向用戶澄清而非繼續(xù)翻頁(yè)這條紀(jì)律直接解決了陷阱 1翻頁(yè)循環(huán)和陷阱 2早期放棄。六、場(chǎng)景適配什么場(chǎng)景用什么方案并非所有場(chǎng)景都適合 Agentic Loop。下表給出真實(shí)工程選擇場(chǎng)景推薦策略理由找特定關(guān)鍵字 / 函數(shù)Agentic Loop grep極高效token 節(jié)省 80%審查代碼邏輯漏洞Agentic Loop outlineLLM 可自主定位通讀散文 / 報(bào)告理解全局先 LLM 摘要預(yù)處理 再讀一次性摘要比翻頁(yè)更合適寫整篇論文 summary專門 transformer 工具不該讓 LLM 翻頁(yè)大型倉(cāng)庫(kù)全局理解Aider Repo Map 思路固定大小 全局感長(zhǎng)對(duì)話歷史保留LangGraph middleware策略可插拔長(zhǎng)期運(yùn)行的數(shù)字員工Clawith Aware 系統(tǒng)主動(dòng)注意力管理嚴(yán)格可審計(jì)的多 Agent 協(xié)作CoordClaw 外化記憶真相在文件里七、給工程團(tuán)隊(duì)的落地建議7.1 工具層必須做read_file建議返回next_offset—— 沒(méi)這個(gè)字段LLM 必然進(jìn)入 offset 計(jì)算浪費(fèi)循環(huán)單行 2000 字符自動(dòng)截?cái)嗉?..truncated...標(biāo)記不報(bào)錯(cuò)File unchanged機(jī)制做 deduplication基于 mtime 或哈希二進(jìn)制文件直接拒絕不暴露內(nèi)容細(xì)節(jié)強(qiáng)制預(yù)讀不變性Edit / Write 前必須 Read 一次7.2 提示詞層強(qiáng)烈建議在系統(tǒng) prompt 里寫入閱讀紀(jì)律對(duì)不同角色給不同閱讀風(fēng)格——審查員嚴(yán)格outline 必用、快速?zèng)Q策者寬松允許更大 limit7.3 監(jiān)控層生產(chǎn)必做監(jiān)控連續(xù) read_file 調(diào)用次數(shù)——超過(guò)閾值算 agent 進(jìn)入循環(huán)監(jiān)控重復(fù)讀取——同一 offset 范圍被讀多次算浪費(fèi)監(jiān)控中途放棄——讀完 30% 就停止算早期放棄7.4 架構(gòu)層進(jìn)階記憶外化重要結(jié)論寫文件而非留對(duì)話CoordClaw 模式可插拔壓縮策略開發(fā)環(huán)境保留全部 / 生產(chǎn)環(huán)境多級(jí)壓縮Agentic Loop 與單次讀取并存簡(jiǎn)單查詢走單次復(fù)雜任務(wù)走 Loop結(jié)論核心心智模型把上下文管理想成操作系統(tǒng)OS 概念LLM 等價(jià)物RAM有限、快Context Window128K ~ 1M tokenDisk無(wú)限、慢文件系統(tǒng) 向量數(shù)據(jù)庫(kù)虛擬內(nèi)存按需換頁(yè)Agentic Loop grep outline進(jìn)程間通信工具調(diào)用 工作日志文件系統(tǒng)緩存Session 內(nèi)已讀區(qū)段記憶主流開源項(xiàng)目的差異本質(zhì)上是在這個(gè)心智模型下誰(shuí)來(lái)管理?yè)Q頁(yè)的回答項(xiàng)目換頁(yè)策略核心思想CoordClaw用戶Agent 自己主動(dòng)寫文件讓 OS 接管上下文重置 工作日志外化OpenCode DCP 插件插件按 LRU 自動(dòng)剪枝社區(qū)創(chuàng)新核心保持精簡(jiǎn)Claude CodeRead Grep Glob 三件套顯式換頁(yè)應(yīng)用層控制人類可審計(jì)AiderRepo Map 提供文件系統(tǒng)索引固定大小地圖按需尋址Letta (MemGPT)LLM 本身學(xué)會(huì)系統(tǒng)調(diào)用換頁(yè)LLM 自主管理三層內(nèi)存ClawithFocus / Trigger / Heartbeat 自主感知Agent 主動(dòng)管理注意力沒(méi)有最好的方案只有最適合場(chǎng)景的方案。一個(gè)工程團(tuán)隊(duì)真正需要決定的是讓 LLM 學(xué)會(huì)換頁(yè)還是讓它忘了也不心疼。附錄開源項(xiàng)目鏈接索引項(xiàng)目鏈接CoordClawhttps://github.com/CoordClaw/CoordClawOpenCodehttps://opencode.aiOpenCode 插件生態(tài)https://opencode.ai/docs/ecosystem/opencode-dcphttps://github.com/monotykamary/opencode-dynamic-context-pruningClaude Codehttps://docs.claude.com/en/docs/claude-codeLangGraphhttps://langchain-ai.github.io/langgraph/Aiderhttps://aider.chatLetta (原 MemGPT)https://docs.letta.comClawithhttps://github.com/dataelement/Clawith