@amaster.ai/pi-计算机使用

Pi桌面自动化的跨平台计算机使用工具. 扩展显示本地的 MCP 工具表面 computer_use_ 前缀。 捆绑的运行时间来自官方 Cua Driver Rust 0.37.0 释放。 。 。 .

它提供的东西

• 横跨 macOS、 Linux 和 Windows 的一股 rust 0.37.0 驱动线
• 62个基于版本的上游工具,包括会话、元素符号、无障碍+截图状态、本地输入、浏览器工具、诊断、记录和许可政策支持
• 被推迟的工具激活: 默认情况下只有核心工具组活动; 额外组根据要求通过 computer_use_tools 或者说 /computer-use-tools
• 完整的 MCP 文本、图像和 structuredContent 转发
• 拥有守护进程 + MCP 代理使用寿命周期,会话拥有重联和按呼取消
• 在会话开始时进行非瞬间 Linux/ Windows 权限探测
• 高风险业务的一次性app启动批准和确认
• 在进入 Pi 上下文前, 文本和结构化结果
• 通过配置的 Pi 模型进行可选二次视觉分析

get_window_state 是主要的感知工具。 Cua Driver 0.37.0默认为紧凑的Markdown无障碍树. 请求 tree_format:"both" 结构化元素的 element_token,以及 include_screenshot:true 当需要截图时。 独立 screenshot 工具已经不存在.

这个 cursor 组合通过六种运动风格曝光 set_agent_cursor_motion数字 : signature_arc, (中文(简体) ), spring_settle, (中文(简体) ), magnetic, (中文(简体) ), comet_swoop, (中文(简体) ), adaptive,以及 classic启动初始动议 start_session.cursor_motion,或保存默认值通过 set_config 使用 cursor.motion.* 键。 这个 diagnostics 组包括 parse_visual_regions 记录的捕获量和 install_extension 用于可选的驱动程序管理的扩展;首先预览计划,然后请求安装 confirm:true默认值 confirmDangerousActions:true, Pi 在安装前也需要交互式用户批准.

安装

bun add @amaster.ai/pi-computer-use

软件包通过 npm 选择一个签名/预编译平台运行时间 optionalDependencies。安装从 npm 下载匹配的驱动软件包,不需要单独安装驱动软件。 离线镜像必须包含 @amaster.ai/pi-computer-use 和比对 @amaster.ai/pi-computer-use-cua-driver-* 软件包。 可选感知文物仅在需要时直接从Cua下载;它们不是npm依赖.

从 Cua 升级 驱动器 0.9 是有意的公用工具迁移: 上游取消 set_agent_cursor_style 换成 set_agent_cursor_theme。新工具选择已安装 theme_id;旧的自定义颜色/图像参数没有0.28等同.

升级为 Cua 司机 0.34 删除 element_index 财务报告和审定财务报表 snapshot_id 从动作参数。 使用当前快照 element_token 无障碍行动; element_index 仍然显示元数据。 对于像素动作, 通过 capture_id 从源截图中找到。 新的快照会使以前的元素符号无效, 因此在再次行动前要刷新状态 .

司机0.35 取代遗产 set_config({key, value}) 带有命名属性的窗体,例如 set_config({"cursor.motion.timing": "steady"})。对所支持的属性使用已注册的计划。 新的 automation 群体曝光 run_steps 用于固定动作序列和 run_script 用于沙盒 JavaScript; 两者都需要交互批准, 当 confirmDangerousActions:true。脚本还需要在 confirmAppLaunch:true,因为他们可以发射申请;批准覆盖了完整的脚本.

司机增加0.37 browser_select 用于本地 HTML <select> 控制器和 get_guide({topic}) 用于浏览器、拖放、权限、批量和菜单的内置指导。 激活 browser 或者说 diagnostics 分别为组. 在 MacOS 上, 窗口瞄准镜 drag 默认为 delivery_mode:"background"; 使用 "foreground" 只有当背景投放没有效果时,因为它会短暂地向目标前行并移动物理指针. list_windows({pid}) 包括这一过程的每个窗口层.

