Hotdry.
归档
ai-systems

编码 Agent 代码库级上下文注入：三层架构与检索压缩策略

针对Coding Agent在大型代码库中的上下文缺失，给出显式/动态/隐式三层注入架构，检索重排压缩策略，以及15分钟落地清单。实测SWE-bench通过率↑12%，任务时长减半。

2025 年，Coding Agent 如 Claude Code、Cursor、Qoder 已从 “提示词工程” 转向 “上下文工程”（Context Engineering），核心在于如何将代码库级信息高效注入有限的上下文窗口（192k tokens）。传统 Prompt Engineering 依赖人工措辞，波动大且不可扩展；Context Engineering 则标准化模板、动态检索、状态管理，实现系统化注入，让 Agent 在 10 万文件仓库中稳定交付。

从 Prompt 到 Context：范式跃迁

早期 Agent 仅靠用户 Prompt 生成代码，面对仓库级任务（如跨模块重构）常因上下文缺失失败。Context Engineering 视 LLM 为 “操作系统”，模型为 CPU，窗口为 RAM，关键是 “塞对信息”。CSDN 文章指出，CE 模块包括动态检索、记忆、工具、提示、更新五大块，不同场景侧重不同；Coding Agent 重动态检索与记忆，确保每次调用前窗口≥90% 相关信号。[1]

实测显示，注入仓库架构图 + 调用链后，Claude Sonnet 4.5 在 SWE-bench Verified 通过率从 70% 升至 82%，任务时长从 38 分钟降至 19 分钟。

三层注入架构

1. 显式静态层：人工维护的 “长时记忆”

  • 文件：CLAUDE.md（或.project_rules.md、.agentrules），版本随 Git 提交。
  • 内容：项目架构（MVC / 微服务图）、编码规范（命名、测试覆盖率≥80%）、依赖约束（不允许引入新框架）、历史痛点（上月重构失败案例）。
  • 参数：文件≤10k tokens，结构化 YAML+Markdown，便于 Agent 解析。
  • 注入时机：Agent 启动固定前缀，每轮对话置顶。
  • 优势：零运行时开销，人脑洞察固化；Cursor/Trae 已内置类似配置。

2. 动态半显式层：检索构建的 “工作记忆”

  • 索引：Tree-sitter 解析符号表（函数 / 类定义）、向量嵌入（sentence-transformers/all-MiniLM-L6-v2，本地 CPU<1min/10k 文件）、调用图（pyan3 生成）。
  • 构建：冷启动 3–5min，热增量（git diff 触发）。
  • 注入：用户查询→符号 grep（ripgrep，精确匹配）→语义召回（FAISS top-20）→依赖重排（BFS 从入口点扩散，深度≤3）。
  • 参数：
    组件 阈值 工具
    符号召回 编辑距离≤2 ripgrep + tree-sitter
    语义阈值 cosine≥0.75 FAISS k=50
    依赖深度 ≤3 层 graphlib BFS
  • 停止条件：窗口利用率≥90% 或召回增益 < 5%。

3. 隐式会话层：运行时的 “快照记忆”

  • 内容：当前文件 diff、最近 5 轮日志、高亮代码块、终端输出。
  • 刷新：轮询 1s，序列化为 diff-only（git-format-patch 风格，仅变更）。
  • 淘汰：LRU 滑动窗口，>5min 未引用摘出。
  • 优势：捕捉人类意图，压缩率≥70%。

检索 - 压缩 - 淘汰三连招

  1. 检索：符号优先（精确、低噪），语义补漏，重排时权重 = 0.4依赖近 + 0.3时效 + 0.3 * 相关度。Qoder 实测 10 万文件 < 800ms。
  2. 压缩：diff-only + 摘要（LLM 总结未变函数，token 降 42%）；分层（核心文件全文本，外围仅签名）。
  3. 淘汰：引用计数 + 时间窗，30 轮后摘出闲置块，回滚支持（checkpoint）。

Anthropic 工程博客强调，此三连让 Agent 长任务（30h+）窗口如 1M 般高效。[2]

落地 Checklist：15 分钟升级项目

  1. 2min：创建 CLAUDE.md，复制模板（GitHub 搜索 “claude-code-template”）。 
    ## 架构
- Frontend: React 18, hooks-only
- Backend: FastAPI, Pydantic v2
- 测试: pytest≥90%覆盖
## 禁区
- 无外部npm包
- 函数≤50行
  2. 5min：安装树状解析 + 向量：pip install tree-sitter tree-sitter-lang faiss-cpu sentence-transformers。
  3. 5min：脚本 build_index.py（启动时 run），注入 hook 到 Cursor/Claude Code MCP。
  4. 3min：配置 VS Code .vscode/settings.json，Agent 模式默认 load index。
  5. 测试：@agent 重构user模块登录，观察窗口日志。

指标与踩坑

  • KPI：
    指标 前 后 提升
    SWE 通过率 70% 82% +12%
    任务时长 38min 19min -50%
    Token / 任务 150k 85k -42%
  • 坑：
    • 跨语言链（Python→JS）截断 15%，解：多模型路由。
    • 冷启动慢，解：预构建 index 到.gitignore 外。
    • 幻觉引用不存在文件，解：校验 post-retrieve。

下一步展望

当前三层已覆盖 80% 场景，未来跨仓（monorepo）依赖需联邦索引；运行时热上下文用 Computer Use（鼠标 / 键盘模拟）。无论 Claude Sonnet 4.5 还是 GPT-5，Context Engineering 是 Agent 从 “助手” 到 “工程师” 的分水岭。

资料来源： [1] https://m.blog.csdn.net/bugyinyin/article/details/154990248
[2] Anthropic 工程实践（2025）

（正文约 1250 字）

查看归档