核心概念

BrowserPilot 里没有「任务队列」这个对象。下面这五个词分开看。

词	是什么	谁保存	生命周期
任务	你对 Agent 说的一句目标，例如「取前 5 个仓库」	你的 Agent 客户端，不在 BrowserPilot 里	对话结束就没了
步骤	一次 MCP 工具调用，例如 page_click	不单独保存；失败时附一张现场截图	一次调用
工作流	把步骤存成一张节点图	workflows.json	同名覆盖，编号不变
运行	一次 workflow_run 的执行	runs.json，最多 200 条	每次运行一条
环境	一套登录态 + 一扇窗口	envs.json + partitions/<env-id>	关窗不删；env_delete 才清

任务：留在对话里

BrowserPilot 不保存「任务」这个对象。你说给 Agent 的目标由客户端管理；BrowserPilot 只看到一串工具调用。

这带来两个直接后果：

• 同一个任务可以产生 3 次调用，也可以产生 80 次；BrowserPilot 不会替 Agent 记住「任务做到哪」。
• Agent 逐步调用工具时不会写运行记录。要留档，把步骤存成工作流，再跑一次。

步骤：一次工具调用

一次 page_click、一次 page_wait、一次 page_script 都是一步。步骤是同步的：调用返回，Agent 才知道结果。

失败时工具会返回 ok: false 和错误原因；如果带了 tabId，还会附一张现场截图（errorShot）。这张图不进运行记录，只在这次返回里。

工作流：把步骤存成图

工作流是一张从左向右的节点图，当前有 22 种节点：

• 流程：开始、结束、判断、循环
• 页面：打开、点击、填写、选择、按键、滚动、滑动、上传
• 等待与提取：等待、提取、导出
• 数据与调试：页面脚本、代码、CDP、HTTP 请求、下载
• 人机协作：交接、验证码

Agent 第一次做某件事时仍然要一步步调工具；做通后用 workflow_write 把图写下来。之后只调用一次 workflow_run，主进程顺着边跑完，不再把每个节点交回给模型。

工作流不是鼠标轨迹，也不往页面里注入脚本。它是一份可读的 JSON，能导出、导入、放到市场。

运行：一次执行，一条记录

workflow_run 是一次运行；workflow_batch 的每一行也是一次运行。

运行记录里有：

• 成功/失败
• 停在哪一步（节点编号）
• 输出（outputs）
• 产生的文件（files）
• 失败时的现场截图；如果当时开着抓包，还有 HAR

存储上限是 200 条，界面列表最多显示 50 条。目前没有逐次工具调用的审计日志。

环境：登录的容器

一套环境就是一个 Electron 持久分区：session.fromPartition('persist:' + id)。

• 一套环境一扇窗口；这套窗口里的标签共享登录。
• 不同环境互不可见。同一网站要多个账号，就开多套环境。
• 关窗口不清登录；env_delete 会清掉这个分区的 Cookie 并删除记录。
• env_default 是默认环境，名称可以改，不能删。

Agent 用 env-... 指定环境；不给就用默认环境。窗口没开时，第一次操作会在同一个进程里把它打开。

会话

日常说法里的「会话」有两层：

• 浏览器会话：环境分区里的 Cookie 与 localStorage，关窗后仍在。
• Agent 会话：你和客户端的那段对话，BrowserPilot 不保存。

文档里说「会话」时，一般指第一层；说「任务」时，指第二层。

控制状态：谁在操作

状态	页面	含义
agent	遮罩 + 「接管」	Agent 正在操作；人点一下交还
handoff	无遮罩，顶部提示	等人完成一步；下一步目标出现时重新上锁
shared	无遮罩	人和 Agent 同时操作；任务不暂停

page_lock 强制上锁，page_unlock 放开，page_handoff 进入交接。工作流里的「交接」节点等价于 page_handoff，会等下一个目标出现，最长 10 分钟；下一个节点没有定位时会立即重新上锁。

为什么这样分

• 登录放进环境：登录是状态，不是步骤。把它从对话里拿出来，换账号只需换环境，工作流不用改。
• 步骤存成工作流：重复操作不该每次让模型重新想。图是确定的，跑一次调用就够。
• 运行留记录：失败要能定位。节点、错误、截图、HAR 都在一条记录里。
• 控制状态显式化：人和 Agent 都可能在同一页上操作，必须有一个字段说清楚现在是谁。

下一节看界面：界面一览。