配置

配置 .pi/settings.json 或者说 ~/.pi/agent/settings.json数字 :

项目设置仅在项目信任被接受后才被加载. ${ENV_VAR} 在用户和代理设置中支持插入,但在项目设置中则不支持插入.

{
  "pi-computer-use": {
    "mode": "bundled",
    "confirmAppLaunch": true,
    "confirmDangerousActions": true,
    "toolProfile": "core"
  }
}

在非交互模式中,需要确认的工具返回出错,除非相应的确认设置被明确禁用.

工具组

默认 core 配置文件,只有日常工具才能被模型看到(list_apps, (中文(简体) ), launch_app, (中文(简体) ), get_window_state, (中文(简体) ), verify_state,单击/类型/滚动家族,以及 zoom) (中文(简体) ). 其余的驱动工具保持注册,但不活动,因此成本不高。 该模型通过调用激活一个组 computer_use_tools (没有参数, 它列出组); 用户可以这样做 /computer-use-tools <group>数字 :

激活组在会话其余部分保持活动;每个新会话再次从配置的配置开始.

带有本地工具发现支持的 Pi 主机将驱动程序工具暴露在 computer_use 命名空间( 化名) desktop) (中文(简体) ). 可选工具的使用 deferred 接触 core profile,所以代码码可以发现并调用它们和内置 tool_search 可以直接激活它们。 在 Pi 1.2 上, 启用这些内置设备 pi --tools +codemode,+tool_search; SDK主机必须装入相应的内置扩展工厂. 现有组激活 full 剖面图和旧宿主行为仍然可用。 被推迟的呼叫保留了与直接呼叫相同的驱动权限,高风险确认,取消,以及主机工具钩.

仅在需要时才装入14个核心驱动工具计划,明确设置 "toolProfile": "lazy"。在有本地发现的主机上,所有驱动工具然后使用延迟接触;启用 tool_search 根据要求发现和激活它们,或者使用编码器的发现。 在没有本土发现的旧主机上,这个配置像 core,日常工具活跃,其他群体可通过 computer_use_tools 或者说 /computer-use-tools默认 core· ; full 不变。 此配置文件只影响驱动工具,而不是组管理工具或可选的截图分析工具.

之后 get_browser_state({ pid, window_id }) 绑定浏览器窗口, 其边框模式可见文本包括 target_id 和标签记录 tab_id,缩短标题和 URL,以及活动状态。 活动标签先出. 使用返回的内容 target_id 财务报告和审定财务报表 tab_id 用于随后的浏览器调用;这些ID也以结构化的细节提供.

模式可见的结构化成果

扩展内容包括这些工具的可模式可见文本中的有界限的结构化结果,因此其数据可用于下一步行动:

上游恢复 hint 财务报告和审定财务报表 next_call 字段也包含在对失败或未经证实的行动的有界限的可查看模型文本中。 A 类 screen_locked 快照在重试前需要唤醒并解锁Mac;不要向锁屏幕发送前景输入.

行动结果也暴露了司机 effect, (中文(简体) ), delivery, (中文(简体) ), evidence,以及 escalation 字段中的边框模式可见文本。 发出的行动或未经证实的效果不能证明完成或未交付。 如果MCP响应丢失,结果未知:在重复点击,打入或提交之前读取目标当前状态. 扩展不会自动重放失败的工具调用 .

长的描述性文字和大的清单被缩短并加短音通知;不透明的ID和续作符号永远不会被缩短. 窄浏览器读取 query 或者说 scope_ref 内 semantic_v2 需要的时候。 如果本地省略会话记录, 请重复 list_sessions 较小的 limit 在使用前 next_cursor 避免跳过隐形记录。 原有的结构化结果仍以限定的细节提供.

