| 1 | # 桌面浏览器 |
| 2 | |
| 3 | [English](DESKTOP_BROWSER.md) |
| 4 | |
| 5 | 桌面浏览器是 Reasonix 窗口内由用户与 Agent 共同操作的原生 Chromium 表面。网站在壳 |
| 6 | 拥有的 Electron `WebContentsView` 中渲染；Agent 的每项能力都经过 Go 桌面服务，因此 |
| 7 | 本地与远程 Agent、审批、取消、证据与操作记录共享同一实现。本文是浏览器面板、壳的 |
| 8 | 表面管理器、Go `BrowserExecutor` 与 Agent 可见工具之间的契约。背后没有壳的会话由 |
| 9 | [CDP 后端](BROWSER_CDP.zh-CN.md)提供同一批工具。 |
| 10 | |
| 11 | ```text |
| 12 | Agent 工具调用 ─▶ Go BrowserExecutor ─▶ ledger.reserve ─▶ host/browser.* ─▶ WebContentsView |
| 13 | ▲ │ │ |
| 14 | └── 结果 / 证据 ──────┴─────────── ledger.settle ◀──────────┘ |
| 15 | 用户在页面输入 ─▶ guest preload ─▶ 壳：epoch++ ─▶ desktop/event browser:takeover |
| 16 | ``` |
| 17 | |
| 18 | ## 表面与信任 |
| 19 | |
| 20 | - 应用窗口可信。网站视图不可信：sandbox 开启，context isolation 开启，无 Node |
| 21 | integration，无应用 preload，不能访问 `reasonix://`。它们唯一的 preload 只观察可信 |
| 22 | 用户输入以请求接管，不向页面暴露任何东西。 |
| 23 | - 分区：`persist:browser` 是同一 Reasonix 数据目录下共享的登录分区；`temp:<id>` 分区 |
| 24 | 只存在于内存，最后一个标签关闭即丢弃。远程 Serve 窗口与 MCP App 框架使用各自分区， |
| 25 | 从不与浏览器分区共享。 |
| 26 | - 壳中的 `BrowserSurfaceManager` 拥有创建、可见性、边界、焦点与销毁。React 面板提交 |
| 27 | 布局矩形，壳按窗口校验后应用。任何应用覆盖层（对话框、菜单、命令面板）设置单一 |
| 28 | 覆盖状态，隐藏所有原生网站视图，页面永远不能盖住应用。 |
| 29 | - 一个任务拥有自己的标签。标签携带 `{tabID, taskID, sessionID, epoch, partition}`； |
| 30 | 切换可见标签不会把运行中的计划转到别的标签。 |
| 31 | |
| 32 | ## 面板 |
| 33 | |
| 34 | 右侧工作区加入浏览器面板：任务内标签栏、地址栏、前进/后退、刷新、缩放、可重试的 |
| 35 | 加载错误、下载列表、DevTools、响应式视口、元素选择、页面诊断和录制。标签元数据保存 |
| 36 | 到 Electron userData 下的 `browser-tabs-v1.json`，包含任务/会话、地址、标题、顺序和 |
| 37 | 视口偏好；不保存 grant、表单、DOM ref 或未完成操作。启动恢复占位标签，明确访问后 |
| 38 | 才加载；临时标签不恢复。本地 HTML 保存原文件引用，重新授权后生成新预览地址，不 |
| 39 | 持久化旧 token URL。现有操作日志保持不变。每窗口最多 32 个逻辑标签，不自动驱逐。 |
| 40 | |
| 41 | 本轮运行时升级、验证证据和发布限制见 |
| 42 | [浏览器升级验收记录](BROWSER_RUNTIME_UPGRADE_ACCEPTANCE.md)。 |
| 43 | |
| 44 | 本地 `.html` / `.htm` 文件默认在该面板运行。聊天文件链接、成果卡片、文件树与 Agent |
| 45 | 按需预览共用一条链路：按文件来源重新授权，生成带随机令牌的 loopback HTTP URL，并 |
| 46 | 绑定到当前任务和会话的标签；“查看源码”仍进入文件面板，“在外置浏览器打开”仅由用户 |
| 47 | 显式触发。刷新会重新授权并替换令牌，关闭标签、会话销毁或离开文件 URL 会解除绑定。 |
| 48 | 用户接管时 Agent 不能刷新或另开副本绕过接管；用户点击刷新可以更新页面，但标签仍保持 |
| 49 | `human` 模式。 |
| 50 | |
| 51 | 这条文件链路服务于单文件和受现有静态预览策略支持的资源。需要模块构建、客户端路由或 |
| 52 | 本地 API 的项目继续由 Agent 通过终端启动或复用项目声明的开发服务器，再用 |
| 53 | `browser_open` 打开已确认的地址。SSH 文件首期仍使用原文件预览。 |
| 54 | |
| 55 | ## 浏览器控制设置 |
| 56 | |
| 57 | 设置中心的「浏览器控制」页管理下列开关，取值都保存在壳 userData 配置目录 |
| 58 | （`desktop-shell/`）下的 `browser-control.json`。 |
| 59 | |
| 60 | - **内置浏览器控制**（`controlEnabled`，默认开启）。壳通过 `desktop/browserControl` |
| 61 | 推送给 Go，Go 在构建会话时读取：新会话完全不注册浏览器工具，正在运行的会话保持 |
| 62 | 启动时的工具集。 |
| 63 | - **忽略证书校验**（`ignoreCertificateErrors`，默认关闭）。只对访客会话放宽 |
| 64 | `setCertificateVerifyProc`：访客视图工厂准备分区时应用，开关变化时对全部存活的访客 |
| 65 | 会话重新应用，无需重启。应用窗口与远程窗口仍使用 Chromium 默认校验。 |
| 66 | - **清除内置浏览器缓存**：清除 `persist:browser` 的 HTTP 缓存以及 Cache Storage、 |
| 67 | Service Worker 和着色器缓存，保留 Cookie 与本地站点数据。 |
| 68 | - **清除全部浏览器数据**：额外清空所有存储类型，内置浏览器中的所有站点都会退出登录； |
| 69 | 内存态 `temp:<id>` 分区不受影响。 |
| 70 | - **导入 Chrome 登录状态**：读取最近使用的 Chrome Profile 的 `Cookies` 数据库，逐条 |
| 71 | 解密（macOS 用登录钥匙串中的 `Chrome Safe Storage`，Linux 用众所周知的 `peanuts` |
| 72 | 口令，Windows 用 `Local State` 中的 DPAPI 主密钥）后写入 `persist:browser`。已过期 |
| 73 | 的 Cookie、App-Bound（`v20`）取值与解密失败的行计入跳过；不会读取密码。 |
| 74 | |
| 75 | ## Agent 能力 |
| 76 | |
| 77 | 工具通过现有 capability 注册表注册为一个 `browser` 能力，包含下列操作。每个写操作 |
| 78 | 都走正常审批策略（`ask`、`allow`、`deny`）、正常取消上下文与证据轨迹；没有独立的 |
| 79 | 浏览器审批系统。 |
| 80 | |
| 81 | | 工具 | 读/写 | 用途 | |
| 82 | | --- | --- | --- | |
| 83 | | `browser_tabs` | 读 | 列出任务标签及 URL、标题、加载状态 | |
| 84 | | `browser_open` | 写 | 在共享或临时分区打开标签到某 URL | |
| 85 | | `browser_preview` | 写 | 按需授权本地任务文件，并在任务绑定标签中运行或刷新 | |
| 86 | | `browser_navigate` | 写 | 导航绑定标签（URL、后退、前进、刷新） | |
| 87 | | `browser_snapshot` | 读 | 带元素引用的结构快照 | |
| 88 | | `browser_screenshot` | 读 | 视口或元素的 PNG，作为图像返回 | |
| 89 | | `browser_click` | 写 | 点击引用元素（在其中心派发可信鼠标事件） | |
| 90 | | `browser_type` | 写 | 用可信键盘事件向引用元素输入文本；可选提交 | |
| 91 | | `browser_press` | 写 | 按键或组合键 | |
| 92 | | `browser_scroll` | 写 | 滚动视口或元素 | |
| 93 | | `browser_select` | 写 | 选择下拉选项 | |
| 94 | | `browser_upload` | 写 | 把任务文件附加到文件输入 | |
| 95 | | `browser_download` | 读 | 等待或列出标签的下载 | |
| 96 | | `browser_close` | 写 | 关闭标签 | |
| 97 | |
| 98 | `browser_preview` 只在支持共享文件预览服务的本地桌面执行器上通过 |
| 99 | `use_capability` 发现；它不进入常驻工具定义，也不向系统提示注入 URL、端口或标签状态。 |
| 100 | |
| 101 | 快照格式：在主框架及每个可达框架的隔离世界中生成的无障碍风格树 |
| 102 | （`role "name" [state] ref=e12`）。引用绑定 `{tabID, frameID, documentVersion}`；导航、 |
| 103 | 页面替换或接管使所有早先引用失效，带过期引用的动作返回 `not_executed: stale reference` |
| 104 | 而不是猜测。输入与点击由壳以可信输入事件派发，从不给元素赋值，因此 React 受控输入、 |
| 105 | 自定义控件与动态页面的行为与真实用户一致。 |
| 106 | |
| 107 | 截图与下载从不经过控制帧：壳把它们写入 Go 在请求中指定的任务临时目录并返回路径； |
| 108 | Go 通过现有通道把文件转成图像或文件结果。上传只读取任务拥有的文件；远程任务通过 |
| 109 | 现有 SFTP 传输与任务临时目录中转，远程路径永远不会被当作本机路径。 |
| 110 | |
| 111 | ## 所有权、接管与未知写入 |
| 112 | |
| 113 | - 授权 `{sessionID, taskID, runtimeGeneration, tabIDs, expiresAt}` 在任务开始使用浏览器 |
| 114 | 时由 Go 签发，并在服务重启、会话变化、连接世代变化或任务结束时撤销。壳拒绝授权 |
| 115 | 不是当前的 `host/browser.*` 调用。 |
| 116 | - 浏览器工具栏的“接管”按钮通过可信应用 IPC 立即将标签切为 `human` 模式并递增 epoch。 |
| 117 | 即使处于抑制 Agent 输入回声的 750 毫秒窗口内，显式接管仍立即生效；页面键盘、鼠标或 |
| 118 | 触控输入的自动检测在该窗口内仅尽力而为。旧 epoch 的待执行与排队动作被取消，Go 收到 |
| 119 | `browser:takeover`。“恢复”将控制权交回 Agent 并再次递增 epoch，要求重新读取页面。 |
| 120 | 登录页、验证码与 passkey 始终交由用户：标签处于 `human` 模式时 Agent 不能读取或操作它。 |
| 121 | - 每个写操作在壳执行前先在账本中预留 `{operationID, sessionID, generation, tabID, epoch, |
| 122 | documentToken, action, digest}`。壳报告 `executed` 或带原因的 `not_executed`；回复丢失、 |
| 123 | 崩溃或服务重启使操作保持 `unknown`。未知操作展示给用户，绝不自动重放；重复的 |
| 124 | `operationID` 永久被拒绝。 |
| 125 | - 网站视图渲染进程崩溃只取消该标签的动作，并以 `human` 模式重载最后的安全 URL。应用 |
| 126 | 渲染进程崩溃暂停所有浏览器动作，直到界面重新挂载。 |
| 127 | |
| 128 | ## 宿主调用 |
| 129 | |
| 130 | | 方法 | 用途 | |
| 131 | | --- | --- | |
| 132 | | `host/browser.grant` `revoke` | 安装或撤销授权 | |
| 133 | | `host/browser.tabs.list` `open` `close` `activate` `navigate` | 绑定授权的标签生命周期 | |
| 134 | | `host/browser.snapshot` | 标签结构快照，返回 `documentToken` | |
| 135 | | `host/browser.act` | 一个已预留的动作；返回 `{executed, reason, documentToken}` | |
| 136 | | `host/browser.screenshot` | 捕获到任务拥有的文件路径 | |
| 137 | | `host/browser.downloads` | 列出或等待标签的下载 | |
| 138 | | `host/browser.layout` | 应用面板矩形与覆盖状态 | |
| 139 | |
| 140 | 壳发出的事件：`browser:tabs`（标签列表变化）、`browser:takeover`（`{tabID, epoch, reason}`）、 |
| 141 | `browser:download`（进度）、`browser:crash`。 |
| 142 | |
| 143 | ## 远程 Agent |
| 144 | |
| 145 | 远程 Reasonix Agent 通过现有 SSH 连接与转发管理器，以承载同一 `BrowserExecutor` 契约的 |
| 146 | 受限 Host RPC 使用本机浏览器。授权绑定远程连接世代、会话与任务；断线、重连或切换会话 |
| 147 | 即撤销。浏览器授权与 provider 代理凭据分开；没有共享 token。旧的远程 Serve 构建通过 |
| 148 | 能力协商不宣告浏览器，保留全部现有远程功能。 |
| 149 | |
| 150 | 线上形态是每台桌面一个 loopback HTTP broker。全新 Serve 的 bootstrap 把 |
| 151 | `REASONIX_BROWSER_BROKER` / `REASONIX_BROWSER_TOKEN`（仅进程环境）指向经反向转发的 |
| 152 | broker；被复用的 Serve 在桌面轮换路由后通过 `POST /browser/broker` 重新指向。broker 为 |
| 153 | 每个主机连接世代铸一个随机 bearer token——注册新世代即替换主机旧 token——鉴权后才把 |
| 154 | `/v1/browser/<method>` 派发给 `browser.Executor`。每个请求携带 |
| 155 | `X-Reasonix-Browser-Session`；broker 把它解析到唯一展示该会话的桌面标签，其余一律以 |
| 156 | `no_grant` 拒绝。壳在桌面写出的截图与下载经现有 SFTP 通道中转进远程主机的每工作区 |
| 157 | 暂存目录（`~/.reasonix/browser-relay/<workspace>/`），serve 侧工具只读对它们而言是 |
| 158 | 本机的路径。带 broker 启动的 Serve 在 `/auth/token` 握手的 |
| 159 | `X-Reasonix-Serve-Capabilities` 响应头中宣告 `browser`。 |
| 160 | |
| 161 | ## 验收 |
| 162 | |
| 163 | ### 右侧面板尺寸 |
| 164 | |
| 165 | 没有已有宽度偏好时，右侧面板首次打开以窗口宽度的 45% 为目标。 |
| 166 | 普通并排布局最小宽度为 300px、最大不超过窗口的 70%，并优先为聊天保留 |
| 167 | 400px；空间不足时使用覆盖展示。拖动或键盘调整继续沿用已有的本机宽度 |
| 168 | 存储格式，关闭、重开和重启可恢复。窗口缩小时的临时压缩不会写回偏好。 |
| 169 | |
| 170 | 窗口小于 1024px 时左侧导航默认折叠，可手动展开；跨越断点后恢复自动规则， |
| 171 | 宽窗口的导航偏好保持不变。小于 768px 时右侧面板占满应用内容区域，保留 |
| 172 | 顶部窗口操作和面板关闭入口；关闭后回到聊天，放大窗口后恢复并排宽度。 |
| 173 | 文件、概览和内置浏览器共用这套规则。HTML 内部排版仍由页面 CSS 决定， |
| 174 | 面板不会自动缩放或改写固定宽度的网页。 |
| 175 | |
| 176 | 验证：`pnpm exec tsx src/__tests__/responsive-dock.test.ts` 和 |
| 177 | `pnpm test:dock-responsive-browser`。后者使用真实应用组件和模拟会话验证尺寸、 |
| 178 | 拖动、关闭重开及刷新恢复。运行 `node bench/responsive-dock.mjs --electron` |
| 179 | 可在独立临时配置的 Electron 窗口中执行同样检查，使用实际原生窗口调整尺寸。 |
| 180 | 这些尺寸检查不覆盖 Agent 操作 HTML 页面本身的执行闭环。 |
| 181 | |
| 182 | iframe、动态 DOM、受控输入、弹窗、上传与下载、导航历史、临时分区、共享与隔离登录； |
| 183 | 审批前接管、审批后派发前接管、执行后回执丢失、崩溃后重启、重复 operation ID；远程 |
| 184 | SSH 断连、世代变化、过期授权、跨会话误路由。[迁移记录](DESKTOP_SHELL_MIGRATION.zh-CN.md#验收门槛) |
| 185 | 中的真实任务关闭本阶段。 |
| 186 |