一位开发者推出了一种三层代码库地图，让 AI 编程智能体能够在不同会话之间保持“位置感”。

为什么 AI 智能体需要地图

基于对话的编程助手仅在提示词窗口保持打开时，才会构建代码库的心理模型。当上下文窗口关闭时，模型就会消失，迫使智能体不得不从头开始重新发现符号、导入关系和文件关联。这种反复的过程浪费了计算周期，并且当开发者在文件间切换或在休息后返回项目时，会降低智能体的实用性。

构成地图的三层结构

  • 结构层 (Structural layer) —— 符号、函数调用和导入语句的目录。它回答的是“谁调用了谁”这一静态问题。
  • 时序层 (Temporal layer) —— 源自 git 的信号，例如文件变更率和所有权历史。它展示了代码的哪些部分变化最频繁，以及谁通常会修改它们。
  • 行为层 (Behavioral layer) —— 从智能体自身的编辑和导航历史中提取的真实使用模式。它揭示了在编程会话期间哪些文件实际上是同时打开的，从而暴露了静态分析所忽略的“真实邻居”。

行为层权重最高，因为它反映了开发者（以及智能体）的真实工作方式，而不仅仅是代码的连接方式。

向智能体提供地图的两种方式

  1. 环境路径 (Ambient Path) —— 注入到每次交互中的简洁摘要。它无需任何额外调用，即可为智能体提供即时的“你正处于 X 模块，附近有这些符号”的快照。
  2. 深度路径 (Deep Path) —— 智能体在需要更丰富细节时可以调用的按需查询工具，例如经常一起变化的文件列表或最近的所有权时间线。

将环境信息与深度信息分离，既能保持常规提示词的轻量化，又能在需要时提供深度信息。

保持系统精简的设计规则

  • 跳过重量级的语言服务器。 该地图依赖于浅层解析而非完整的类型推断。其目标不是在引擎性能上超越成熟的静态分析器，而是通过行为洞察来补充它们。
  • 按项目限制图谱范围。 系统不会跨代码库缝合全局依赖图。这种隔离减少了内存占用并加快了更新速度。
  • 复用现有的存储。 文件变更日志来源于智能体自身对工具调用的记忆，从而避免了重复存储并保持了数据源的一致性。

实践中的地图构建

  1. 收集结构数据：通过快速扫描源文件，提取符号和导入行。
  2. 提取时序指标：从代码库的 git 历史中提取数据，记录哪些文件提交最频繁以及作者是谁。
  3. 采集行为信号：通过记录智能体在实际编程会话中的文件打开、编辑和导航操作。这些日志构成了定义行为邻居的“共现”矩阵的基础。
  4. 填充环境路径：根据当前任务，提供一份简短且有序的最相关符号和文件列表。
  5. 开放深度路径：将其作为一组轻量级的查询函数（例如，“列出最近会话中一起编辑的文件”）。

快速钩子 (Fast hooks) 会在每次编辑发生时进行捕获；较慢的后台扫描则负责重新计算变更统计数据。两者结合，既能保持地图的新鲜度，又不会拖慢开发者的工作流。

经验教训

  • 将环境信息与按需查询分离。 保持始终存在的摘要极其精简可以防止 Token 膨胀，而更丰富的查询则作为可选内容。
  • 按任务优先级排序上下文。 根据当前的编辑焦点对环境符号进行排序，可以提供更有用的建议。
  • 激进但智能地刷新。 快速钩子捕获高频变更；定期扫描处理低频变更和所有权转移。
  • 浅层解析在速度上更具优势。 深层的类型分析会增加延迟，却无法提供驱动该地图优势的行为洞察。

核心总结： 通过将静态结构、git 历史和真实使用情况分层整合到一个紧凑的两层访问模型中，开发者可以为 AI 编程智能体提供一份持久的代码库地图。保持始终存在的摘要精简，可以有效防止 Token 膨胀。