ruflo Flow Nexus Sandbox Agent 技能：基于 E2B 隔离沙箱的 MCP 代码执行环境管理指南

本文以 ruflo 仓库中的 Agent 技能定义文件 .agents/skills/agent-sandbox/SKILL.md 为主体，系统讲解 Flow Nexus Sandbox Agent 的职责边界、mcp__flow-nexus__ 系列沙箱工具的完整参数、六类环境模板与标准部署流程，并结合仓库内 plugin/commands/flow-nexus/sandbox.md 等配套文档补充实操模式。读完本文，你可以完整复现“创建沙箱 → 注入配置 → 执行代码 → 生命周期回收”的隔离代码执行方案，并理解该技能在 ruflo 多智能体体系中的定位。

一、技能文件结构与 Agent 角色定位

该技能文件位于 .agents/skills/agent-sandbox/SKILL.md，采用双 frontmatter 结构：

• 外层入口：name: agent-sandbox，description: Agent skill for sandbox - invoke with $agent-sandbox，声明该技能通过 $agent-sandbox 调用；
• 内层人设定义：name: flow-nexus-sandbox，color: green，将 Agent 设定为“Flow Nexus Sandbox Agent”——一个使用 E2B 沙箱管理隔离执行环境的专家。

技能文档为该 Agent 明确了六项核心职责（core responsibilities）：

1. 使用合适的模板与环境创建并配置 E2B 沙箱；
2. 在隔离环境中安全执行代码，并进行恰当的资源管理；
3. 管理沙箱从创建到终止的完整生命周期；
4. 处理文件上传、下载和环境配置；
5. 监控沙箱性能与资源占用；
6. 排查执行问题与环境故障。

从源码结构看，仓库内并没有 mcp__flow-nexus 系列工具的服务端实现代码，这些工具以 mcp__flow-nexus__ 前缀作为外部 MCP 服务器的调用入口；仓库内的产物是技能定义（SKILL.md）、命令用法文档（plugin/commands/flow-nexus/ 目录）以及配套的 Flow Nexus 技能族（如 plugin/skills/flow-nexus-swarm/SKILL.md、plugin/skills/flow-nexus-neural、plugin/skills/flow-nexus-platform 等目录）。因此本文的参数与行为描述以技能/命令文档为事实依据。

二、沙箱工具箱：六个核心 MCP 操作

技能文档中定义的 sandbox toolkit 覆盖了沙箱的创建、执行、文件管理与状态管理四大类操作，以下是完整继承的调用示例：

// 创建沙箱
mcp__flow-nexus__sandbox_create({
  template: "node", // node, python, react, nextjs, vanilla, base
  name: "dev-environment",
  env_vars: {
    API_KEY: "key",
    NODE_ENV: "development"
  },
  install_packages: ["express", "lodash"],
  timeout: 3600
})

// 执行代码
mcp__flow-nexus__sandbox_execute({
  sandbox_id: "sandbox_id",
  code: "console.log('Hello World');",
  language: "javascript",
  capture_output: true
})

// 文件管理
mcp__flow-nexus__sandbox_upload({
  sandbox_id: "id",
  file_path: "$app$config.json",
  content: JSON.stringify(config)
})

// 沙箱管理
mcp__flow-nexus__sandbox_status({ sandbox_id: "id" })
mcp__flow-nexus__sandbox_stop({ sandbox_id: "id" })
mcp__flow-nexus__sandbox_delete({ sandbox_id: "id" })

结合 plugin/commands/flow-nexus/sandbox.md 命令文档，各工具的关键参数语义可以补充完整：

2.1 sandbox_create：创建沙箱

参数	说明	取值/备注
template	环境模板	node / python / react / nextjs / vanilla / base 六选一
name	沙箱名称	如 my-sandbox、dev-environment
env_vars	环境变量注入	任意键值对，如 API_KEY、NODE_ENV
install_packages	创建时安装的依赖包	如 ["express", "cors", "dotenv"]、["numpy", "pandas", "scikit-learn"]
startup_script	启动脚本	如 npm run dev（命令文档中的扩展参数）
timeout	存活时限	单位为秒，示例值 3600（1 小时）

命令文档给出的创建示例（timeout: 3600 // seconds）明确标注了超时单位是秒，这是配置沙箱回收策略时需要注意的细节。

2.2 sandbox_execute：代码执行

mcp__flow-nexus__sandbox_execute({
  sandbox_id: "sandbox_id",
  code: `
    console.log('Hello from sandbox!');
    const result = await fetch('https://api.example.com');
    return result.json();
  `,
  language: "javascript",
  capture_output: true
})

language 指定解释语言，capture_output 为 true 时回收执行输出，便于 Agent 把 stdout/返回值带回编排链路。

2.3 文件与生命周期管理

除技能文档中的 sandbox_upload 外，命令文档还给出了列表查询与更完整的文件上传写法：

// 列出指定状态的所有沙箱
mcp__flow-nexus__sandbox_list({ status: "running" })

// 状态查询
mcp__flow-nexus__sandbox_status({ sandbox_id: "id" })

// 上传文件（命令文档示例使用绝对路径）
mcp__flow-nexus__sandbox_upload({
  sandbox_id: "id",
  file_path: "/app/data.json",
  content: JSON.stringify(data)
})

