人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载导读本文围绕openjiuwen.core.sys_operation.sandbox.launchers.base模块展开该模块定义了 openJiuwen agent-core 沙箱体系中最核心的两类抽象LaunchedSandbox沙箱启动后返回的描述符与SandboxLauncher沙箱生命周期管理基类。读者将掌握沙箱的 launch / pause / resume / delete / check_status 五阶段生命周期模型、SandboxLauncherConfig配置参数语义以及pre_deploy内置启动器与SandboxGateway网关调用链的协作方式可直接据此对接 Docker、E2B 等自研沙箱运行时。一、模块定位沙箱生命周期管理的统一抽象在 openJiuwen agent-core 中沙箱Sandbox是 Agent 执行文件操作、Shell 命令与代码的隔离环境。sys_operation.sandbox包采用启动器Launcher— 网关Gateway— 操作提供者Provider三层结构Launcher只负责沙箱运行时的生命周期创建、暂停、恢复、销毁、状态查询不关心具体业务操作Gatewaygateway.py负责端点解析、启动器调度与操作路由Providerbase_provider.py提供read_file、execute_cmd、execute_code等实际能力。launchers/base.md所定义的SandboxLauncher正是第一层——所有具体运行时启动器Docker、E2B、预部署服务等的统一基类是整套沙箱体系可插拔的关键抽象。二、LaunchedSandbox沙箱启动后的持久句柄LaunchedSandbox是一个frozenTrue的 dataclass作为SandboxLauncher.launch()的返回值被ContainerManager用来在 pause / resume / delete 等后续调用中唯一标识一个运行中的沙箱实例。dataclass(frozenTrue) class LaunchedSandbox参数说明字段定义见 base.py字段类型说明默认值base_urlstr沙箱服务的 HTTP 基础地址。对于 E2B 这类由服务商托管的沙箱该值为空字符串必填sandbox_idstr运行时分配的不透明标识符如 Docker 容器 ID、E2B sandbox ID。对生命周期由外部托管的远程启动器可为NoneNonehost_portint宿主机映射端口仅 Docker 场景使用其余场景为NoneNone需要特别注意的是该描述符是不可变的frozenTrue这保证了句柄在整个生命周期内语义稳定不会被误修改。设计意图见 base.py 注释是它是跨 pause / resume / delete 调用的持久句柄调用方据此识别沙箱而无需重复保存完整运行时信息。从源码看SandboxRecordsandbox_store.py在LaunchedSandbox基础上进一步补充了status、launcher_type、sandbox_type、container_config_hash、created_ts、last_used_ts、metadata等字段用于网关侧的记录持久化与空闲驱逐。三、SandboxLauncher沙箱生命周期基类class SandboxLauncher基类的设计哲学见 base.py 的 docstring除launch外的所有方法在基类中都是 no-op空操作子类只需按自己运行时实际支持的能力进行覆写。这意味着一个只支持创建与销毁的简单启动器无需为 pause / resume 编写无意义实现。3.1 async launch —— 唯一返回描述符的入口async launch( config: SandboxLauncherConfig, timeout_seconds: int, isolation_key: Optional[str] None, ) - LaunchedSandboxconfig沙箱启动器配置SandboxLauncherConfigtimeout_seconds超时秒数isolation_key沙箱隔离键默认None返回LaunchedSandbox即沙箱描述符。基类中该方法直接raise NotImplementedError强制子类实现。源码注释给出了关键实现建议base.py强烈建议实现方使用sandbox_id作为容器名 / 标签这样在下一次launch()调用时可以按 ID 找到已暂停的沙箱并直接恢复unpause而不是重新创建。也就是说launch()的语义是启动或恢复这也是网关实现暂停后下次自动续用的基石。3.2 async pause —— 挂起而非销毁async pause(sandbox_id: str) - None挂起沙箱以保留状态、同时不消耗计算资源。基类 no-op对支持快照挂起的运行时如 Docker pause、虚拟机快照进行覆写。3.3 async resume —— 恢复已暂停沙箱async resume(sandbox_id: str) - None恢复先前被暂停的沙箱。基类 no-op。3.4 async delete —— 永久销毁async delete(sandbox_id: str) - None永久销毁沙箱并释放其资源。注意基类签名为async def delete(self, sandbox_id: str, **kwargs) - None实际实现可接收额外关键字参数如网关在 gateway.py 中会传入isolation_key、base_url、sandbox_type。3.5 async check_status —— 状态查询async check_status(sandbox_id: str) - SandboxStatus查询沙箱当前状态返回 SandboxStatus。基类的 no-op 实现直接返回SandboxStatus.RUNNINGbase.py——这隐含了一个约定若运行时无法真正探测状态可保守假设为运行中代价是网关无法据此触发暂停恢复逻辑。四、SandboxLauncherConfig配置模型与参数语义launch()的第一参数类型是SandboxLauncherConfigPydanticBaseModel定义见 sandbox_config.md各字段语义如下字段类型默认值说明launcher_typestr必填启动器类型作为SandboxRegistry的注册键gateway_urlstr远程沙箱网关服务端点sandbox_typestrmock沙箱提供方类型如aio、e2b、mockon_stopLiteral[delete, pause, keep]delete停止策略delete销毁沙箱pause暂停、下次启动时恢复keep保持运行idle_ttl_secondsintNone空闲超时秒数超时后自动驱逐沙箱extra_paramsDict[str, Any]{}透传给 Launcher 的任意参数其中on_stop与idle_ttl_seconds直接参与网关侧的资源回收逻辑on_stopSandboxGateway.release_sandbox中按keep不处理、pause调用pause_sandbox、其余值调用delete_sandbox分支处理gateway.pyidle_ttl_seconds_evict_idle通过InMemorySandboxStore.evict_expired找出(now - last_used_ts) idle_ttl_seconds的记录并调用launcher.delete驱逐gateway.py。此外SandboxLauncherConfig的子类PreDeployLauncherConfig增加了base_url沙箱服务地址http://或ws://并将launcher_type固定为pre_deploy、sandbox_type默认aio用于连接已部署好的外部沙箱服务。五、内置实现PreDeploymentLauncher仓库当前内置的唯一官方启动器是PreDeploymentLauncherpre_deployment_launcher.py注册名为pre_deploy注册点见 gateway.py。class PreDeploymentLauncher(SandboxLauncher): async def launch(self, config, timeout_seconds, isolation_keyNone) - LaunchedSandbox: if not isinstance(config, PreDeployLauncherConfig): raise ValueError(PreDeploymentLauncher requires PreDeployLauncherConfig) return LaunchedSandbox(base_urlconfig.base_url)由于沙箱已预先部署launch()不做实际创建仅做类型校验后直接返回LaunchedSandbox(base_urlconfig.base_url)——这就是连接已有沙箱服务场景下sandbox_id为None、base_url承载连接信息的典型例子。delete()则按sandbox_type分发到扩展层实现这些扩展不在本文范围内仅说明行为yuanrong通过build_yuanrong_shared_scope_key/delete_yuanrong_sandbox按共享作用域键删除jiuwenbox、jiuwenbox-conch通过build_jiuwenbox_shared_scope_key/delete_jiuwenbox_sandbox删除。该启动器未覆写 pause / resume / check_status即采用基类的 no-op / 默认 RUNNING 行为——符合只覆写运行时支持的能力的设计约定。六、与SandboxStatus状态枚举的协作check_status的返回类型SandboxStatus定义在网关存储模块sandbox_store.pyclass SandboxStatus(Enum): RUNNING running PAUSED paused KILLED killed这三个状态在网关_get_endpoint中构成完整的状态恢复状态机gateway.py存储中有记录且标记 RUNNING → 直接复用端点刷新last_used_ts无记录 → 调用launcher.launch()新建有记录但本地状态存疑 → 调用launcher.check_status()获取真实状态真实状态为 RUNNING → 更新记录并复用真实状态为 PAUSED → 调用launcher.resume()恢复更新记录为 RUNNING 并复用其他KILLED / 异常→ 删除记录并launch()新建。这一逻辑正是对launch()启动或恢复语义的消费方验证暂停的沙箱通过check_statusresume被无缝续用避免重复创建。同时SandboxRecord会在创建时记录container_config_hash对镜像、环境变量、卷、资源限制、网络、服务端口做 SHA-256 摘要见 gateway.py供容器配置比对使用。七、Launcher 的注册与网关调度完整调用链Launcher 通过SandboxRegistrysandbox_registry.py进行注册与创建SandboxRegistry.register_launcher(name, launcher_cls) # 注册 SandboxRegistry.create_launcher(launcher_type) # 按类型实例化未知类型抛 ValueError还提供装饰器SandboxRegistry.launcher(name)便捷注册方式。网关侧完整调用链如下SandboxGatewayClient.invoke(op_type, method, **params) └─ SandboxGateway.handle_request(config, request) └─ _get_or_create_provider(config, isolation_key, op_type) └─ _get_endpoint(config, isolation_key) ← 生命周期核心 ├─ store 命中且 RUNNING → 复用端点 ├─ store 未命中 → launcher.launch() → 写 SandboxRecord ├─ 真实状态 PAUSED → launcher.resume() └─ 真实状态非存活 → 删记录 launcher.launch() └─ _evict_idle() → launcher.delete() ← 空闲驱逐客户端层gateway_client.py提供invoke/invoke_stream全链路路由以及静态方法release(isolation_key, on_stopdelete)触发资源回收。此外操作侧封装SandboxGatewayClientMixinsandbox_mixin.py支持在隔离键模板如{session_id}中动态解析当前会话 ID实现同会话共享沙箱的隔离策略。八、自定义 Launcher 的落地指南结合基类契约与网关消费逻辑新增一个沙箱运行时启动器如自研 Docker 启动器的要点如下继承SandboxLauncher实现launch()将其返回的LaunchedSandbox.base_url填为实际可访问地址sandbox_id填为运行时唯一 ID用sandbox_id作为容器名 / 标签以便下次launch()复用或check_status()定位按运行时能力选择性覆写pause/resume/delete/check_status其余保留基类 no-op通过SandboxRegistry.launcher(your_type)注册并在SandboxGatewayConfig.launcher_config中指定launcher_type为对应注册名结合SandboxLauncherConfig规划on_stop策略与idle_ttl_seconds使网关的暂停恢复与空闲驱逐逻辑生效。九、小结SandboxLauncher与LaunchedSandbox构成了 openJiuwen agent-core 沙箱生命周期的核心契约前者定义了启动 / 暂停 / 恢复 / 销毁 / 状态查询的五阶段抽象且刻意让非核心方法保持 no-op 以降低实现负担后者提供了跨调用稳定引用沙箱的不可变句柄。配合SandboxLauncherConfig的on_stop与idle_ttl_seconds策略以及SandboxGateway._get_endpoint中检查状态 → 恢复 → 复用的状态机沙箱资源得以在 Agent 会话间高效复用并自动回收。相关文件索引本文主体文档launchers/base.md基类实现base.py配置模型sandbox_config.md内置启动器pre_deployment_launcher.py注册机制sandbox_registry.py网关调度gateway.py状态与存储sandbox_store.py赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core 文档重排Reranker基类 API 全解析从抽象接口到三种内置实现openJiuwen agent core 文档重排Reranker基类 API 全解析从抽象接口到三种内置实现 本文深入剖析 openJiuwen ag人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 存储层完全指南BaseKVStore / BaseDbStore / BaseVectorStore 抽象与内置实现深度解析openJiuwen agent core 存储层完全指南BaseKVStore / BaseDbStore / BaseVectorStore 抽象与内置实人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 检索器统一抽象接口Retriever 基类深度解析与实战指南openJiuwen agent core 检索器统一抽象接口Retriever 基类深度解析与实战指南 导读 本文围绕 openJiuwen agent c人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇react-native-gesture-handler 长按手势 LongPressGesture 完整开发指南下一篇如何永久保存微信聊天记录WeChatMsg数据备份完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考