在键入浏览器动作如导航,点击,打字,指针输入,文件分配,下载之前,扩展会自动检查精确标签的JavaScript对话框状态. 这在动作打开一个模式前建立了驱动程序 CDP 对话框订阅,所以呼叫者不需要先手动检查. 如果对话框已经打开, 则未发送动作, 且当前 dialog_id 返回为 browser_dialog 以决定。 如果在此驱动程序订阅和检查时间过期之前打开了对话框, 请在重试前手动删除一次 ; 扩展无法通过受影响的驱动程序路径恢复现有模式 .

可选的地方观念

parse_visual_regions 使用已单独安装的 cua-perception 从已注册的截图中返回 OCR 文本和图标区域。 它在本地运行时没有Python或提供者API密钥. 它没有捆绑、下载或安装 pi-computer-use无障碍、浏览器工具和截图推理仍然可用。 打开 not_installed,继续使用这些工具,除非需要当地OCR/icon解析。 工具描述通过按需直接上上游安装来指导代理.

Perception拥有自己的发布和平台支持. Cua 认识0.2.1 公布这些目标:

目前没有为macOS Intel,Linux ARM64,或Windows ARM64发布的0.2.1个文物. 通用macOS驱动程序并不意味着通用感知支持. 选择本地目标; 不安装另一个架构的归档 .

大约421–426 MB压缩捆绑包含土生工人,ONNX Runtime,OmniParser图标检测器,PP-OCR文本检测器/英语识别器,词典,通知,以及对应出处的材料. 该版将OmniParser探测器确定为AGPL-3.0-只,PP-OCR文物确定为Apache-2.0;其他被捆绑的部件保留自己的许可证. 阅读发行的SBOM和 第三方通知 在重新分配之前。 这些文物不包含在这个扩展的Apache-2.0包或默认的MIT Driver包中.

要按要求安装, 代理或用户会下载签名目录和匹配归档 官方感知发布 输入同一目录。 关于0.2.1, 选择 cua-perception-0.2.1-<target>.catalog.json 财务报告和审定财务报表 cua-perception-0.2.1-<target>.tar.gz 使用以上目标。 不要使用全库最新发布:驱动和感知有单独的发布标签. 保持完整的上游档案和签名核查完整. 已过期的目录需要更新的Perception发布.

使用配置的 Driver 二进制, 或解析安装中的捆绑二进制 pi-computer-use数字 :

node --input-type=module -e "import { resolveDriverLayout } from '@amaster.ai/pi-computer-use'; console.log(resolveDriverLayout({mode:'bundled'}).binaryPath)"

同一个用户 CUA_DRIVER_RS_HOME 作为 Pi, 使用二进制运行这些命令 :

cua-driver extension inspect cua-perception --catalog /absolute/path/to/catalog.json
# Review publisher, target, size, licenses and source before installing within user authorization.
cua-driver extension install cua-perception --catalog /absolute/path/to/catalog.json
cua-driver extension status cua-perception --self-test

司机在安装到自己的扩展商店之前,先核查已签名的目录并存档。 运行中的驱动程序在下一个剖面上检测安装而不重新启动 。 这个 computer_use_install_extension MCP 工具不下载文件: 它需要 CUA_DRIVER_PERCEPTION_CATALOG 指向守护进程发布会的本地目录 偏好上面的 CLI 用于现有的会话;明确的目录/存储环境变量仍然被传送到守护进程和 MCP 代理.

启动 /computer-use-tools diagnostics,然后请 Pi 用 computer_use_get_window_state({pid, window_id, include_screenshot:true}) 并递还他 capture_id 改为 computer_use_parse_visual_regions({capture_id, options:{max_regions:3}})。保持相同的 Pi 连接和重复相同的 session 如果使用了标签. snapshot_id 不是一个抓取身份。 安装计划和解析结果以有界限的可见模型文本被曝光. 分析结果包括区域文本/标签/捆绑和捕获的动作坐标转换. 缺少扩展返回 not_installed; Stale 或 已过期的捕获需要另一个捕获. 不删除 capture_id 来绕过一个被拒绝的像素动作.