// 停止 / 删除
mcp__flow-nexus__sandbox_stop({ sandbox_id: "id" })
mcp__flow-nexus__sandbox_delete({ sandbox_id: "id" })

sandbox_list 支持按状态过滤，配合 sandbox_status 轮询可实现技能文档所要求的“Monitor Performance”职责；stop 与 delete 的区分则对应“暂停回收”与“彻底销毁”两种清理粒度。

三、六类沙箱模板：从最小 Linux 到全栈框架

技能文档枚举了该 Agent 管理的模板（Sandbox templates you manage）：

• node：Node.js 开发环境，内置 npm 生态；
• python：Python 3.x，pip 包管理；
• react：React 开发，附带构建工具链；
• nextjs：全栈 Next.js 应用；
• vanilla：基础 HTML/CSS/JS 环境；
• base：最小化 Linux 环境，用于自定义搭建。

模板选择原则在部署流程中体现为“Select Template”步骤：先分析需求，再按技术栈匹配。命令文档中的 Common Patterns 给出了两个可直接复制的典型配置：

// API 开发沙箱
mcp__flow-nexus__sandbox_create({
  template: "node",
  name: "api-dev",
  install_packages: ["express", "cors", "dotenv"],
  startup_script: "npm run dev"
})

// ML 沙箱
mcp__flow-nexus__sandbox_create({
  template: "python",
  name: "ml-training",
  install_packages: ["numpy", "pandas", "scikit-learn"]
})

前者展示了 install_packages + startup_script 的组合，让沙箱创建即进入可开发的 dev server 状态；后者展示了 Python 数据科学依赖的一次性注入。

四、标准部署流程与质量基线

技能文档定义了六步部署方法（deployment approach），构成该 Agent 的工作闭环：

1. Analyze Requirements：理解开发环境的需求与约束；
2. Select Template：选择合适模板（Node.js、Python、React 等）；
3. Configure Environment：配置环境变量、依赖包与启动脚本；
4. Execute Workflows：在沙箱中运行代码、测试与开发任务；
5. Monitor Performance：跟踪资源使用与执行指标；
6. Cleanup Resources：不再需要时正确终止沙箱。

与之配套，文档给出了六条质量基线（quality standards），这些约束本质上对应隔离执行环境的安全与成本控制要求：

• 始终使用合理的资源限制与超时（对应 timeout 参数）；
• 实现完善的错误处理与日志；
• 安全地管理环境变量（敏感凭证通过 env_vars 注入而非硬编码）;
• 高效的资源清理与生命周期管理（stop / delete 成对意识）；
• 清晰的执行日志与调试支持（对应 capture_output）；
• 支持多环境、可扩展的沙箱编排。

文档末尾的总结句强调了设计取向：“始终考虑安全隔离、资源效率，以及支撑快速开发与测试循环的清晰执行工作流”。

五、在 ruflo Flow Nexus 体系中的位置

ruflo 仓库将 Flow Nexus 拆分为多个技能与命令文档协作：

• 沙箱技能（本文主体）：.agents/skills/agent-sandbox/SKILL.md，负责隔离执行环境；
• 沙箱命令文档：plugin/commands/flow-nexus/sandbox.md，面向 CLI/命令场景的简版用法速查；
• Swarm 编排技能：plugin/skills/flow-nexus-swarm/SKILL.md，覆盖 swarm_init、task_orchestrate、workflow_create/execute 等云端编排工具，与沙箱能力互补——前者解决“多个 Agent 如何协作”，后者解决“代码在哪里安全地跑”；
• MCP 接入方式：该 Swarm 技能文档给出 Flow Nexus 的接入命令，包括 npm install -g flow-nexus@latest、npx flow-nexus@latest login，以及将 MCP 服务器挂到 Claude Code 的 claude mcp add flow-nexus npx flow-nexus@latest mcp start，沙箱工具正是通过这条 MCP 通道暴露给 Agent 的（适用前提：已注册并登录 Flow Nexus 账户）。

从能力关系看，一个典型的 ruflo 多智能体流水线是：Swarm 技能负责初始化拓扑并分发任务，承担执行类任务的 Agent 通过沙箱技能创建 E2B 沙箱、注入 env_vars 与依赖包、执行代码并回收输出，最后按六步流程中的 Cleanup 步骤回收资源。

六、实操要点小结

1. 先选模板再谈配置：六类模板（node/python/react/nextjs/vanilla/base）决定了后续 install_packages 与 language 的合理取值；
2. 参数完整性：创建时尽量一次给全 name、env_vars、install_packages、timeout，避免运行时反复注入；
3. 执行必开输出回收：capture_output: true 是 Agent 判断执行结果、做错误处理的前提；
4. 生命周期显式管理：sandbox_list 定期盘点 + sandbox_status 巡检 + sandbox_stop/sandbox_delete 分级清理，对应质量基线中的“资源清理”条款；
5. 凭证走 env_vars：API 密钥等通过环境变量注入隔离环境，不落入代码与日志。

相关延伸阅读可参考仓库中的 plugin/skills/flow-nexus-swarm/SKILL.md（Swarm 与工作流编排）与 plugin/commands/flow-nexus/sandbox.md（沙箱命令速查），配合本文的技能文件即可完整掌握 ruflo 中基于 E2B 的隔离执行环境方案。