Computer Use
从任务，到可核实的结果。

文件对象、文件名、MIME、大小；目标网站、项目和操作意图。

任务：使用我的网站 A 账号，将 report.pdf 上传到项目 B 的文档区，并返回文件链接。

附件：report.pdf
类型：application/pdf
位置：用户设备

[P00]

Bot 也可使用连接电脑中的已授权路径，不要求所有文件先进入网页聊天。 [S07]

ArrayBuffer / Uint8Array、SHA-256、文件元信息。

字节：<原始 PDF>
摘要：<原文件 SHA-256>
元信息：{"name":"report.pdf","mimeType":"application/pdf","size":123456}

[P00]

摘要核验是此案例的文件完整性规划，不代表任意 CopyToBox 调用都自动完成全链路验收。 [S07]

请求体为 PDF 原始字节，摘要放在查询参数。

POST /api/blobs?sha=<SHA-256>
Content-Type: application/octet-stream

<report.pdf 原始字节>

响应示意：{"blobId":"blob-demo","size":123456}

[P00]

/api/blobs 属于网页参考接入；不是 Bot 的通用文件上传协议。Bot 可通过 CopyToBox 拉取字节。 [S07]

持久字节、blobId、长度、摘要和用户关联信息。

用户设备的原字节 → 助手的持久文件存储

网页保留：
{"name":"report.pdf","mimeType":"application/pdf","size":123456,"blobId":"blob-demo"}

[P00]

本例的 Postgres / 文件存储是参考选型，不将其当作 Bot 当前数据库部署证明。 [S08]

任务文字、会话、clientTurnId、模型选择和 attachments 元数据。

POST /api/turn
Content-Type: application/json

{"text":"上传 report.pdf 到网站 A 的项目 B 文档区","clientTurnId":"turn-demo","attachments":[{"name":"report.pdf","mimeType":"application/pdf","size":123456,"blobId":"blob-demo"}]}

[P00]

在 Bot 中主代理负责组织任务，可委派 browserUse 或 computerUse 子代理。 [S01]

Run 状态、文字活动、partial 回复和终态；不承载本方案的连续桌面画面。

GET /api/runs/run-demo/events

event: partial
data: {"partial":"正在准备 report.pdf 的执行环境…"}

网页重连后读取同一 Run 的持久状态。

[P00]

SSE 属于网页参考接入；Bot 的消息交付与转录链路需按桌面/Host 架构理解。 [S08]

镜像、容器标识、网络、回环映射和用户卷配置。

智能助手 → Docker CLI → unix:///var/run/docker.sock

容器：用户隔离的沙箱
服务：microvm-agent :8080
宿主入口：127.0.0.1:<映射端口>
持久卷：用户工作目录

[P00]

Bot 使用自身 Box 连接与生命周期；独立镜像默认单主桌面，而非完整来宾操作系统。 [S09]

受控任务路径、PDF 的 Base64；解码后的原始字节。

POST /write
Content-Type: application/json

{"path":"/root/workspace/.agent-turn/demo/inbox/report.pdf","b64":"<PDF 的 Base64>"}

沙箱得到：report.pdf 原始二进制文件

[P00]

Bot 可调用 CopyToBox；Box 执行服务不是此示例的 microvm-agent /write。 [S07]

原文件引用、沙箱路径、长度、摘要；文件元数据入持久存储。

原文件：blob-demo
沙箱副本：/root/workspace/.agent-turn/demo/inbox/report.pdf

长度一致：true
SHA-256 一致：true
产物引用：artifact-demo

[P00]

browser_upload 会暂存文件并建立摘要、字节数等产物引用；不能只凭同名路径判断身份。 [S04]

受控命令或专用工具参数；结构化执行结果，不包含登录密钥。

运行模式示意（不是部署命令）：

automation
  Playwright + headless Chromium

takeover-ready
  Playwright + headed Chromium
  Linux：Xvfb + VNC + websockify + 授权代理
  完整 VM：使用已验收的来宾桌面接入方式

两种模式均需绑定 userId / runId / environmentId。

[P00]

