从实际契约开始
权威接口是 SandboxConnector。可以用 Boat作为 HTTP 操作、精确操作查找与异步删除的紧凑参考。但它的私有端口与 TTL 语义属于特定 Provider,不能未经核对直接照搬。
接口要求实现
preview,但只有完整访问链路可用时才能声明用户预览能力。不支持的路径应明确失败。Provider 账户密钥不得进入 guest 或浏览器;访问 Runtime 的私有传输还需独立成立,不能只考虑用户预览。
区分连接适配器和资源实现
ConnectionAdapter 提供严格配置 schema、能力列表以及 validate(config, credential)。验证只返回安全元数据,例如实际检查过的操作,不能返回上游响应体或 Token。列表请求成功只能证明列表权限,不能证明创建配额、镜像能力或完整执行权限。
以下是结构示意,不是可运行实现。ExampleConnector 需要实现完整接口,能力声明必须有相应依据:
contract_tests: true 和 live_resource: true。新增条目会继承这些声明。因此暴露新 Provider 前,必须取得相应证据,或把这里调整为逐 Provider 的证据元数据。注册本身不构成验证。保留的 Daytona 工厂用于历史资源清理,不能作为公开未验证候选项的范例。
先实现生命周期回执与恢复
共享生命周期、操作台账和镜像准备负责持久化意图、所有权与 fencing。连接器必须提供崩溃后可对账的精确标识。- 将持久化的
operation_id用于 Provider 幂等键,或精确名称和标签。超时后不能为了取得成功响应而换一个操作 ID 再创建。 - 创建返回异步操作句柄时,在提供回调的情况下先调用
request.record(resourceId, providerOperationId),再开始轮询。持久化失败时保留不确定结果。 - 响应丢失后重建连接器,按原操作查找精确匹配。零结果不普遍等于没有分配,最终一致性或未结束的异步操作可能仍需调查;多个结果有歧义,不能随意认领其中一个。
- 异步删除实现
reconcileDeletion(id, context),先用context.record保存已接受的句柄,重启后继续查询同一操作。Boat 展示了为什么“资源提前消失,但没有删除回执”不足以确认彻底清除。 - 端点等对象可能比计算资源存活更久时,实现
cleanupAssociatedResources。不能误删共享项目、账户凭据或其他 Session 的资源。
SandboxCreationRejected 当前编码的是配额拒绝,只有 Provider 证明没有接受资源或操作时才可使用;不能把全部 429 或超时转成明确拒绝。
只声明真正支持的策略
可选方法与属性覆盖镜像准备、暂停恢复、快照、前置检查、原生委托访问和关联资源清理。需要实现完整生命周期,不能用空方法返回成功:resumeMode: 'memory'与'filesystem'恢复语义不同。文件系统恢复需要重启 Runtime;如果冷启动清空/tmp,workspace 与 Harness 缓存要放在持久目录。reconcileResume对账已有资源,不能静默创建替代计算资源。- 必要时声明控制平面执行期限,并验证重启后的对账。控制平面停止时不能保证及时删除。Provider 自动休眠、显式暂停、到期与删除是不同状态。
- 使用快照时先持久化 checkpoint 句柄,恢复时使用新的操作上下文,清理时删除所拥有的快照,并处理计算资源 ID 变化。
- 使用预构建镜像时实现 prepare、inspect、find、delete 生命周期,保存镜像和构建回执。只有真实链路支持时才声明公有或私有镜像仓库能力;仓库凭据留在控制平面。
- 不支持 allowlist 时在分配前拒绝。声明网络策略需要真实允许与拒绝探测。原生凭据访问只接受委托代理授权,不能传递上游原始密钥。
私有 HTTP 目标由谁持有和释放
SandboxHttpTarget 是内部传输对象,不是可以返回给浏览器的预览响应。url 与 headers 供控制平面访问 Runtime 或用户服务;release 用于释放本次请求拥有的隧道、代理进程或连接租约。
不能在收到 HTTP headers 后立即拆隧道:流式 body 可能仍在读取。也不能只在成功响应后清理,否则中断、错误和跳转会遗留连接。参考RuntimeClient、预览入口与传输测试。
参考测试证明了什么
Boat 的现有六项确定性测试覆盖:复用持久删除句柄而不重复 DELETE、先保存句柄再轮询、无回执时不把资源 404 当作彻底清理、分配前拒绝不支持的网络策略、将端口授权从 URL 转为内部请求 header,以及拒绝截断命令输出。它们使用模拟 fetch,不会联系 Boat 账户。 这套参考没有替你的新连接器验证全部创建分页、快照、真实网络隔离或供应商账户语义。按上面的场景表为新实现补齐独立测试,再完成真实旅程。复用参考代码和运行参考测试,都不能作为新 Provider 的 live_resource 证据。 共享操作复核测试补充 Boat 的适配器测试:创建响应丢失后,零匹配仍保留 unknown;两个匹配资源保留multiple_resources,不绑定其中任何一个;后续只有一个精确匹配时采用原资源,不再创建。隔离数据库执行记录覆盖这些断言。这证明受控连接器下的共享生命周期行为;新增供应商仍须测试自己的查询、分页与回执契约。
响应丢失测试必须重建适配器
只断言 timeout 不能验证恢复。为假 Provider 建立跨连接器实例保留的操作存储,让连接器实例与远端模拟状态分开:- 接受操作
op-a的创建,分配resource-a,然后在返回响应前抛错。断言只发起一次分配请求。 - 新建连接器实例,保留同一假 Provider 存储。查询
findByOperation("op-a"),要求找到原资源,且没有新增分配。 - 列表暂时返回零匹配,但 Provider 仍报告已接受的 pending 操作。生命周期必须保留不确定性;不能把空页当成已确认不存在。
- 在不同分页中放入两个精确匹配,断言两者都返回给调用方,让对账层识别歧义。
- 删除时先持久化回执,中断轮询,再重建连接器并携带原回执继续。断言不重复 DELETE,且达到供应商特定完成条件前不报告完成。
完成用户配置入口
当前 Console 的 Provider 表单渲染、配置序列化和名称列表位于 app.js。注册时同步更新相关路径;进入 catalog 不等于已经有完整配置表单。提供明确字段约束、凭据说明,以及只覆盖实际验证范围的反馈。 遵守 Console 设计契约:使用应用自有的可访问控件、完整 en/zh-CN 文案目录、键盘与焦点行为,并实际检查两种语言。Sandbox 平台配置与模型端点、Agent Tools 分开。补充对应产品集成页,写明前置条件、限制、故障恢复和精确验证范围。验证后再提升支持状态
先使用 fake transport 和现有 Boat 测试。至少覆盖:
现有参考实现的定向检查命令: