# Intro

分析 agentscope、agentscope-java 对于容器沙箱的支持。

## 支持的沙箱类型

| 沙箱类型 | agentscope | agentscope-java |
| --- | --- | --- |
| Docker | ✅ `DockerWorkspace` | ✅ `DockerFilesystemSpec` |
| Kubernetes | ✅ `K8sWorkspace`| ✅ `KubernetesFilesystemSpec` |
| E2B | ✅ `E2BWorkspace` | ✅ `E2bFilesystemSpec` |
| Daytona | ✅ `DaytonaWorkspace` | ✅ `DaytonaFilesystemSpec` |
| AgentRun | ❌ | ✅ `AgentRunFilesystemSpec` |
| OpenSandbox | ✅ `OpenSandboxWorkspace` | ❌ |
| Bubblewrap | ✅（依赖操作系统） | ❌ |

## 架构对比

### agentscope

Workspace + Backend + Gateway

```
WorkspaceManager (服务侧缓存 / TTL / IsolationPolicy)
        │
        ▼
SandboxedWorkspaceBase.initialize()
  ├─ _provision_backend()     ← Docker/E2B/K8s/Daytona/OpenSandbox 各实现
  ├─ _ensure_workspace_layout()  (/workspace、skills、sessions、data、.mcp)
  └─ _setup_mcp_gateway()     ← 容器内 FastAPI MCP Gateway
        │
        ▼
BackendBase (exec_shell / read_file / write_file)
  └─ 内置工具 Bash/Read/Write/Edit/Grep/Glob 透明落到沙箱内
```

关键设计：通过 MCP 网关收敛文件系统相关 tool 的访问，采用空闲 TTL 驱逐的方案释放沙箱资源。

### agentscope-java

Filesystem Spec + SandboxManager

```
HarnessAgent.Builder.filesystem(DockerFilesystemSpec / …)
        │
        ▼
SandboxFilesystemSpec.toSandboxContext(hostWorkspaceRoot)
  └─ SandboxContext(client, options, snapshotSpec, workspaceSpec, isolationScope)
        │
        ▼
SandboxLifecycleHook
  PreCall  → SandboxManager.acquire → Sandbox.start() 
  PostCall → Sandbox.stop() (tar 快照) → persist state → release
        │
        ▼
SandboxBackedFilesystem + ShellExecuteTool
  └─ 文件工具 / execute
```

关键设计：在ReAct生命周期内，通过 hook 机制（2.0版本叫中间件）start、stop 沙箱。

## Docker沙箱双端对照表

| 对比项 | agentscope | agentscope-java |
| --- | --- | --- |
| API 形态 | Docker Engine API | CLI |
| 保活命令 | `sleep infinity` | `while :; do sleep 3600; done` |
| 镜像策略 | all-in-one镜像，自动构建并内容哈希缓存 | 用户指定 |
| 默认网络 | Docker 默认| 用户指定 |
| 持久化 | Bind-mount（可选） | Tar 快照为主 + 可选 bind-mount |
| 生命周期 | Workspace 长生命周期 | 按 Agent `call` 借还 |
| MCP | 容器内 Gateway | Harness 侧注册；沙箱只做 FS/Shell |
| 资源限制 | 较弱（构造参数少） | memory / cpu / ports / network |
| 水平扩展 | 不适合 | 需外置快照/状态存储 |

### 优点

- agentscope：
  - 通过 HTTP API 与 Docker 引擎交互，除了与本机 Docker 引擎交互之外，还可以访问远程服务器上的 Docker 引擎。
  - 自动构建镜像，且可以随着依赖库的增删不断迭代 Dockerfile。
- agentscope-java：
  - 每次 call 的时候都会在 start/stop/snapshot 生成 tar 包快照。
  - 隔离级别更贴近多租户场景（SESSION/USER/AGENT/GLOBAL）覆盖多租户常见模型。

### 弊端

- agentscope：
  - 文件沙箱的生命周期过长，强依赖 TTL 清扫。
  - 工作区没有快照或副本能力，可以自行开发。
- agentscope-java：
  - 随着工作区目录越来越大，会导致快照越来越慢（tar命令）可以自定义这个逻辑规避。
  - 没有 agentscope 那样不断迭代镜像的能力，需要人工干预（私以为自动迭代沙箱镜像是个伪需求）
  - 若隔离级别会 session 级别，每个 session 都会被拉起一个容器（要控制一台服务器的会话总数量）