第三章：File Storage Backend

Chapter 3: File Storage Backend

---

从大脑到记忆库：代理如何安全存储文件？

在上一章ForgeAgent核心，我们看到了代理如何“思考”和“行动”。但就像人类需要笔记本记录重要信息一样，代理也需要一个安全可靠的存储系统来保存文件。本章将揭秘代理如何通过文件存储后端，在本地硬盘、云存储等不同环境中自由存取文件！

---

核心使命：统一管理文件的“万能文件夹”

想象你的AI助手需要同时：

1. 在本地保存会议记录
2. 从云端下载用户上传的文件
3. 确保代理无法越权访问敏感目录

文件存储后端就是这样一个“万能文件夹”：

• 统一接口：用相同的代码操作本地/云端文件
• 安全限制：禁止代理访问指定路径外的文件
• 自动适配：无缝切换不同存储类型（如本地硬盘、AWS S3）

---

关键概念拆解

1. 统一接口：FileStorage抽象类

就像U盘插到不同电脑都能用，FileStorage定义了所有存储类型共有的方法：

class FileStorage(ABC):
    @abstractmethod
    def read_file(self, path: str) -> str:
        """读取文件内容"""
        
    @abstractmethod
    async def write_file(self, path: str, content: str) -> None:
        """写入文件内容"""

2. 存储适配器：本地/云端实现

通过子类实现具体逻辑：

# 本地存储（来自local.py）
class LocalFileStorage(FileStorage):
    def read_file(self, path):
        with open(self.get_path(path), "r") as f:
            return f.read()

# 云端存储（来自s3.py）
class S3FileStorage(FileStorage):
    def read_file(self, path):
        obj = self.s3.get_object(Key=path)
        return obj['Body'].read().decode()

3. 安全沙箱：路径限制

def _sanitize_path(self, path: str):
    """验证路径是否在允许范围内"""
    full_path = self.root / Path(path)
    if not full_path.is_relative_to(self.root):
        raise ValueError("路径越权！禁止访问根目录外的文件！")

---

实战演练：保存会议记录到云端

目标：让代理将会议纪要保存到S3存储桶，并保证安全性

步骤1：配置云端存储

from forge.file_storage import get_storage

# 创建S3存储实例
storage = get_storage(backend="S3", root_path="/agpt-storage")

步骤2：保存文件内容

async def save_meeting_notes():
    content = "今日议题：项目进度汇报"
    await storage.write_file("meeting/2024-03-01.txt", content)
    
    # 验证存储成功
    assert storage.read_file("meeting/2024-03-01.txt") == content

关键验证点

• 路径安全：尝试写入../../../etc/passwd会抛出ValueError
• 云端同步：文件会自动上传到S3的agpt-storage/meeting/2024-03-01.txt

---

内部运作：文件操作的幕后流程

以写入文件为例，流程如下：

安全检查细节（关键代码）

# 路径验证逻辑（来自base.py）
def _sanitize_path(self, path):
    full_path = self.root / Path(path)
    if not full_path.is_relative_to(self.root):
        raise ValueError("路径越权！")

---

扩展能力：多存储类型自动切换

通过简单配置即可切换存储类型：

# 使用本地存储
storage = get_storage(backend="local", root_path="/tmp/forge")

# 使用GCS存储（需配置相关凭证）
storage = get_storage(backend="GCS", root_path="/forge-bucket")

---

总结与展望

通过本章，你已掌握：
✅ 理解文件存储后端的抽象设计
✅ 如何安全操作本地/云端文件
✅ 通过统一接口管理不同存储类型

下一章我们将学习如何让代理像交响乐团一样协调任务——任务工作流编排，带你了解代理如何高效执行复杂流程！

---