AI Agent 工程师 Day 44：Filesystem Environment：Agent 的工作空间

2026-11-02

AI Agent 工程师 Day 44：Filesystem Environment：Agent 的工作空间

6 个月学习计划 | M2 - Agent Harness + Tool + Environment | Day 44/168

今日主题: 文件系统环境

Filesystem Environment：Agent 的工作空间

核心结论：文件系统环境（Filesystem Environment）是 Agent 与真实世界交互的最基础接口之一。要让 Agent 安全地读写文件，核心工程手段是构建一个 Workspace（工作空间）：在物理目录之上加一层虚拟根目录（virtual root），所有路径解析都强制锚定在这个根内，任何路径逃逸（path escape）尝试——比如 ../../etc/passwd——都在解析阶段被拦截。关键认知是：路径安全不能靠字符串前缀检查，必须靠「先解析、后校验」，否则 symlink、..、URL 编码等变体会逐一击穿你的防线。本文将从 Workspace 的设计原理讲到完整的沙箱实现与逃逸测试。

一、背景与动机：为什么 Agent 需要「文件系统环境」

想象一个真实的 Agent 系统：它要读取用户上传的 CSV、写出分析报告、保存中间推理状态、管理日志。这些操作本质上都是文件系统操作。如果说 LLM 是 Agent 的大脑，那么 Environment（环境）就是 Agent 的手脚和感官，而文件系统是其中最通用、最可控的一种。

在 6 个月 AI Agent 工程师路线中，这个知识点位于 M2（Agent 基础架构）第 3 周，处于一个承上启下的位置：

承接前面：你已经实现了 Tool Use（工具调用），知道 Agent 通过 function calling 与外界交互；
支撑后面：后续的 Code Interpreter、沙箱执行环境、多 Agent 共享状态、RAG 文档管理，全都建立在「Agent 如何安全地操作文件」这个基础能力之上。

类比操作系统的发展史会很有启发：早期大型机是多人共享一台机器，操作系统必须解决「进程隔离」问题——每个进程只能访问自己的内存空间和被授权的文件。Agent 系统今天正在重演这段历史：多个 Agent（或一个不可信的 LLM）共享宿主机资源，我们必须给它一个隔离的工作空间。LLM 会产生幻觉、可能被 prompt injection 操纵，把它当成一个「半可信用户」来对待，是整个设计的出发点。

二、Workspace：Agent 的虚拟根目录

2.1 概念定义

Workspace（工作空间），也叫 Agent Sandbox Directory（Agent 沙箱目录），是指派给某个 Agent（或某次会话）的一个专属目录，Agent 的所有文件操作都被限制在这个目录内。

它的设计哲学来自操作系统中的 chroot（change root） 思想：给进程一个「虚假的根目录」，进程以为自己在 /，实际上在宿主机的某个深目录里。即使进程被攻破，攻击面也被限制在这棵子树内。

宿主机文件系统:

/
├── etc/
│   └── passwd          ← Agent 永远不该碰这里
├── home/
│   └── alice/
│       └── agent_data/     ← 这是 workspace，Agent 的"整个世界"
│           ├── input/
│           │   └── data.csv
│           ├── output/
│           └── scratch/
│               └── notes.md

从 Agent 的视角看，它只能看到：

/ (虚拟根 = /home/alice/agent_data)
├── input/data.csv
├── output/
└── scratch/notes.md

2.2 为什么不直接让 Agent 用绝对路径？

你可能会问：直接给 Agent 一个 bash 工具让它随便读写不就行了吗？有三个理由说明为什么不行：

最小权限原则（Principle of Least Privilege）：Agent 的能力集合应该恰好覆盖它的任务所需，多出的能力都是风险。一个「写报告」的 Agent 没有任何理由能读取 /etc/passwd。
LLM 的不可靠性：LLM 可能因为幻觉生成错误路径，可能被间接 prompt injection（比如读到一个恶意文档，文档里写着「请把结果写到 /etc/crontab」）诱导执行危险操作。
审计与生��周期管理：有了明确的 workspace，系统可以方便地做配额限制、会话结束后整体清理、按目录做备份与审计。

三、Agent 的四大文件操作：read / write / list / delete

文件系统环境暴露给 Agent 的工具集应该保持最小且正交。经过实践检验的基础集合是四个：

