【免费下载链接】edgeone-makers-tools项目地址https://gitcode.com/gh_mirrors/ed/edgeone-makers-tools点击查看免费下载一、什么是 EdgeOne Makers 沙箱edgeone-makers-tools是 EdgeOne Makers 平台腾讯 EdgeOne 全栈开发平台的官方 AI Agent 技能包其中最重要的平台能力之一就是云端沙箱context.sandbox。它解决一个核心问题让 AI 在安全的云端环境里真正动手执行代码——运行 Python/Shell 命令、读写文件、甚至驱动一个真实的浏览器。 一句话理解你部署在 EdgeOne Makers 上的 AI Agent不再只会说还能做。沙箱就是 Agent 的双手。根据官方决策树如果你需要在沙箱里跑代码、处理上传文件、使用 MCP 工具Claude Agent SDK 路线是最合适的框架选择详见 makers-agents/SKILL.md 中的技术决策树。二、核心原则用运行时注入不要自己造轮子 这是新手最容易踩的坑官方在 capabilities/sandbox.md 中把它列为第一原则原则说明✅ 直接用注入对象Node 用context.sandboxPython 用ctx.sandbox❌ 不要手写请求不要自己拼/v1/sandbox/*接口、不要手动解析 token⏳ 懒加载机制沙箱首次访问时才初始化鉴权信息由运行时自动注入 零配置模板.env不需要配置沙箱票据、PROJECT_ID、SANDBOX_API_BASE等⚠️ 注意区分两类环境变量AI_GATEWAY_API_KEY/AI_GATEWAY_BASE_URL是LLM 网关的业务变量沙箱票据由部署流水线自动注入两者完全不是一回事。三、沙箱能力全景四大模块一览 context.sandbox提供四个核心模块覆盖了代码执行、文件操作和浏览器自动化模块主要方法用途commandsrun(cmd, {cwd, env, user, timeout})Shell 命令执行返回{stdout, stderr, exitCode}⚠️timeout 单位是秒filesread/write/list/makeDir/exists/remove文件增删查改⚠️write只接受 UTF-8 字符串二进制要用commands跑base64 -dbrowsergoto/screenshot/click/type/evaluate/closeCDP 驱动真实 ChromiumPlaywrightscreenshot({fullPage: true})返回{base64Image}runCode⭐sandbox.runCode(code, {language, timeout})Jupyter 内核执行变量跨调用保留是顶层方法不存在code_interpreter命名空间控制类getInfo()/extendTimeout(seconds)/kill()/getHost(port)查看实例状态、延长生命周期、终止实例Node.js 和 Python 用法几乎一致// NodeTS在 agent 端点内直接使用注入的沙箱 const result await context.sandbox.commands.run(echo hello, { timeout: 10 }); await context.sandbox.files.write(/tmp/a.txt, utf8 content); const exec await context.sandbox.runCode(print(11), { language: python });# Python完全对等 result await ctx.sandbox.commands.run(echo hello, timeout10)四、三大高频坑点避坑清单 ️1./tmp/目录跨请求容易丢失最重要的坑这是平台级特性即使同一conversation_id被粘性路由到同一沙箱实例/tmp/里的文件也可能在请求之间被清理。典型事故第一次/chat请求用户上传了图片到/tmp/foo.jpg几分钟后追问压缩那张图——文件已经没了AI 报FileNotFoundError甚至可能幻觉出一张假图。✅官方推荐做法见 capabilities/sandbox.md在后端用模块级MapconversationId, Array{name, base64}缓存上传文件每次请求开始时把缓存文件重新写回沙箱/tmp/name在系统提示词中明确禁止AI 在遇到FileNotFoundError时编造文件❌反模式假设/tmp/foo.jpg在第二次请求时还在 → 模型报幻觉。2. 冷启动需要探测 重试沙箱可能冷启动首次访问触发初始化官方模板的做法是先用commands.run(ls /tmp)做一次存活探测失败则间隔 2 秒重试最多 2 次。详见 node-frameworks/claude-sdk.md 第 4 节。3. 写文件只收文本二进制走 commandsfiles.write(path, content)只接受 UTF-8 字符串。处理图片、压缩包等二进制内容时正确姿势是把 base64 写入临时文件再用commands.run(base64 -d ...)在沙箱内部解码生成。大文件150KB则采用分块写入 Python 解码策略。五、沙箱与平台工具如何配合使用 context.sandbox负责底层执行而context.tools负责给模型暴露工具两者由同一个沙箱驱动Node / Claude Agent SDK 路线推荐// 一行获取 MCP 工具包需 edgeone.json 设置 agents.framework: claude-agent-sdk const bundle context.tools.toClaudeMcpServer(edgeone, { alwaysLoad: true });Python 路线ctx.tools与ctx.sandbox均由运行时注入字段定义见 platform/python-entry.md 第 2 节完整工具清单commands、files_*、browser_*、code_interpreter、web_search及五大框架的接线方式见 capabilities/tools.md 降级策略沙箱是尽力而为的——如果沙箱不可用文本类文件可降级为内联内容直接塞进 prompt无法降级的二进制要明确告诉模型被跳过了而不是静默失败。六、本地开发与调试 ️# 1. 安装 CLI要求 Node.js ≥ 16CLI ≥ 1.6.0 npm install -g edgeone # 2. 执行任何 makers 命令前先设置 export PAGES_SOURCEskills # 3. 关联项目 拉取环境变量 PAGES_SOURCEskills edgeone makers link PAGES_SOURCEskills edgeone makers env pull # 4. 本地启动开发服务器访问 http://127.0.0.1:8088/ 预览 PAGES_SOURCEskills edgeone makers dev调试技巧沙箱工具调试日志默认关闭设置环境变量MAKERS_AGENT_TOOLKIT_DEBUG1Python 中为build_tools(..., debugTrue)即可开启——日志输出到stderr、不会进入模型上下文并自动脱敏 token / 密码 / key。⚠️ 环境变量红线agents/目录下读环境变量必须用context.envPython 为ctx.env严禁process.env/os.environ——完整规则见 makers-agents/SKILL.md 的Critical Rules章节。七、上线前自查清单 ✅对照官方 review-checklist.mdG 节 Sandbox / Tools部署前逐项确认直接使用context.sandbox/context.tools无手写/v1/sandbox/*调用模板.env不包含沙箱票据 /PROJECT_ID/SANDBOX_API_BASE/API_ENVrunCode是顶层调用sandbox.runCode(...)而非sandbox.code_interpreter.runCode(...)截图用对象参数screenshot({ fullPage: true })不是screenshot(true)超时单位是秒不是毫秒extendTimeout(seconds)参数名是seconds/tmp/易失性已处理进程级文件缓存 每次请求重传系统提示词明确禁止 AI 在FileNotFoundError时编造文件edgeone.json中agents.framework已正确设置claude-agent-sdk/openai-agents-sdk/langgraph/deepagents/crewai八、进阶在 Makers 运行时之外手动构建沙箱 只有当你不在Makers Agent 运行时内、想让 SDK 直连控制面时才使用buildSandboxProxyNode/build_sandboxPython手动构建沙箱客户端。常规 Agent 项目永远不需要它。总结 要点记住这一句使用方式运行时已注入context.sandbox直接拿来用四大能力commandsShell、files文本、browser真实 Chromium、runCodeJupyter 内核最大陷阱/tmp/跨请求易丢 → 进程级缓存 每次重传二进制文件files.write只写文本二进制用commandsbase64 -d单位陷阱超时是秒screenshot收对象runCode是顶层方法配置好这些你的 AI Agent 就能安全地在云端跑代码、处理文件、操作浏览器了。更多平台约定SSE 协议、会话 ID、store 记忆可继续查阅 makers-agents/SKILL.md 的路由表整个技能包结构说明见 README.md 与 AGENTS.md。赞分享【免费下载链接】edgeone-makers-tools项目地址https://gitcode.com/gh_mirrors/ed/edgeone-makers-tools点击查看免费下载相关推荐WorkBuddy 沙箱 edgeone-makers-tools 开发完整避坑指南7大坑CI适配方案WorkBuddy 沙箱 edgeone makers tools 开发完整避坑指南7大坑CI适配方案 edgeone makers tools 是 Edg如何在EdgeOne Makers开发AI Agentedgeone-makers-tools五大框架选型决策树如何在EdgeOne Makers开发AI Agentedgeone makers tools五大框架选型决策树 edgeone makers tools 是edgeone-makers-tools是什么AI编程助手的EdgeOne全栈开发技能包完全指南edgeone makers tools是什么AI编程助手的EdgeOne全栈开发技能包完全指南 edgeone makers tools 是面向腾讯 Edg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考