Agent 沙箱工作区如何设计和实现？
未标记
考查重点：工作区初始化与执行隔离。用户/任务独立工作区和执行账号，从指定版本初始化，工具限制文件网络资源，结束保产物再回收
本题目录
参考答案
核心回答
Agent沙箱工作区要同时解决任务文件放在哪里、代码在什么环境执行、允许访问哪些资源，以及结束后怎样保留产物和回收环境。可以按用户和任务建立独立工作区，从指定代码版本或输入快照初始化，在受限执行环境中运行工具，把任务状态与最终产物保存到可恢复的位置。
目录负责组织文件，沙箱负责限制进程和资源。只给每个Agent换一个工作目录，并不能阻止它读取其他目录、访问网络或启动宿主机命令；这些边界要由工具执行器和操作系统隔离共同实施。
从一个任务的生命周期设计
创建任务时记录用户、任务ID、代码版本、输入文件、运行镜像和资源配置，准备独立的可写层或存储卷。共享依赖可以复用只读缓存，用户输入、临时文件和输出目录则按任务隔离，避免两个任务互相覆盖。
工具执行器根据任务ID找到对应环境，传递受控参数、工作目录和短期凭证，记录命令结果、退出状态与资源消耗。任务调度状态存放在可靠状态库，不能只依赖容器里的聊天记录；容器退出后仍能知道任务是否完成、哪些产物已经确认。
结束时先检查产物，再按策略保存文件、日志和版本信息，最后回收进程、挂载、临时凭证及执行环境。超时、取消和异常退出也走清理路径。长任务可以保存检查点，但恢复前仍需确认输入版本和已发生的外部动作。
隔离具体怎样实现
文件访问只挂载任务所需目录，源数据可只读，输出目录可写；路径校验考虑规范化、符号链接和挂载语义。不要把宿主机根目录、容器管理socket或整套长期密钥交给任务。
进程与网络通过命名空间及相应策略限制，CPU、内存、进程数、存储和运行时长设置配额。网络访问按任务需要开放目标和服务身份，访问外部业务系统时继续校验用户权限；容器里的请求也不能天然越过业务授权。
普通容器共享宿主内核，适合环境复现和基本隔离，但隔离强度仍取决于配置。运行不可信代码、面对多租户攻击时，可评估gVisor或微虚机等方案，同时验证系统调用兼容性、启动耗时和运维成本。不是每项任务都需要最重隔离，也不能把容器名称当作安全保证。
以两个容器任务为例，区分文件布局、进程隔离与外部访问控制：
这是一种容器部署示意。宿主工具执行器与操作系统共同限制资源，图不表示每个系统调用都由工具执行器转发；外部业务动作也不会随工作区回滚。
多个Agent怎样共享产物
同一任务可以共享一个只读基线，由各执行者写独立分支或目录，最后由明确的归并者处理结果。需要并发修改同一文件时，应有版本检查、锁或冲突合并策略；共享盘只提供存储，不自动解决并发覆盖。
文件系统抽象可以把本地磁盘、对象存储和远端环境统一为读写接口，但仍要定义原子写、版本和权限。对象存储的重命名、目录和一致性语义可能与本地文件系统不同，不能只换一个路径就假定行为完全一致。
常见追问
沙箱快照能撤销所有操作吗？ 可以恢复相应文件或环境状态，但发信、退款等外部动作不会随工作区回滚。它们需要幂等记录、状态查询或明确的补偿流程。
怎样验证这套设计？ 分别检查正常任务、越界路径、软链接、任务间读写、资源超限、断线恢复和异常清理；同时测量环境就绪时间、执行耗时与产物恢复成功率，区分启动优化和隔离有效性。
对应教程
- 第8章：Docker快速入门与Dify部署排障：§1.2–1.3说明容器的可复现性与共享内核特点；本文在此基础上展开任务工作区、权限和生命周期设计。
参考资料
- 国内：Harness工程中的执行环境：借鉴执行环境与文件系统的职责，说明正文中模型动作如何接到工作区、可靠任务状态与沙箱约束。
- 国内：Agent文件系统边界与隔离：文件系统访问边界一节解释工作目录为何不是安全边界，以及路径穿越、符号链接、挂载和并发任务需要怎样验证。
- 国内：Workspace与抽象文件系统：Workspace与抽象文件系统部分说明文件、产物、配置和远端存储的分工，并提醒文件回滚不能撤销外部业务写入。
- 国外：Docker Engine security：依据 namespaces、cgroups、挂载与 capabilities 的机制，说明正文中进程可见范围、资源配额和宿主访问限制。
- 国外：Introduction to gVisor security：参考 Sentry 应用内核与保护范围，解释正文中普通容器与更强隔离方案的取舍条件。
DeerFlowPython
核心回答
DeerFlow 把沙箱工作区拆成线程文件目录、沙箱 Provider 和统一文件工具：按用户与线程定位上传文件、过程文件和最终产物，工具通过 Provider 读写对应环境。目录解决文件归属，Provider 决定实际在哪执行；本地文件模式与容器模式的隔离能力不同。
例如整理上传资料并生成报告时，输入放 uploads，中间笔记放 workspace，报告放 outputs。普通子 Agent 委派会带入父任务的线程和文件上下文，因此可以读取已有材料、交回文件产物；这不等于每个子 Agent 都获得一台独立虚拟机。
线程路径怎样变成工具可用的工作区？
Paths 在用户作用域下，将线程文件组织到 {base_dir}/users/{user_id}/threads/{thread_id}/user-data/，下分 workspace、uploads、outputs；不带用户的旧路径另有兼容逻辑。ThreadDataMiddleware 根据运行上下文中的用户与线程，生成三个实际路径，放入 thread_data。模型侧使用固定虚拟路径 /mnt/user-data/...，不需要知道部署机器的真实目录。路径定义、线程路径注入。
默认可以延迟到首次文件或命令工具调用时再初始化沙箱。ensure_sandbox_initialized() 在复用或申请环境前检查沙箱执行授权，并结合当前用户、线程校验缓存的沙箱身份；不能只拿历史状态中的 sandbox_id 就认定环境仍适用。初始化与复用。
本地文件模式和容器后端有什么区别？
LocalSandboxProvider 在宿主进程侧操作文件。 它按用户、线程缓存 LocalSandbox，把虚拟路径映射到对应实际目录。文件工具先校验允许路径，再解析真实路径并检查是否仍在当前线程目录内；自定义挂载还要遵守只读标记。当前示例配置默认使用此 Provider，并设置 allow_host_bash: false。开启宿主命令后，命令可以使用宿主真实路径，所以这些映射不能替代进程隔离。本地 Provider、路径边界检查。
AioSandboxProvider 的本机后端才负责创建独立容器。 无 provisioner_url 时选择 LocalContainerBackend，由它管理 Docker 或 Apple Container；配置 provisioner 时改用远端后端。这里的“本机容器后端”和上面的“宿主文件 Provider”是两种实现。后端选择、容器运行时。
本机容器通过挂载把当前线程三个目录暴露为相同的虚拟路径，因此后端写入上传文件后，容器可以直接读取。远端环境若不共享存储，则需要文件同步，不能只把同一个路径字符串传过去。线程目录挂载、远端同步配置。
文件怎样从生成走到交付？
以 /mnt/user-data/outputs/report.md 为例，write_file 先取得沙箱并确保线程目录存在；本地模式完成路径映射和越界检查后调用 sandbox.write_file()，容器模式由对应 Provider 的文件接口处理。读取也走同一沙箱抽象。主 Agent 和普通子 Agent 可以共享线程文件，因此并行工作宜分配不同产物路径，最后再汇总，不能把共享工作区当成自动冲突合并机制。文件读写入口、写入处理、委派携带文件上下文。
文件准备好后，present_files 将路径规范到当前线程的 outputs 范围，并把虚拟路径加入状态中的 artifacts，供客户端展示。它负责登记交付引用，不负责生成文件或判断报告结论是否正确。产物呈现。
环境释放与文件保留怎样配合？
并发的主、子 Agent 执行分别持有沙箱租约，最后一个使用者释放后才进行相应环境回收，避免主任务先结束就关闭仍被子任务使用的环境。AIO 的健康环境可以进入预热池复用；本地 Provider 的 release() 则不删除线程文件。线程文件与执行环境分开管理，才便于后续读取产物和继续任务。租约生命周期、AIO 释放、本地释放。
这种设计的取舍是：本地模式启动和调试简单；容器或远端 Provider 提供更独立的执行环境，但增加镜像、挂载、同步和回收成本。应按代码可信程度与部署方式选后端，目录隔离、工具授权和进程隔离分别落实。
参考资料
- 国内：DeerFlow：Sandbox 配置：依据本地模式、宿主命令开关和 AIO 容器模式的区别说明后端选择，并采用远端是否共享目录决定同步方式的约定。
- 国内：JavaGuide：Harness Engineering：采用文件系统保存产物、执行环境承接工具动作的分工，解释线程文件与运行资源为何分开管理。
- 国内：zero2Agent：Agent 文件系统访问边界与工作目录隔离：采用路径校验与运行隔离各有职责的解释，说明本地路径映射不能视为宿主进程的安全边界。
- 国内：WeThinkIn：Workspace 与抽象文件系统：采用统一文件接口与底层存储语义的区分，说明虚拟路径统一后，远端同步和并发文件归属仍需处理。
- 国外：Docker Engine security：依据命名空间、资源限制与挂载配置的职责，说明使用容器后的隔离仍取决于实际权限和挂载范围。
- 国外：Introduction to gVisor security：依据用户态应用内核及系统调用处理机制，解释通用答案中普通容器和更强隔离选项的区别。
