TrueForge 沙箱环境(Sandbox Environments)UI 功能默认开启:从 Feature Flag 到生产可用的演进
TrueForge 沙箱环境(Sandbox Environments)UI 功能默认开启:从 Feature Flag 到生产可用的演进
导读
本文围绕 TrueForge 仓库中的变更集(changeset)enable-sandbox-environments-by-default.md 展开,核心主题是:移除沙箱环境(Sandbox Environments)前端的 feature flag,让 Environments UI 在 @truefoundry/trueforge 与 @truefoundry/trueforge-ui 两个包中默认启用。对于 TrueForge 的开发者、Agent 平台集成方以及使用沙箱环境的用户来说,本文将讲清三个层面的内容:这条变更在版本管理上意味着什么、feature flag 在源码中是如何发挥作用的、以及默认开启后 Environments 页面背后完整的 CRUD 能力与配置语义。读完你将掌握 Environments 功能从"实验开关"到"默认能力"的完整技术脉络,并能在集成时正确理解相关路由、Server 适配与配置项的作用。
变更集内容解读:一次"去 flag 化"的 patch 变更
变更集是 Changesets(基于 .changeset/README.md 中说明的 @changesets/cli 构建工具)为多包仓库生成、用于统一版本与发布说明的机制。本次变更文件的核心内容非常简短但语义明确:
---
'@truefoundry/trueforge': patch
'@truefoundry/trueforge-ui': patch
---
Remove the sandbox-environments frontend feature flag and always enable environments UI.
逐字段解读:
- 涉及包:
@truefoundry/trueforge(后端 harness 包,见 packages/trueforge/package.json)与@truefoundry/trueforge-ui(基于 assistant-ui 构建的 Agent 聊天 UI 包,见 packages/trueforge-ui/package.json),两者均标记为patch级变更,说明这是一次向后兼容的行为调整,不会破坏现有 API 与集成。 - 变更内容:删除
sandbox-environments前端 feature flag,并"始终启用"(always enable)Environments UI。这意味着此前的沙箱环境管理界面是通过前端特性开关控制的(对应变更集 feature-flag-sandbox-environments.md 中描述的 "Add a frontend feature flag for sandbox-environment management"),而本次变更将其正式转正为默认能力。
从变更历史的时间线可以看出 Environments 功能的演进路径:
- 引入阶段:变更集 feature-flag-sandbox-environments.md 首次为沙箱环境管理"添加前端 feature flag",功能默认处于受控状态;
- 打磨阶段:变更集 environments-ui-polish.md 对 Environments UI 做了一系列体验优化,包括默认 Updated 值的连字符显示、Building 状态标签、仅表单的创建抽屉、secrets 文档链接与 allowed-hosts 文案,以及"沙箱关闭时隐藏 Manage Environments 入口"等;
- 默认开启:本次变更移除 flag,Environments UI 对所有用户默认可见可用。
这条变更同时暗示了一个重要事实:feature flag 是纯前端的(frontend feature flag),后端沙箱环境的 API 与数据模型早已具备,前端只是通过开关渐进式地开放界面入口。这也与"环境变更如何到达运行中的会话"等文档化能力(见 docs/sandbox.mdx)的沉淀节奏一致。
feature flag 的前世今生:代码中它是如何被"移除"的
要理解"移除前端 feature flag"具体指什么,需要先看清 Environments 功能在源码中的启用机制。以下分析均基于当前仓库代码状态,可用于推断移除前后系统的行为差异。
Chrome 门控(Chrome Gating)机制
在 trueforge-ui 中,页面入口的显隐由一个统一的门控函数体系控制,集中在 packages/trueforge-ui/src/server/serverChrome.ts。其中与 Environments 相关的门控逻辑是:
/** Environments page (sandbox environments CRUD). */
export function isEnvironmentsChromeEnabled({
sandboxEnvironments,
}: {
sandboxEnvironments: SandboxEnvironmentServer | null | undefined;
}): boolean {
return sandboxEnvironments != null;
}
关键点在于:门控只检查 sandboxEnvironments Server 是否被注入。当 createTrueForgeServer(见 packages/trueforge-ui/src/server/createTrueForgeServer.ts)在构造 Server 选项时传入 sandboxEnvironments 端口,Environments 入口即启用。在官方适配器中,该端口由 packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts 中的 createSandboxEnvironmentServer({ client }) 提供:
sandboxEnvironments: createSandboxEnvironmentServer({ client }),
serverChrome.ts 中的 toEffectiveRoutes 进一步把这些门控映射到具体路由:environments: isEnvironmentsChromeEnabled({ sandboxEnvironments }) ? routes.environments : null。也就是说,在移除前端 feature flag 之前,门控通常还需要额外叠加一个"功能开关为真"的判断;移除之后,只要后端注入 sandboxEnvironments Server,Environments 页面、侧边栏按钮与路由就全部可用,无需任何前端开关参与。
侧边栏入口与页面路由
侧边栏的 Environments 按钮实现位于 packages/trueforge-ui/src/atoms/EnvironmentsButton.tsx,其启用条件与门控保持同步:
const enabled = isEnvironmentsChromeEnabled({ sandboxEnvironments: sandboxEnvironmentServer }) && shell != null;
if (!enabled) return null;
按钮点击时会打开 environmentsOpen 的抽屉/页面,并在首次打开时上报 AnalyticsEvents.Environment.PAGE_OPENED 埋点事件。路由层面,packages/trueforge-ui/src/routing/ShellRouteSync.tsx 会通过 useOptionalSandboxEnvironmentServer() 获取可选的 Server 端口,并调用 toEffectiveRoutes 计算出最终生效路由集合。因此可以推断:移除 feature flag 的本质,是把 Environments 的可用性从"依赖前端开关"改为"仅依赖后端端口注入",让默认集成即开箱即用。
Environments 页面背后的 Server 适配层
移除 flag 并默认启用后,用户看到的 Environments 页面背后是一个完整的 CRUD Server 适配器:packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/sandboxEnvironments/sandboxEnvironmentServer.ts。它负责把运行时 DTO 与 SDK wire 格式互相映射,并提供以下能力:
| Server 方法 | 对应 SDK 调用 | 说明 |
|---|---|---|
listEnvironments |
client.sandboxEnvironments.list |
分页列出环境;默认页大小 25,上限 1000(与后端路由限制一致),支持 pageToken 分页游标 |
getEnvironment |
client.sandboxEnvironments.get(name) |
按名称获取单个环境 |
createEnvironment |
client.sandboxEnvironments.create |
基于 Manifest 创建环境 |
createOrUpdateEnvironment |
client.sandboxEnvironments.createOrUpdate |
不存在则创建、存在则整体更新(幂等语义) |
deleteEnvironment |
client.sandboxEnvironments.delete(name) |
按名称删除环境 |
该适配层还承担了两组双向映射:
toUiManifest:把 SDK 的SandboxEnvironmentManifest转换成 UI 层结构,包括资源默认值(CPU 默认 1、内存默认 1、磁盘默认 3)以及networking中的networkBlockAll、domainAllowList与按hosts划分的secrets;toWireManifest:把 UI 层的 Manifest 还原为 SDK wire 格式提交给后端。
其中 secrets 的映射值得注意——每个 secret 由 env(环境变量名)、value(值)与 hosts(允许发送该值的目标主机)三元组构成,这与 docs/sandbox.mdx 中"Secrets 是网络域(network-scoped)限定"的文档描述完全对应。此外 toIsoInstant 统一把 Date 或字符串转换为 ISO 8601 时间,用于 createdAt / updatedAt 的展示。
默认启用后的 Environments 核心配置语义
由于本次变更使 Environments UI 默认可见,理解其配置项的语义就变得直接相关。以下内容以 docs/sandbox.mdx 的官方说明为准:
什么是沙箱环境
沙箱(sandbox)为 Agent 提供安全隔离的运行环境,用于执行代码、操作文件与运行 shell 命令,与 TrueForge 服务端及基础设施分离。TrueForge 采用 sandbox as tool 模式:Agent 主循环与凭据留在 harness 中,沙箱只负责 exec / 文件 / shell 操作。模型与 MCP 凭据永远不会进入沙箱,简单问答与 MCP 调用不产生沙箱开销。
沙箱环境(Sandbox Environment)是可复用的沙箱蓝图:它描述基础镜像与可选的构建脚本、分配的 CPU / 内存 / 磁盘、环境变量、出站网络规则与 secrets。Agent 创建沙箱时,TrueForge 会克隆其指向的环境。
环境字段与生效时机
Environments 页面每行展示构建状态、资源、网络与最后更新时间。新建环境的表单字段(见 docs/images/sandbox-environment-new.png)及其生效时机如下表:
| 字段 | 说明 | 生效时机 |
|---|---|---|
| Build Script | 构建快照时运行一次的 Shell 脚本,例如 pip install httpx |
下次新建沙箱时,且环境为 Ready 后 |
| Environment Variables | 提供给沙箱进程的普通 KEY=value 对 |
沙箱创建时 |
| Block All Network | 阻断全部出站流量,开启时忽略域名白名单与 secrets | 沙箱创建时 |
| Domain Allow List | 沙箱可访问的主机逗号分隔列表,例如 api.github.com,api.openai.com |
沙箱创建时 |
| Secrets | 按网络域注入的凭据,见下方"Secrets"说明 | 值与主机的编辑立即作用于现有沙箱;新增 secret 在下一次创建时生效 |
构建状态与快照重建
新创建或编辑后的环境会先显示 Building(TrueForge 正在烘烤快照),完成后变为 Ready;只有 Ready 的环境才能被 Agent 选中。修改 build script 或 CPU / memory / disk 会触发新快照烘烤,环境回到 Building 状态,已存在的沙箱继续使用旧快照,直到被替换。自定义环境归属于创建它的用户,且只要仍有已保存的 Agent 引用该环境,就无法删除。
网络控制
默认情况下沙箱出站流量不受限,每个环境可通过 Networking 下的两个控制收紧:
- Domain allow list:逗号分隔的允许主机列表,白名单之外的主机请求一律被阻断,用于把沙箱限定在任务实际需要的服务范围内;
- Block all network:完全禁止出站访问,开启期间域名白名单与 secrets 均被忽略,适用于只做本地代码与文件操作的环境。
网络变更在沙箱创建时生效,因此既有会话会沿用当前策略,直到其沙箱被替换。
Secrets 的注入语义
Secrets 保存的是沙箱自身出站调用所需的凭据(例如 API Token 或 git 凭据),不是模型或 MCP 凭据——后者始终留在 harness 中。每个 secret 包含:
- Env name:沙箱进程看到的环境变量名,例如
GITHUB_TOKEN; - Hosts:该值允许被发送到的目标主机。沙箱进程能看到变量,但 provider 只把值转发给这些主机。
由于 secrets 按网络域限定,Block all network 开启时无法添加 secrets。
变更如何到达运行中的会话
环境设置在沙箱创建时被读取,因此多数修改只影响新会话。唯一的例外是 secrets:保存环境时其值会立即同步到 provider,即便快照重建仍处于 Building 状态。完整对照表(摘自 docs/sandbox.mdx):
| 你修改的内容 | 沙箱已存在的会话 | 新会话 |
|---|---|---|
| 轮换值或编辑已有 secret 的 hosts | 立即生效,下一次请求即用新值或新 hosts,无需新建会话 | 使用更新后的 secret |
| 新增 secret(新环境变量名) | 不注入(secrets 仅在沙箱创建时挂载) | 获得新 secret |
| 环境变量 / 域名白名单 / 全阻断网络 | 保持原状,直到沙箱被替换 | 使用保存的环境 |
| build script / CPU / memory / disk | 在现有构建上继续运行,直到沙箱被替换 | 等待环境 Ready 后使用新构建 |
从"开关"到"默认":对集成者的影响
本次变更对不同类型的用户产生如下影响:
- 使用官方 harness 与官方 UI 的用户:无需任何配置改动即可看到并管理 Environments 页面,沙箱环境管理能力默认开放;
- 自建 Server 端口的集成方:只要在
createTrueForgeServer中注入sandboxEnvironments端口,Environments 入口即默认可见;不再需要维护额外的前端开关状态; - 仅用后端 API 的用户:影响为 0,因为该 flag 是纯前端开关,后端沙箱环境 API 与数据模型没有变化,属于
patch级兼容变更。
从代码结构推断,移除 feature flag 之后,门控逻辑收敛为"端口注入即启用"的单一判据(isEnvironmentsChromeEnabled),Chrome 门控与路由门控继续在 packages/trueforge-ui/src/server/serverChrome.ts 中保持一致,避免了界面入口与路由之间的状态漂移。
小结
本文以变更集 enable-sandbox-environments-by-default.md 为线索,梳理了 TrueForge 沙箱环境 UI 从受控 feature flag 走向默认启用的完整路径:flag 引入(feature-flag-sandbox-environments.md)→ 体验打磨(environments-ui-polish.md)→ 移除 flag 默认开启。在实现层面,Environments 的可用性由 serverChrome.ts 的门控、EnvironmentsButton.tsx 的侧边栏入口、ShellRouteSync.tsx 的路由同步以及 sandboxEnvironmentServer.ts 的 CRUD 适配器共同支撑,其配置语义与生效时机以 docs/sandbox.mdx 为准。对集成者而言,这条变更意味着 Environments 成为默认就绪的开箱能力——只要后端端口注入到位,无需任何前端开关,即可获得完整的沙箱环境管理体验。