typesafe-computer-use（社区昵称jev）是一款"花几分钱就把电脑开明白"的 computer use 工具：它用 OCR 读屏、让 TypeSafe 分类器决定下一步动作、然后执行点击，每步成本约 $0.0002。过去它只在 macOS 上打磨，如今Windows 10/11 适配器已实验性登陆——但官方原话是"expect it to break"（预计它会坏）。本文带你快速看懂 Windows 版与 macOS 版的底层差异，并列出 5 个新手最容易踩的坑。

⚠️Beta 提示：项目整体处于 0.x 快速迭代期，设置和行为可能随版本变化。它驱动的是你真实的鼠标键盘，请务必先用 dry run 试跑。

一、先搞懂它怎么工作：Windows 版只是换了"手脚"

jev 的核心循环是：确定性地读屏 → 代码补全事实（日期、焦点、URL）→ 一次 TypeSafe 请求回答三个选择题 → 执行动作。完整拆解可看 docs/how-a-step-works.md。

对上层循环来说，"手脚"由谁提供并不重要。架构上由 typesafe_computer_use/platform_adapter.py 在启动时选定适配器：

• Windows 系统 → 加载 typesafe_computer_use/windows.py
• 其余系统 → 默认加载 typesafe_computer_use/macos.py

两个适配器实现同一套Desktop接口（点击、按键、截图、OCR、控件树等 20+ 方法），tests/test_platform_adapter.py 会逐一比对它们的参数签名是否对齐。换句话说：决策逻辑完全共享，Windows 版只换了最底下那一层平台零件👇

二、Windows vs macOS：底层零件逐项对照

依赖切换由 pyproject.toml 中的sys_platform标记自动完成，uv sync时按系统装对应那组包，无需手动干预。

📸 上图是项目测试夹具里的真实读屏截图：注意右上角的 "Restore pages?" 气泡——这类浮在页面上层的弹窗在 macOS 和 Windows 上都可能被误点，是双平台共同的已知限制（见 docs/known-limits.md）。

三、5 个必须注意的坑（Windows 用户必看）

官方 docs/windows.md 说 Windows 适配器从未在 Windows 上跑过 CI（CI 只在 macOS 和 Linux 上测试它的纯逻辑），下面 5 个坑正是"实验性"三个字的真实含义。

坑1：不先装英文 OCR 语言包，jev 就是"瞎"的

Windows.Media.Ocr 的语言包不随系统全量内置，必须一次性从管理员（elevated）PowerShell 安装：

Add-WindowsCapability -Online -Name "Language.OCR~~~en-US~0.0.1.0"

漏掉这一步不会报"权限错误"，而是 OCR 直接读不出文字，表现为 agent 反复停步、置信度走低——排查起来很绕。

坑2：OCR 只认英文，且每行都"自认为 100% 可信"

macOS 的 Vision OCR 会给出置信度，jev 用它过滤低质量行（阈值见 typesafe_computer_use/config.py 的MIN_OCR_CONFIDENCE = 0.3）。而 Windows 适配器里写死：

• OCR_LANGUAGE = "en"：中文界面的按钮和文本基本读不到，建议把任务界面切成英文；
• OCR_CONFIDENCE = 1.0：每行都按"确定"处理，误识别不会被置信度拦下，误读会直接进决策。

坑3：激活应用只认进程名，窗口标题不算数

Windows 上"应用 = 进程"：activate按可执行文件名精确匹配（如notepad.exe），已知浏览器则按产品名映射（Google Chrome→chrome.exe）。匹配规则刻意严格：

• 不做子串匹配、不看窗口标题——Chrome 标签页哪怕起名 "Excel"，也不会被当成 Excel；
• 想激活记事本就写notepad.exe，写Notepad同样能命中（.exe后缀不敏感），但写 "记事本" 就会失败。

坑4：遇到 UAC 弹窗或锁屏，会"拒绝点击"并直接结束运行

这是 Windows 上最反直觉的一点。macOS 上合成点击没权限时会被系统静默丢弃；Windows 适配器的 click_at 采用"先移动、再回读"策略：

1. 移动鼠标到目标坐标；
2. 立即回读光标实际落点，1 像素容差；
3. 光标没到（通常是 UAC 提权弹窗或锁屏把输入劫持走了）→ 抛Missed异常，直接终止本次运行，绝不盲目落点。

所以跑--act前：别锁屏、别弹提权框。想中途叫停老规则依旧有效：Ctrl-C，或把鼠标猛甩到屏幕左上角。

坑5：企业策略拦截clicker.exe时，有官方绕行方式

如果终端安全策略把clicker.exe拦了，不要改配置，直接换一种等效启动方式（参数完全相同）：

uv run python -m typesafe_computer_use "你的目标" --act

对应clicker-inspect的检查模式则用... typesafe_computer_use inspect。

四、Windows 上手快速清单

1. Windows 10/11 + Python 3.12+ + uv（此链接为 uv 官方文档）；
2. git clone https://gitcode.com/gh_mirrors/ty/typesafe-computer-use后cd进目录执行uv sync——Windows 专用依赖会自动装上；
3. 管理员 PowerShell 安装英文 OCR 语言包（坑1）；
4. 复制.env并至少填入TYPESAFE_API_KEY（每次决策都要用）；
5. 先 dry run：uv run clicker "open notepad.exe"，看它"打算做什么"；
6. 满意后再加--act真跑；记得主显示器是唯一会被截图的屏幕。

🎯一句话总结：Windows 版 typesafe-computer-use 架构上与 macOS 完全同构，只是把"手脚"从 Quartz/AX/Vision 换成了 UI Automation/SendInput/Media.Ocr——代价是英文 OCR、无置信度过滤、严格的进程名匹配，以及 UAC 场景下的强制熔断。官方文档 docs/windows.md 只有十几行，因为它诚实地写着：它还没被充分测试过，欢迎你来踩坑并回报结果。