AI Agent / 系统课时
实现文件读取工具
实现文件读取工具
本篇解决智能体如何读取指定文件,同时避免一次返回过多内容导致上下文膨胀。完成后,你可以实现一个带路径校验和大小限制的基础文件读取工具。
学习目标
- 掌握文件读取工具的核心接口设计
- 实现路径、范围和大小控制
- 理解智能体访问文件时的安全边界
文件读取工具的设计原则
文件读取工具看似简单,但智能体调用时需要考虑多个限制:读取哪个文件、读取多少内容、是否允许访问该路径。
一个实用的文件工具通常接收文件路径和读取范围,例如起始行号、结束行号或最大字符数,然后返回结构化结果。
实现带限制的读取接口
下面实现一个最小版本,支持按路径读取文本文件,并限制最大返回长度。
python
from pathlib import Path
MAX_CHARS = 2000
class FileReadTool:
def __init__(self, root: str):
self.root = Path(root).resolve()
def read(self, path: str):
target = (self.root / path).resolve()
# 防止读取工作目录之外的文件
if not str(target).startswith(str(self.root)):
raise ValueError("path is outside workspace")
content = target.read_text(encoding="utf-8")
return content[:MAX_CHARS]
reader = FileReadTool("<PATH>")
print(reader.read("example.txt"))预期输出
text
文件前 <2000 字符内容>其中 <PATH> 表示实际工作目录,返回内容会根据文件实际大小变化。
控制读取范围
大型项目中,完整读取文件会消耗大量上下文。更合理的方式是支持范围参数。
例如:
- 按行读取,定位代码附近内容
- 按字符限制,避免超长响应
- 按文件类型过滤,拒绝无关二进制文件
对于代码 Agent,行范围读取通常比全文读取更有效,因为模型只需要关注当前任务相关区域。
安全边界处理
文件工具属于高权限工具,需要明确访问范围。
常见保护措施包括:
- 限制工作目录
- 禁止读取敏感配置文件
- 限制单次返回大小
- 记录调用日志
如果工具直接接受任意绝对路径,智能体可能意外访问不应该暴露的数据。
验证工具行为
可以通过测试不同输入确认边界:
bash
python file_reader.py --path example.txt预期输出
text
读取成功,返回文件内容摘要测试时还应验证不存在文件、越界路径和超大文件等情况。
本课总结
- 文件读取工具需要同时考虑功能和安全限制。
- 返回内容大小控制可以保护智能体上下文窗口。
- 路径校验是文件类工具的基础安全措施。
下一课预告
下一课将继续完善工具调用流程,让智能体能够根据任务选择并执行已经注册的工具。
按自己的节奏,确认真正理解。