16. Sandbox 原理：安全执行和文件边界

只要能执行，就必须谈边界

Agent 能调用工具以后，很快会遇到执行问题：读文件、写文件、运行脚本、生成报告。

这些动作不能直接放任模型在宿主机上随便做。

Sandbox 解决的是边界问题。

Sandbox 管什么

至少管三件事：

能访问哪些路径
能执行哪些操作
生成的文件放在哪里

如果边界不清楚，Agent 很容易把临时文件、用户文件、系统文件混在一起。

DeerFlow 的 sandbox 目录

相关源码：

backend/packages/harness/deerflow/sandbox/

能看到：

local/
local_sandbox.py
local_sandbox_provider.py
middleware.py
sandbox.py
sandbox_provider.py
security.py
tools.py

这说明 sandbox 不只是一个目录路径，而是一套 provider、middleware、安全检查和工具层。

Local 和 Docker 的取舍

本地 sandbox 方便开发。

Docker sandbox 更适合隔离和长期运行。

快速开始可以先本地跑，但只要涉及不可信输入、代码执行或长期服务，就应该认真考虑隔离边界。

这一篇你要记住

Sandbox 不是为了“更高级”。

它是为了让 Agent 的执行行为可控，尤其是文件和命令执行。

下一篇看 sandbox 源码怎么管理路径和操作。

为什么报告生成也需要 Sandbox

很多人以为 sandbox 只和“执行代码”有关。

其实只要 Agent 会写文件，就需要边界。

研究型 Agent 会生成 Markdown 报告、缓存抓取内容、保存中间结果。如果这些文件路径不受控，后续很难清理、下载和审计。

最小边界

第一版至少要明确：

工作目录在哪里
报告输出目录在哪里
是否允许覆盖已有文件
是否允许访问项目外路径

这些规则比“能写文件”本身更重要。

失败时怎么看

如果文件没生成，先查：

sandbox 是否创建成功
工具拿到的路径是否正确
写文件权限是否足够
最终返回的路径是否和实际路径一致

不要只看 Agent 的文字回复。