typesafe-computer-use（项目内简称jev）是一个用"分类器驱动"的 AI 电脑操作工具：你说一句英文目标，它就能像人一样操作 Mac，而每一步的成本只有约$0.0002。它"看懂"屏幕的方式非常特别——不靠大模型盯着截图硬猜，而是靠一条五步决策循环：先确定性地读屏（OCR + 辅助功能树），再由代码补齐"事实"，然后向 TypeSafe 分类器发一次请求回答三个选择题，确定性地执行动作，最后在分类器停步时由写作模型（writer）接管读屏作答。

下面完整拆解这条循环的每一步。

上图为项目测试夹具中的一张真实桌面截图：左侧是 Chrome 书签页，右侧浮着一个"Restore pages?"气泡弹窗——这正是一条"分类器需要看懂的场景"：页面上的文字由 OCR 读，而气泡里的 "Restore" 按钮只有辅助功能树能可靠给出，五步循环会把两者合并成同一份编号物品清单。

为什么不用大模型，而是"五步循环"？

传统的前沿模型 computer use 每一步都要把整张截图发出去、等上几秒再拿到一个"计划"。但项目作者发现：大多数步骤根本不需要计划，只需要从一短名单里快速、便宜地选一个动作，并给出可卡阈值的置信度（来源：README.md）。

TypeSafe 提供的正是这种"决策模型"：对最多 255 个选项给出完整概率分布，几百毫秒内返回，输出 token 免费。于是整个项目被设计成一条围绕分类器的循环：

分类器负责选，代码负责算事实，写作模型只负责写自由文本。

官方给出的实测对比（同一张截图、同一个目标）：

代价也很诚实：大模型能"免费"从像素里读出日期并比较，而这条循环必须用代码把这些推理重建为确定性状态。这正是第二步存在的意义。

五步决策循环总览 🔄

官方文档 docs/how-a-step-works.md 用一张流程图描述了完整走法，核心就五步：

1. 感知（Perceive）：对最前窗口做 Vision OCR，同时遍历辅助功能树（Accessibility Tree），两者合并成一份带来源标记的编号物品清单
2. 补事实（Enrich）：代码在状态里加入日期偏移、重复标签所在的行、当前聚焦输入框、当前 App 与 URL、以及"这个屏幕已经试过哪些动作"
3. 决策（Decide）：一次 TypeSafe 请求，回答三个Choice——做什么类型的动作（kind）、点哪个物品（item）、去哪个网站（site）
4. 执行（Act）：动作确定性地执行，循环等待，下一次截图是唯一证人
5. 接管（Hand-off）：分类器停步（done / 低置信度 / 卡死 / 步数用尽）时，writer 读屏作答，或交还一个 focus / question 让循环继续

下面逐步拆解。

第一步：感知——OCR + 辅助功能树双通道读屏 📸

这一阶段的关键思想是**"结构化优先于像素"**（见 VISION.md）：先读能读到的结构，OCR 只是兜底。

OCR 只读"该读的"

Vision OCR 约占一步时间的三分之二，且按文本量计费，所以省钱的唯一办法是少读屏幕（docs/how-a-step-works.md）：

• 裁剪（Crop）：只读最前窗口 + 同列的菜单栏条带。桌面和后台窗口的文字对决策是噪音
• 复用（Reuse）：把新截图与上一帧按 256px 图块对比，未变化的图块直接沿用上一步的识别结果；只有变化的图块被聚成小矩形重新读

时间行会诚实地告诉你读了多少，例如：ocr 0.31s (22% of screen, 2 rects)。

辅助功能树补上 OCR 看不见的图标

OCR 看不见图标，辅助功能树能。每一步都会遍历最前进程，收集有标签、在屏内的可操作控件。覆盖率因 App 而异：Finder 100%、Chrome 88%、Slack 85%，而 Spotify 只暴露 3 个窗口按钮。所以项目把 AX 定位为"加成来源，而非替代"。

树遍历还很"狠"地做剪枝，防止被假坐标坑：

• 跳过真实 frame 不落在显示区内的子树
• 跳过小于 4pt 的节点
• 跳过AXMenu子树
• 上限 4000 节点或 0.6 秒，超了就明说

两条通道最后合并成一份编号物品清单，每项标注来源：ocr（文本块）、ax（控件）、ax+ocr（两者指向同一物）。OCR 从按钮上读到的符号（比如书签星☆、返回箭头←）会被当作那个控件的图标，避免"一个点击被拆成两个选项"。

第二步：代码补"事实"——模型不再猜 🧮

大模型读屏时的"免费推理"（日期比较、字段是否聚焦、URL 是否干净）在这条循环里都要变成代码算好的状态，这是整个架构最值得学的地方。

代码会往状态里塞入：

这些"事实"由 typesafe_computer_use/dates.py（日期）、typesafe_computer_use/decide.py（状态组装）等模块负责，让分类器只需要"选择"，而不是"理解+推理"。

