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