技术上可用无头浏览器；但该 Bot 基线的 browser_* 与 Computer 装配都要求 Box 的桌面能力。 [S01]

CDP JSON 命令；浏览器进程和上下文标识。

// 示意：此函数只负责连接，不负责授权。
const browser = await chromium.connectOverCDP(cdpEndpoint);
const contexts = browser.contexts();

// 后端还须按登记信息核对目标 context / page。
// 不将 contexts[0] 本身当作账号或任务身份证据。

[P00] [D01] [D02]

Bot 浏览器工具绑定 Box、窗口与 view，不把新建空 context 当作恢复原会话。 [S04]

导航指令走 CDP JSON；网页与 API 响应走网站 HTTPS。

Playwright → 浏览器：导航到 https://site-a.example/
浏览器 → 网站：HTTPS GET /
网站 → 浏览器：HTML、JS、CSS、图片和 API 数据

网站域名为示意，占位地址不发起真实请求。

[P00] [D01] [D02]

由 browserUse 使用 browser_navigate；实际业务请求由 Box 中浏览器发出。 [S04]

DOM / 可访问性信息、控件定位信息、工具文字结果。

{"url":"https://site-a.example/projects/B","title":"项目 B","elements":[{"role":"button","name":"上传文件","count":1},{"role":"heading","name":"文档"}]}

链路：CDP JSON → 程序输出 → HTTP JSON → 模型工具文字

[P00]

browser_snapshot 返回与当前快照关联的元素引用；页面变化后需要新观察。 [S04]

单张 PNG / JPEG、截图尺寸和文件引用；模型收到图像内容块。

PNG 截图 → /read 返回 b64 → 智能助手解码保存

模型输入示意：
{"type":"image","mimeType":"image/png","data":"<PNG 的 Base64>"}

供应商最终格式由模型适配器转换。

[P00]

网页截图与桌面截图不同；X11 执行器生成 WebP。所选 Provider 是否收到图像需实测。 [S03]

RFB 帧缓冲区域更新；经 WebSocket 传递二进制远程桌面消息。

画面方向：
Chromium → Xvfb
  → X 显示访问 / 画面采集 → VNC
  → RFB / TCP → websockify
  → 授权代理 → RFB / WSS → noVNC

模型截图另走图像工具；桌面不向模型逐帧发送。

[P00]

noVNC 供用户查看/接管；Agent 的 Computer 动作直接走执行资源与 X11，不必穿过查看器。 [S03]

登录状态、当前账号可见标识、项目访问情况；不返回原始 Cookie。

{"signedIn":true,"accountMatches":true,"projectAccessible":true}

智能助手的会话 Cookie ≠ 网站 A Cookie
用户自己电脑里的网站 Cookie ≠ 沙箱浏览器里的 Cookie

[P00]

模型 Provider 登录与业务网站登录不同；本页不要求复制 Cookie 或读取认证文件。 [S08]

必须的会话与认证信息；可选 RFB 键鼠输入。最终登录请求由浏览器通过网站 HTTPS 发出。

无 GUI 路径：已有获准会话，或受控认证通道 → Chromium → 网站 HTTPS
可选 GUI 路径：noVNC 键鼠 → RFB / WebSocket → VNC / Xvfb → 同一 Chromium

有效会话必须确认；人工接管方式按需开启。

[P00]

有 WebAuthn 桥接源码；browser_fill 的 secret-slot 执行则明确未安装 resolver，不能宣称通用自动填密已完成。 [S04]

认证证据、控制会话状态、当前操作许可。

无 GUI：完成认证 → 核实账号 / 项目 / 授权 → 自动执行
可选接管：完成认证 → 释放人工控制 → 核实并恢复自动执行

[P00]

统一仲裁 browserUse、computerUse 与人工输入是工程验收要求；浏览器单写者或 X11 内部串行并不单独证明跨通道互斥。 [S03]

URL、项目 ID、文档区域、按钮角色与唯一性。

页面证据：
域名：site-a.example
项目标识：B
区域：文档
上传控件：role=button, name=上传文件, count=1

[P00] [D01] [D02]

优先 browser_snapshot + ref；网页视口坐标与 Computer 桌面坐标不能互换。 [S04]

