AI Agent / 系统课时
实现代码问答模式
实现代码问答模式
本节实现一个只读代码问答能力,让智能体能够搜索项目文件、定位符号、分析调用关系,并根据源码上下文解释代码含义,同时保证整个过程不会修改用户工作区。
学习目标
- 理解代码问答模式与代码修改模式的职责边界。
- 掌握文件搜索、符号索引和调用链分析的组合流程。
- 实现一个可验证的只读源码分析工作流。
代码问答模式的核心职责
代码问答模式解决的问题是“理解已有代码”,而不是“改变已有代码”。用户提出“这个函数做什么”“哪里调用了这个接口”“为什么这里会报错”等问题时,智能体需要通过检索和分析已有源码生成答案。
该模式通常包含四个只读能力:
- 项目搜索:根据关键词、路径或语义找到相关文件。
- 符号定位:定位类、函数、变量、接口定义。
- 调用链分析:追踪调用方和被调用方关系。
- 源码解释:结合上下文生成自然语言说明。
与修改模式相比,问答模式不产生 Patch,不写入文件,也不触发编辑器状态变化。
设计只读分析链路
代码问答智能体通常先建立项目索引,再根据用户问题逐步缩小范围。

一个简单的工具编排示例如下:
python
from dataclasses import dataclass
@dataclass
class CodeQuestion:
question: str
class ReadOnlyCodeAgent:
def answer(self, question: CodeQuestion):
# 只执行检索和分析,不允许修改文件
files = self.search_files(question.question)
symbols = self.find_symbols(files)
return self.explain(symbols)
def search_files(self, query):
return ["src/service/user.py"]
def find_symbols(self, files):
return ["UserService.create_user"]
def explain(self, symbols):
return f"相关代码符号:{symbols}"
agent = ReadOnlyCodeAgent()
print(agent.answer(CodeQuestion("用户创建流程在哪里实现")))预期输出
text
相关代码符号:['UserService.create_user']实际项目中,搜索结果不会固定返回文件,而是需要结合语言服务器、代码索引库或向量检索系统生成候选上下文。
符号定位与调用链分析
仅搜索文件名无法回答复杂问题。例如用户询问“订单创建后如何发送通知”,智能体需要找到订单入口、业务服务、事件发布位置以及通知处理逻辑。
常见分析顺序如下:
- 根据自然语言问题提取关键实体。
- 搜索相关文件和符号。
- 获取函数定义和引用位置。
- 拼接调用路径。
- 根据上下文生成解释。
调用链分析的重点不是展示所有代码,而是提取回答问题所需的最短路径。
只读模式的边界控制
代码问答模式必须明确工具权限,避免智能体在回答问题时误调用修改能力。
推荐将工具分层:
| 工具类型 | 问答模式权限 |
|---|---|
| 文件读取 | 允许 |
| 搜索索引 | 允许 |
| 符号分析 | 允许 |
| 文件写入 | 禁止 |
| Patch 应用 | 禁止 |
如果未来扩展为多模式智能体,应让模式选择阶段决定工具集合,而不是让模型自行尝试所有工具。
本课总结
- 代码问答模式通过搜索、定位、分析和解释完成只读源码理解。
- 符号索引和调用链分析比简单文本搜索更适合复杂项目。
- 权限隔离是保证问答模式安全性的关键。
下一课预告
下一节将实现代码修改模式,让智能体根据需求生成计划、执行 Patch,并同步更新工作区。
按自己的节奏,确认真正理解。