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 提供受控运行环境并处理执行结果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现项目搜索工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通