跳转到内容

这页专门回答一个问题:

这些概念到底怎么放在同一张图里理解?

如果你只记一句话,记这个:

workspace 是逻辑项目边界,sandbox 是执行宿主边界,worker 是在宿主中运行的执行角色。

系统里有两条需要同时看的链路:

Agent Engine -> Workspace -> Session -> Run

这条链路回答:

  • 当前是哪个项目
  • 这个项目声明了哪些能力
  • 会话属于谁
  • 一次执行如何落在某个 run 上

Agent Engine -> Worker -> Sandbox -> Active Workspace Copy

这条链路回答:

  • 由谁执行
  • 在哪个宿主里执行
  • 文件和命令实际落在什么执行副本上
flowchart TD
A["Agent Engine"] --> B["Workspace"]
B --> C["Session"]
C --> D["Run"]
A --> E["Worker"]
E --> F["Sandbox"]
F --> G["Active Workspace Copy"]
B -. "materialize into active copy" .-> G
D -. "executed by owner worker" .-> E
概念它是什么它不是什么
Agent Engine调度、执行、恢复、审计、API / SSE 暴露系统不是单个 agent 定义
Workspace项目、能力发现、会话归属边界不是执行宿主
Session某个 workspace 下的一段连续协作上下文不是执行线程
Run一次模型推理与工具循环不是长期驻留对象
Worker承载 run 执行的角色不是项目本身
Sandboxworker 所在的文件系统与进程宿主环境不是 workspace 的别名
Active Workspace Copy活跃 workspace 在宿主中的实际执行副本,也就是 sandbox 里真正被读写和执行命令的那份文件不是新的 workspace 类型
Runtime新建 workspace 时使用的初始化源不是当前活跃执行副本
Spec用户额外叠加给 runtime 的扩展层不是整个 runtime 结构
对比项WorkspaceSandbox
关注点项目与能力宿主与执行环境
回答的问题“这是哪个项目?”“当前在哪儿跑?”
典型内容AGENTS.md、agents、models、skills、hooks文件系统、进程、命令执行、挂载点
API 主语/workspaces/sandboxes

结论:

  • workspace 定义项目身份和能力集合
  • sandbox 定义活跃副本的文件系统与进程上下文
对比项WorkspaceRuntime
关注点当前项目初始化来源
何时使用运行中、发现能力、执行任务POST /workspaces 创建时
是否参与当前执行是否

结论:

  • runtime 负责“从什么初始化”
  • workspace 负责“当前到底在运行什么项目”
对比项WorkerSandbox
关注点执行角色执行宿主
回答的问题“谁在执行?”“执行发生在哪个环境里?”
典型动作消费 run、驱动 tool loop、flush / evict提供文件、进程、命令、挂载、生命周期

结论:

  • worker 是角色
  • sandbox 是 worker 所处环境

文件读写和命令执行总是针对“活跃执行副本”进行,而不是针对抽象的 workspace 元数据。

因此:

  • 查 catalog、查元数据、创建或删除项目时,用 /workspaces
  • 读文件、写文件、执行命令时,用 /sandboxes

这是为了保证:

  • embedded
  • self_hosted
  • e2b

三种 provider 下,上层 API 语义保持一致。

这里的 /sandboxes 路由、/workspace 根路径,以及“文件与命令总是挂在 sandbox 视角下”这套设计,是为了和 E2B 的接口语义保持兼容而刻意固定下来的,不是可以随意切回 /workspaces 文件 API 的内部实现细节。/workspaces 本身仍然保留,用于 workspace 的身份、元数据、catalog 与生命周期管理。

典型过程:

  1. workspace 在逻辑上被创建或导入
  2. controller / owner routing 决定它归哪个 worker
  3. worker 在自己的执行环境里 materialize 出该 workspace 的执行副本
  4. run 在这个执行副本上执行文件读写、命令和工具调用
  5. workspace 空闲、drain 或删除时,再 flush / evict 回外部存储或受管源目录
模式活跃执行副本通常在哪
embedded本机进程可访问的本地 workspace
self_hosted远端 sandbox 内的执行副本
e2b远端 E2B sandbox 内的执行副本

注意:

  • 逻辑上的 workspace 身份不变
  • 变化的只是活跃执行副本所在的宿主位置

如果你在看:

  • terminology.md 看命名边界
  • workspace/README.md 看 workspace 里声明什么
  • server-config.md 看这些对象在部署里落到哪里
  • openapi/workspaces.md 看项目与能力对象怎么管理
  • openapi/files.md 看活跃执行副本怎么暴露文件和命令能力

按顺序记:

  1. Runtime 初始化 Workspace
  2. Spec 扩展 Runtime
  3. Engine 运行 Workspace
  4. Worker 在 Sandbox 里执行 Run
  5. 活跃 Workspace 会 materialize 成 Active Workspace Copy