🎯 课程主题
使用 FilesystemFileSearchMiddleware 中间件为 Agent 赋予本地文件系统的搜索与分析能力。
📝 核心知识点
1. FilesystemFileSearchMiddleware 概述
- 概念说明：基于系统的 glob（文件路径检索）和 grep（文件内容检索）工具，让 Agent 能够搜索和分析本地文件。
- 关键细节：添加该中间件后，Agent 执行时会自动注册 glob 和 grep 两种工具，无需手动定义。
2. glob 与 grep 两种检索方式
- 概念说明：
- glob：根据文件路径 / 文件名模式进行匹配检索（如
*.py、**/*.md）。 - grep：根据文件内容进行正则匹配检索（如查找包含特定函数的代码文件）。
- glob：根据文件路径 / 文件名模式进行匹配检索（如
- 关键细节：Agent 会根据用户的自然语言问题自行判断使用哪种工具，可能先后调用多次。
3. 核心参数配置
- 概念说明：通过构造函数参数控制中间件的行为。
| 参数 | 说明 | 示例值 |
|---|---|---|
path | 检索的根目录路径 | "./todo_workspace" |
file_pattern | 文件格式过滤（如注销则检索所有文件） | "*.py" |
use_ripgrep | 是否使用 ripgrep 加速 grep 检索 | True（需安装 ripgrep 库） |
max_file_size_mb | 单次读取文件的最大大小（MB） | 10 |
- 关键细节：
use_ripgrep=True要求已安装 ripgrep 库，它比原生 grep 速度更快。max_file_size_mb不能过大（避免 OOM）也不能过小（避免频繁 I/O 影响性能）。
🏗️ 架构与工作流
用户提问："找到包含 A 函数的 Python 或 Jupyter 文件"
│
▼
Agent 分析问题
│
├──► glob search（按文件路径匹配找 .py / .ipynb）
│ │
│ ▼
│ 返回匹配的文件列表
│
└──► grep search（按内容匹配"包含 A 函数"）
│
▼
返回包含目标内容的文件
💻 代码实战
from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware
from langchain_openai import ChatOpenAI
model = ChatOpenAI(model="gpt-4o")
# 创建 FilesystemFileSearchMiddleware
fs_middleware = FilesystemFileSearchMiddleware(
path="./todo_workspace", # 检索的目标目录
# file_pattern="*.py", # 注销后检索所有文件类型
use_ripgrep=True, # 启用 ripgrep 加速（需先 pip install ripgrep）
max_file_size_mb=10, # 单次读取文件最大 10MB
)
agent = create_agent(
model=model,
tools=[],
middleware=[fs_middleware],
)
# 提问：查找包含某个函数的 Python 或 Jupyter 文件
response = agent.invoke({
"messages": [{"role": "user", "content": "找到包含 A 函数的 Python 或 Jupyter 文件"}]
})
# Agent 会自动调用 glob 和 grep 工具完成检索
for msg in response.get("messages", []):
print(msg.pretty_print() if hasattr(msg, "pretty_print") else msg)
⚠️ 常见问题与避坑指南
use_ripgrep=True需要预装ripgrep库，否则会报错；Windows 下安装可能需要额外配置。max_file_size_mb设置过大可能导致内存溢出（OOM），设置过小会导致对大文件进行多次切片读取，增加交互轮次。- 检索路径
path是相对当前工作目录的，注意确认 Agent 运行时的 CWD。
💡 个人总结与延伸
FilesystemFileSearchMiddleware 让 Agent 具备了"本地文件管家"的能力，通过 glob + grep 的组合可高效定位代码文件。关键在于理解它并非通过传统的 Tool 绑定，而是中间件自动注入检索工具。use_ripgrep 和 max_file_size_mb 两个参数直接影响检索速度和内存安全，需根据实际文件规模合理配置。