awlevin/typesafe-computer-use 来源: https://github.com/awlevin/typesafe-computer-use

typesafe-computer-use 通过你输入的简单英文指令驱动一台Mac完成目标，每一步的成本约为五十分之一美分。它从不向大型模型发送截图，而是通过确定性方式读取屏幕，询问一个小型分类器接下来该执行哪个操作，仅在真正需要自由文本输入的字段中才调用文本生成模型。

clicker "go to techcrunch and take me to the checkout page for the cheapest tickets to their next upcoming event" --act

为何前沿模型计算机使用功能强大但昂贵：每一步都发送截图并等待数秒以获取计划。

大多数步骤并不需要一个计划。它们只需要从一个简短列表中快速、低成本地做出一个选择，并附带一个可用于条件判断的置信度数值。

TypeSafe (https://docs.typesafe.ai) 正是提供这样的服务：一个决策模型，能在几百毫秒内回答一个针对最多255个选项的Choice请求，返回完整的概率分布和经过校准的置信度，并且输出令牌免费。

本项目是一个围绕该模型构建的计算机使用循环。

在相同截图和目标下测量，每次一步决策：

坦诚的注意事项：大型模型直接从像素中读取事件日期并独立进行比较。分类器则需要下文描述的日期解析功能。前沿模型免费完成的每一步推理，在这里都必须重建为确定性的状态。

安装

需要 macOS 14 或更新版本、Python 3.12 或更新版本、uv (https://docs.astral.sh/uv/)。

git clone https://github.com/awlevin/typesafe-computer-use
cd typesafe-computer-use
uv sync
cp .env.example .env  # 填入密钥

在“系统设置 > 隐私与安全性”中，为你的终端授予屏幕录制和辅助功能权限。没有前者，捕获的内容将是墙纸。没有后者，合成点击会被静默丢弃，且 --act 无法启动。

使用

uv run clicker "open the Playground"  # 干运行：一步，打印将执行的操作
uv run clicker "open the Playground" --act  # 驱动机器，最多100步
uv run clicker "log in" --act --steps 20 --delay 3  # 更长更慢
uv run clicker-inspect "any goal"  # 3-2-1，捕获，打开标注后的屏幕及载荷

请先清空终端。它位于屏幕上，因此其文本是OCR输入的一部分。

停止正在运行的任务。 在终端获得焦点时按 Ctrl-C，或从任何应用将鼠标猛甩到屏幕左上角。循环也会在遇到 done 或 none、置信度低于 --min-confidence（0.4）、连续两次无操作后，或达到 --steps 时自动停止。

答案生成。 当循环自行停止时，写手会读取它停止时的屏幕并打印结果：目标要求的信息，或者如果屏幕不包含该信息，则说明现状及下一步。若本应执行操作的干运行或中止的运行，则不会打印答案。

一个步骤的工作原理

screencapture ─► Vision OCR ─► 将行合并为块 ─► 丢弃重复目标的行
                                                    │
辅助功能 ─► 可操作元素（角色、标签、框），修剪至显示范围内，标记的可按压项保留为屏外控件 │
                                                    │
                                                    └─► 一个带编号的项列表，每项携带其来源
                                                    │
辅助功能 ─► 聚焦字段（角色、标签、占位符、值、框）
AppleScript ─► 前台应用及进程ID，活动标签页URL
时钟 ─► 本地日期和时间
dates.py ─► 在任何包含日期的块上标注 "dated 2026-10-13 (in 27 days)"，在其相邻块上标注 "near a line dated ..."
                                                    │
                                                    ▼
一次 TypeSafe 请求，三个 Choice，若包含屏外控件则为四个
┌────────────────────────────────────────────────────────────┐
│ kind : click_item | use_browser | type_text | scroll... │
│ item : 哪一项（仅用于 click_item）                      │
│ site : 哪个网站（仅用于 use_browser）                   │
│ offscreen : 哪个隐藏控件（仅用于 press_offscreen）      │
└────────────────────────────────────────────────────────────┘
                                                    │
                                                    ▼
确定性操作 ─► 等待 ─► 下一步

项携带了其来源：文本块为 ocr，应用声明的控件为 ax，两者同时找到同一项时为 ax+ocr。一个 ax 项在标准中读作 button 'Share' (top-right)，这样分类器就能区分真正的控件和一行文本。

将决策拆分为三个问题，可以将屏幕噪声排除在动作选择之外。构建此系统时发现的所有停滞，都源于两个含义相同的选项。置信度衡量的是集中程度，因此重叠的选项总是会被视为不确定。请确保动作集互斥。

OCR成本

视觉识别约占一个步骤的三分之二，其费用按文本量而非像素数计算，因此唯一真正的节省在于读取更少的屏幕内容。

• 裁剪。 每一步读取带有8点边距的前台窗口，加上相同列上方的菜单栏条带，并限制在显示范围内。桌面上和后台窗口中的文本对决策而言是噪声。将条带裁剪至窗口宽度是裁剪在全高窗口上生效的关键。代价是：时钟和窗口右侧的菜单附加项将不会被读取。它们仍然可以通过辅助功能树被点击。

• 重用。 捕获的图像与前一次捕获的1/8缩放版本，在256像素的块中进行比较。未改变的块保留上一步生成的行。改变的块被聚类成斑点，边和角视为相连，每个斑点成为一个独立读取的矩形。分散的变化是常见情况，比如时钟数字加上一处重绘，而一个跨越两者的矩形将横跨整个显示区域。每个矩形都会扩大，直到没有已知行跨越其边缘，因为裁剪穿过的行只会返回其可见部分；扩大后相遇的矩形会合并，超过四个时则按最近配对合并至四个。当变化块超过60%、区域累计矩形面积超过60%、或应用切换或窗口移动时，则直接读取整个区域。计时行会显示读取量及分块数：ocr 0.31s (22% of screen, 2 rects)。重放（--image）始终读取整个图像且从不重用，因此离线重放与原始运行匹配。

辅助功能树

OCR无法看到图标。辅助功能树可以，因此每一步还会遍历前台进程中带有标签的、屏幕上的控件。覆盖率不均匀，在一台Mac上的十个应用中测量：Finder 100%的屏幕控件带标签，Chrome 88%，Slack 85%，Notion 68%，Spotify 0%（其CEF外壳仅暴露三个窗口按钮，无其他）。终端将网格暴露为一个文本区域。因此AX是一个额外来源，而非替代。标签存在于 AXDescription（Web和Electron）、AXTitle（AppKit），或较短的 AXValue（其他情况）中。装饰性图片使用其周围控件的标签；列表行则从浅层的 AXStaticText 获取标签。框架信息可能不准确，因此遍历会严格修剪：

• 跳过任何实际框架不在显示范围内的子树（备忘录会报告向下200个屏幕的行，Chrome会将滚动出视口的节点停在上方）
• 跳过宽度或高度小于4点的任何节点（Chromium会将滚动出视口的网页节点限制为细条）
• 跳过 AXMenu 子树，它们是关闭菜单后面的成千上万个零尺寸项
• 跳过无名的 AXGroup 布局框，即使可按压
• 达到4000个节点或0.6秒时停止，并予以说明

此处测量的遍历：Finder 152个控件用时0.08秒，Chrome 172个控件用时0.59秒。辅助功能握手属性（AXManualAccessibility、AXEnhancedUserInterface）在此macOS上不受支持，因此不依赖它们。

屏外控件

AXPress 不需要元素可见。备忘录会选择停在显示区域下方数千点处的行，Chromium会将点击传递给一个因页面滚动而被限制为1像素细条的链接，而一个自动隐藏的Dock会从底部边缘下方5点处交出其所有37个项目。因此，相同的遍历会保留其修剪掉的、标记的、可按压节点，并将它们作为一个单独的上限列表提供，而不是混入项列表中：捕获中没有任何内容指向它们，鼠标点击会落在完全不同的地方。列表按角色和标签去重，删除可见项已有的标签，并在120个控件后停止，之后这些子树会像之前一样被修剪，因此遍历成本与以往相同。仅在列表非空时提供，作为一个 press_offscreen 动作加上一个 offscreen 问题，步骤日志会将其计在 ax= 旁边。拒绝即结束：没有像素可以回退，因此被视为无操作。遍历发现的内容取决于应用，且节点和时间上限首先对大树生效：备忘录和Chrome将所有4000个节点用于已在屏幕上的内容，并报告无隐藏项。

动作空间

自由文本的来源

分类器从不生成文本。写手模型在三个地方运行，每个都有一个小数据包和结构化回复：

• type_text 接收目标、最近的操作、聚焦字段的标签和占位符，以及字段附近的OCR行。它返回 {fill, text}。凭证字段返回 fill: false，不会输入任何内容。输入后，一个Noul会评估字段当前是否持有合理的值。低于0.5则清空字段。
• use_browser 并带 site: other 时接收目标并返回 {ok, url}。代码会拒绝任何不是带有主机名的干净https URL的内容。
• 答案生成，一次，在循环自行停止时。它接收目标、所有采取的操作、运行停止的原因、最后屏幕的文本以及捕获本身（因为OCR有时会误读字母并丢失布局）。它返回 {achieved, answer}，并被告知仅从屏幕获取答案。当操作使上一步的捕获过时，会先再次捕获屏幕。此调用使用 CLICKER_ANSWER_MODEL，一个比逐步写手更强的阅读模型。

密码永远不会被输入。请依赖浏览器的密码管理器或OCR可读取的SSO按钮。

运行文件夹

每次运行都会写入 runs/<timestamp>/，以便可以重放停滞并进行离线修复：

每个步骤也会记录其成本，因此慢的阶段一目了然：

timing: capture 0.31s screenshot 0.28s app 0.01s window 0.02s field 0.01s url 0.01s ocr 0.31s (22% of screen) ax 0.06s decide 0.21s act 0.05s total 0.95s

capture 涵盖其下的四次往返；当步骤未执行操作时，act 会被省略。

重放保存的捕获，如同实时运行，无需触碰屏幕：

uv run clicker "same goal" --image runs/<timestamp>/step-003-raw.png --app "Google Chrome" --url "https://example.com/"

代码结构

typesafe_computer_use/
    macos.py      唯一触及Quartz、AX、AppleScript的模块（平台适配器），包括用于可操作元素的有界遍历
    perception.py 捕获、OCR、读取区域和变更块缓存、块合并、目标回声过滤器、辅助功能项源，以及两者的合并
    dates.py      日期解析和 "in N days" 提示
    decide.py     状态、标准、三选一请求、Noul检查
    writer.py     写手模型、结构化回复、URL验证、最终答案
    actions.py    每个操作一个处理程序，每个返回一行历史记录
    runner.py     步骤循环、运行文件夹、停止规则、答案交接
    report.py     日志记录、标注截图、载荷转储
    timing.py     阶段计时器、计时行、运行摘要
    cli.py        `clicker` 和 `clicker-inspect`
tests/           纯逻辑：日期、合并、阅读顺序、回声过滤器、配置、决策、使用假树遍历树

Linux移植版将 macos.py 替换为xdotool和AT-SPI，并将Vision OCR替换为PaddleOCR或RapidOCR。树遍历本身通过可调用对象获取子节点、属性和动作，因此只有这三个绑定需要更改。其他部分不感知平台。

已知限制

• OCR只能看到文本，辅助功能树仅覆盖发布了树的应用。在终端、画布或Spotify中，仅图标的按钮两个来源都不可见。
• 两个相同的标签只获得一个粗略的区域提示并平分选票。
• 仅捕获主显示器。
• 在 --act 运行期间使用机器会与它争夺焦点和光标。
• 网站目录故意很小；写手覆盖其余部分。

开发

uv run ruff check . && uv run ruff format --check .
uv run pytest -q

CI在macOS上运行相同命令。参见 CONTRIBUTING.md。

许可证

MIT