环境与 Builds API
程序化保存共享或个人环境，读取构建状态和真正用于启动的快照。
This page has not been translated into English yet. The original Chinese version is shown below.
环境 API 对应 Dashboard 保存的仓库与 environment.json 配置。创建环境和创建 Agent 的 repos 上限不同，不能混用请求 schema。
创建和读取环境
POST /v1/environments 需要以下字段，成功返回 201。
| 字段 | 规则 |
|---|---|
owner | personal 为 key 用户的环境，team 为团队环境 |
name | 最长 255 字符，同一 owner 下唯一 |
repos | 必填，最多 100 项，每项有 url；无仓库传空数组 |
environmentJson | 必填，JSON 编码后的字符串，不是嵌套对象 |
同名冲突返回 409 environment_name_conflict，可能带已有 environmentId。仓库不可访问返回 400 repository_access，无效环境配置返回 400 validation_error。
{
"owner": "team",
"name": "Web app",
"repos": [{ "url": "https://github.com/your-org/your-web-app" }],
"environmentJson": "{\"install\": \"pnpm install\"}"
}GET /v1/environments/{id} 返回最新保存配置，可包含 repoFile 指向仓库内文件、environmentJson 字符串和 versionId。没有保存版本时省略 versionId。DELETE /v1/environments/{id} 永久删除环境，无法撤销。
查询 Builds
| GET 路径 | 用途 |
|---|---|
/v1/environments/{id}/builds | 最新优先，每页最多 10 个，使用 nextCursor 继续 |
/v1/environments/{id}/builds/{buildId} | 单个 Build，ID 不属于环境时返回 build_not_found |
/v1/environments/{id}/builds/active | 实际启动来源 |
列表末页省略 nextCursor。Build status 为 IN_PROGRESS、SUCCEEDED、FAILED、CANCELLED 或 SKIPPED；SKIPPED 表示没有需要重建的内容。trigger 为 RECURRING、CONFIG_CHANGE 或 MANUAL。
draft: true 的 Build 未激活前不会用于启动 Agent。失败对象的 type 区分 INSTALL_FAILED 和 TERMINAL_FAILURE，code 可进一步说明原因；进行中的构建没有 completedAt。
活跃镜像与最新构建不同
active 端点返回 type: build 并带 buildId，或 type: universal_image 表示 Cursor 默认镜像。不要简单拿列表第一个 Build 作为启动来源，失败或 draft 构建可能不是 active。