> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/native-tools/browser-and-computer.md).

# 浏览器与电脑控制

读取并驱动真实浏览器和真实桌面：辅助功能快照、元素引用、在付款页面停止的有限任务，以及为每一步挑选决策的小模型。

当代理需要像人一样使用电脑，通过打开页面、阅读屏幕、点击按钮或输入短语时，这些工具就派上用场。桌面和浏览器控制都来自一个可加载模块 TinyComputer。它会在首次使用时下载。

## 两个界面，一个模型

桌面和浏览器会生成同一种“屏幕”：一个人可以交互的事物的紧凑列表。每个项目都有角色、名称、值、状态、支持的操作，以及它所在框的标签。该列表最多包含 254 个控件。两个界面提供同一小组操作（点击、输入、勾选、取消勾选、展开、折叠、滚动、等待、按键），因此代理只需学习一套词汇。

元素通过引用来定位，绝不用坐标或 CSS 选择器。像 `@s8f3k2p9:e1` 这样的桌面引用与生成它的快照绑定。对它执行操作，要么会找到所描述的元素，要么会因引用失效而报错，提示代理重新查看。它绝不会点击自那以后移动到那个位置的其他东西。浏览器引用在重新绘制后仍然有效，因为它们是只要元素还在页面上就持续存在的标记。

## 浏览器

浏览器是真实的 Chrome 或 Chromium，通过模块内置的库经由 Chrome DevTools Protocol 驱动。Chrome 作为独立进程运行，但它和模块之间没有任何中间层：没有驱动二进制、没有本地 HTTP 桥，也没有第二个 OpenHuman 进程。

* **打开** 一个会话。你可以启动一个新的浏览器（无头或有头），也可以附加到你已经在运行的 Chrome。附加很重要，因为许多网站会拒绝新的自动化浏览器，但会向你自己的浏览器提供服务。任务结束时，附加的浏览器只会断开连接，绝不会关闭。
* **快照** 页面。默认模式， `sight`，会运行一个小型页面内脚本，像人一样读取页面：真实的链接、按钮和字段，以及任何带有指针光标、点击处理器或 Tab 停止点的内容。它会丢弃隐藏、零大小、透明和已禁用的项目。它会把折叠线以下的项目标记为屏幕外，把对话框后面的项目标记为被遮挡。当它无法读取页面时，会回退到可访问性树，且 `感知：“tree”` 强制使用树。
* **执行**：点击（可选在新标签页中）、填写、输入、按键、选择、勾选、悬停、滚动、等待、读取和返回。
* **读取** 页面内容，可作为文本、Markdown 或序列化 DOM，然后 **评估** JavaScript。
* **下载**：列出浏览器的下载事件并等待文件完成。仅凭页面快照无法证明文件已完成下载。

截图绝不会以内联形式返回。回复会携带一个句柄，代理按块读取，完成后释放。