动作 ID、原文件摘要、账号、项目、目录、已知文档 ID 与观察条件。

动作记录示意：
{
  "actionId": "upload-demo",
  "runId": "run-demo",
  "fileSha": "<SHA-256>",
  "account": "<已确认账号>",
  "projectId": "B",
  "previousDocumentIds": ["old-demo"],
  "state": "prepared"
}

持久准备 → 建立监听 → 领取执行权
→ 记录 dispatching → 触发上传

上述状态与互斥为工程要求，不表示已有实现。

[P00]

Bot 有规范化摘要、审查及浏览器回执接线；本例完整业务幂等与重启恢复仍需按网站验收。 [S04]

沙箱文件路径和浏览器文件输入；实际文件字节在沙箱本地。

async function chooseFile(page, filePath, mode) {
  if (mode === "input") {
    await page.getByLabel("上传文件").setInputFiles(filePath);
    return;
  }
  const chooserPromise = page.waitForEvent("filechooser");
  await page.getByRole("button", { name: "选择文件", exact: true }).click();
  const chooser = await chooserPromise;
  await chooser.setFiles(filePath);
}

page：已认证的受管页面
filePath：步骤 9 已核对的沙箱绝对路径

[P00] [D01] [D02]

browser_upload 需要 driver v3、/workspace 下的绝对路径；非空文件上限 16 MiB。 [S04]

FileList 元信息、页面上传状态、明确的提交操作。

输入证据：name=report.pdf, size=123456

网站策略：
自动上传 → 等待已有上传回执
显式提交 → 唯一按钮可操作后点击一次

不得因为等待超时自动切换成第二次 GUI 点击。

[P00] [D01] [D02]

browser_upload 只报告控件接受情况，服务器受理与文档可用性必须另行核对。 [S04]

PDF 字节、网站会话、CSRF 或站点要求的上传参数。

POST https://site-a.example/<真实上传端点>
Cookie: <浏览器管理的网站会话>
Content-Type: multipart/form-data; boundary=<示意>

文件字段：report.pdf 原始字节
项目参数：<网站实际要求>

也可能由网站采用直传对象存储或分块上传。

[P00]

网站上传走浏览器与目标服务的业务连接；不把 CDP、RPC 或 RFB 称为 PDF 的业务上传协议。 [D01]

新文档 ID / 版本、文件信息、目标目录、文件链接与证据来源。

{"documentId":"doc-new-demo","projectId":"B","fileName":"report.pdf","status":"ready","url":"https://site-a.example/projects/B/documents/doc-new-demo","evidence":"本次回执与文档详情一致"}

[P00]

browser_session_status 查询执行/恢复状态；网站文档 ID 与 ready 状态是另一层业务证据。 [S04]

必须的动作状态、账号与项目、文档 ID / 版本和 URL；可选截图字节与受控引用。

Postgres：actionId、runId、结果状态、文档 ID、URL、证据引用
文件存储：证明截图原字节

unknown：保留操作意图与已知外部证据；等待核对

[P00]

状态文档仍将 Browser Flow 生产闭环列为未完成；底层回执代码不等于业务恢复已全面验收。 [S13]

累积回复、文件链接、截图引用；按需读取 PNG / JPEG；另有实时画面。

SSE 文字：
event: partial
data: {"partial":"已将 report.pdf 上传到项目 B 文档区。链接：https://site-a.example/projects/B/documents/doc-new-demo"}

证明图：HTTP GET <受控截图文件引用>
实时桌面：独立 RFB / WebSocket 连接

[P00]

可返回网站链接；Box 本地产物用 SendMessage 显示为附件，或用 CopyFromBox 放到用户磁盘。 [S07]

控制权释放、连接关闭、进程退出结果和环境保留策略。

结束：本次控制权、任务监听、临时资源
按策略保留：用户资料、原文件证据、任务回执

stop / keepWarm：按生命周期保留
destroy：可能删除卷，不用于普通任务收尾

[P00]

Bot 的账户槽、容器和数据卷有独立生命周期；普通收尾不得据此推断可删除用户数据。 [S08]