AI Agent / 系统课时
实现项目搜索工具
实现项目搜索工具
本课实现一个可被智能体调用的项目搜索工具,让 Agent 能根据关键词快速定位代码、文档和配置内容。最终结果是一个具备参数校验、范围控制和结构化返回值的搜索能力。
学习目标
- 理解项目搜索工具在 Agent 工具系统中的职责边界。
- 掌握封装文本搜索能力的基本实现方式。
- 学会设计适合模型理解的搜索结果格式。
设计搜索工具的输入与输出
项目搜索工具的核心不是简单执行 grep,而是把搜索能力包装成稳定的 Tool 接口。输入需要明确搜索关键词、目标目录和匹配范围,输出需要包含文件位置、匹配内容和上下文信息,方便模型继续推理。
一个简单的工具定义可以保持如下结构:
python
from pathlib import Path
def search_project(keyword: str, project_path: str) -> list[dict]:
"""在项目目录中搜索关键词并返回匹配位置。"""
results = []
root = Path(project_path)
for file in root.rglob("*"):
if file.is_file() and file.suffix in {".py", ".js", ".md"}:
text = file.read_text(encoding="utf-8", errors="ignore")
if keyword in text:
results.append({"file": str(file), "keyword": keyword})
return results预期输出
text
[
{"file": "src/main.py", "keyword": "search_project"}
]控制搜索范围与安全边界
工具直接访问文件系统时,需要限制可搜索目录,避免 Agent 读取无关文件。实际项目中通常只开放工作区目录,并过滤依赖目录、缓存目录和敏感配置文件。
常见控制策略包括:
- 限制根目录,只允许搜索项目工作区。
- 排除 node_modules、build、.git 等无关目录。
- 限制返回数量,避免大量结果占用上下文。
优化返回结果格式
搜索结果应该面向模型消费,而不是直接复制终端输出。推荐返回结构化字段,例如文件路径、行号、匹配片段和上下文范围。
当结果过多时,可以增加分页或摘要机制,让 Agent 根据需要继续查询,而不是一次加载整个项目。
常见错误
只返回“找到几个文件”会降低 Agent 的判断能力,因为模型无法知道匹配位置和内容关系。另一个常见问题是没有限制搜索范围,导致工具执行时间过长或暴露不必要文件。
本课总结
- 项目搜索工具负责把文件检索能力转换为稳定的 Agent 能力。
- 搜索范围、返回数量和结果结构决定工具是否可靠。
- 面向模型设计输出,比直接暴露命令结果更有效。
下一课预告
下一课将实现命令执行工具,为 Agent 提供受控运行环境并处理执行结果。
按自己的节奏,确认真正理解。