pi-computer-use：用 Pi 控制 MacOS 和 Windows 上的应用

这是什么

pi-computer-use 是 Pi 的一个开源扩展（主语言 TypeScript，★1313），让 AI agents 能够操作 macOS 和 Windows 上的桌面应用。它基于操作系统无障碍 API 和屏幕录制权限，使 agent 可以“看见”应用窗口中的内容（按钮、文本、控件），并执行点击、打字、滚动等交互。macOS 端需要系统 14 以上，并需授权 Accessibility 和 Screen Recording；Windows 端直接使用平台无障碍 API，无需额外 helper 应用或 TCC 权限流。

本质上，它是一个 面向桌面 GUI 的受控操作接口，将 agent 与桌面软件的交互抽象为结构化的观察‑行动循环。项目的架构核心是不可变、状态作用域的观测（immutable, state-scoped observations）：桌面表面与 CDP（Chrome DevTools Protocol）页面构成多根森林，渐进式轮廓查询的结果会被缓存，实时工作按物理资源排序，独立根可以并行执行。

解决的问题

许多桌面应用没有 API、终端命令或文件接口，传统自动化方案（如截图+坐标点击、OCR+鼠标模拟）脆弱且难以维护 —— 屏幕分辨率变化、窗口位置偏移都会导致失败。pi-computer-use 让 AI agent 能以感知语义的方式操作桌面软件：它通过无障碍树获取当前窗口的结构化表示（标题、按钮标签、文本框状态），而非依赖像素级截图。agent 据此可以：

• 精确定位“保存按钮”而不关心屏幕坐标；
• 等待某个 UI 元素出现或消失后再执行下一步；
• 在多个窗口/应用间切换上下文。

这解决了两个核心痛点：缺乏程序化接口时的交互需求 和 传统自动化工具对环境变化的脆弱性。项目文档明确强调，如果应用已有可靠的 API 或 MCP 服务器，应优先使用它们；pi-computer-use 仅在屏幕界面是唯一可用接口时才有价值。

核心功能

扩展注册的工具有 8 个，覆盖观察、搜索、操控、等待四大类：

| 工具 | 作用 | |------|------| | find_roots | 发现当前所有打开的窗口和应用根节点 | | observe_ui | 获取指定窗口中当前可见的全部 UI 元素 | | search_ui | 在当前可见界面中搜索特定文本、按钮或控件 | | expand_ui | 展开 UI 树的某部分以查看更细粒度的子元素 | | inspect_ui | 深入检查某个控件属性（如 enabled、value） | | act_ui | 执行一个或多个意图步骤（点击、打字、滚动、按控件） | | read_text | 读取窗口中指定区域或控件的文本内容 | | wait_for | 轮询等待特定 UI 状态变化（出现/消失/变更） |

核心引擎是 act_ui：它接受一个或多个意图步骤（而非低级鼠标事件），自动保持焦点在关联输入域之间，验证操作是否交付，并在失败时安全恢复。执行完成后会返回一个完整的后继状态（successor state），如果身份置信度允许，还会生成紧凑的 diff。旧的直接工具（screenshot、click、set_text、computer_actions）已不再作为公共扩展表面。

架构上，每个工具都返回不可变的状态快照，agent 可以依赖这些快照进行决策，而无需重新扫描整个屏幕。

亮点 / 与同类相比

• 基于无障碍 API，而非视觉截图：与 Anthropic 的 Computer Use 演示（依赖截图+坐标）不同，pi-computer-use 通过 Accessibility Tree 获取语义化 UI 结构，不需要 OCR 或图像识别，对屏幕分辨率、缩放、窗口位置变化更加鲁棒。
• 意图级别的操作定义：act_ui 接受“点击提交按钮”或“在搜索框输入查询”这样的意图，而非 “move mouse to (x,y) → click”。这降低了 agent 的推理负担，也减少了因坐标偏差导致的失败。
• 不可变状态作用域与多根并行：观测结果按作用域缓存，agent 可以同时监控多个窗口而无需串行扫描；wait_for 也包含状态缓存重用机制。
• 与 Pi 深度集成：安装后直接作为 Pi agent 的工具集使用，提供一致的界面 /computer-use 查看当前配置。
• MIT 许可开源：代码完全开放，便于社区审计和贡献。Windows 支持直接复用平台无障碍接口，无需额外收费组件。
• 安全设计：操作前需要用户显式授权 mac 权限，Windows 依赖交互式桌面会话；agent 的操作范围通过工具接口严格限制，不能执行任意系统命令。

相比同类项目（如 Playwright 的桌面模式、SikuliX、Appium），pi-computer-use 更专注为 LLM agent 提供简洁的观察‑行动抽象，而非通用自动化框架。它的设计哲学是“让 agent 像人一样阅读 UI”，而非“模拟人眼和手指”。

适合谁用 / 上手

适合人群：

• 使用 Pi 并希望让 agent 操作本地桌面应用的开发者或高级用户；
• 希望自动化那些没有 API 的桌面软件的团队（如旧版企业工具、专业设计软件）；
• 研究 Computer Use 方向的技术爱好者，需要开源参考实现。

上手步骤：

1. 确保已安装 Pi（从 pi.ai 获取）。
2. 运行 `pi install npm:@injaneity/pi