17. Sandbox 源码：执行环境和文件路径怎么管理

这一篇看哪些文件

Sandbox 相关目录：

backend/packages/harness/deerflow/sandbox/

建议先看：

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

sandbox.py：抽象边界

sandbox.py 通常定义 sandbox 的基础能力。

读的时候关注：

文件读写接口
命令执行接口
路径处理方式
错误类型

sandbox_provider.py：谁来创建环境

Provider 负责创建和管理 sandbox。

如果以后要换成本地、Docker 或远程执行环境，provider 是重要扩展点。

local_sandbox.py：本地实现

本地实现适合开发和调试。

但本地实现不等于安全隔离。读源码时要注意它如何限制路径，如何处理文件操作。

middleware.py：把 sandbox 注入执行链路

middleware 负责把 sandbox 放进 Agent 运行上下文。

如果工具调用时能拿到 sandbox，通常就是在这层完成连接。

security.py：安全检查

这里重点看路径、命令、文件访问相关检查。

不要只看 happy path。安全代码最重要的是异常路径和拒绝策略。

这一篇你要记住

Sandbox 源码主线是：

抽象接口 → provider 创建环境 → middleware 注入 → tools 使用 → security 兜底

后面做报告产物时，会用到这些文件边界。

路径处理是重点

读 sandbox 源码时，最应该关心路径。

包括：

相对路径如何转绝对路径
是否允许 ../
文件是否限制在工作目录内
并发写入怎么处理

项目里有 file_operation_lock.py，这说明文件操作并发也是需要处理的问题。

工具层怎么使用 sandbox

sandbox/tools.py 值得看。

它通常会把 sandbox 能力包装成 Agent 可调用工具。

也就是说，Agent 不应该直接操作文件系统，而是通过受控工具完成读写。

安全检查不要绕过

如果你后面新增文件工具，不要为了方便直接读写宿主机路径。

先看现有 security 和 provider 逻辑，保持同一套边界。