Agent Scope Java 2.x 系列【25】Harness：沙箱（Sandbox）

文章目录

[1. 概述](#1. 概述)
[2. 隔离共享规则](#2. 隔离共享规则)
- [2.1 slot 生成规则](#2.1 slot 生成规则)
- [2.2 USER（默认）](#2.2 USER（默认）)
- [2.3 SESSION](#2.3 SESSION)
- [2.4 AGENT](#2.4 AGENT)
- [2.5 GLOBAL](#2.5 GLOBAL)
[3. 后端沙箱选型](#3. 后端沙箱选型)
- [3.1 Docker](#3.1 Docker)
- [3.2 Kubernetes](#3.2 Kubernetes)
- [3.3 Daytona](#3.3 Daytona)
- [3.4 E2B](#3.4 E2B)
- [3.5 AgentRun（阿里云 FC3.0）](#3.5 AgentRun（阿里云 FC3.0）)
[4. 工作区映射进沙箱规则](#4. 工作区映射进沙箱规则)
- [4.1 框架内置自动同步](#4.1 框架内置自动同步)
- [4.2 BindMount 宿主机目录挂载（仅 Docker、K8s 可用）](#4.2 BindMount 宿主机目录挂载（仅 Docker、K8s 可用）)
- [4.3 单向隔离约束](#4.3 单向隔离约束)
[5. 自定义自研沙箱后端](#5. 自定义自研沙箱后端)

1. 概述

HarnessAgent 做了一层文件系统 + 命令执行统一抽象接口 ：上层 Agent、Skill、用户 Prompt 只调用统一抽象 API，完全不感知底层存储 / 执行载体是本地磁盘、远端共享存储还是隔离沙箱容器。

抽象接口下提供三套可互换底层实现：

本机 + Shell（本地文件实现）
共享存储实现（分布式多副本）
沙箱 Sandbox 容器实现（Docker/K8s/E2B 等）

前两种模式我们之前已经介绍过了，现在主要介绍 Sandbox 模式。

沙箱（Sandbox）将 Agent 文件读写、命令执行完全隔离在独立环境，宿主无任何风险，提供三大核心能力：

安全执行边界：不可信输入、高危脚本、删除类命令全部隔离，不会污染宿主系统；
跨调用快照恢复 ：
- 自动保存依赖安装产物、临时文件、完整工作环境，重复调用无需重装；
- 恢复优先级：存活容器直接复用 → 快照重建容器 → 全量冷启动；
分布式多副本共享：集群任意节点均可恢复同一用户沙箱状态，适配负载均衡。

2. 隔离共享规则

IsolationScope 是沙箱的共享划分规则，决定：哪些对话 / 用户共用一套沙箱工作环境、哪些完全隔 离，配置在 SandboxFilesystemSpec （例如 DockerFilesystemSpec），共 4 种枚举：USER、SESSION、AGENT、GLOBAL。

核心配套标识：

userId：业务侧用户唯一 ID（同一个人）
sessionId：单次对话会话 ID（同一用户多开对话）

粒度	共享逻辑	并发风险	适用场景
USER（默认）	同userId所有会话共用；无userId自动降级SESSION	多副本并发会覆盖状态，需分布式锁	SaaS多用户，跨会话保留代码环境
SESSION	单个sessionId独立沙箱	天然并发安全，无竞争	对话强隔离、一次性代码任务
AGENT	当前Agent下全部用户/会话共用一套	并发冲突极高，必须加锁	全局公共工具Agent、共享知识库
GLOBAL	整个存储实例全局唯一沙箱	严重写竞争，谨慎启用	极少全局公共执行场景

沙箱底层会根据 IsolationScope + 标识组合生成唯一 slot，slot 相同则共用沙箱。

并发风险总结对照表：

Scope	多副本并发冲突	是否需要分布式锁
USER	有，同用户会覆盖状态	建议开启
SESSION	无，会话完全隔离	不需要
AGENT	严重，全用户争抢同一沙箱	强制开启
GLOBAL	极高，全局竞争	强制开启

选型建议：

C 端多用户代码助手、SaaS 产品：默认 USER + 分布式锁 + OSS 快照
对话数据强隔离、会话之间互不干扰：SESSION
内部公共工具 Agent、所有人共用一套预置环境：AGENT
离线统一批量执行、无多租户隔离需求：谨慎使用 GLOBAL

2.1 slot 生成规则

slot 是沙箱环境的唯一分区标识 / 唯一索引键 ，框架用一串唯一字符串 代表一套独立工作区，相同 slot → 共用一套沙箱，不同 slot → 完全隔离两套沙箱。

由两部分拼接计算生成：

隔离粒度 IsolationScope（USER / SESSION / AGENT / GLOBAL）
运行时传入的身份标识（userId、sessionId）

2.2 USER（默认）

共享逻辑：

同一个 userId，无论多少个 sessionId，全部共用同一个沙箱 slot
如果调用上下文没有传入 userId，框架自动降级走 SESSION 规则，业务无需做空值判断

示例，用户 alice，开了 2 个对话 conv-1、conv-2 时：

执行 pip install pandas 在 conv-1
切到 conv-2 可直接使用 pandas，不用重装

优缺点：

优点：同一用户跨对话环境持久，贴合 SaaS 产品体验
缺点：多副本并发下，同一用户同时发两条请求会争抢沙箱，环境状态可能被覆盖，必须配分布式执行锁

2.3 SESSION

共享逻辑：只以 sessionId 为唯一区分，每个对话独立一套沙箱，互不干扰，和 userId 无关。

示例，alice 的 conv-1、conv-2 是两套完全独立容器，A 会话安装的包，B 会话看不见。

优缺点：

优点：天然并发安全，不存在多请求争抢覆盖问题，不需要分布式锁
缺点：同一用户多会话环境不互通，每次新会话要重新安装依赖，资源开销更大

2.4 AGENT

共享逻辑：当前这个 HarnessAgent 实例下，所有 userId、所有 sessionId 共用同一个沙箱。

示例，不管是 alice 还是 bob，不管什么会话，全部跑在同一个容器里，A 用户生成的文件、安装的依赖，B 用户可见。

优缺点：

优点：全局一套公共工具环境，适合纯工具型 Agent（统一预置脚本、公共依赖）
缺点：数据完全互通，存在用户数据泄露风险；并发冲突极强，生产必须加锁

2.5 GLOBAL

共享逻辑：整个存储实例全局唯一沙箱，所有 Agent、所有用户、所有会话共享一套环境。

使用场景：极少使用，仅内部离线批量统一任务场景，多租户业务严禁使用。

风险：并发写冲突、用户文件互相污染、数据泄露风险最高。

3. 后端沙箱选型

所有沙箱后端实现同一套标准抽象接 口：上层 Agent、文件工具（read_file/write_file）、execute 命令、AGENTS.md、技能脚本完全无感知，切换后端只改 filesystem 配置，业务代码零改动。

3.1 Docker

适用场景：本地开发调试、单机私有化部署、内部可信环境

优势：

启动简单，无集群依赖；
原生支持 BindMountEntry，可直接挂载宿主机本地代码 / 数据集目录；
Shell 执行无额外网络开销，调试友好。

短板：无法分布式跨节点共享容器，多副本集群不推荐。

3.2 Kubernetes

适用场景：自建大规模集群、离线批量代码任务、企业私有化容器平台

优势：

支持节点级宿主机目录 BindMount；
原生容器编排、资源配额、扩缩容；
适合高并发、长时间运行的沙箱任务。

短板：运维成本高，需要维护 K8s 集群。

3.3 Daytona

适用场景：通用云上托管沙箱，通过 HTTP API 远程调用

优势：开箱即用，无需自建容器底座，轻量化接入；

短板：云上服务，不支持挂载宿主机本地目录，无 BindMount 能力。

3.4 E2B

适用场景：线上代码运行场景，看重环境快照恢复速度

优势：托管沙箱服务，平台内置快照能力，环境启停、恢复性能优化更好；

短板：云端隔离，无法绑定本地宿主机目录，依赖外网 / 服务商 API。

3.5 AgentRun（阿里云 FC3.0）

适用场景：国内线上生产环境、低延迟需求、合规要求国内节点

优势：

大陆地域部署，网络延迟低；

支持实例级 NAS、OSS 动态挂载云存储；

底层基于函数计算弹性扩缩，无需管理容器集群；

Harness 框架层面与其他沙箱后端完全等价，接入逻辑统一。

短板：云厂商绑定，本地开发无法使用。

4. 工作区映射进沙箱规则

4.1 框架内置自动同步

宿主 workspace 下固定目录会在每次沙箱启动增量同步到沙箱内部：

text 复制代码

AGENTS.md / skills/ / subagents/ / knowledge/

同步逻辑：

基于文件内容哈希对比，无变更文件跳过传输，减少 IO 开销；
修改宿主脚本后，下次新建 / 恢复沙箱自动加载新版本。

4.2 BindMount 宿主机目录挂载（仅 Docker、K8s 可用）

作用：挂载大型本地代码仓库、数据集，避免每次启动全量同步；

限制：Daytona / E2B / AgentRun 均为云端托管环境，无宿主机访问权限，不支持该能力。

4.3 单向隔离约束

沙箱内部新增 / 修改 / 删除文件，不会反向同步到宿主机器；

如需获取沙箱运行产出文件，只能通过 Agent read_file 工具读取沙箱内文件内容。

5. 自定义自研沙箱后端

现有后端无法满足时，可以自建远程执行服务、第三方私有沙箱 API、单元测试内存 Mock 沙箱等。

实现方式：

实现框架定义的沙箱契约接口（文件读写、命令执行、快照、生命周期）；
将自定义实现传入 filesystem() 构建器配置即可启用；

参考最小 Demo：测试用例 InMemorySandbox，可直接作为改造模板。