目录职责
沿一次提交读代码
- 客户端入口:TypeScript SDK和Python SDK发起相同 HTTP 操作。Console 也调用这些公共接口,不拥有另一套执行状态。
- 身份与路由:server.ts校验请求身份和调用范围,解析 Session ID、输入与幂等键,交给领域服务。每次资源查找和跨资源绑定都要验证租户归属。
- 持久提交:runs.ts管理幂等、活动 Run 约束、状态推进与事件;sessions.ts固定配置与资源关联。状态和事件必须先落库再向客户端发送。
- 调度执行:worker.ts持租约执行准备、原调用恢复、事件摄取和结果完成。旧 worker 不能在租约失效后更新新状态;客户端断开不取消任务。
- 云资源:connector 契约与注册表提供创建、检查、文件、命令和私有访问。具体 Provider 差异留在 adapter,不把供应商分支散落到通用 Run 编排。
- Sandbox 进程:Runtime监督 Harness 进程;Harness 契约定义安装、调用与结果。控制平面不执行上传的用户源码,Runtime 不持有云资源管理职责。
- 外部 Tool:tool_bridge.py衔接调用,broker.ts处理授权、审批、派发与持久结果。原始账户凭据留在控制平面;不确定副作用进入reconciliation.ts。
- 完成与交付:Artifacts保存交付文件;worker 检查实际结果和产物后推进终态。自然语言“已完成”不是执行成功证据。客户端查询持久结果,并单独关闭 Session 清理资源。
运行时调用关系
图表示运行时职责,不是所有模块的静态 import 图。 图中使用较短名称以避免类名单词被拆开:Worker 对应ExecutionWorker,Sandbox lifecycle 对应 SandboxLifecycle,Provider connector 对应 SandboxConnector 及适配器,Tool broker 对应 ToolBroker。Provider adapter 操作云资源;Harness adapter 定义执行程序的安装与调用;Runtime 监督 Sandbox 内进程。Tool bridge 把调用交给 mailbox,再由控制平面 broker 处理授权、审批和外部派发,不是让 Harness 持有账户管理权限直接调用任意服务。
Console 的api helper向 /v1 发起请求。它的本地身份引导属于客户端认证,不构成第二套 Run 状态存储;改变 Console 展示不能替代领域层状态变更。
从一个症状定位函数和测试
这些文件是阅读与验证入口,不表示仅运行它们即可覆盖所有变更。测试涉及数据库或进程时,按测试指南准备前提并记录实际结果;真实 Provider / 模型旅程另行执行,不能由模拟测试推断通过。
一个修改边界的反例:某个 Provider 需要特殊私有 HTTP 隧道,不应在 worker 中加入
provider === ... 的网络实现。先查看 connector 的私有访问契约、目标释放责任与对应 adapter,在这一边界表达差异,再检查 Runtime 和预览调用者是否正确释放资源。这样同一修复才能同时作用于执行与预览,而不形成两份供应商逻辑。
状态恢复从哪里看
- Run 和调用恢复:execution/worker 与 runs;不要重放已开始但结果未知的操作。
- 暂停、快照和资源删除:lifecycle.ts与checkpoints.ts。空闲、paused、closed 与云资源删除不是同一状态。
- 凭据访问:access-server.ts和 modules/access;不能把原始 key 注入 env 作为兼容性回退。
- 存储升级:migrate.ts与编号 SQL;不要修改已应用迁移去伪装新 schema。
如何选修改位置
阅读源码时完成一项不创建云资源的走查:找到 submit 路由、幂等键检查、worker 的调用持久化、Runtime 执行入口、Tool 派发边界和结果落库位置。能够说明各步失败后谁恢复、哪些动作不可盲重试,才算理解执行路径;仅能列目录不够。
本页基于当前文件结构与实现核对,不声称新增测试已通过。确定性验证与真实 Provider/模型验收分别记录,敏感资源标识留在本地私有证据。
下一步:Sandbox 连接器、Harness 适配器、Tool 与应用连接器。