沙箱原子 API
context.sandbox.* 是开发者直接调用的视角，可以基于沙箱原子 API 自己封装工具。commands
在沙箱中执行一次性 shell 命令，每次调用都是独立新进程（不保留进程状态、不保留 cwd、不保留环境变量改动；如需变量跨调用保留，用
runCode）。commands.run(cmd, opts?) — 执行 shell 命令。opts 支持 cwd / env / user / timeout（秒）；返回 { stdout, stderr, exitCode }。TS 示例：
const { stdout, exitCode } = await context.sandbox.commands.run('pip install requests && python -c "import requests; print(requests.__version__)"',{ timeout: 60 },)
Python 示例：
result = await context.sandbox.commands.run('pip install requests && python -c "import requests; print(requests.__version__)"',timeout=60,)
files
读写沙箱实例内的文件系统。文本场景直接用，二进制资产（如
.png ）建议先用 commands 在沙箱内下载或解码，再通过其他通道读出（比如上传到对象存储后给前端 URL）。files.read(path) — 读取文本文件内容。files.write(path, content) — 写入文本文件（不存在则创建，存在则覆盖）。files.list(path) — 列出目录，返回 EntryInfo[]（{ name, type, path }）。files.makeDir(path) / files.make_dir(path) — 创建目录。files.exists(path) — 判断文件或目录是否存在。files.remove(path) — 删除文件或目录。TS 示例：
await context.sandbox.files.makeDir('/work/output')await context.sandbox.files.write('/work/output/result.json', JSON.stringify(data))const entries = await context.sandbox.files.list('/work/output')
Python 示例：
await context.sandbox.files.make_dir('/work/output')await context.sandbox.files.write('/work/output/result.json', json.dumps(data))entries = await context.sandbox.files.list('/work/output')
browser
通过 CDP 连接沙箱内置 Chromium（底层 Playwright），适合需要状态保持的多步浏览器流程，如登录后操作、表单交互、动态页面截图。
browser.cdpUrl — CDP 连接地址，可被外部 Playwright 直连。browser.liveUrl — NoVNC 可视化地址，供人工实时查看页面。browser.goto(url) — 导航到目标 URL，返回 { url, title, status }。browser.screenshot(fullPage?) — 截图返回 { base64Image }。browser.click(selector) — 点击元素。browser.type(selector, text) — 在输入框键入文本。browser.evaluate(script) — 在页面上下文执行 JavaScript。browser.getContent() / browser.get_content() — 获取当前页面 HTML，返回 { content }。browser.close() — 关闭浏览器连接。TS 示例：
// 登录后再截图（LLM 工具单独调 browser_screenshot 做不到）await context.sandbox.browser.goto('https://example.com/login')await context.sandbox.browser.type('input[name=user]', 'alice')await context.sandbox.browser.type('input[name=pass]', 'secret')await context.sandbox.browser.click('button[type=submit]')await context.sandbox.browser.goto('https://example.com/dashboard')const { base64Image } = await context.sandbox.browser.screenshot({fullPage: true})
Python 示例：
await context.sandbox.browser.goto('https://example.com/login')await context.sandbox.browser.type('input[name=user]', 'alice')await context.sandbox.browser.type('input[name=pass]', 'secret')await context.sandbox.browser.click('button[type=submit]')await context.sandbox.browser.goto('https://example.com/dashboard')shot = await context.sandbox.browser.screenshot(full_page=True)
runCode
在沙箱内置 Jupyter kernel 中执行代码，变量跨调用保留。
runCode(code, opts?) / run_code(...) — 执行代码。opts 支持 language（默认 python，也支持 javascript / r / bash）、timeout（秒）；返回 Execution { results, logs, error }。TS 示例：
// 用 Python 处理 CSV 并生成图片const exec = await context.sandbox.runCode(`import pandas as pddf = pd.read_csv('/work/data.csv')df.plot().get_figure().savefig('/work/out.png')print('done')`, { language: 'python' })
python 示例：
exec = await context.sandbox.run_code("""import pandas as pddf = pd.read_csv('/work/data.csv')df.plot().get_figure().savefig('/work/out.png')print('done')""",language='python',)