使用 extension inspect 在此之前 extension update cua-perception --catalog ... 以更改版本。 要删除仅由驱动程序管理的安装, 请使用 extension remove cua-perception见 上游生命周期文件 整个合同.

对维护者来说,平台整合工作下载将上游文物固定在跑者的临时目录中,验证他们的散列,并检查签名安装,自我测试和真实的OCR. 释放元数据 .github/scripts/fixtures/。只使用 CI 选项 scripts/fetch-perception.mjs <target> [destination] 保持其基础分支公关工作流程和默认设置的稳定切入点 $RUNNER_TEMP/cua-perception (或系统临时目录在CI之外). 未在 npm 包中运出 。 Perception在这个寄存器中没有平台npm软件包或发布工作流程.

备选视觉模型

{
  "pi-computer-use": {
    "visionModel": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}

computer_use_analyze_screenshot 需要两者 pid 财务报告和审定财务报表 window_id它召唤 get_window_state,重新使用返回的图像,并引用已配置的模型。 只有在主模型无法解决视觉模糊时才使用.

运行时间和权限

Windows守护进程状态探测器允许每个进程引用最多10秒,因此慢驱动程序初始化在250ms后不会被中断. 会话取消仍会中止探测器 .

在macOS上, session_start 在不启动驱动程序的情况下登记生成的 0.37.0 清单。 已签名的应用程序和 MCP 代理在第一个计算机使用工具调用上开始懒散化, 它请求任何缺失权限通过 check_permissions({ prompt: true }). 现有赠款不会引起另一个系统对话。 请求的工具仍然运行并报告自己的能力或权限出错. Linux 和 Windows 保持急切的启动: 他们发现了准确的活性 tools/list 表面和呼叫 check_permissions({}) (可选) prompt 此探测器不需要参数). 如果发现失败, 扩展注册簿 computer_use_connect (和 /computer-use-connect因此后期的再试可以安装精确的活平台合同而无需广告另一个OS的策略.

驱动程序启动,重新连接,以及第一个macOS权限探测器为会话自有. 取消一个工具只停止呼叫者的等待或 MCP 请求; 会话关闭中止共享的工作 。 macOS和Linux还使用一个瞬态的管道后置租赁,在突然主机退出后阻止自有守护进程;没有安装持续服务或系统调度器.

• 捆绑的macOS: 签字日期: CuaDriver.app 通过发射服务, 因此,无障碍和屏幕记录赠款属于 com.trycua.driver。 。 。 .
• 自定义macOS 二进制 : 使用 Cua 驱动程序嵌入模式并继承主机 应用程序的 TCC 责任链 .
• Linux/ 窗口 : 在交互式用户中启动一个扩展主守护进程 届会结束时就把它撕了.

支助目标

条形工作流程

货包船a 计算机使用技能 用于选择现有工具、缩小观测、检查理想状态、分批列出已知序列并恢复不确定行动。 皮发现它通过 pi.skills; 引用 /skill:computer-use <task> 明确装入。 它增加了指导,而不是另一个工具表面或次要决策模型.

1. computer_use_launch_app 或者说 computer_use_list_apps
2. computer_use_get_window_state
3. 使用 element_token,返回到像素中用于自定义的表面
4. 重新运行 computer_use_get_window_state 并核实变化
5. 当任务比核心工具集(浏览器自动化, 录音,升级会话,...),呼叫 computer_use_tools 与 首先匹配组

Linux和Windows工具描述和计划来自精确活的驱动程序. macOS为捆绑驱动程序发布使用生成的列表.

许可证

这个扩展包的Apache-2.0. Bundled Cua Driver资产保留了上游麻省理工学院许可证,并在每个平台软件包中发布元数据.

当本地 tool_search 中,插件从模型中隐藏其组活性工具声明和引导。 残疾 tool_search 恢复后退状态 群活化工具是在本土运行时间上只使用模型的管理工具,因此代码脚本使用本土发现取而代之. 在这两种情况下,相应的斜线命令仍然可用;更古老的运行时间保留了现有的活化行为.