第三步：一次请求，回答三个选择题 ✅

决策阶段是整个循环的心脏。每次只发一个TypeSafe 请求，内含三个Choice（有屏外控件时是四个）：

kind : click_item | use_browser | type_text | scroll… item : 点哪个物品（仅 click_item 时用） site : 去哪个网站（仅 use_browser 时用） offscreen : 按哪个屏外控件（仅 press_offscreen 时用）

把决策拆成三个问题，是为了把屏幕噪音挡在动作选择之外。作者总结的一条血泪经验：构建中遇到的每次卡死，都源于"两个选项其实一个意思"——置信度衡量的是概率集中度，选项重叠必然读作犹豫。动作集必须互斥（typesafe_computer_use/decide.py 中的fixed_actions就是这张互斥动作表）。

完整动作空间（节选自 docs/how-a-step-works.md）：

第四步：确定性执行，下一帧屏幕是唯一证人 🖱️

动作执行是完全确定性的代码路径（typesafe_computer_use/actions.py），没有任何模型参与。

这里有个朴素但深刻的设计：动作描述里不写"效果"，只有下一帧截图才能证明发生了什么。所以循环维护一份"屏幕签名"（App + 页面 + 页面文本）用于检测卡死：

• 连续3 次动作后屏幕没变（被拒的动作、加载中空等的 wait、滚到底的 scroll）→ 停
• 连续2 次做出"本屏早前已试过"的动作（点了一个没反应的按钮，或两个页面来回跳）→ 停
• 两帧"算同一个屏幕"的判定很宽容：最多差 1 行文本（且该行 ≤ 总行数的 1/10），这样时钟跳动、跑马灯不会伪装成"有进展"

规则整体偏"宁可继续跑"，绝不轻易停掉一个正在推进的循环。

另外，每次点击/按键/滚动前都会检查鼠标是否在屏幕左上角——那是用户的物理急停开关，从任何 App 里把鼠标甩到左上角都能立刻停住整个运行。

第五步：分类器停步后，Writer 接管 ✍️

分类器从不生成文本，它只会"停下"。一旦停下（done/none、置信度低于--min-confidence默认 0.4、卡死、步数用尽），writer 模型接管读屏，返回一个结构化答案：

{achieved, answer, focus, question}

三个出口：

• answer：目标要的信息，或"目前进展 + 卡在哪"
• focus：一句话的下一步（"Click the 'Arrives in 2-4 days' filter"），连同原目标一起放回分类器状态，循环继续跑。实测中，一次 0.39 置信度停步的截图，加上 focus 后同一个分类器能到0.92直接选对
• question：只有你能回答的问题（"13 寸还是 15 寸？"），在终端问你，回答会并入状态

安全阀：--handoffs默认上限 10 次，提问最多 3 次；第三次卡死在同组页面上则判定stuck收场。writer永远不直接挑点击——每个动作仍是分类器的决定。

每次运行结束时还会打印"谁干了多少活"，这是整个设计的健康指标：

calls: classifier 14 (82%, 3.9s) writer 3 (18%, 21.4s) handoffs 1 questions 0

如果 writer 占比变高，说明状态（分类器读到的东西）需要修，而不是加更多 hand-off。

关键模块导航 📂

想看源码？项目模块划分一目了然（完整地图见 docs/layout.md）：

快速上手：第一次跑通五步循环 🚀

环境要求：macOS 14+ / Python 3.12+ / uv。

git clone https://gitcode.com/gh_mirrors/ty/typesafe-computer-use cd typesafe-computer-use uv sync cp .env.example .env # 填入 TYPESAFE_API_KEY

记得给终端授予Screen Recording（否则截图是壁纸）和Accessibility（否则--act拒绝启动）两个权限，然后：

uv run clicker "open the Playground" # 干跑：走一步，打印它会做什么 uv run clicker "open the Playground" --act # 真的驱动鼠标键盘 uv run clicker-inspect "any goal" # 3-2-1 倒计时后截图并打开标注界面

小贴士：先清空终端再跑——终端在屏幕上，它的文字也是 OCR 输入的一部分 😄。

小结：五步循环的设计智慧 💡

1. 便宜在"少问"：把能算的（日期、行号、URL、聚焦）全部交给代码，模型只做选择题
2. 感知是双通道：OCR 管文字，辅助功能树管图标，合并成一份清单
3. 决策拆三个问题：动作、物品、站点互不干扰，动作集严格互斥
4. 截图是唯一证人：卡死检测靠屏幕签名，而不是模型自述
5. 停步不是失败：writer 的 focus / question 让循环带着"故事"继续跑

这套五步决策循环把"AI 看懂屏幕"从昂贵的整帧推理，变成了一条每步 $0.0002、约 1.5 秒的确定性流水线——这正是 typesafe-computer-use 的核心价值所在。