Deep Agents 学习笔记（二）：虚拟文件系统

第三章主要讲 Deep Agents 里的虚拟文件系统。刚开始看会觉得就是给 Agent 加了一套文件读写工具，但后面会发现，它其实和上下文管理关系很大。

1. 为什么 Agent 需要文件系统

Agent 做简单问答时，所有信息都放在上下文里问题不大。

但复杂任务不一样，比如查资料、读代码、整理结果、反复修改文件，这些过程会产生很多中间内容。如果全部一直留在 Context 里，很快就会变得很长。

所以 Deep Agents 的一个思路是：

复制代码

当前要用的信息放进 Context
暂时不用的内容写到文件里
后面需要时再读回来

这个其实就是 Context Engineering 的一种做法。

我觉得可以把它理解成：

复制代码

Context = 当前工作区
Filesystem = 外部记录

模型没必要一直"记住"所有东西，只要需要的时候能重新找到就行。

2. 主要文件工具

Deep Agents 提供了几个常用文件工具：

工具	用途
`ls`	查看目录
`read_file`	读取文件
`write_file`	新建或覆盖文件
`edit_file`	修改已有文件
`delete`	删除文件
`glob`	按文件名或路径找文件
`grep`	搜索文件里的内容

其中我觉得比较容易混的是 glob 和 grep。

简单理解：

复制代码

glob：找文件
grep：找内容

比如想找所有 Python 文件：

复制代码

**/*.py

更适合用 glob。

如果想找哪些文件里出现了 create_agent，就用 grep。

3. read_file 不一定要整个文件都读进来

这一点挺实用。

read_file 可以指定读取范围，比如：

复制代码

read_file(
    "/workspace/report.md",
    offset=100,
    limit=50
)

意思就是只读文件的一部分。

所以遇到很大的文件时，不一定直接全部读取，可以先：

复制代码

grep 找位置
→ read_file 读附近内容

这和我们平时看日志、查代码其实差不多。

如果一个日志几千上万行，直接全部丢给模型显然很浪费。

4. 大结果可以先存到文件里

Agent 调工具时，有时候会返回很长的内容。

比如搜索结果特别多，如果这些内容全都留在上下文里，会很占 token。

Deep Agents 可以把比较大的结果先保存到文件系统里，然后上下文里只保留文件位置和一小部分预览。

后面如果还需要，再：

复制代码

grep
→ read_file

重新读取。

这一点我觉得比较关键，因为它说明：

文件系统不只是保存最终结果，也可以用来保存中间过程。

5. Backend 是什么

文件工具只是上层接口，文件到底存在哪里，是 Backend 决定的。

这一点有点像：

复制代码

Agent 只管 read_file / write_file
底层到底存内存、本地磁盘还是长期存储，由 Backend 决定

常见的几个 Backend：

StateBackend

默认使用的 Backend。

主要保存当前任务里的临时文件，比如：

复制代码

plan.md
notes.md
search_results.md

比较像 Agent 的草稿区。

任务换了以后，这些内容不一定还保留。

FilesystemBackend

这个就是真正操作本地文件。

比如 Agent 可以直接读写一个代码仓库里的文件。

这就比较接近 Codex、Claude Code 这类 Coding Agent 的使用方式了。

StoreBackend

这个用于长期保存。

比如：

复制代码

用户偏好
长期记忆
一些长期配置

和 StateBackend 的区别可以简单记：

复制代码

StateBackend：当前任务
StoreBackend：跨任务保存

CompositeBackend

实际使用时，临时文件和长期文件通常都会有。

比如：

复制代码

/workspace/

存当前任务的草稿，

复制代码

/memories/

存长期记忆。

这种情况下可以用 CompositeBackend，把不同路径交给不同 Backend。

6. 文件权限和 Shell 权限不是一回事

FilesystemBackend 主要是让 Agent 操作文件。

但如果用了 LocalShellBackend，Agent 还可以执行命令，例如：

复制代码

python train.py
pip install xxx

这个权限就高很多了。

所以我会把它们理解成：

复制代码

FilesystemBackend
= 可以动文件

LocalShellBackend
= 可以动终端

后者风险明显更高。

如果是真实生产环境，一般不能直接把宿主机 Shell 完全交给 Agent，最好放在 Sandbox 里。

7. Permission

Agent 能调用某个工具，不代表这个操作一定应该执行。

所以还需要权限控制。

主要有：

复制代码

allow
deny
interrupt

可以简单理解成：

复制代码

allow：直接执行
deny：直接拒绝
interrupt：先停下来让人确认

比如 Agent 想删除一个重要文件，就可以先触发 interrupt，然后由用户确认。

这其实就是 Human-in-the-Loop。

8. Tool、Permission、Backend 的区别

这一章里这三个概念容易混。

我自己的记法是：

复制代码

Tool
→ 能做什么

Permission
→ 允不允许做

Backend
→ 实际在哪里做

比如：

复制代码

Agent
→ edit_file
→ Permission 检查
→ Backend 真正修改文件

这样就比较清楚了。

前两章更多是在讲 Agent 怎么搭起来，第三章开始真正进入复杂 Agent 的工程问题：上下文怎么控制、文件怎么保存、权限怎么限制。

一句话总结

Deep Agents 的虚拟文件系统，让 Agent 会读写文件，让它学会管理上下文。