从 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