Skip to main content

Environment 结构

Environment 对象和配置字段结构。

Environment 对象

创建、查询、列表、更新和归档接口都会返回该结构。
字段类型说明
idstringEnvironment ID,前缀为 env_
typestring固定值 "environment"
namestringEnvironment 名称
descriptionstringEnvironment 描述
configEnvironment configEnvironment 配置
metadataobjectMetadata 对象,默认 {}
archived_atstring | nullUTC 归档时间;未归档时为 null
created_atstringUTC 创建时间
updated_atstringUTC 最后更新时间

Environment config

字段类型必填说明
typestring是"cloud" 或 "self_hosted"
packagesEnvironment packages否Environment 关联的包声明
setup_scriptstring否用户 setup script 文本,详见 Environment setup script
startup_scriptstring否沙箱每次启动都执行的脚本,详见 Environment startup script
storageEnvironment storage否自有 OSS bucket 挂载,仅 cloud config 支持
self_hosted config 可以包含 type 和可选的 setup_script、startup_script:
{"type": "self_hosted", "setup_script": "./initialize-worker.sh"}
self_hosted config 仅支持 type 和可选的 setup_script、startup_script。self_hosted 的 startup_script 只保存并原样返回,由外部 worker 决定是否执行。

Environment packages

packages 是包管理器到软件包规格字符串数组的映射。请求支持 apt、npm 和 pip。Cloud Environment 响应还会返回若干保留字段;省略的数组会返回为 []。
key类型说明示例
typestring响应中固定为 "packages""packages"
aptstring 数组Debian/Ubuntu 系统包声明["git", "curl", "build-essential"]
npmstring 数组Node.js package 声明["typescript@5.0.0", "eslint"]
pipstring 数组Python package 声明["pandas", "PyYAML==6.0.1"]
cargostring 数组响应中的保留字段;当前不支持通过该字段安装依赖[]
gemstring 数组响应中的保留字段;当前不支持通过该字段安装依赖[]
gostring 数组响应中的保留字段;当前不支持通过该字段安装依赖[]

Environment setup script

setup_script 是 sandbox 准备阶段、packages 安装完成之后执行的一段 shell 脚本,用 /bin/bash -lc 运行。常用于克隆代码、写配置文件、warmup 缓存等无法用 packages 表达的初始化步骤。
约束值
类型string
最大长度64 KB
解释器/bin/bash -lc
超时10 分钟
执行时机sandbox 准备阶段,packages 安装完成之后
执行成功后会在沙箱内写入完成标记,本次 sandbox 内不会重复执行;沙箱被回收重建后会再次执行。 脚本以非零状态退出会导致 Session 启动失败。错误响应中会带上 setup_script 的 exit code 与 stderr 摘要,便于定位失败原因。
{
  "config": {
    "type": "cloud",
    "setup_script": "set -euo pipefail\n[ -d /data/workspace/repo/.git ] || git clone https://github.com/me/repo /data/workspace/repo\ncd /data/workspace/repo && pnpm install --frozen-lockfile"
  }
}

Environment startup script

startup_script 是沙箱每次启动都会执行的一段 shell 脚本:沙箱第一次启动时在 setup_script 之后执行,之后每次从暂停中恢复都会再执行一次。用来拉起不会跨暂停保留的进程,例如数据库、dev server 等后台服务。 沙箱暂停再恢复后,磁盘上的文件都还在,进程不会保留。结果落在磁盘上的步骤(安装依赖、克隆代码、生成缓存)放 setup_script;启动进程放 startup_script。
setup_scriptstartup_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,沙箱照常可用。每次启动时失败都会产生一条 session.error,error.type 为 environment_startup_failed_error,message 中带 exit code 与输出末尾;agent 也会收到失败提示。本次启动内不会重试。
{
  "config": {
    "type": "cloud",
    "packages": {"apt": ["redis-server"]},
    "startup_script": "pgrep -x redis-server || redis-server --daemonize yes\ncurl -s -o /dev/null localhost:3000 || (cd /data/workspace/repo && nohup pnpm dev > /tmp/dev.log 2>&1 &)"
  }
}

Environment storage

storage.buckets[] 声明挂载到沙箱 /mnt/buckets/<name> 的自有 OSS bucket,仅 cloud config 支持,最多 8 个。完整说明(凭证、授权、权限策略、沙箱行为)见 挂载自有 OSS Bucket(Beta)。
字段类型必填说明
namestring是挂载目录名,同一 Environment 内唯一
providerstring是固定为 "aliyun-oss"
regionstring是OSS region ID,例如 cn-hangzhou
bucketstring是bucket 名称
prefixstring否只挂载该前缀;省略表示整个 bucket
accessstring否read_only(默认)或 read_write
accelerator_endpointstring否<label>.oss-data-acc.aliyuncs.com
credentialobject是{"type":"ram_role","role_arn":"..."} 或 {"type":"access_key","access_key_id":"...","access_key_secret":"..."}
credential 只写不读:响应只返回 type;access_key 还会返回打码的 access_key_id(如 LTAI****sKey)。更新时省略该字段或原样回传打码值会保留已保存的凭证。
{
  "type": "cloud",
  "storage": {
    "buckets": [
      {
        "name": "datasets",
        "provider": "aliyun-oss",
        "region": "cn-hangzhou",
        "bucket": "my-bucket",
        "prefix": "team/data/",
        "access": "read_only",
        "credential": {"type": "ram_role", "role_arn": "acs:ram::1234567890123456:role/qoder-oss-mount"}
      }
    ]
  }
}