Mastra E2B Desktop 沙箱实战指南用mastra/e2b-desktop为 Agent 赋予完整桌面操控能力【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文围绕 Mastra 仓库中的mastra/e2b-desktop工作区包展开讲解如何以 E2B Desktop 为后端为 Mastra Workspace 提供「计算机使用」computer-use云沙箱Agent 不仅能在 Linux 虚拟机中执行 shell 命令、管理进程与文件还能通过截图、鼠标、键盘与屏幕信息直接操作图形化桌面并通过带认证的 noVNC 流实时观察桌面。读完本文你将掌握该提供器的安装方式、配置参数、computer 能力映射、底层 SDK 逃生口escape hatch以及它的版本演进与依赖约束。一、背景Mastra Workspace 与 E2B Desktop 的相遇Mastra 的 Workspace 机制允许 Agent 运行在隔离沙箱中而mastra/e2b-desktop正是为 Workspace 提供的一类「桌面型」沙箱提供器。其官方定位一句话即可概括在 E2B 云沙箱中运行一个完整的 Linux 桌面环境并支持截图、鼠标与键盘控制见 README。从源码结构看它复用了两层依赖mastra/e2bworkspace 包提供基础的E2BSandbox负责命令执行、进程管理、文件上传、暂停/恢复重连等能力e2b/desktopSDK在基础沙箱之上叠加桌面显示与输入控制能力。E2BDesktopSandbox扩展自mastra/e2b的E2BSandbox其关系正如e2b/desktop的 SDKSandbox之于e2b的关系基类提供的一切能力命令、进程、文件、重连都作用于同一个桌面虚拟机见 sandbox/index.ts 的类注释。二、核心能力一览根据 CHANGELOG 0.1.0 条目该包于 0.1.0 首次引入核心能力是一个由 E2B Desktop 支撑的 computer-use 沙箱提供器将 E2B 的命令、进程、文件与重连支持与截图、鼠标、键盘、屏幕信息以及带认证的 noVNC 工具结合。具体拆解为四个维度能力维度说明命令与进程继承自E2BSandbox可执行任意 shell 命令、管理后台进程文件操作支持文件写入、读取、列举作用于桌面虚拟机同一文件系统桌面控制computer截图、鼠标点击/拖动/滚动/移动、键盘输入/按键组合、屏幕尺寸、光标位置实时可视化带认证的 noVNC 流 URL可直接在浏览器中查看桌面当E2BDesktopSandbox被放入Workspace时Agent 会自动获得mastra_workspace_computer_*系列工具——文件、shell 与 computer 工具全部自动注入无需手动声明见 sandbox/index.ts 特性注释。三、安装与快速开始安装命令见 READMEnpm install mastra/e2b-desktop将该包与mastra/core配合使用mastra/e2b-desktop将mastra/core声明为 peer dependency当前版本要求1.67.0-0 2.0.0-0见 package.json。最简用法CHANGELOG 与 README 中的权威示例import { Agent } from mastra/core/agent; import { Workspace } from mastra/core/workspace; import { E2BDesktopSandbox } from mastra/e2b-desktop; const sandbox new E2BDesktopSandbox({ resolution: [1280, 720] }); const agent new Agent({ name: desktop-agent, instructions: You can control a Linux desktop and run shell commands., model: anthropic/claude-sonnet-4-6, // file shell computer tools are all emitted automatically workspace: new Workspace({ sandbox }), });关键点E2BDesktopSandbox的构造不需要手动指定模板。源码中定义了常量DEFAULT_DESKTOP_TEMPLATE desktop当未提供template选项时自动使用 E2B 托管的desktop模板无需构建模板这与基础提供器需要挂载式模板的做法不同见 sandbox/index.ts。四、配置参数详解E2BDesktopSandbox的构造函数接受E2BDesktopSandboxOptions它继承E2BSandboxOptions的全部字段凭据、超时、env、metadata、network、template、instructions并新增两个桌面专属选项见 sandbox/index.ts 接口定义参数类型说明resolution[number, number]桌面显示分辨率[宽, 高]像素仅对新创建的沙箱生效dpinumber桌面显示 DPI仅对新创建的沙箱生效这两个参数会在创建 SDK 沙箱时透传给e2b/desktop的Sandbox.create见 createSdkSandbox 实现单元测试也验证了resolution与dpi会被原样传入且timeoutMs默认 300,000ms见 index.test.ts。此外在 MastraEditor 集成场景中provider.ts还暴露了完整的可序列化配置模式见 provider.ts包括template模板 ID默认 E2B desktop 模板timeout执行超时毫秒默认 300000env/metadata环境变量与自定义元数据domain/apiUrl自托管 E2B 时的域名与 API 地址apiKey/accessTokenE2B API 密钥与访问令牌。非可序列化选项如TemplateBuilder回调、运行时对象会被排除在该配置之外以保证编辑器存储安全。五、computer 能力Agent 如何「操作」桌面computer是E2BDesktopSandbox覆写的核心只读属性类型为SandboxComputer每个操作都会先通过withDesktop确保沙箱已运行再调用e2b/desktopSDK 的对应方法见 sandbox/index.tscomputer 方法底层 SDK 方法作用screenshot()desktop.screenshot()返回{ data, mediaType: image/png }leftClick(x, y)/rightClick(x, y)/doubleClick(x, y)同名鼠标三键点击moveMouse(x, y)desktop.moveMouse(x, y)移动光标drag(from, to)desktop.drag([x,y],[x,y])拖拽坐标被转换为数组形式scroll(direction, amount)desktop.scroll(...)滚动type(text)desktop.write(text)键入文本press(key)desktop.press(key)按键支持组合键如[ctrl,s]getScreenSize()desktop.getScreenSize()屏幕尺寸getCursorPosition()desktop.getCursorPosition()光标位置streamUrl()见下节noVNC 直播流 URL值得注意的是所有 computer 操作都会自动启动沙箱若检测到底层虚拟机已死例如抛出sandbox has been killed还会通过retryOnDead自动重建沙箱后重试。这些行为均有单元测试覆盖见 index.test.ts。六、noVNC 实时桌面视图computer.streamUrl()提供带认证的 noVNC 查看地址实现「看得见」的桌面首次调用时通过desktop.stream.start({ requireAuth: true })启动带认证的流启动过程以 SDK 沙箱 ID 为键做记忆化memoize同一沙箱只启动一次沙箱被重建resume/recreate后会自动重新启动生成 URL 时优先携带authKey形如vnc.html?password...若流由外部通过desktop逃生口启动且未启用认证则降级返回无认证的普通 URL无法启动时返回null见 ensureStreamStarted 与 streamUrl 实现。测试场景完整覆盖了「带认证 URL」「记忆化只启动一次」「容忍外部启动的流」「启动失败返回 null」四种情形见 index.test.ts Stream URL 测试组。七、sandbox.desktop逃生口直接操作底层桌面 SDKCHANGELOG 明确指出该提供器还通过sandbox.desktop导出底层桌面 SDK用于桌面专属操作。这是一个 getter返回e2b/desktop的Sandbox实例若沙箱尚未启动会抛出SandboxNotReadyError见 sandbox/index.ts。典型用法源码 JSDoc 示例const sandbox new E2BDesktopSandbox(); await sandbox.start(); await sandbox.desktop.launch(xfce4-terminal); await sandbox.desktop.open(https://mastra.ai);由此可以解锁抽象层未覆盖的 APIlaunch()启动应用、open()打开 URL、窗口辅助方法、自定义流控制等。八、模板解析与沙箱生命周期模板解析逻辑见 resolveTemplate 实现若已解析过模板 ID直接复用若未显式提供template选项使用默认的desktop模板——因为是 E2B 托管模板无需任何构建步骤若显式提供了模板则走基础提供器的完整解析流程ID、builder 或 customizer。沙箱的创建与重连分别由两个工厂钩子完成createSdkSandbox调用E2BDesktopSdkSandbox.create(templateId, {...})connectSdkSandbox调用E2BDesktopSdkSandbox.connect(sandboxId, opts)——两者都经由e2b/desktopSDK而非基础的e2bSDK。单元测试验证了默认创建时传入模板desktop且不会触发基础 SDK 的create/Template.exists/Template.build显式模板按原样传入已有运行中沙箱时走connect路径见 index.test.ts。此外clone()方法可基于当前沙箱配置构造同类型兄弟沙箱支持id、env、idleTimeoutMinutes内部转换为timeout毫秒等覆盖项见 sandbox/index.ts。九、版本演进从 0.1.0 到 0.1.2-alpha.0CHANGELOG 完整记录了三个里程碑0.1.0首个稳定版本新增mastra/e2b-desktop即本文介绍的 computer-use 沙箱提供器PR #21707依赖mastra/core1.62.0与mastra/e2b0.10.0。0.1.1打包与文档优化更新 README 以确保信息准确、及时PR #22858从 npm 发布产物中移除CHANGELOG.md减小包体积PR #22737依赖升级至mastra/core1.64.0、mastra/e2b0.11.0。0.1.2-alpha.0依赖下限调整将mastra/corepeer dependency 下限提升至1.67.0以匹配其依赖的mastra/e2bPR #23652依赖mastra/core1.67.0-alpha.3、mastra/e2b0.12.0-alpha.0。十、测试体系如何验证桌面能力该包同时提供单元测试与真实环境集成测试见 package.json 测试脚本pnpm test:unit运行排除 integration 后缀的单元测试mock 掉e2b与e2b/desktopSDK覆盖构造选项、模板解析、computer 操作映射、stream URL 各分支、Workspace 工具注入断言工具名与WORKSPACE_TOOLS.COMPUTER完全一致、desktop 逃生口等见 index.test.tspnpm test/pnpm test:cloud运行真实集成测试需要E2B_API_KEY环境变量未配置时自动跳过。集成测试包含两类见 index.integration.test.tscomputer-use 冒烟测试截图返回真实 PNG校验魔数\x89PNG、鼠标移动与光标位置往返一致moveMouse(101,102)后getCursorPosition()返回同一坐标、GUI 与 shell 命中同一台机器shell 写入文件后经desktop.files.read读回、streamUrl解析出带password的认证地址共享一致性测试套件通过createSandboxTestSuite复用工作区通用用例并声明能力矩阵——不支持挂载桌面模板无 FUSE 工具、支持重连/并发/env/工作目录/超时默认命令超时 30s。十一、适用场景与注意事项典型场景需要 Agent 操作真实 GUI 的自动化任务——浏览器自动化open打开页面后截图分析、桌面应用测试、跨 shell 与图形界面的复合任务等。注意事项resolution与dpi仅对新创建的沙箱生效重连既有沙箱时不会被应用桌面模板不支持文件挂载FUSE需依赖文件读写 API 而非挂载方式见 集成测试能力矩阵使用sandbox.desktop前必须确认沙箱已启动否则会抛出SandboxNotReadyError若在 MastraEditor 中以e2bDesktopSandboxProvider注册沙箱可在 UI 中通过可视化表单配置resolution、dpi、timeout等字段见 provider.ts 的 configSchema。需要深入源码的读者建议从 入口文件 出发沿E2BDesktopSandboxsandbox/index.ts→ 基类mastra/e2b的E2BSandboxworkspaces/e2b→ 上游e2b/desktopSDK 的调用链逐层阅读即可完整理解桌面能力的实现边界。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
