外部文件访问

本章说明如何让运行中的容器访问“不在 Agent 包里“的外部文件，例如用户本地的大型数据集或文档。

本地部署前提：当前系统设计为本地部署，用户的本地机器就是 Backend 和 K3s 所在的宿主机。因此，用户的本地文件可以直接通过 hostPath 挂载进容器，无需网络传输。

1. 两种场景

graph LR
    subgraph SMALL["场景一：小文件上传"]
        U1[用户上传] -->|附件| B1["Backend 复制到 in/"]
        B1 --> C1["容器读取 /workspace/in/"]
    end

    subgraph LARGE["场景二：大文件或本地目录"]
        U2[用户授权挂载] -->|mount_grant| B2[Backend 生成 hostPath 卷]
        B2 --> C2["容器读取 /workspace/mounts/"]
    end

场景一：小文件上传

用户通过 Helper 界面上传文件，文件经过以下链路到达容器：

1. 用户在 Web UI 中选择文件
2. Helper 将文件传递给 Backend（由于都在本机，这一步几乎是瞬时的）
3. Backend 将文件复制到 workspaces/[run-id]/in/
4. 容器启动后从 /workspace/in/ 读取

适用范围：文档、表格、配置文件等小于 100 MB 的文件。

场景二：大文件或本地目录挂载

对于大型数据集或需要整个目录的场景，使用 mount_grant（挂载授权）机制：

1. 用户在创建 Run 时指定本地目录路径（如 /Users/xxx/datasets/）
2. Backend 校验路径是否在白名单内
3. K3s 编排器将路径添加为 hostPath 卷
4. 容器内通过 /workspace/mounts/[名称] 直接读取

适用范围：GB 级数据集、代码仓库、日志目录等。

本地部署优势：由于用户的机器就是宿主机，hostPath 直接指向用户本地磁盘上的目录，无需复制或传输文件，容器可以即时访问。

2. 本地文件访问流程

在本地部署模式下，文件访问的完整流程如下：

sequenceDiagram
    participant U as 用户
    participant H as Helper（Web UI）
    participant B as Backend（本机）
    participant C as 容器

    U->>H: 选择本地文件/目录
    alt 小文件上传
        H->>B: 传递文件（localhost，无网络延迟）
        B->>B: 复制到 workspaces/[run-id]/in/
        B->>C: 容器通过 hostPath 挂载工作区
        C->>C: 读取 /workspace/in/ 中的文件
    else 大文件/目录挂载
        H->>B: 发送 mount_grant 请求（目录路径）
        B->>B: 校验路径白名单
        B->>C: 直接 hostPath 挂载用户本地目录
        C->>C: 读取 /workspace/mounts/[名称]
    end

关键优势：

• 所有通信走 localhost，零网络延迟
• 大文件/目录通过 hostPath 直接挂载，无需复制
• 用户本地文件系统的读写速度等于容器内的读写速度

2.1 这些操作是同步还是异步

3. 访问网络文件

当前系统不内置网络文件下载功能，但 agentcore 可以：

1. 在容器内下载：如果容器网络策略允许出站流量，agentcore 可以通过工具调用直接从 URL 下载文件
2. 通过工具桥接：未来计划通过 Helper 工具桥（tool bridge）让容器间接访问 Helper 能触达的网络资源

4. 安全约束

5. 限制与未来改进

下一步

了解了外部文件访问后，请继续阅读 外部数据库访问。