Environment 对象和配置字段结构。
Environment 对象
创建、查询、列表、更新和归档接口都会返回该结构。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Environment ID,前缀为 env_ |
type | string | 固定值 "environment" |
name | string | Environment 名称 |
description | string | Environment 描述 |
config | Environment config | Environment 配置 |
metadata | object | Metadata 对象,默认 {} |
archived_at | string | null | UTC 归档时间;未归档时为 null |
created_at | string | UTC 创建时间 |
updated_at | string | UTC 最后更新时间 |
Environment config
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | 是 | "cloud" 或 "self_hosted" |
packages | Environment packages | 否 | Environment 关联的包声明 |
setup_script | string | 否 | 用户 setup script 文本,详见 Environment setup script |
startup_script | string | 否 | 沙箱每次启动都执行的脚本,详见 Environment startup script |
storage | Environment storage | 否 | 自有 OSS bucket 挂载,仅 cloud config 支持 |
self_hosted config 可以包含 type 和可选的 setup_script、startup_script:
self_hosted config 仅支持 type 和可选的 setup_script、startup_script。self_hosted 的 startup_script 只保存并原样返回,由外部 worker 决定是否执行。
Environment packages
packages 是包管理器到软件包规格字符串数组的映射。请求支持 apt、npm 和 pip。Cloud Environment 响应还会返回若干保留字段;省略的数组会返回为 []。
| key | 类型 | 说明 | 示例 |
|---|---|---|---|
type | string | 响应中固定为 "packages" | "packages" |
apt | string 数组 | Debian/Ubuntu 系统包声明 | ["git", "curl", "build-essential"] |
npm | string 数组 | Node.js package 声明 | ["typescript@5.0.0", "eslint"] |
pip | string 数组 | Python package 声明 | ["pandas", "PyYAML==6.0.1"] |
cargo | string 数组 | 响应中的保留字段;当前不支持通过该字段安装依赖 | [] |
gem | string 数组 | 响应中的保留字段;当前不支持通过该字段安装依赖 | [] |
go | string 数组 | 响应中的保留字段;当前不支持通过该字段安装依赖 | [] |
Environment setup script
setup_script 是 sandbox 准备阶段、packages 安装完成之后执行的一段 shell 脚本,用 /bin/bash -lc 运行。常用于克隆代码、写配置文件、warmup 缓存等无法用 packages 表达的初始化步骤。
| 约束 | 值 |
|---|---|
| 类型 | string |
| 最大长度 | 64 KB |
| 解释器 | /bin/bash -lc |
| 超时 | 10 分钟 |
| 执行时机 | sandbox 准备阶段,packages 安装完成之后 |
setup_script 的 exit code 与 stderr 摘要,便于定位失败原因。
Environment startup script
startup_script 是沙箱每次启动都会执行的一段 shell 脚本:沙箱第一次启动时在 setup_script 之后执行,之后每次从暂停中恢复都会再执行一次。用来拉起不会跨暂停保留的进程,例如数据库、dev server 等后台服务。
沙箱暂停再恢复后,磁盘上的文件都还在,进程不会保留。结果落在磁盘上的步骤(安装依赖、克隆代码、生成缓存)放 setup_script;启动进程放 startup_script。
setup_script | startup_script | |
|---|---|---|
| 执行次数 | 每个沙箱一次 | 沙箱每次启动(首次启动、每次恢复)各一次 |
| 适合 | 安装依赖、克隆代码、生成缓存 | 启动服务、拉起后台进程 |
| 约束 | 值 |
|---|---|
| 类型 | string |
| 最大长度 | 64 KB |
| 解释器 | /bin/bash -lc,工作目录、环境变量与 setup_script 相同 |
| 超时 | 5 分钟 |
| 执行时机 | 沙箱每次启动后、执行第一个工具之前;首次启动时在 setup_script 之后 |
- 脚本必须能退出。常驻进程放到后台,并把输出重定向到文件,例如
nohup pnpm dev > /tmp/dev.log 2>&1 &;脚本正常退出后,这些后台进程会继续运行。前台运行、不退出的命令会一直阻塞工具调用,直到超时。 - 脚本退出不等于服务就绪:脚本一退出,agent 的第一个工具调用就会开始,而放到后台的服务可能还要几秒才开始监听。需要 agent 一上来就能访问的服务,在脚本末尾等它的端口可用再退出,例如
for i in $(seq 30); do curl -sf -o /dev/null localhost:3000 && break; sleep 1; done。 - 超时后脚本连同它启动的后台进程一起被停止,按失败处理。
- 恢复时之前的进程可能仍在运行(部分运行时暂停时保留内存),脚本要自己处理"服务已经在运行"的情况,例如
pgrep -x redis-server || redis-server --daemonize yes。不要用pgrep -f去匹配脚本里也出现的文字:执行脚本的 shell 命令行里带着脚本全文,会被匹配上,服务就永远不会启动;请用pgrep -x按进程名判断,或检查服务端口。 - 同一次启动内最多执行一次:脚本开始执行前就会记录,中途被打断也不会在本次启动内重跑,下次启动时再执行。
session.error,error.type 为 environment_startup_failed_error,message 中带 exit code 与输出末尾;agent 也会收到失败提示。本次启动内不会重试。
Environment storage
storage.buckets[] 声明挂载到沙箱 /mnt/buckets/<name> 的自有 OSS bucket,仅 cloud config 支持,最多 8 个。完整说明(凭证、授权、权限策略、沙箱行为)见 挂载自有 OSS Bucket(Beta)。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 挂载目录名,同一 Environment 内唯一 |
provider | string | 是 | 固定为 "aliyun-oss" |
region | string | 是 | OSS region ID,例如 cn-hangzhou |
bucket | string | 是 | bucket 名称 |
prefix | string | 否 | 只挂载该前缀;省略表示整个 bucket |
access | string | 否 | read_only(默认)或 read_write |
accelerator_endpoint | string | 否 | <label>.oss-data-acc.aliyuncs.com |
credential | object | 是 | {"type":"ram_role","role_arn":"..."} 或 {"type":"access_key","access_key_id":"...","access_key_secret":"..."} |
credential 只写不读:响应只返回 type;access_key 还会返回打码的 access_key_id(如 LTAI****sKey)。更新时省略该字段或原样回传打码值会保留已保存的凭证。