开发工具包与 CLI 指南

应用集成优先使用 SDK。调试线协议、构建内部工具或验证 Gateway 行为时，可以使用原始 HTTP API。

层级	建议
浏览器或移动端	不要直接调用 Sandbox API，而是调用你的后端。
你的后端	持有 `SEACLOUD_API_KEY`，创建沙箱，保存 Sandbox ID，暴露产品级动作。
Agent runner	使用 SDK helper 操作命令/文件，并只把任务相关数据传入沙箱。
Sandbox runtime	只接收该工作负载需要的环境变量、源码文件和凭据。
支持 Dashboard	读取沙箱详情、日志、指标、使用限额和可观测性摘要。

安装

SDK	安装命令
Node	`npm install @seacloudai/sandbox`
Python	`pip install seacloud-sandbox`
Go	`go get github.com/SeaCloudAI/sandbox-go`

export SEACLOUD_BASE_URL="https://sandbox-gateway.cloud.seaart.ai"
export SEACLOUD_API_KEY="YOUR_API_KEY"

变量	必填	用途
`SEACLOUD_BASE_URL`	是	Gateway Base URL。
`SEACLOUD_API_KEY`	是	作为 `X-API-Key` 发送的 API Key。

能力	Node	Python	Go
创建	`Sandbox.create(...)`	`Sandbox.create(...)`	`sandbox.Create(...)`
重连	`Sandbox.connect(...)`	`Sandbox.connect(...)`	`sandbox.Connect(...)`
文件	`sandbox.files`	`sandbox.files`	`sbx.Files()`
命令	`sandbox.commands`	`sandbox.commands`	`sbx.Commands()`
公网 URL	`sandbox.getHost(port)`	`sandbox.get_host(port)`	`sbx.GetHost(port)`
代码解释器	`sandbox.runCode(...)`	`sandbox.run_code(...)`	`RunCode`
模板构建	`Template.build(...)`	`Template.build(...)`	`sandbox.BuildTemplate(...)`

控制面调用：

X-API-Key: <SEACLOUD_API_KEY>

调用 envdUrl 运行时接口：

X-Access-Token: <envdAccessToken>

运行时健康检查是例外：GET {envdUrl}/health、GET {envdUrl}/ 和 OPTIONS * 不需要运行时 Token。

Method	Path	说明
`POST`	`/api/v1/sandboxes`	创建沙箱。
`GET`	`/api/v1/sandboxes`	列出可见沙箱。
`GET`	`/api/v1/sandboxes/:sandboxID`	查询详情。
`POST`	`/api/v1/sandboxes/:sandboxID/connect`	重连运行时访问。
`POST`	`/api/v1/sandboxes/:sandboxID/pause`	暂停运行时。
`POST`	`/api/v1/sandboxes/:sandboxID/refreshes`	刷新 TTL。
`POST`	`/api/v1/sandboxes/:sandboxID/timeout`	设置秒级超时。
`DELETE`	`/api/v1/sandboxes/:sandboxID`	删除沙箱。
`GET`	`/api/v1/usage/limits`	查询沙箱配额使用情况。
`GET`	`/api/v1/usage/template-limits`	查询模板/构建配额使用情况。
`GET`	`/api/v1/observability/summary`	查询用户/项目用量、配额检查、接口可用性和建议动作。

保存不透明 ID 和公开状态字段。不要解析 ID，也不要从 ID 推导基础设施状态。

字段	是否保存	说明
`sandboxID`	是	查询详情、日志、指标、重连和删除的主键。
`templateID`	是	审计和可复现需要。
`state` / `status`	是	展示当前生命周期状态。
`timeline`	可选	适合作为用户可见进度。
`diagnostic`	可选	适合排障文案和下一步建议。
`envdUrl`	短期使用	通过 SDK/runtime helper 使用，不要视为永久地址。
`envdAccessToken`	密钥	不要暴露给浏览器、用户或模型 Prompt。
`requestID`	错误时保存	用于支持工单和日志关联。

Method	Path	说明
`POST`	`/api/v1/templates`	创建自定义模板元数据。
`GET`	`/api/v1/templates`	列出可见模板。
`GET`	`/api/v1/templates/resolve/:ref`	解析官方别名或标签。
`GET`	`/api/v1/templates/:id`	查询模板详情。
`POST`	`/api/v1/templates/:id/builds/:buildID`	启动构建。
`GET`	`/api/v1/templates/:id/builds/:buildID/status`	轮询构建状态。
`GET`	`/api/v1/templates/:id/builds/:buildID/logs`	读取构建日志。
`POST`	`/api/v1/templates/:id/rollback`	回滚到 ready 构建。

分组	路由
REST helpers	`GET /files`、`POST /files`、`POST /files/batch`、`POST /files/compose`、`POST /run`、`GET/POST /file`
Filesystem RPC	`POST /filesystem.Filesystem/*`
Process RPC	`POST /process.Process/*`

表面	路由	说明
沙箱日志	`GET /api/v1/sandboxes/:sandboxID/logs`	支持 cursor、direction、level、search，`limit` 最高 `1000`。
构建日志	`GET /api/v1/templates/:id/builds/:buildID/logs`	支持 cursor、direction、level，`limit` 最高 `100`。
沙箱指标	`GET /api/v1/sandboxes/:sandboxID/metrics`	面向 Dashboard 的控制面快照。
批量指标	`GET /api/v1/sandboxes/metrics`	查询可见沙箱的当前指标。
运行时指标	`GET {envdUrl}/metrics`	带 `X-Access-Token` 的直接运行时快照。

控制面错误使用以下结构：

{
  "code": 400,
  "message": "templateID is required",
  "requestID": "req-..."
}

遇到 429 时，读取 details.usageEndpoint，并向用户展示 scope、resource、metric、used、limit 和 remaining。

MVP 沙箱接入建议使用 SDK 或原始 HTTP API。