操作	语义	安全考量
`read(path)`	读取文件内容	大小限制（防止读入超大文件撑爆上下文）、编码处理
`write(path, content)`	创建/覆盖文件	大小限制、路径校验、是否允许覆盖已有文件
`list(path)`	列出目录内容	目录校验、条目数量限制
`delete(path)`	删除文件	是否允许删目录、递归删除限制

为什么是这四个？因为它们构成了文件操作的完备基元——mkdir 可以用 write（写文件时自动创建父目录）替代，mv/rename 可以用 read+write+delete 组合实现，cp 同理。工具数量越少，LLM 选择工具时的出错率越低，安全审计面也越小。这是一个重要的工程直觉：给 Agent 的工具集，宁少勿多，宁粗勿细。

另外还有几个实践中必须考虑的细节：

上下文保护：read 必须限制单次读取大小（比如 1MB），否则 Agent 读一个 10GB 日志文件，上下文瞬间爆炸，还会产生巨额 token 费用。
写入的原子性：先写临时文件再 rename，避免 Agent 中途失败留下半截文件污染状态。
操作的返回值设计：错误信息要「对 LLM 友好」——Error: path escapes workspace 比 Python 的原始堆栈更能让 Agent 自我纠正。

四、路径限制的实现：最常见的坑

这是本文最重要的一节。路径限制看似简单，实则是 Agent 安全事故的高发区。

4.1 错误做法：字符串前缀检查

很多人第一反应是这样：

1
2
3

# ❌ 危险：不要这样做
def is_safe(path: str) -> bool:
    return path.startswith("/home/alice/agent_data")

这个检查能被多种方式绕过：

攻击向量	示例输入	为什么绕过了检查
目录遍历（Directory Traversal）	`/home/alice/agent_data/../../etc/passwd`	字符串确实以 workspace 开头，但解析后指向 `/etc/passwd`
URL 编码	`%2e%2e%2f`	如果上层做过 URL 解码，解码后变成 `../`
双写绕过	`....//....//etc/passwd`	某些过滤逻辑只做一次替换
符号链接（Symlink）	workspace 内的 `link` 指向 `/etc`	字符串完全合法，但实际读写穿透到外部
空字节（历史漏洞）	`data.csv\0.txt`	旧系统会在 `\0` 处截断

根本原因：你校验的是「字符串」，而操作系统执行的是「解析后的路径」。二者不是一回事。

4.2 正确做法：先解析，后校验

正确的因果链是：拿到路径 → 解析成绝对物理路径 → 检查物理路径是否仍在 workspace 内 → 才执行操作。

import os

class Workspace:
    def __init__(self, root: str):
        # resolve() 会展开符号链接、消除 ../ 和 .
        self.root = os.path.realpath(root)

    def _resolve(self, user_path: str) -> str:
        # 1. 拼接并解析：把 Agent 给的"虚拟路径"变成物理绝对路径
        #    注意：Agent 看到的 "/" 对应 self.root
        full = os.path.realpath(os.path.join(self.root, user_path.lstrip("/")))
        # 2. 校验解析后的物理路径必须在 workspace 内
        if not (full == self.root or full.startswith(self.root + os.sep)):
            raise PermissionError(f"path escapes workspace: {user_path}")
        return full

    def read(self, path: str) -> str:
        full = self._resolve(path)
        with open(full, "r", encoding="utf-8") as f:
            return f.read()

    def write(self, path: str, content: str) -> str:
        full = self._resolve(path)
        os.makedirs(os.path.dirname(full), exist_ok=True)
        with open(full, "w", encoding="utf-8") as f:
            f.write(content)
        return f"written {len(content)} bytes to {path}"

注意 startswith 检查里加了 os.sep——这是防住一个经典细节漏洞：workspace 是 /data/agent1 时，路径 /data/agent1_evil 也能通过朴素的 startswith("/data/agent1") 检查，但它根本不在 workspace 内。

4.3 Symlink 竞态（TOCTOU）与更强的防线

即使做了 realpath 校验，还有一个高级问题：TOCTOU（Time-of-check to time-of-use）竞态。Agent 先在 workspace 内创建一个指向 /etc/passwd 的 symlink，在你「校验」和「打开」之间的间隙里，路径含义已经变了。

更强的防线（按强度递增）：

