Environment 数据结构

Environment 对象

创建、查询、列表、更新接口都会返回该结构。

字段	类型	说明
`id`	string	Environment ID，前缀为 `env_`
`type`	string	固定值 `"environment"`
`name`	string	Environment 名称，最长 255 字符；去除首尾空白后不能为空
`description`	string	Environment 描述
`config`	Environment config	规范化后的 Environment 配置；缺省的 package manager 字段会被补齐
`metadata`	object	Environment metadata，省略时为 `{}`
`archived_at`	string \| null	归档时间，RFC 3339 格式；active 时为 `null`
`created_at`	string	创建时间，RFC 3339 格式
`updated_at`	string	最后更新时间，RFC 3339 格式
`identity_id`	string \| null	Forward 归属身份；PAT 创建时通常为 `null`
`icon_url`	string \| null	Forward 关联的 icon URL
`binding_info`	Binding info	绑定信息（Template 引用计数等）

Environment config

Environment 运行时配置对象。省略时默认使用 {"type":"cloud"}；显式传入时不能为 null 或空对象。

字段	类型	必填	说明
`type`	string	是	`"cloud"` 或 `"self_hosted"`。仅当整个 `config` 省略时，才默认使用 `cloud`
`packages`	Environment packages	否	`cloud` Environment 的预装包声明；不能为 `null`
`setup_script`	string	否	见 Environment setup script

`self_hosted` config

self_hosted Environment 只允许 type 和可选的 setup_script；传入 packages 或其他不支持的字段返回 400 invalid_request_error。

{"type": "self_hosted", "setup_script": "./initialize-worker.sh"}

`cloud` config 响应形态

响应中的 cloud config 会补齐 packages 中所有保留的 package manager 数组（未声明的返回 []），示例：

{
  "type": "cloud",
  "packages": {
    "type": "packages",
    "apt": [],
    "cargo": [],
    "gem": [],
    "go": [],
    "npm": [],
    "pip": []
  }
}

Environment packages

packages 是"包管理器名称 → 软件包规格字符串数组"的映射。当前实际执行安装的管理器为 apt / npm / pip；cargo / gem / go 是响应中的保留字段，暂不支持通过这里安装依赖。

key	类型	说明	示例
`type`	string	响应中固定为 `"packages"`，请求侧不要传入	`"packages"`
`apt`	string 数组	Debian/Ubuntu 包声明，通过 `apt-get install -y` 安装	`["git", "curl"]`
`npm`	string 数组	Node.js 全局包声明，通过 `npm install -g` 安装	`["pnpm@9"]`
`pip`	string 数组	Python 包声明，通过 `pip install` 安装	`["PyYAML==6.0.1"]`
`cargo`	string 数组	响应保留字段；当前不支持通过该字段安装依赖	`[]`
`gem`	string 数组	响应保留字段；当前不支持通过该字段安装依赖	`[]`
`go`	string 数组	响应保留字段；当前不支持通过该字段安装依赖	`[]`

每个 value 都必须是字符串数组。未声明的 package manager 数组会在响应中补为 []。

Environment setup script

setup_script 是 sandbox 准备阶段、packages 安装完成之后执行的一段 shell 脚本，常用于克隆代码、写配置文件、warmup 缓存等无法用 packages 表达的初始化步骤。

约束	值
类型	string
最大长度	64 KB
解释器	`/bin/bash -lc`
执行时机	sandbox 准备阶段，`packages` 安装完成之后
超时	10 分钟
非零退出	本次 sandbox 准备失败
重复执行	同一个 sandbox 中成功执行后不再重复；sandbox 回收重建后会再次执行

{
  "config": {
    "type": "cloud",
    "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
  }
}

Environment metadata

Environment 的自定义元数据键值对；created_by 为 Forward 保留字段，调用方不可传入（传入返回 400）。

约束	值
调用方提交上限	通常 15 个自定义键值对
key 最长	64 个字符
value 类型	string
value 最长	512 个字符

Binding info

Forward 在 Environment 响应中携带的引用聚合。

字段	类型	说明
`agent_template_count`	integer	当前绑定该 Environment 的 Template 数量

列表分页字段

字段	类型	说明
`data`	Environment 对象数组	当前页记录
`has_more`	boolean	是否还有下一页
`next_page`	string \| null	下一页向后游标（推荐使用）；`has_more=true` 时等于当前页 `last_id`，否则为 `null`
`first_id`	string \| null	当前页第一条记录 ID
`last_id`	string \| null	当前页最后一条记录 ID

请求侧的三种游标参数 page / after_id / before_id 互斥，同时提供多个返回 400；推荐使用 page，语义等价于 after_id。

​Environment 对象

​Environment config

​self_hosted config

​cloud config 响应形态

​Environment packages

​Environment setup script

​Environment metadata

​Binding info

​列表分页字段