用 AI 编程助手写代码，体验好坏的关键不在模型多大，而在它能不能准确拿到你项目里的上下文。一个只看到当前文件片段的助手，给出建议往往是错的——它不知道你的封装、命名约定、依赖关系。
这篇拆一下 AI 编程助手的上下文工程。
一、为什么上下文比模型更重要
让 AI 改一个函数，它需要知道：
- 这个函数被谁调用（改签名会不会破坏调用方）
- 项目里的工具类怎么封装的（不该自己现写一套）
- 团队命名和风格约定
- 相关的类型定义、配置文件
这些信息全在代码库里，但不在当前打开的编辑器里。所以 AI 编程助手的核心工程问题是：如何在有限的上下文窗口里，选中最相关的片段。
二、代码库索引的三层结构
主流做法是建一套分层索引：
| 层级 | 索引什么 | 用途 |
|---|---|---|
| 文件级 | 目录树、文件路径、大小 | 快速定位模块归属 |
| 符号级 | 类名、函数名、变量名、类型定义 | 精确跳转和引用查询 |
| 语义级 | 代码片段的向量表示 | 按自然语言找相关代码 |
符号级索引是代码场景独有的优势——不像自然语言文本，代码有明确的语法结构。解析 AST 能精确得到"这个函数在哪个文件、第几行、被谁引用"。这比纯向量检索精准得多。
语义级索引补充了符号索引的盲区：用户问"哪里处理了订单超时"，代码里没有叫"超时"的函数，但语义相关。这时向量检索能召回相关片段。
实际产品通常组合使用：先用符号索引找到结构上相关的代码（调用链、类型定义），再用语义检索补充自然语言描述的场景。
三、检索策略：从宽到窄
拿到用户问题后，检索流程一般是：
1. 粗筛：定位相关目录/模块（缩小范围）
↓
2. 符号查询：找出相关函数、类、类型的定义与引用
↓
3. 语义检索：补充描述性匹配的片段
↓
4. 重排：按相关性排序，取 Top-K
↓
5. 组装：拼成结构化的上下文交给模型
第 5 步的组装方式很关键。直接把代码片段堆上去效果不好，要做结构化：
【当前文件】
（完整内容或光标附近的片段）
【相关定义】
- UserService.updateProfile（定义位置）
- ProfileDTO（类型定义）
【调用方】
- ProfileController.update（调用当前函数）
【项目约定】
（从配置文件或文档中提取的规范）
【问题】
用户提出的具体请求
这种结构让模型知道每段代码的角色，而不是面对一堆无标注的代码。
四、Agent 模式的差异
早期的编程助手是"补全式"：给上下文，让它续写。现在主流是"Agent 式"：它能自己决定读哪些文件、执行什么命令、改哪些地方。
Agent 模式的技术要点：
工具调用循环。 模型输出"我要读某个文件"，系统执行读取，把结果返回给模型，模型再决定下一步。这个循环可能持续十几轮。
状态管理。 多轮工具调用中要维护"已经做了什么、还剩什么"，否则会重复读同一个文件或在改错后不知道回滚。
验证闭环。 改完代码要能跑测试、跑编译检查，根据失败信息自我修正。这是"能跑"和"能跑对"的区别。
人工确认点。 涉及删除文件、改配置、执行危险命令时，要有确认机制。全自动的 Agent 在没有护栏时风险很大。
五、代码知识库与规范约束
团队使用 AI 编程工具，一个常见问题是生成的代码风格不统一。解决办法是把团队规范变成助手可见的约束：
- 在项目里维护一份规范文档（命名、分层、异常处理约定）
- 助手在组装上下文时把这份文档带上
- 或者用规则文件的形式（在项目根目录放约定文件，助手自动读取）
这类"规范驱动"的做法，本质是把隐性的团队知识显式化，让模型有据可依。比事后 code review 一段段纠正效率高得多。
六、实际使用的几个经验
1. 需求描述要具体。 "优化一下这个函数"不如"把这个循环里的数据库查询改成批量查询，保持返回结构不变"。
2. 让它先读再改。 复杂改动先让助手分析现状、给出方案，确认后再动手。一次性让它改一大片，出错难定位。
3. 小步提交。 每完成一个可验证的小改动就提交，出问题时容易回滚。
4. 测试是护栏。 有测试的项目，AI 改动后能自动验证；没测试的项目，AI 改动的风险会放大。
5. 别指望它懂业务。 业务规则、历史包袱、和客户的约定，这些不在代码里。涉及业务判断的部分必须人工把关。
七、写在最后
AI 编程助手的上限由上下文质量决定，不只是模型能力。理解索引、检索、组装这条链路，你就知道为什么有些项目里助手特别聪明（代码结构清晰、命名规范），有些项目里助手总是答错（代码混乱、缺乏类型定义）。
当前的 AI 编程与模型订阅方案可以看官方页面——查看云聚 AI 权益与 AI 编程工具相关方案。具体档位与权益以页面实际展示为准。
你们团队在用 AI 编程助手吗？遇到过它读错上下文的情况吗？评论区聊聊。