点击、输入、按键和其他有后果的操作会先在聊天中请求你的批准。计划任务无人可询问，因此默认情况下它只能打开和读取页面。操作员可以让 cron、后台以及免审批的工作流轮次通过 `[browser] unattended_actions`。参见 [Linux 和 Docker 上的 TinyComputer 浏览器](/openhuman/zh/kai-fa/tinycomputer-docker.md#4-unattended-actions).

会话是有上限的。该模块最多同时允许 8 个。OpenHuman 在每个对话线程中最多保留 6 个，并有 30 分钟空闲超时，因此长对话会复用一个浏览器，而不会每轮都新开一个。会话可以限制为一组来源。

## 桌面

桌面控制读取操作系统的可访问性树，这是屏幕阅读器使用的同一接口。它覆盖正在运行的应用、窗口、显示器、通知中心条目、剪贴板和截图。

桌面控制目前仅适用于 macOS。Windows 桌面控制尚不支持；在 Windows 上请使用浏览器。Linux 不受支持（见下表）。

操作通过可访问性 API 进行，而不是通过合成输入。默认情况下，它们不会抢占焦点、移动你的光标或触碰剪贴板，因此你使用机器时任务也可以继续运行。对于需要这些的应用，也提供有头模式和真实鼠标及按键事件，但这只是例外。

对于密集型应用，骨架快照只停留在三层，并返回结构而不含叶子细节。这就是数万 token 与几百 token 之间的区别。

## 任务

在这些基础之上，是一个有边界的任务循环。你描述结果，模块规划步骤，然后一个小型决策模型（[Jev](/openhuman/zh/kai-fa/jev.md)）来决定每一次点击。任务启动后会立即返回一个状态，代理轮询并响应：

| 状态                | 含义                           |
| ----------------- | ---------------------------- |
| `运行中`             | 进行中。                         |
| `需要输入`            | 没有你就无法填写的字段。                 |
| `需要批准`            | 不可逆步骤。只有明确批准才能执行。            |
| `需要人工介入`          | 验证码、一次性密码、双重验证或登录。没有任何模型能通过。 |
| `需要计划`            | 未配置规划器时的纯文本说明。               |
| `检查点`             | 故意停止，页面保持打开。                 |
| `完成`, `失败`, `已取消` | 最终状态。                        |

每个任务都遵循两条规则：

* **到达付款页面时，任务总会停止。** 它会变成一个无法继续的检查点，页面保留给人工处理。代理不会付款。
* **秘密值绝不会进入模型。** 你标记为秘密的事实会以 `${name}` 模板形式共享。规划器、决策模型和救援模型只能看到名称，实际值会在本地输入到字段中。

页面和屏幕文本被视为数据，绝不是指令。安全规则是普通代码，而不是模型判断。

## 代理工具

| 工具                 | 作用                                                                                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `浏览器`              | 以上所有功能都通过一个 `动作` 参数： `打开`, `快照`, `读取页面`, `点击`, `填写`, `输入`, `获取文本`, `获取标题`, `获取 URL`, `等待`, `按键`, `悬停`, `滚动`, `是否可见`, `查找`, `任务`, `继续任务`, `取消任务`, `确认待处理项`, `列出下载`, `等待下载`, `关闭`. |
| `浏览器打开`            | 打开一个 URL 并返回一个会话。                                                                                                                                                                |
| `列出桌面应用`, `列出桌面窗口` | 哪些程序正在运行，以及它们在哪里。                                                                                                                                                                |
| `启动桌面应用`           | 启动一个应用。                                                                                                                                                                          |
| `桌面快照`, `桌面查找`     | 读取屏幕，或在屏幕上查找某个东西。                                                                                                                                                                |
| `桌面目标`, `继续桌面目标`   | 运行一个桌面任务并处理其中的停止点。                                                                                                                                                               |

不可逆步骤会经过 OpenHuman 的 [批准门控](/openhuman/zh/gong-neng/approval-gate.md)，并绑定到确切动作和 URL 的摘要。如果未安装批准门控，则该动作会被拒绝。

## 平台支持

| 平台      | 桌面                                            | 浏览器 |
| ------- | --------------------------------------------- | --- |
| macOS   | 是。需要“辅助功能”权限，截图还需要“屏幕录制”权限，而打开通知中心则需要“自动化”权限。 | 是   |
| Windows | 尚未支持                                          | 是   |
| Linux   | 否                                             | 否   |

首次读取之前会进行权限检查。由未授权进程调用可访问性 API 通常会返回空树，而不是错误，这看起来就像一个没有按钮的应用。缺少权限时会返回带名称的拒绝信息，说明需要更改哪个设置。

Linux 不受支持。模块注册表没有发布 Linux 版本，因此那里既没有桌面控制，也没有浏览器自动化，尽管浏览器引擎本身本可以运行。

## 设置

**连接 > 电脑控制** 其中包含全部内容：模块状态和契约版本、决策模型（Jev、OpenJEV 或 Levanto Sage）以及其计费所走的路径、规划器和救援模型，以及浏览器部分（可执行文件路径、感知模式和允许的域）。

`[desktop] approvals_enabled` 默认值为 `false`。它只控制一件狭窄的事：模块在桌面目标执行过程中的自身确认停顿。关闭时，核心在模块重新观察并重新验证确切目标后会自动继续。开启时 `true`，该停顿会显示为一张批准卡。它不会削弱 [批准门控](/openhuman/zh/gong-neng/approval-gate.md)。不可逆步骤仍然需要批准，并且如果没有安装门控就会被拒绝。桌面目标确认是一次性的，并在 10 分钟后过期。

## 适用场景

* 驱动没有 API 且没有 [原生集成](/openhuman/zh/gong-neng/integrations.md).
* 多步骤的 UI 流程，其中每个快照都会显示下一个要操作的元素。
* 在聊天中自动化本地应用。

## 另请参阅

* [网页抓取器](/openhuman/zh/gong-neng/native-tools/web-scraper.md)：当你只需要文章，而不是整个页面时。
* [Jev](/openhuman/zh/kai-fa/jev.md)：负责选择每一步的决策模型。
* [批准门控](/openhuman/zh/gong-neng/approval-gate.md)：哪些会被搁置，以及在未安装门控时会发生什么。