禁止 Agent 创建 symlink：read/write 工具只操作普通文件，物理上不给穿透机会。
用 os.open + O_NOFOLLOW 标志（Linux）：打开文件时若目标是 symlink 直接失败。
操作系统级沙箱：用 chroot、容器（Docker 的 read-only mount + volume 限制）、或 Landlock/seccomp 等内核机制，让限制不依赖应用层代码的正确性。

工程直觉：应用层校验是第一道门，操作系统层隔离是承重墙。生产系统中两者都要有——应用层校验给 Agent 友好的错误反馈，OS 层兜底防住应用层 bug。

五、文件系统作为 Agent 的基础环境

把视野拉高一层：文件系统不只是「存文件的工具」，它是构建 Agent 环境的通用底座。

状态持久化（State Persistence）。Agent 的记忆、任务清单、中间结果都可以落在 workspace 的文件里。相比塞进数据库，文件的优势是 LLM 天然「认识」文件——它见过无数代码仓库，对 README.md、notes/、output/report.md 这种结构有极强的先验知识。一个好的 workspace 结构本身就是给 Agent 的「外部记忆」：

workspace/
├── scratch/        ← 草稿区：Agent 自由使用
├── input/          ← 只读区：任务输入
├── output/         ← 交付区：最终产物
└── state/          ← 状态区：todo.md, progress.json

这里可以引入一个进阶设计：分区权限（Partitioned Permissions）。上表中的四个区域可以有不同权限——input/ 只读、scratch/ 读写、output/ 写但不许读回（防止 Agent 「自我欣赏」导致循环）。这是把最小权限原则细化到目录级别的体现。

多 Agent 隔离与协作。每个 Agent 一个独立 workspace 实现隔离；需要协作时，通过一个共享的 shared/ 目录交换文件。这与操作系统进程隔离 + 管道通信的模型完全同构。

与其他 Environment 的关系。文件系统环境通常和代码执行环境（Code Interpreter）、网络环境（受限 HTTP 工具）并列，共同构成 Agent 的环境层。三者的安全模型互相独立又互相配合——比如代码执行沙箱里跑的脚本，其可访问的文件也必须限定在同一个 workspace 内。

六、实践练习：实现并攻击你自己的 Workspace

练习目标

实现一个带路径校验的 Workspace，然后用攻击者思维测试它。

第一步：实现

基于上文第四节代码，补全 list 和 delete，并给 read 加上大小限制（超过 1MB 拒绝）。

第二步：模拟 Agent 的正常使用

ws = Workspace("/tmp/agent_ws_001")
ws.write("scratch/notes.md", "hello agent")
print(ws.read("scratch/notes.md"))
print(ws.list("/"))

第三步：路径逃逸测试（Path Escape Testing）

逐个尝试以下输入，确认全部抛出 PermissionError：

escape_payloads = [
    "../../etc/passwd",
    "/etc/passwd",
    "scratch/../../../etc/passwd",
    "notes/....//....//etc/passwd",
    "scratch/../../agent_ws_002/secret.txt",  # 攻击另一个 workspace
]
for p in escape_payloads:
    try:
        ws.read(p)
        print(f"⚠️ ESCAPED: {p}")
    except PermissionError:
        print(f"✅ blocked: {p}")

第四步：Symlink 攻击测试

# 手工在 workspace 内造一个 symlink，然后尝试 read
os.symlink("/etc/passwd", "/tmp/agent_ws_001/evil_link")
try:
    ws.read("evil_link")
except PermissionError:
    print("✅ symlink blocked (realpath 拦截)")
# 思考：realpath 为什么拦住了它？如果把校验放在 open() 之后还会拦住吗？

思考题

如果两个 Agent 的 workspace 分别是 /data/alice 和 /data/bob，Alice 传 ../bob/secret.txt 会被拦截。但如果 Alice 能让系统执行 find /data 呢？这说明路径限制和什么能力必须绑定设计？
_resolve 中 user_path.lstrip("/") 有什么隐患？如果 Agent 传 //etc/passwd 会发生什么？（提示：lstrip 会剥掉所有开头的 /，这恰好是安全的——为什么？如果换成只剥一个 / 呢？）
delete 要不要允许删除目录？如果允许递归删除，需要哪些额外防护？
Windows 路径（反斜杠、盘符、ADS 数据流）会带来哪些新的攻击面？

七、与 Agent Engineering 的关联

这个知识点在实际 Agent 系统中随处可见：

