OpenSandbox 公共 API 契约治理：specs 目录规范、OpenAPI 接口契约与变更护栏解析

OpenSandbox 公共 API 契约治理specs 目录规范、OpenAPI 接口契约与变更护栏解析【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 以specs/目录作为公共接口契约的唯一事实来源source of truth通过一份面向维护者与 AI Agent 的治理文档specs/AGENTS.md约束所有对外 API 的演进方式先改契约、再改实现、同步更新消费方。本文以该治理文档为主体结合仓库内四份 OpenAPI 规范文件与回归测试完整解析生命周期、诊断、执行、出口四类接口的职责边界、验证命令与Always / Ask first / Never三级变更护栏帮助读者在二次开发或集成时准确理解改一个接口字段会波及哪些组件。一、为什么需要一份契约治理文档OpenSandbox 是一个跨语言、跨组件的大型沙箱运行时项目控制面服务server/、沙箱内执行器components/execd/、出口代理components/egress/、命令行工具cli/以及五种语言 SDKsdks/共同工作。任何一个公共字段的重命名或删除都可能引发跨仓库的连锁破坏。为此仓库将specs/目录划定为公开 API 契约的权威来源并用AGENTS.md明确治理规则任何契约变更都应优先采用增量式additive修改避免破坏性变更凡是影响下游代码的契约改动必须同步阅读对应的消费方指南生命周期类改动影响控制面读 server/AGENTS.mdSDK 可见的契约改动读 sdks/AGENTS.mdexecd 或 egress 相关改动读 components/ 下各组件的 README / DEVELOPMENT 文档CLI 可见的诊断、生命周期、出口改动读 cli/README.md这一契约先行、消费方同步的流程从机制上避免了规范文件与实现、文档、SDK 模型漂移的问题。二、Contract Map四大 OpenAPI 契约及其消费方specs/AGENTS.md的 Contract Map 一节将契约分为四份 OpenAPI 规范文件分别对应不同的运行时与消费方。它们的中文索引见 docs/api/index.md该文档同时给出了各规范的服务端基地址。规范文件职责主要消费方服务端基地址按 docs/api/index.mdsandbox-lifecycle.yml沙箱生命周期管理创建、暂停、恢复、终止、快照server/、cli/、各语言 sandbox SDKhttp://localhost:8080/v1diagnostic-api.yml沙箱诊断日志与事件尽力而为的排障描述符server 诊断、CLI 诊断、troubleshooting 流程http://localhost:8080/v1execd-api.yaml沙箱内代码执行、命令执行、文件系统操作components/execd/、code-interpreter SDKhttp://localhost:44772egress-api.yaml沙箱出口策略的运行时接口egress sidecar 与相关文档http://localhost:180802.1 sandbox-lifecycle.yml沙箱生命周期 API这是四份契约中分量最重的一份约 2277 行。其info.description定义了沙箱的核心生命周期模型Creation→ 沙箱被供给进入RunningExecution→ 运行中可接受请求Pause可选→Pausing→Paused异步过程Resume可选→Resuming→Running异步过程Termination→Stopping→Terminated可由 kill 动作、TTL 到期或错误触发Error→ 任意状态在严重错误下可转为Failedstatus字段通过state、reason、message三个子字段提供细粒度信息。SandboxState枚举完整罗列了八个状态及其转移路径Pending → Running创建完成后 Running → Pausing请求暂停时 Pausing → Paused暂停完成 Paused → Resuming请求恢复时 Resuming → Running恢复完成 Running/Paused → Stoppingkill 请求或 TTL 到期 Stopping → Terminated终止完成 Pending/Running/Paused/Resuming → Failed出错时规范同时声明未来版本可能新增状态值客户端必须优雅处理未知状态——这是典型的增量兼容设计。该规范的主要端点基路径/v1POST /sandboxes— 从镜像或快照创建沙箱支持timeout、资源限制、网络策略、生命周期钩子GET /sandboxes— 列表查询支持state多次传参为 OR、metadataURL 编码的键值对、page/pageSize分页GET /sandboxes/{sandboxId}— 获取完整沙箱信息含启动源与 entrypoint创建响应中不含这些字段DELETE /sandboxes/{sandboxId}— 删除沙箱经Stopping转为TerminatedPOST /sandboxes/{sandboxId}/pause、/resume— 异步暂停/恢复POST /sandboxes/{sandboxId}/snapshots、GET /snapshots、GET/DELETE /snapshots/{snapshotId}— 快照的创建、列表、查询、删除POST /sandboxes/{sandboxId}/renew-expiration— 续期绝对到期时间RFC 3339PATCH /sandboxes/{sandboxId}/metadata— JSON Merge PatchRFC 7396语义更新元数据GET /sandboxes/{sandboxId}/endpoints/{port}— 获取沙箱内某端口的公网访问端点GET/PUT /sandboxes/{sandboxId}/networkpolicy— 读取/整体替换出口网络策略POST /metrics/events— SDK 上报创建延迟等遥测事件Phase 1POST/GET/DELETE /templates、/templates/{templateId}— Fsb golden-image 模板管理runtime.typefsb专用2.2 diagnostic-api.yml 与 egress-api.yamldiagnostic-api.yml定义尽力而为的排障描述符——诊断日志与事件要么内嵌纯文本内容要么返回下载 URL。规范明确声明它不定义结构化的审计或可观测性模型端点仅两个GET /sandboxes/{sandboxId}/diagnostics/logs与/diagnostics/events均支持可选 scope。egress-api.yaml定义由沙箱内 egress sidecar 直接暴露的运行时出口策略接口。与生命周期 API 不同它需要先解析沙箱在出口端口上的 endpoint再直接调用 sidecar。核心端点GET /policy读取当前强制策略与派生运行模式、PATCH /policy按 sidecar 合并语义增量更新规则、DELETE /policy按 target 移除规则。相关实现与文档见 components/egress/。2.3 认证方式生命周期与诊断 API全部操作要求 API Key 认证。HTTP 头方式为OPEN-SANDBOX-API-KEY: your-api-keySDK 客户端自动读取环境变量OPEN_SANDBOX_API_KEY。execd API所有端点要求X-EXECD-ACCESS-TOKEN请求头docs/api/index.md。三、execd-api.yaml沙箱内的执行接口契约作为契约地图的第二大块约 2631 行execd 规范定义了沙箱内部的能力面六大功能模块与components/execd/的 Go 实现一一对应健康检查GET /ping代码解释上下文context生命周期管理 SSE 流式执行。POST /code/context创建会话保持跨多次执行的状态POST /code基于 Jupyter kernel 执行代码并通过 SSE 流式返回DELETE /code中断执行GET/DELETE /code/contexts管理上下文命令执行POST /command支持前台/后台模式可指定timeout毫秒、uid/gid、envsGET /command/status/{id}查询状态GET /command/{id}/logs增量拉取后台命令 stdout/stderr完成后的命令元数据至少保留 24 小时由每小时一次的清理任务移除Bash 会话POST /session创建持 shell 状态的会话POST /session/{sessionId}/run在会话内执行并 SSE 流式输出DELETE /session/{sessionId}销毁文件系统/files/info元信息、/files删除、/files/permissionschmod/chown、/files/mv、/files/searchglob 模式、/files/replace批量文本替换verbosetrue时返回每文件替换计数、/files/uploadmultipart 上传、/files/download支持 Range 断点续传与offset/limit按行读取、/directories/list支持depth控制符号链接不被遍历、/directoriesmkdir -p 语义创建/递归删除系统指标GET /metrics与GET /metrics/watch每秒一次的 SSE 实时流隔离执行基路径/v1/isolatedPOST /session创建隔离 bash 会话、/capabilities查询隔离器能力、/session/{sessionId}/run支持前台SSE与后台background: true返回 202 run handle两种模式以及配套的 diff/commit、文件与目录操作端点3.1 契约级约束RunCommandRequest 的互斥输入components/execd/对命令执行有明确的输入契约commandshell 文本与argv原生参数数组必须恰好提供其一。这一约束不仅写在 OpenAPI 规范中还被自动化回归测试固化在 specs/tests/test_execd_schema.py合法{command: echo hello}、{argv: [printf, %s, ]}、{argv: [...], cwd: /tmp}非法空 body、两者同时出现、command为空字符串或null、argv为空数组或含null元素测试通过Draft202012Validator.check_schema校验规范自身合法性再以 15 组用例逐一断言 payload 的通过与拒绝运行方式为uv run specs/tests/test_execd_schema.py脚本头部以 PEP 723 声明了jsonschema4.18,5与PyYAML6,7依赖。这是契约与测试同步落地的直接证据。3.2 SSE 流式事件类型代码与命令执行接口统一使用 Server-Sent Events 实时推送输出支持的事件类型docs/api/index.mdinit初始化、status状态更新stdout/stderr标准输出/错误流result执行结果、execution_count执行计数execution_complete执行完成、error错误信息四、契约变更的验证命令specs/AGENTS.md的 Commands 一节给出了改动落地前的两条验证路径。生命周期消费方验证针对 server 侧cd server uv sync --all-groups uv run ruff check uv run pytest即进入 server/ 目录用 uv 同步全部依赖组依次执行静态检查ruff与完整测试套件pytest。server 的测试覆盖了生命周期路由的方方面面例如 server/tests/test_routes_create_delete.py、server/tests/test_routes_pause_resume.py、server/tests/test_routes_snapshots.py、server/tests/test_routes_renew_expiration.py、server/tests/test_routes_patch_metadata.py 等可用于验证契约改动与路由实现的一致性。受影响 SDK 的重新生成与工作区验证cd sdks pnpm install --frozen-lockfile在 sdks/ 工作区用 pnpm 按冻结 lockfile 安装依赖为受影响的 SDK 重新生成派生代码如 sdks/sandbox/go/、sdks/sandbox/python/、sdks/sandbox/javascript/ 等目录下的生成模型。五、三级变更护栏Always / Ask first / Never治理文档用三组规则划定了契约维护者的行为边界这也是本文最有操作价值的经验清单。Always必须做保持 operation ID、schema 名称、示例与描述与既有命名风格一致规范编辑后重新生成派生输出在可行时于同一变更中更新受影响的消费方保持规范示例与 server schemas、生成的 SDK 模型对齐明确指出未经验证的下游影响面Ask first先确认再做破坏性契约变更重命名或删除公共字段、操作新增顶层 API 面但未同步实现对齐Never严禁未经批准重命名或删除公共字段不更新源规范就手工编辑派生输出假定只改规范就能与 server、SDK、文档或发布影响隔离这三层护栏的本质是把公共 API 的兼容性从个人自觉上升为流程强制增量字段永远优先于字段重定义契约与消费方更新必须同批落地。六、Good Patterns增量演进的最佳实践治理文档最后给出了三个可复用的演进模式与 OpenSandbox 各规范的实现互为印证行为变化时给出具体示例与描述——例如 specs/sandbox-lifecycle.yml 的POST /sandboxes内置了 deny-with-allowlist、allow-with-denylist、manual-cleanup、secure-access、restore-snapshot、restore-snapshot-with-entrypoint、lifecycle-hooks 七组完整请求示例PATCH /sandboxes/{sandboxId}/metadata提供 add-and-replace、delete-key、mixed-operations、empty-body 四组示例。示例即规格调用方可直接照抄改造。用显式的向后兼容字段新增取代字段重定义——SandboxLifecycleschema 明确声明未来生命周期事件以新增可选字段方式加入不改变既有字段语义SandboxState与SnapshotState同样预留未知状态值优雅处理条款。契约与消费方更新同步落地——正如本文开头所述每类契约都有对应的消费方指南文件需要一并阅读与验证。七、快速定位指南契约唯一事实来源specs/sandbox-lifecycle.yml、diagnostic-api.yml、execd-api.yaml、egress-api.yaml契约中文/英文索引docs/api/index.md契约回归测试specs/tests/test_execd_schema.py生命周期消费方验证入口server/AGENTS.md 与 server/tests/ 下的路由测试SDK 契约消费方sdks/AGENTS.mdexecd / egress 组件实现components/execd/、components/egress/CLI 可见契约变更cli/README.md需要特别说明的是specs/AGENTS.md面向的是维护公开契约的工程师与 AI Agent因此它规定的验证命令uv sync、ruff check、pytest、pnpm install与三级护栏是仓库内开发期约束普通使用者无需执行只需将specs/下的四份 OpenAPI 文件视为权威接口文档即可。理解这套契约治理模型能让你在阅读 OpenSandbox 任何组件的接口时快速判断哪个字段是稳定契约、哪个变更会波及哪些消费方。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考