doc/tmp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add

Browse Source
This commit is contained in:
V-LiuShuang
2026-07-29 17:25:12 +08:00
parent 8979eca3a0
commit 28f3727f43
1 changed files with 23 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
agentscope-sandbox.md
View File

@@ -4,57 +4,15 @@
## 支持的沙箱类型
| 沙箱类型 | agentscope | agentscope-java | 共同点 |
| --- | --- | --- | --- |
| Docker | ✅ `DockerWorkspace` | ✅ `DockerFilesystemSpec`（harness 内置） | 本地隔离、需 Docker |
| Kubernetes | ✅ `K8sWorkspace`（Pod + PVC） | ✅ `KubernetesFilesystemSpec`（extension） | 集群级资源、适合生产 K8s |
| E2B | ✅ `E2BWorkspace` | ✅ `E2bFilesystemSpec` | 云沙箱 SDK、metadata/API 重连 |
| Daytona | ✅ `DaytonaWorkspace` | ✅ `DaytonaFilesystemSpec` | 云沙箱、标签/API 重挂接 |
| AgentRun | ❌ 暂未支持 | ✅ `AgentRunFilesystemSpec`（阿里云） | — |
| OpenSandbox | ✅ `OpenSandboxWorkspace` | ❌ 暂未支持 | — |
| Bubblewrap | ✅（另有 Local） | ❌（有 LocalFilesystemSpec） | Linux 轻量沙箱 / 本机模式 |
### agentscope
| 后端 | 供给方式 | 持久化 | Teardown | Bootstrap |
| --- | --- | --- | --- | --- |
| **Docker** | aiodocker 建容器 | Bind-mount 或 ephemeral | kill + delete 容器 | 镜像已含 gateway |
| **K8s** | Pod + PVC（`as-ws-{id}`） | PVC 跨 Pod 存活 | 删 Pod，默认可保留 PVC | 首次 apt + uv + gateway |
| **E2B** | `AsyncSandbox.create/connect` | pause 保留磁盘 | `pause()` | 首次 bootstrap |
| **Daytona** | SDK create / label 查找 | `stop(force=False)` | stop + close client | 首次 bootstrap（路径由 SDK 推导） |
| **OpenSandbox** | `Sandbox.create` / resume / connect | `pause()` | pause + close | 首次 bootstrap |
云后端共性：用 `agentscope.workspace.id`（或等价 metadata/label）索引；Manager 缓存 miss 时可跨服务副本重连——这是文档推荐的**分布式部署**路径。
[OpenSandbox](https://open-sandbox.ai/getting-started) 是通用沙箱平台（Docker/K8s 运行时 + 多语言 SDK）。agentscope 通过官方 `opensandbox` SDK：
- 按 metadata 过滤 RUNNING/PAUSED 沙箱并 resume/connect；
- close 时 **pause** 保文件系统；
- 与 E2B 类似走 `_bootstrap_commands` 安装 gateway。
Java 侧 v2.0.0 **未集成**，若要在 Java 使用需自研 `SandboxClient` 或等待官方 extension。
## 隔离模型
| | agentscope `IsolationPolicy` | agentscope-java `IsolationScope` |
| 沙箱类型 | agentscope | agentscope-java |
| --- | --- | --- |
| 会话级 | `PER_SESSION` | `SESSION`（沙箱默认） |
| 用户级 | `PER_USER`（跨 agent 慎用） | `USER`（跨 session 共享记忆/快照） |
| Agent 级 | `PER_AGENT`（默认，按 user+agent） | `AGENT`（按 agent 名共享） |
| 全局 | 无对等枚举 | `GLOBAL` |
| 绑定时机 | Session 创建时写入 `workspace_id` | 每次 call 用 RuntimeContext 算 isolation key |
### agentscope-java
| 后端 | 模块位置 | 交互方式 | 持久化侧重 |
| --- | --- | --- | --- |
| **Docker** | harness 核心 | CLI | Tar 快照 + 可选 bind |
| **Kubernetes** | extension | fabric8 / Pod 侧 exec+tar（文档侧亦描述 agent-sandbox WarmPool 演进） | 快照 Spec；集群侧还可结合 PVC/模板 |
| **E2B** | extension | E2B HTTP + envd；支持 TAR / NATIVE_SNAPSHOT 等持久化模式 | 平台快照或 tar |
| **Daytona** | extension | Control Plane HTTP API | 快照 Spec；不应用 host bind-mount（有则 WARN） |
| **AgentRun** | extension | 阿里云 AgentRun API；可配 NAS/OSS mount、MCP URL | 云侧空闲超时 + 快照 Spec |
公共能力均来自 `SandboxFilesystemSpec`：`isolationScope`、`snapshotSpec`、`executionGuard`、`workspaceProjection*`。
| Docker | ✅ `DockerWorkspace` | ✅ `DockerFilesystemSpec` |
| Kubernetes | ✅ `K8sWorkspace`| ✅ `KubernetesFilesystemSpec` |
| E2B | ✅ `E2BWorkspace` | ✅ `E2bFilesystemSpec` |
| Daytona | ✅ `DaytonaWorkspace` | ✅ `DaytonaFilesystemSpec` |
| AgentRun | ❌ | ✅ `AgentRunFilesystemSpec` |
| OpenSandbox | ✅ `OpenSandboxWorkspace` | ❌ |
| Bubblewrap | ✅（依赖操作系统） | ❌ |
## 架构对比
@@ -76,11 +34,10 @@ BackendBase (exec_shell / read_file / write_file)
└─ 内置工具 Bash/Read/Write/Edit/Grep/Glob 透明落到沙箱内
```
关键设计点：
关键设计：
1. **模板方法**：子类只实现 `_provision_backend` / `_teardown_backend` / `_bootstrap_commands`。
2. **容器内 MCP Gateway**：宿主机通过 `GatewayClient` + `backend.exec_shell` 驱动网关（一般不依赖宿主机到沙箱的端口映射）。
3. **WorkspaceManager**：`PER_AGENT` / `PER_SESSION` / `PER_USER`，空闲 TTL 驱逐；云后端可按 metadata/label 跨节点重连。
- **容器内 MCP Gateway**：宿主机通过 `GatewayClient` + `backend.exec_shell` 驱动网关（一般不依赖宿主机到沙箱的端口映射）。
- **WorkspaceManager**：`PER_AGENT` / `PER_SESSION` / `PER_USER`，空闲 TTL 驱逐；云后端可按 metadata/label 跨节点重连。
### agentscope-java
@@ -103,29 +60,30 @@ SandboxBackedFilesystem + ShellExecuteTool
└─ 文件工具 / execute 全部转发到沙箱
```
关键设计点：
关键设计：
1. **声明式 Spec**：`DockerFilesystemSpec` 等只描述「如何创建」，不是运行时文件系统本身。
2. **Call 边界生命周期**：每次推理前后自动 acquire/start/stop，适合多租户按次计费与快照恢复。
3. **快照与执行后端正交**：换 Docker/K8s/E2B 不影响 `LocalSnapshotSpec` / `RedisSnapshotSpec` / `OssSnapshotSpec` 的选择。
4. **Workspace Projection**：启动时把宿主 `AGENTS.md`、`skills/`、`subagents/`、`knowledge/` 等打 tar 注入沙箱，按内容 SHA-256 增量跳过。
- **生命周期管理**：每次推理前后自动 acquire/start/stop，适合多租户与快照恢复。
- **快照与沙箱解耦**：换 Docker/K8s/E2B 不影响 `LocalSnapshotSpec` / `RedisSnapshotSpec` / `OssSnapshotSpec` 的选择。启动时把宿主 `AGENTS.md`、`skills/`、`subagents/`、`knowledge/` 等打 tar 注入沙箱，按内容 SHA-256 增量跳过。
## 基于Docker的沙箱
双端对照表
## Docker沙箱双端对照表
| 对比项 | agentscope | agentscope-java |
| --- | --- | --- |
| API 形态 | aiodocker（Engine API） | docker CLI |
| API 形态 | Docker Engine API | CLI |
| 保活命令 | `sleep infinity` | `while :; do sleep 3600; done` |
| 镜像策略 | 自动构建并内容哈希缓存 | 用户指定现成镜像 |
| 默认网络 | Docker 默认（通常有网） | **`none`** |
| 镜像策略 | 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 引擎交互，agentscope-java 通过 cli 与 Docker 引擎交互。明显 agentscope 的设计更靠谱一些，因为通过 HTTP API 端点交互，有2个好处：
- agentscope 实例本身可以容器化部署，而 agentscope-java 必需在宿主机用 `java -jar` 运行，因为它需要在宿主机上执行 `docker run` 命令。
- 通过 HTTP API 端点 agentscope 可以控制远程服务器上的 Docker 容器。
### agentscope
#### 实现原理