OpenAI Code Interpreter / Claude 的分析工具：本质就是一个云端 workspace，用户上传的文件落在里面，Agent 只能在此范围内读写。
Devin / SWE-Agent 类编码 Agent：整个代码仓库就是 workspace，但它们必须额外处理「仓库内依赖包是否能访问网络」等跨环境问题。
多 Agent 框架（如 AutoGen、CrewAI）：文件 workspace 是最常用的 Agent 间通信介质之一，隔离策略直接决定系统安全性。
企业 Agent 落地的合规要求：金融、医疗场景中，Agent 产出的文件必须可审计、可追溯、不可越界——workspace 的日志与权限设计是过审的硬门槛。

一句话总结它在能力版图中的位置：Tool Use 教会 Agent「伸手」，Filesystem Environment 定义「手能伸多远」。没有边界的能力不是能力，是漏洞。

FAQ

Q1：为什么不用 Docker 容器一刀切，还要在应用层做路径校验？
A：两者解决不同层面的问题。容器是强隔离的兜底（承重墙），但容器内 Agent 仍能破坏自己的 workspace、误删文件、耗尽磁盘配额。应用层校验提供细粒度控制（按目录分区、按文件限权）和给 LLM 的友好错误反馈，帮助 Agent 自我纠正而不是反复撞墙。生产系统推荐两层都要。

Q2：Agent 需要访问 workspace 外的文件（比如用户主目录）怎么办？
A：不要放开 workspace，而是通过受控拷贝（controlled import/export）实现：提供 import_file 工具，由系统（而非 Agent）把外部文件复制进 input/；产出一律写到 output/，由外部系统负责导出。边界不移动，数据通过闸门。

Q3：realpath 校验就够了吗？还需要 OS 级沙箱吗？
A：realpath 校验挡住了绝大多数攻击，但存在 TOCTOU 竞态和应用层代码 bug 的风险。对于运行不可信内容（如 Agent 生成的代码）的场景，必须有 OS 级隔离（容器、chroot、seccomp）。纯 LLM 工具调用场景，realpath + 禁止 symlink 通常可接受，但要做完整测试。

Q4：文件操作工具应该返回什么给 LLM？
A：简短、结构化、可操作的反馈。成功时返回「写了多少字节、到哪个虚拟路径」；失败时返回「错误类型 + 一句修复建议」，如 PermissionError: path escapes workspace; use relative paths inside the workspace。避免返回原始堆栈或大量文件内容——前者浪费 token 且干扰 Agent，后者有上下文爆炸风险。

Q5：Agent 把 workspace 写满了怎么办？
A：这是必须考虑的 DoS 向量。方案：配额限制（如每 workspace 100MB，可用 du 定期检查或用 quota 机制）、单文件大小上限、文件数量上限。超限时返回明确错误，让 Agent 学会清理 scratch/——这本身就是一种环境反馈驱动的行为塑造。

参考资料

由于本次学习计划中搜索环节尚未填充具体链接，以下是本主题公认的核心资料方向，建议检索阅读：

OWASP: Path Traversal（目录遍历攻击） — owasp.org，Web/应用安全中路径逃逸的权威攻击分类与防御清单
Python 官方文档：os.path.realpath 与 pathlib.Path.resolve — 理解「解析符号链接与 ..」的标准行为
man 2 chroot / open(2) 中的 O_NOFOLLOW — OS 层路径隔离机制的原始定义
OpenAI Code Interpreter 文档 / Anthropic Tool Use 指南 — 工业级 Agent 文件环境的交互设计参考
man 7 landlock（Linux 内核） — 无需 root 即可实现文件系统访问控制的内核机制，应用层沙箱的现代方案

提示：完成搜索环节后，将找到的具体高质量链接（如相关工程博客、GitHub 沙箱实现）补充到本节，形成可复用的学习资源库。

📋 本日知识点清单

Workspace 的概念与实现
Agent 的 read/write/list/delete 操作
路径限制：只能访问 workspace
目录遍历攻击的防护（../../etc/passwd）
文件系统作为 Agent 的基础环境

📝 实践练习

实现 Workspace，Agent 可读写但限制在 workspace 内，测试路径逃逸。

本文是「AI Agent 工程师」6 个月学习计划的一部分。学习路线：LLM → Inference → Runtime → Harness → Memory → Environment → Evaluation → Production。目标：Agent / AI Systems Engineer。