AI Agent后端MCP 服务浏览器控制Agent 评测【免费下载链接】sandboxAll-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.项目地址https://gitcode.com/gh_mirrors/sandbox103/sandbox点击查看免费下载在 AIO SandboxAll-in-One Sandbox for AI Agents中Chromium 浏览器下载的文件不会直接出现在宿主机上而是先落入沙盒容器的文件系统中。本文以官方指南 browser-downloads.md 为核心系统讲解浏览器下载的默认落盘位置、如何通过 CDPChrome DevTools Protocol配置下载行为、如何用文件 API 查看与导出下载产物以及下载链路的安全红线。读完本文你将能够在自己搭建的 AI Agent 工作流中完整打通浏览器触发下载 → 沙盒内定位 → 文件 API 导出到宿主机的闭环。下载链路总览为什么下载文件会消失在沙盒里AIO Sandbox 把浏览器、Shell、文件系统、MCP 与 VSCode Server 整合进同一个 Docker 容器。因此 Chromium 进程写入的任何文件都落在容器的隔离文件系统内而不是宿主机磁盘上。这一点决定了浏览器下载处理的基本思路下载产物由 Chromium 写入沙盒文件系统路径固定、可控Shell 可以直接查看下载目录因为 Shell 与浏览器共享同一套沙盒文件系统文件 API 可以把产物拉回宿主机实现跨容器传输。换句话说浏览器下载本质上被拆成了两步第一步让 Chromium 把文件写进沙盒第二步通过文件 API 把沙盒里的文件取出来。下面分别展开这两步的实操。默认下载目录Chromium 通常会遵循浏览器默认行为把文件下载到当前运行用户的下载目录。AIO Sandbox 镜像内运行用户为gem因此默认下载目录为/home/gem/Downloads这是一个固定的已知路径Agent 可以据此预测下载产物的落点无需先探查用户目录结构。用文件 API 列出下载目录Sandbox 的 HTTP 服务默认监听8080端口本地映射常为127.0.0.1:8080:8080文件列表接口为POST /v1/file/list。列出下载目录curl -X POST http://localhost:8080/v1/file/list \ -H Content-Type: application/json \ -d {path: /home/gem/Downloads}从 SDK 源码看这一接口在 Python 客户端中对应client.file.list_path(path...)见 sdk/python/agent_sandbox/file/client.py底层请求路径即为v1/file/list。list_path还支持recursive递归列出、show_hidden显示隐藏文件、file_types按扩展名过滤如[.pdf, .csv]、include_size附带文件大小、sort_by按 name/size/modified/type 排序等可选参数适合在下载目录文件较多时做精准检索。通过 CDP 配置下载行为在触发下载之前先要通过 CDP 配置 Chromium 的下载行为。AIO Sandbox 的浏览器会话会暴露一个 CDP 地址获取方式有两种通过 SDK调用client.browser.get_info()其返回结果中的cdp_url字段即为浏览器级 CDP 连接地址接口定义见 sdk/python/agent_sandbox/browser/client.py直接请求GET /v1/browser/info返回同样的信息。方式一通过 Playwright 连接 CDPPlaywright 等 CDP 客户端可以在触发下载前配置下载行为。示例与官方指南一致from agent_sandbox import Sandbox from playwright.sync_api import sync_playwright client Sandbox(base_urlhttp://localhost:8080) cdp_url client.browser.get_info().cdp_url with sync_playwright() as p: browser p.chromium.connect_over_cdp(cdp_url) page browser.new_page() page.context.set_default_timeout(30_000)这段代码里有两个关键点connect_over_cdp(cdp_url)是把 Playwright 附着到沙盒内已运行的 Chromium 实例上而不是再启动一个新浏览器。仓库中的 examples/playwright-integration/main.py 使用异步写法playwright.chromium.connect_over_cdp(cdp_url)完成同样的连接可以作为对照参考page.context.set_default_timeout(30_000)设置 30 秒默认超时避免下载或页面加载期间操作挂起。连接成功后page上发生的页面交互点击下载链接、触发window.print导出等就会把文件写入沙盒下载目录。方式二直接在浏览器级 CDP 连接上调用Browser.setDownloadBehavior如果你不依赖 Playwright而是直接使用 Chrome DevTools Protocol可以在浏览器级 CDP 连接上发送Browser.setDownloadBehavior命令{ method: Browser.setDownloadBehavior, params: { behavior: allow, downloadPath: /home/gem/Downloads, eventsEnabled: true } }参数说明参数取值作用behaviorallow/deny/defaultallow允许下载并写入downloadPathdeny阻止下载default沿用浏览器默认行为downloadPath沙盒内绝对路径下载文件的落盘目录与默认下载目录保持一致即可/home/gem/DownloadseventsEnabledtrue/false是否派发Browser.downloadWillBegin与Browser.downloadProgress事件便于程序化跟踪下载进度触发下载后如何确认完成触发下载后有两种方式确认下载结果监听 CDP 事件订阅Browser.downloadWillBegin下载开始包含下载项 GUID 与建议文件名与Browser.downloadProgress下载进度携带state: completed/canceled等状态据此判断下载何时结束直接查询文件系统通过文件 API 检查下载目录POST /v1/file/list的返回中确认目标文件已出现。这种方式与事件监听互相独立即使在 CDP 事件不可用或超时的情况下也能兜底。下载文件到宿主机确认下载产物已在沙盒内后通过文件下载接口把文件拉回宿主机。文件下载接口为GET /v1/file/download参数为沙盒内绝对路径curl -L \ http://localhost:8080/v1/file/download?path/home/gem/Downloads/report.pdf \ --output report.pdf这里的-L用于跟随可能的重定向--output report.pdf把响应流写入宿主机本地文件。SDK 中对应方法为client.file.download_file(path..., change_policy...)见 sdk/python/agent_sandbox/file/client.py底层以流式方式消费响应字节适合大文件下载。用change_policyabort防止读取到写了一半的文件下载产物可能仍被后台进程如正在落盘中的 Chromium持续写入。若此时直接下载可能拿到一个不完整或正在变化的文件。此时可以追加change_policyabortcurl -L \ http://localhost:8080/v1/file/download?path/home/gem/Downloads/report.pdfchange_policyabort \ --output report.pdfchange_policy的类型定义见 sdk/python/agent_sandbox/types/file_download_change_policy.py可取两个值取值行为ignore默认行为不检测源文件变化直接流式下发abort服务端在开始传输前或传输过程中检测到源文件发生变化时中断本次下载从 SDK 底层实现sdk/python/agent_sandbox/file/raw_client.py可以看出change_policyabort时若服务端检测到文件变化接口会返回409 ConflictSDK 中对应抛出ConflictError。因此在使用该策略时应把收到 409理解为文件还在变化、需要稍后重试的信号而不是真正的失败。用 SDK 下载的等价写法不依赖 curl 时也可以直接在 Python 里完成同样的下载from agent_sandbox import Sandbox client Sandbox(base_urlhttp://localhost:8080) with open(report.pdf, wb) as f: for chunk in client.file.download_file( path/home/gem/Downloads/report.pdf, change_policyabort, ): f.write(chunk)这样可以把触发下载 → 轮询目录 → 导出文件全部收敛进一个 Python 脚本便于在 Agent 循环里复用。完整实战一条龙脚本把上面的要素组合起来可以得到一个完整的下载闭环触发下载 → 确认落盘 → 导出到宿主机import time from agent_sandbox import Sandbox from playwright.sync_api import sync_playwright client Sandbox(base_urlhttp://localhost:8080) cdp_url client.browser.get_info().cdp_url # 1. 触发下载 with sync_playwright() as p: browser p.chromium.connect_over_cdp(cdp_url) page browser.new_page() page.context.set_default_timeout(30_000) page.goto(https://example.com/report) page.click(a#download) # 2. 轮询等待下载完成 for _ in range(30): result client.file.list_path(path/home/gem/Downloads) if any(item.get(name) report.pdf for item in result.items): break time.sleep(1) # 3. 导出到宿主机 with open(report.pdf, wb) as f: for chunk in client.file.download_file( path/home/gem/Downloads/report.pdf, change_policyabort, ): f.write(chunk)几点说明步骤 2 的轮询用的是文件 API 而非 CDP 事件即使 CDP 事件流断开也能完成确认若下载本身耗时较长可以把set_default_timeout(30_000)调大或改用手动轮询change_policyabort保证导出的是一份稳定的文件避免读到半成品。与浏览器其他配置的衔接下载行为与浏览器整体配置相互独立但常需协同。AIO Sandbox 支持通过环境变量在容器启动时配置浏览器详见 browser-config.md例如BROWSER_EXTRA_ARGS--disable-dev-shm-usage追加 Chromium 启动参数、BROWSER_USER_AGENT自定义 User-Agent、HOMEPAGE设置启动首页。这些配置影响页面如何渲染与请求行为进而影响下载入口是否可用而下载落盘路径则由 CDP 的downloadPath或浏览器默认行为决定两者互不覆盖。此外运行时也可以通过以下 API 查看或更新浏览器状态GET /v1/browser/info获取 CDP 地址、视口等信息获取cdp_url的官方入口POST /v1/browser/config调整分辨率等浏览器配置POST /v1/browser/restart软重启重连 Playwright 会话或硬重启经 supervisorctl 重启浏览器进程。安全建议浏览器下载的文件本质上来自不可信的网页内容处理时需遵循以下原则将下载文件视为不可信输入。PDF、Office 文档、脚本等都可能携带恶意内容Agent 解析或执行前应经过校验除非用户明确需要文件应保留在沙盒内处理。沙盒的隔离性是安全边界把文件导出到宿主机前应确认其必要性不要开启过宽的本地文件访问能力除非任务确实需要。下载目录的读写、文件 API 的导出范围都应遵循最小权限原则避免让 Agent 随意访问沙盒内外的大范围路径。小结本文围绕 browser-downloads.md 展开完整覆盖了 AIO Sandbox 中浏览器下载的三个环节落盘Chromium 把下载产物写入沙盒内的/home/gem/Downloads可通过POST /v1/file/list查看配置通过 Playwright 的connect_over_cdp或 CDP 的Browser.setDownloadBehavior设置下载行为并用Browser.downloadWillBegin/Browser.downloadProgress事件或文件 API 确认下载完成导出通过GET /v1/file/download?path...change_policyabort把稳定版本的产物拉回宿主机。配合 SDK 中的client.browser.get_info()、client.file.list_path()与client.file.download_file()实现见 sdk/python/agent_sandbox/browser/client.py 与 sdk/python/agent_sandbox/file/client.py这一链路可以完全编程化直接嵌入到 AI Agent 的自动化循环中。赞分享AI Agent后端MCP 服务浏览器控制Agent 评测【免费下载链接】sandboxAll-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.项目地址https://gitcode.com/gh_mirrors/sandbox103/sandbox点击查看免费下载相关推荐Puppeteer BrowserContextOptions为隔离浏览上下文配置代理与下载行为的完整指南Puppeteer BrowserContextOptions为隔离浏览上下文配置代理与下载行为的完整指南 BrowserContextOptions 是 P浏览器控制测试网页爬虫开发工具Puppeteer 配置深度指南配置文件、环境变量与浏览器下载行为的完整解析Puppeteer 配置深度指南配置文件、环境变量与浏览器下载行为的完整解析 Puppeteer 开箱即用时会自动下载并固定使用一个特定版本的 Chrome浏览器控制测试网页爬虫开发工具Livewire 文件下载完全指南从 Laravel 响应到浏览器 Blob 的完整链路Livewire 文件下载完全指南从 Laravel 响应到浏览器 Blob 的完整链路 在 Livewire 组件中触发文件下载用法与 Laravel 原后端前端上一篇终极指南3步定制Meilix Linux启动界面打造专属系统门面下一篇终极解密5步掌握Hunyuan3D-2高分辨率3D资产生成核心技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 的声明式请求校验：express-validator 模式化验证完全指南)
