Flue Sandbox API参考手册：全部参数详解

Flue Sandbox API参考手册全部参数详解【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue Sandbox API 是 Flue Agent 框架为智能体提供安全执行环境的核心接口。本参考手册逐项拆解与 Sandbox 相关的全部参数从useSandbox()的挂载方式到Sandbox接口的 9 个方法、exec()的 4 个执行参数再到local()工厂的环境变量选项帮助新手快速掌握 Flue 沙箱配置的每一项细节。1分钟看懂Flue Sandbox 是什么在 Flue 中Agent 就是一个函数而 Sandbox沙箱是这个函数运行时的工作环境——它提供执行 shell 命令、读写文件的能力让 Agent 能真正动手干活而不是只会聊天。Flue 的沙箱支持三种模式全部实现同一个Sandbox接口核心逻辑无需任何分支判断模式说明典型场景local本地直接绑定 Node 宿主机的文件系统与子进程本地开发、CLI 运行isolate隔离进程内虚拟文件系统快速试验remote远程容器 / microVME2B、Daytona、Modal 等生产部署⚠️重要Flue没有默认沙箱。如果 Agent 不调用useSandbox()它就没有任何环境——内置的 shell 与文件工具不会被添加沙箱相关操作会直接抛错。useSandbox()挂载沙箱的唯一入口useSandbox()把沙箱工厂绑定到当前 Agent 实例。完整签名如下useSandbox(sandbox: SandboxFactory, options?: { cwd?: string }): void参数类型说明sandboxSandboxFactory沙箱工厂必须提供createSandbox()方法local()的返回值就是options.cwdstring?Agent 在该环境内的工作目录提交开始时读取一次使用规则常见报错来源每次渲染只能调用一次——一个 Agent 只有一个环境重复调用会直接抛错子 Agentsubagent中不可调用委托任务共享父 Agent 的环境需用task()调用的cwd参数来限定范围✅可以条件调用——环境是否存在在每个回合边界重新读取挂载/卸载会在下一轮模型调用前切换并以environment信号告知模型。源码实现use-sandbox.tsSandboxFactory沙箱工厂接口工厂Factory是惰性的构造它很便宜昂贵的createSandbox()只在 harness 初始化时调用一次之后该实例的所有 session 共享同一个沙箱。成员说明createSandbox({ id })核心方法返回PromiseSandbox。id是 Agent 实例 id适配器可据此键控持久化资源同一上下文内多次收到相同id属正常需能容忍createSessionEnv?()已废弃等价于createSandbox仅为兼容旧适配器保留tools?可选。提供后整体替换框架默认的模型侧工具集例如 codemode 沙箱用code工具替代 bash。建议基于导出的createReadTool、createWriteTool、createEditTool、createBashTool、createGrepTool、createGlobTool组合而非从零重建接口定义types.ts#L984-L1009Sandbox 接口9 个方法与参数总表这是 Agent 的活沙箱所有沙箱模式都实现它。文件方法同时接受绝对路径和相对路径相对路径基于cwd解析。方法参数返回值要点exec(command, options?)见下方详解PromiseShellResult在沙箱内执行命令readFile(path)路径Promisestring读取 UTF-8 文本readFileBuffer(path)路径PromiseUint8Array读取二进制内容writeFile(path, content)路径、字符串或字节Promisevoid自动创建缺失的父目录无需先mkdirstat(path)路径PromiseFileStat获取文件元数据路径不存在则抛错readdir(path)路径Promisestring[]列目录条目仅名称exists(path)路径Promiseboolean永不抛错不存在返回falsemkdir(path, { recursive? })路径、recursive可选Promisevoidrecursive: true即mkdir -p语义rm(path, { recursive?, force? })路径、选项可选Promisevoidrecursive删目录树force忽略路径缺失错误cwd—string当前工作目录resolvePath(p)路径string将相对路径解析为绝对路径绝对路径原样返回接口定义types.ts#L259-L311其中FileStat的字段isFile、isDirectory、isSymbolicLink?、size?、mtime?——带?的字段在服务商不暴露时会缺省适配器不允许伪造占位值。exec() 深度解析最易配错的 4 个参数exec()是沙箱 API 中使用频率最高的方法其options有 4 个字段exec(command: string, options?: { cwd?: string; env?: Recordstring, string; timeoutMs?: number; signal?: AbortSignal; }): PromiseShellResult参数类型详解cwdstring?本次命令的工作目录相对路径会先对沙箱cwd解析envRecordstring, string?传给命令的环境变量叠加在沙箱基础环境之上timeoutMsnumber?墙钟截止时间毫秒。会转发给服务商的原生超时选项E2BtimeoutMs、Daytonatimeout、Modaltimeout等粒度更粗的提供商只能向上取整、不能向下signalAbortSignal?中途取消。abort 时 Promise立即以AbortError拒绝绝不等待远端命令收尾若服务商不支持中途取消该命令会成为孤儿继续运行且 abort 消息会明确告知模型命令可能仍在运行选型口诀timeoutMs是服务商原生截止线signal是临时急停。两者互相独立——既有截止线又想急停时两个一起传。返回值ShellResult只有 3 个字段stdout、stderr、exitCodetypes.ts#L959-L963。local()模式下还有两个实用细节超时被杀时exitCode返回124遵循 timeout 命令惯例单次输出超过64MB会杀掉整个进程树并标记失败abort 时先发SIGTERM、2 秒宽限后升级SIGKILL确保后台子进程不会残留在宿主机上。local()本地沙箱工厂参数详解local()把沙箱直接绑定到 Node 宿主机是本地开发最常用的工厂local(options?: { cwd?: string; env?: Recordstring, string | undefined })参数默认值说明cwdprocess.cwd()沙箱工作目录在构造时解析为绝对路径env见下文白名单叠加在默认环境变量白名单之上的覆盖层把某个 key 设为undefined可删除白名单中的默认项环境变量安全模型这是新手最容易忽略的参数默认仅放行 14 个 shell 必需变量PATH、HOME、USER、LOGNAME、HOSTNAME、SHELL、LANG、LC_ALL、LC_CTYPE、TZ、TERM、TMPDIR、TMP、TEMP令牌、密钥、云凭证必须通过env显式声明暴露给命令例如local({ env: { GH_TOKEN: process.env.GH_TOKEN } })环境在沙箱构造时一次性快照之后宿主机process.env的修改不会被拾取。参数定义local-env.ts#L181-L200工厂入口local.ts远程沙箱适配器SandboxDriver 接口要接入 E2B、Daytona、Modal、Mirage、Vercel、Cloudflare 等第三方沙箱实现SandboxDriver接口即可——它与Sandbox的 9 个方法一一对应区别在于exec的取消语义timeoutMs是主要取消契约转交服务商原生超时signal是可选增强仅当服务商 SDK 支持中途取消如 Mirage、Vercel时接线其余适配器忽略它即可——取消竞争统一由sandboxFromDriver包装层接管沙箱死亡时应拒绝为SandboxDiedError让 shell 分类报告为基础设施故障而非调用方取消。孤儿命令结算可通过sandboxFromDriver(driver, cwd, { onOrphanSettled })回调观察OrphanedExecSettlement字段包括command、startedAt、abortedAt、settledAt、result?、error?——供适配器做日志、计费或回收运行时本身从不记录它们。适配器实现sandbox.ts。各服务商的接入蓝图文档在 blueprints/sandbox.md 及 blueprints/sandbox--e2b.md、blueprints/sandbox--daytona.md、blueprints/sandbox--modal.md 等蓝图中。FlueFs面向管道工作的沙箱文件系统除模型侧的 bash / 文件工具外Flue 在harness.fs和session.fs上暴露了FlueFs——方法与Sandbox的文件操作完全一致但属于带外操作不会出现在对话记录里。用它做模型不该看到的管道活暂存文件、收集产物、管理临时空间。如果某次写入需要模型下一回合参考正确做法是让模型自己去读那个文件而不是你替它读。⚠️可移植性提示跨沙箱适配器时请优先使用绝对路径因为各提供商的默认cwd并不相同。常见问题速查问题原因与解法useSandbox() was called twice一次渲染只允许挂载一个环境把沙箱声明收敛到 Agent 主体或单个自定义钩子中子 Agent 中调用useSandbox报错按设计禁止委托共享父环境用task({ cwd })限定工作目录Agent 没有 shell / 文件工具漏调useSandbox()——Flue 没有默认沙箱命令超时了但远端还在跑服务商不支持中途取消命令已成孤儿用timeoutMs走原生截止线或选支持signal的提供商写入新目录报父目录不存在不会发生——writeFile跨所有模式自动创建父目录延伸阅读沙箱接口总定义types.ts适配器与取消竞争实现sandbox.tsuseSandbox钩子use-sandbox.ts本地沙箱实现local-env.ts沙箱生态蓝图目录blueprints/sandbox.md掌握了以上参数你就拥有了完整配置 Flue 沙箱的能力用local()起步本地开发用SandboxDriver平滑切换到远程容器exec的timeoutMs与signal双管齐下保障命令可控——这正是 Flue 让 Agent 安全地动手干活的核心所在。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考