框架与 Playground
把特定框架连接到托管浏览器的注意事项,以及仪表盘中的 Playground:可以一边看实时画面,一边试跑任务或脚本。
框架
任何通过 CDP 连接 Chrome 的工具都可以使用 connectUrl。它是一次性的,因此会自行重连的框架每次连接都需要一个新会话。浏览器在你连接时启动,通常只需几秒(见上文关于超时的说明);无需事先轮询任何状态。
// Patchright (optional; a Playwright fork): npm i patchright
import { chromium } from "patchright";
const browser = await chromium.connectOverCDP(connectUrl, { timeout: 120_000 });
const page = browser.contexts()[0].pages()[0];# Browser Use
from browser_use import Agent, Browser
agent = Agent(task="Find the cheapest flight to Lisbon next Friday", llm=llm, browser=Browser(cdp_url=connect_url))
await agent.run()
# Crawl4AI
from crawl4ai import AsyncWebCrawler, BrowserConfig
config = BrowserConfig(browser_mode="custom", cdp_url=connect_url, use_managed_browser=True)
async with AsyncWebCrawler(config=config) as crawler:
result = await crawler.arun("https://example.com")// Stagehand v4
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
const stagehand = await Stagehand.create({ browser: await localBrowser.connect({ cdpUrl: connectUrl }) });setContent 和 exposeFunction
引擎从不向客户端发送控制台事件,因为查找自动化客户端的页面测量的正是这种转发。托管浏览器也保持这一点:SDK 的 stock_runtime 选项可以在你自己的机器上或 Docker 中为调试运行重新开启这些事件,但它不会应用于云端启动。有两个驱动调用依赖这些事件:
- Playwright 的
page.setContent()会等待一个始终不会到来的控制台事件,因此会超时(Puppeteer 的可以正常使用)。请改为以data:URL 的形式打开 HTML,或者像下面的示例那样自己把它写入页面。 - 在 Playwright 和 Puppeteer 中,
exposeFunction()和exposeBinding()在调用时已打开的页面中生效,该页面一旦发生导航就会失效。请在最后一次导航之后再调用它们,或者改为通过evaluate把结果传回。
// Instead of await page.setContent(html):
// Short HTML: a data: URL (the page gets no origin of its own, so no cookies or storage)
await page.goto("data:text/html," + encodeURIComponent(html));
// Any HTML: write it into a page you have navigated to; it keeps that page's origin
await page.evaluate((html) => {
document.open();
document.write(html);
document.close();
}, html);# Instead of page.set_content(html):
from urllib.parse import quote
page.goto("data:text/html," + quote(html))
# or
page.evaluate("html => { document.open(); document.write(html); document.close(); }", html)一个可以直接上手的辅助函数
一个函数搞定:按上文的重试规则创建会话、连接,并始终停止会话:
// clearcote-hosted.ts
import { chromium, type Browser } from "playwright"; // or "patchright"
const API = "https://www.clearcotelabs.com/api/v1/browsers";
const AUTH = { authorization: "Bearer " + process.env.CLEARCOTE_API_KEY };
const RETRY_CODES = new Set(["NO_CAPACITY", "NO_WORKER"]);
export async function createSession(options: Record<string, unknown> = {}, attempts = 5) {
for (let i = 0; ; i++) {
const res = await fetch(API, {
method: "POST",
headers: { ...AUTH, "content-type": "application/json" },
body: JSON.stringify(options),
});
const body = await res.json().catch(() => ({}));
if (res.ok) return body as { id: string; connectUrl: string; worker: string };
const retry = RETRY_CODES.has(body.code) || (res.status === 429 && !body.code) || [500, 502, 504].includes(res.status);
if (!retry || i + 1 >= attempts) throw new Error([res.status, body.code, body.error].filter(Boolean).join(" "));
await new Promise((r) => setTimeout(r, Math.min(15_000, 1000 * 2 ** i) * (0.5 + Math.random())));
}
}
export async function withBrowser<T>(options: Record<string, unknown>, work: (browser: Browser) => Promise<T>) {
const session = await createSession(options);
try {
const browser = await chromium.connectOverCDP(session.connectUrl, { timeout: 120_000 });
try {
return await work(browser);
} finally {
await browser.close().catch(() => {});
}
} finally {
// Ends the session if closing the browser did not (a no-op otherwise).
await fetch(API + "/" + session.id, { method: "DELETE", headers: AUTH }).catch(() => {});
}
}
// await withBrowser({ profile: { name: "shop", persist: true }, country: "de" }, async (browser) => {
// const page = browser.contexts()[0].pages()[0];
// await page.goto("https://example.com");
// });上传文件
需要文件的页面——<input type="file">、“浏览”按钮、拖放区域——在托管浏览器中接收文件的方式与在本地浏览器中完全相同。文件在你自己的机器上读取,其字节通过连接传输,因此浏览器看不到你磁盘上的路径,你也可以上传一个只存在于脚本运行所在机器上的文件。每个文件的上限为 50 MB。
Playwright 最为简单。setInputFiles 无需点击,直接把文件放进 input,即使 input 被隐藏也有效——许多网站会把真正的 input 藏在一个带样式的按钮后面,所以请直接针对 input 本身,而不是去点击按钮。
// Node.js + Playwright
await page.setInputFiles("input[type=file]", "C:/Users/me/invoice.pdf");
// or build the file in your script, with nothing on disk:
await page.setInputFiles("input[type=file]", {
name: "invoice.pdf",
mimeType: "application/pdf",
buffer: Buffer.from("%PDF-1.4 …"),
});# Python + Playwright
page.set_input_files("input[type=file]", "/home/me/invoice.pdf")当某个按钮会打开系统文件对话框,而又没有可供你定位的 input 时,请改为捕获文件选择器:
const [chooser] = await Promise.all([
page.waitForEvent("filechooser"),
page.click("text=Browse"), // the page's own button
]);
await chooser.setFiles("C:/Users/me/invoice.pdf");Puppeteer。elementHandle.uploadFile() 和 fileChooser.accept() 在托管浏览器上不可用:它们指定的是一个供服务器读取的路径,而该路径可能指向服务器上的任意位置,因此网关会拒绝它们。请在页面内用你传入的字节构建文件,再把它交给 input:
// Puppeteer: construct the file in the page
const b64 = fs.readFileSync("invoice.pdf").toString("base64");
await page.evaluate(({ b64, name, type }) => {
const data = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const dt = new DataTransfer();
dt.items.add(new File([data], name, { type }));
const input = document.querySelector("input[type=file]");
input.files = dt.files;
input.dispatchEvent(new Event("change", { bubbles: true }));
}, { b64, name: "invoice.pdf", type: "application/pdf" });同一个 DataTransfer 也能驱动拖放区域:在其上派发带有该对象的 dragenter、dragover 和 drop 事件。使用本地路径的真实 CDP 拖动(即带有文件的 Input.dispatchDragEvent)会因与 uploadFile() 相同的原因被拒绝。
下载文件
页面下载的文件会保存在我们的服务器上,位于该会话自己的文件夹中。你可以通过脚本已有的连接取回它:使用 Hosted 域的四个命令,由托管网关自己应答,可在任意 CDP 会话上发送。会话结束时文件夹会被删除,所以请在关闭浏览器之前取回需要的文件。
Playwright 会用一个 ID 保存每次下载。Hosted.listFiles 将该 ID 显示为文件的 name,并附上网站给文件起的名字,所以请按 suggestedFilename() 匹配:
// Node.js + Playwright
const cdp = await browser.newBrowserCDPSession();
const [download] = await Promise.all([
page.waitForEvent("download"),
page.click("text=Export"), // whatever starts the download
]);
// Wait until the browser has finished writing it.
const isIt = (f) => f.download?.suggestedFilename === download.suggestedFilename() && f.download.state === "completed";
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find(isIt))) {
await new Promise((r) => setTimeout(r, 250));
}
// Read it in chunks (4 MB each unless you pass length, 8 MB at most).
const parts = [];
for (let offset = 0, eof = false; !eof; ) {
const chunk = await cdp.send("Hosted.readFile", { name: file.name, offset });
parts.push(Buffer.from(chunk.data, "base64"));
offset += chunk.bytes;
eof = chunk.eof;
}
fs.writeFileSync(download.suggestedFilename(), Buffer.concat(parts));
await cdp.send("Hosted.deleteFile", { name: file.name }); // frees room in the session's folder# Python + Playwright
import base64, time
cdp = browser.new_browser_cdp_session()
with page.expect_download() as info:
page.click("text=Export")
name = info.value.suggested_filename
def find():
for f in cdp.send("Hosted.listFiles")["files"]:
d = f.get("download") or {}
if d.get("suggestedFilename") == name and d.get("state") == "completed":
return f
file = find()
while not file:
time.sleep(0.25)
file = find()
data, offset = b"", 0
while True:
chunk = cdp.send("Hosted.readFile", {"name": file["name"], "offset": offset})
data += base64.b64decode(chunk["data"])
offset += chunk["bytes"]
if chunk["eof"]:
break
cdp.send("Hosted.deleteFile", {"name": file["name"]})Puppeteer 以及其他不改动下载设置的客户端,会以网站给出的文件名得到文件。下载完成后文件才会出现;在此之前,浏览器写入的是一个 .crdownload 文件,列出时带有 partial: true。
// Puppeteer
const cdp = await page.createCDPSession();
await page.click("#export");
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find((f) => f.name === "report.csv"))) {
await new Promise((r) => setTimeout(r, 250));
}
const { data, eof } = await cdp.send("Hosted.readFile", { name: file.name }); // loop on offset for files over 4 MB| 命令 | 参数 | 返回 |
|---|---|---|
Hosted.listFiles | 无 | files:name、size、modified(毫秒)、partial,以及 Playwright 命名的下载所带的 download(suggestedFilename、url、state);另有 totalBytes 和 limits。 |
Hosted.readFile | name、offset(0)、length(4 MB,最多 8 MB) | data(base64)、offset、bytes、size、eof |
Hosted.deleteFile | name | 无 |
Hosted.writeFile | name、data(base64,每次调用最多 8 MB)、append | name、size |
name 始终是 listFiles 返回的那个文件名,而不是路径。文件夹最多容纳 1 GB,下载的文件和你放入的文件合计。浏览器下载超过这个量时,会话会结束(原因 max_files_size),所以在较长的会话中请删除已经取回的文件。
Hosted.writeFile 把文件放进会话的文件夹,供同一会话稍后读回:每个文件最多 50 MB,每次调用最多发送 8 MB,其余部分用 append: true 发送。可执行文件类型(.exe、.bat、.ps1 等)会被拒绝。页面无法打开该文件夹中的文件;要把文件交给页面,请按上传文件中的方法使用 setInputFiles。
Playground
仪表盘中的 Playground 会启动一个这样的托管浏览器,你可以在实时画面中看着它运行。它默认打开“Task”:写下浏览器要做的事,智能体会一步一步完成。这就是一次智能体任务,与 POST /api/v1/runs 相同,每一步都会在发生时显示在“What it did”中。你可以随时在实时画面中接管操作。开启“Ask me when it gets stuck”(默认开启)时,智能体在需要人工处理(例如输入登录验证码)时会暂停,你标记完成后它再继续。
任务框下方的几个选项用来设置起始页面(“Start at”)、住宅 IP 所在国家(“Exit”)、每次使用全新设备还是复用同一台设备(“Device”),以及回答是文本还是按你给定结构输出的 JSON(“Output”)。“More”里是其余所有会话选项、最多步数、视频录制和密钥(secret):在任务中写 {{password}},再在这里填入它的值。模型只能看到占位符,值只留在你的标签页中:既不会被保存,也不会出现在链接里。
“Script”则运行你自己的代码。代码在你标签页内的沙箱 frame 中运行,通过浏览器的 WebSocket 直接与它进行 CDP 通信。log() 的输出显示在“What it did”中;在“More”里可以让浏览器保持打开,下一个脚本会在其中继续运行。它的 page 是一个小型辅助对象,并不是 Playwright,因此 Playground 脚本只是一份需要你转写的草稿,而不是可以直接粘贴使用的文件:
| 辅助函数 | 作用 |
|---|---|
page.goto(url, { timeout? }) | 导航并等待 load 事件。 |
page.click(sel) · page.type(sel, text) · page.press(key) | 真实的鼠标和键盘输入,会先将元素滚动到可见区域。 |
page.evaluate(fn, ...args) | 在页面中运行一个函数,并取回其 JSON 结果。 |
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation() | 等待某个元素出现,或等待下一次页面加载。 |
page.scroll(px) · page.screenshot({ fullPage? }) | 用鼠标滚轮滚动;截取一张 JPEG,显示在运行结果中。 |
page.title() · page.url() · page.content() | 文档标题、地址和 HTML。 |
log(...values) · sleep(ms) | 在“What it did”中输出一行(对象会格式化打印);暂停。 |
cdp(method, params) | 向浏览器发送一条原始 CDP 命令(Target.*、Browser.*、Storage.*)。 |
page.cdp(method, params) | 向页面发送一条原始 CDP 命令(Page.*、Runtime.*、DOM.*、Network.*)。 |
报错时会指出出错的脚本行。“Save as…”会把脚本保存在当前浏览器中。
运行结束后,结果显示在下方:任务会给出回答和最后停留的页面,如果要求录制还有录像,以及这次运行的完整时间线;脚本则显示它截取的图片。结果还以另外三种方式提供同一次运行。“Use in code”把它显示为可放进你自己项目的代码:任务对应用 Node、Python 或 curl 调用 runs API,脚本对应 Playwright 或 Puppeteer 下相同的浏览器和选项。“Copy for AI”会复制一段给编程智能体的提示词,包含 API、这次运行及其选项。“Share”会复制一个链接,任务或脚本及其选项都放在链接的 URL 中,因此我们这边不存储任何内容;打开链接的人会用自己的余额运行它。这三种方式都不包含密钥的值。