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
读取成功,返回文件内容摘要

测试时还应验证不存在文件、越界路径和超大文件等情况。

本课总结

  • 文件读取工具需要同时考虑功能和安全限制。
  • 返回内容大小控制可以保护智能体上下文窗口。
  • 路径校验是文件类工具的基础安全措施。

下一课预告

下一课将继续完善工具调用流程,让智能体能够根据任务选择并执行已经注册的工具。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现文件读取工具

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

登录哪都通