@cherrystudio/ 计算机使用

樱桃电脑的TypeScript客户端 使用本地运行时间,用于节点24+和Electron的主要过程.

状态:所有三个平台都执行私人本地应用控制会话. macOS和Windows调整了它们现有的引擎,用于所有七个动作. 视窗使用 UI 自动化和窗口导向消息, 包括坐标点击; 它永远不会 回到全球投入。 Linux 支持发现、观察和语义 元素动作:左键单击,二次动作, setValue,以及 typeText 输入 一个焦点可编辑字段。 X11 上, 指针点击、 拖放、 按键、 页面滚动 使用全球投入和要求 allowGlobalInput: true;密钥需要目标窗口有焦点. 在 Wayland 键上 按下、页滚动和打字,不需要焦点字段 allowGlobalInput: trueSway和Hyprland等基层堆肥公司使用a 没有对话框的虚拟键盘,可以键入任意字符,并且需要 将目标报告为焦点窗口。 在斯威和海普兰, 截图和指针输入也有利于本地的Wayland窗口:指针移动 首先按下按钮,然后将目标报告为 焦点窗口,需要焦点跟踪鼠标(默认)。 关于GNOME, 截图、指针和键盘输入通过樱桃电脑使用壳 扩展名: 用户运行 open-computer-use install-gnome-extension 输入日志 再来一次 requestPermissions({ ids: ['gnomeShell'] }) 显示 Shell 对话框. 扩展抓取覆盖窗口,仅在目标拥有点时点击, 只向焦点窗口发送密钥,并将任何 Unicode 输入文本输入客户端. 在 KDE 等离子体 6 上, open-computer-use install-kde-integration 授权运行时间 kWin 窗口抓取和输入的帮助工具( 无新登录; ) kdeIntegration 权限报告它 : 仅在光标位于点和 目标位于最上方,只在目标活动时才按键,并文本 键盘布局缺失会被拒绝,除非它进入一个有焦点的文本字段. 没有它们, GNOME 和 KDE 键会通过远程Desktop 门户(remoteDesktop 权限); 目标窗口必须活动,并显示键盘布局 拒绝缺少, 无法获取和指针输入 。 查询之前的能力和元素动作 演戏 Windows 消息发送不保证每个应用程序都能接受 背景输入;多窗口选择和GPU窗口抓取仍然有限. macOS支持明确的许可请求. SDK 软件 0.1.1 包括匹配本地 软件包; Windows 引擎适配器的修改需要后续的 SDK/native 发布.

发展

从寄存器根 :

npm install
npm run sdk:check
npm run sdk:test
npm run sdk:build

CI 可以重用一个已完成的建筑 npm run test:built --workspace @cherrystudio/computer-use通过 npm 运行,以便得到 tarball 消费者测试 npm_execpath; 它不会重建 dist/。 。 。 .

protocol/schema.json 在构建过程中生成 TypeScript 线条类型和独立验证器。 生成的文件被忽略;编辑计划并重建. dist/ 包含无害环境管理、共同司法体系及其类型声明。 沥青球测试将已建包安装到一个孤立的消费者中并检查模块格式和TypeScript分辨率.

API 密码

安装方式 npm install @cherrystudio/computer-use (节点24+,可选的依赖性启用). 本地分布补丁会自动安装匹配的帮助. SDK 软件 0.1.0 仍然需要明确当地建造 runtimePath数字 :

import { ComputerUse } from '@cherrystudio/computer-use'

const computer = await ComputerUse.start()
try {
  const capabilities = await computer.getCapabilities()
  const permissions = await computer.getPermissionStatus()
} finally {
  await computer.close()
}

macOS许可查询在私人应用代理的身份下使用非交互飞行前飞行. Windows和Linux X11返回空权限列表,因为它们没有OS权限流;这并不意味着授权. Linux Wayland 报告 remoteDesktop,以及 requestPermissions({ ids: ['remoteDesktop'] }) 显示远程Desktop门户对话框,解析到 granted 或者说 denied; 提前取消返回,但无法关闭对话框. requestPermissions 在Windows和Linux X11上不支持。 在 macOS 上,一个明确的请求在交互之前会验证所有ID,并打开现有的本地登入窗口,在 System Sets 旁边有一个可拖动的帮助器app平板. 请求待决, 直至拖曳被接受, 所请求的权限被按批准被遵守, 或是用户选择 完成 或关闭窗口。 被接受的拖曳结束此交互, 即使macOS仍然需要确认; 在新会话中重新检查并请求任何剩余权限 。 它返回所观察到的飞行前状态,而不是同意的承诺;允许不经批准而解雇。 取消在确认清理前关闭登入窗口并拖曳面板 。 Windows需要Windows PowerShell和一个交互式桌面;Linux直接使用Go与桌面AT-SPI D-Bus服务和X11进行捕获,没有Python或cgo.

如果允许登机,请在等待时让客户活着 requestPermissions,然后将其关闭 finally. 入职后再次以新客户端查询,因为macOS可以在旧的进程中缓存赠款. SDK窗口不重启或终止协议进程;主机拥有该生命周期. 保持签名的助手捆绑身份稳定; 主机自己的权限不能代替助手的赠款 .

以下例子针对存储器的反固定. 在主机中选择一个授权的目标,并保留一个客户端执行控制任务,跨越多个工具呼叫:

import { ComputerUse } from '@cherrystudio/computer-use'

const computer = await ComputerUse.start()
try {
  const apps = await computer.listApps()
  const app = apps.find(app => app.name === 'CherrySDKFixture')
  if (!app) throw new Error('Start the counter fixture first')

  const session = await computer.openAppSession({ appId: app.id }, { signal })
  const state = await computer.getAppState({ appSessionId: session.id }, { signal })
  if (state.tree.status === 'available') {
    const element = state.tree.elements.find(element => element.name === 'Count: 0' && element.actions.includes('click'))
    if (element) {
      const result = await computer.act({
        type: 'click', appSessionId: session.id, snapshotId: state.id, elementId: element.id
      }, { signal })
      // Inspect result.observation before choosing another action.
    }
  }
} finally {
  await computer.close()
}

• ComputerUse.start(options?, callOptions?):明确解析,启动并初始化私人运行时间. 导入软件包不会启动进程或请求权限.
• getCapabilities() 编号 : getPermissionStatus():查询已执行的能力和OS权限状态. 它们不会取代主机的用户授权.
• requestPermissions({ ids }): macOS 的明确的 OS 权限流 accessibility 财务报告和审定财务报表 screenRecording,以及 Linux Wayland 数据 remoteDesktop;在Windows和Linux X11上不支持.
• listApps() 编号 : openAppSession({ appId }):发现目标并创建每个应用程序的控制上下文. 打开活性目标重用其上下文. App ID 识别运行的过程,并在整个运行时间重启时保持有效,直到退出.
• listAppSessions(): 查询本地控制状态( t)active, (中文(简体) ), stopping, (中文(简体) ), stopped)独立于已排队的桌面工作.
• stopAppSession({ appSessionId }): 屏蔽此背景的新/已排队的工作, 取消其主动请求, 等待本地清理 。 它不会退出应用程序或关闭其他上下文 .
• getAppState({ appSessionId }): 获取活动应用程序上下文的结构化观测。 观测默认值为 activation: 'never';没有支持的限制必须被本地法典所拒绝.
• act(action)合同包括: click, (中文(简体) ), performSecondaryAction, (中文(简体) ), scroll, (中文(简体) ), drag, (中文(简体) ), typeText, (中文(简体) ), pressKey,或 setValue。在此切片中仅连接到单个左键点击。 所有动作参考 a appSessionId 联 合 国 snapshotId。单击 elementId 或者说 x/y;坐标是指返回的截图像素. allowGlobalInput 默认为 false 并且是本地执行的限制因素,而不是东道主授权的证据.
• onClosed(listener): 最终清理状态; 返回未订阅的函数。 迟到的订阅者立即收到最终事件.
• close(): 一分机; 取消待处理请求, 需要自有的运行时间的清理确认, 并等待其进程退出 .

Snapshot.tree 财务报告和审定财务报表 Snapshot.screenshot 独立报告 available 或者说 unavailable。可用的树木包括元素和切换原因。 可用的截图包含 image.data: Uint8Array,PNG MIME类型和维度. 抓取必须识别一个应用程序窗口;模糊的映射返回不可用,没有全屏倒置. 此切片中没有元素界限 。 模型特有文本/图像块属于主机适配器.

协议v2需要匹配重建的 SDK/运行时的文物;在更新本地链接后重新启动运行中的主机. 旧无范围观察/行动电话被拒绝. SDK验证快照并停止确认属于所请求的应用会话.

停止在发送后是不可逆转的,包括如果呼叫者取消停止请求. 重复停站是安全的;明确重开被停站的目标会产生新的ID. 主机必须保留用户的停止决定并阻止工具/标语自动重开应用程序或重创建运行时间. 樱桃主机政策、托盘UI和每个应用程序光标的反馈仍有待处理.

取消和失败

接受呼吁 signal 财务报告和审定财务报表 timeoutMs (默认为30秒,但 requestPermissions,它允许5分钟的人类互动。 明确 timeoutMs 覆盖默认值。 取消发送 $/cancelRequest 并等待最多两秒钟,等待原请求的终端响应. 已确认完成的动作可以赢得取消比赛,并按完成后返回. 如果取消无法确认,客户端就变得无法使用并开始关闭.

ComputerUseError 包含 code, (中文(简体) ), effect (单位:千美元)none, (中文(简体) ), possible, (中文(简体) ), applied在相关情况下, cleanup完成但随后观察失败的动作返回 status: 'completed' 与 observation.status: 'unavailable'。该结果或不确定的错误都不会自动重试。 未确认的应用程序清理返回 CLEANUP_FAILED 与 cleanup: unconfirmed中,关闭连接。 具有不确定结果的本地动作会禁用该会话中的更多桌面操作; 在开始新任务前关闭它 .

正常关闭确认会话ID和 cleanup: 'complete',然后需要退出代码 0。 清理无效的强制终止直接拥有的进程, 拒绝 close() 与 CLEANUP_FAILED,和报告 cleanup: 'unconfirmed'。杀害代理无法证明本地帮助者释放了资源。 本地实施必须执行业主-离散清理.

在意外中断后,等待 close() 完成本地进程清理。 关闭或关闭的客户拒绝与 CLOSED;没有重新连接、重放或快照恢复.

运行时间发现和分发

明确 runtimePath 是一个完整的 .app 在macOS上捆绑,或者在Windows/Linux上安装可执行文件. 路径可能包含空格 。 SDK不使用外壳和发射 serve --stdio --session-id <uuid>。macOS捆绑的可执行文件必须是 Contents/MacOS/OpenComputerUse。 。 。 .

没有明确的路径,解决者期望 @cherrystudio/computer-use-{darwin|win32|linux}-{arm64|x64} 在精确的 SDK 软件包版本。 每个包必须曝光 package.json 并载有:

• 马可斯: runtime/Cherry Computer Use.app/Contents/MacOS/OpenComputerUse 它的完整应用程序捆绑.
• 窗口 : runtime/open-computer-use.exe。 。 。 .
• 林纳: runtime/open-computer-use。 。 。 .

SDK将所有6个平台软件包固定到其准确版本 optionalDependencies; npm 选择匹配的OS/CPU. 平台软件包包含本地帮助器,没有npm CLI或安装脚本. macOS发布助手是开发者ID签名并公证. 缺少软件包(包括安装 --omit=optional(a) 提高 RUNTIME_NOT_FOUND;运行时没有路径查询或网络安装。 Electron主机必须在ASAR外包装帮助者,并在必要时提供其资源路径. 已签名的公证和电子包装是单独的验收检查.

代码模式是可选和延期的 。 普通工具和未来的脚本外观可以消耗同一个客户端;SDK没有解释器,模型SDK或Agent会话存储.

樱桃

(原始内容存档于2019-09-21) (英语). SDK QQ @cherrystudio/computer-usemacOS 帮助器 Cherry Computer Use.app(单位:千美元)com.cherryai.cherrystudio.computer-use)), Cherry Computer Use (Dev).app(单位:千美元).dev。嵌入或显式 runtimePath * * * * * * * * * * * @cherrystudio/computer-use-cli SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK SDK s;SDK SDK S;SDK SDK SDK SDK SDK SDK SDK SK SDK SDK SK SDK SK SDK SDK SDK ;SDK ;SDK SDK SDK ;SDK SDK SDK SDK SDK ;0.1.0-;0.1.0-正正;正;正;正;正;正;正;正;正;正;正;正;正;正;正 发布指南键。

持续增加自动化(未释放)

• resolveApp({ query }) 解决一个明确的应用程序名称或运行时的ID。 匹配本土构建也可以启动已安装的应用程序:macOS捆绑,Windows AppsFolder应用程序/可执行路径,和Linux XDG桌面条目(D-Bus活化或Exec;不需要GIO工具). 先解决,然后打开自有的应用程序会话 。 启动等待匹配的可访问窗口;在输入前获得新观察. Windows/Linux桌面政策可能激活所启动的应用程序.
• perform(action) 验证和执行相同的 Action 输入为 act返回时 { status: 'completed', appSessionId } 而不捕捉另一个观察。 此收件确认输入发送,而非用户的任务结果.
• 每个动作都消耗元素/坐标值。 仅 typeText编号 :pressKey 结束 perform 可以重新使用最后一个目标快照ID,并进行本土目标验证. 明确观察取代了键盘目标;错误需要新的观察. 不同的应用/窗口无法继承目标 .
• act 保留现有的行动加观察行为。 新方法需要匹配重建的SDK/原生文物. 在不确定的行动之后,没有自动退缩或重试.

主机拥有应用选择授权,持续代理,输出交付和权限吊销. 这些添加不会暴露MCP或SDK中的JavaScript运行时间.

resolveApp({ query, launch: false }) 只解决运行中的目标。 主机在重新获得持续控件时使用此功能, 因此读取不能默默地重新启动用户关闭的应用程序 。 明确约束默认允许在被支持的平台上发射.

getAppState({ appSessionId, includeScreenshot: false }) 在macOS,Windows或Linux上收集AX状态而无需调用本地截图后端. 承认/真实保存捕获。 跳过截图报告 CAPTURE_NOT_REQUESTED,而不是许可失败。 坐标输入需要由截图驱动的观察;语义输入和键盘定位仍然可用. 此选项需要匹配未释放的 SDK/内建.

在macOS上,SDK typeText 将键盘文本发送给已验证的应用程序PID,包括没有可编辑的AX字段的键盘驱动控制. 它不替换AX值或激活应用程序. 每个完整的相册单独发送;新行发送回. setValue 仍然是明确的可编辑控制值操作。 遗留的MCP文本-字段路径和其他平台保留了自己的输入限制.

授权启动应用程序

resolveAppIdentity({ query }) 不启动就解决已安装的应用程序 或启动它。 它返回一个马厩 id显示 name,和犬类 query。 。 。 . macOS 接受捆绑名/ IDs/ 路径; Windows 接受 AppsFolder 名/ AUMID 并 可执行名称/路径; Linux 接受桌面名称/ID/路径. 授权身份 调用前的主机 resolveApp({ query, expectedIdentity: id, launch: true })。 。 。 . 运行时间检查 expectedIdentity ; 更改身份失败 没有发射。 运行 AppInfo 和应用程序会话包含相同的可选 identity; 不透明 id 仍然是运行时控制引用.

launch: false 保留其只运行的语义. Windows/ Linux 不启动 应用程序并拒绝已安装的身份解析 UNSUPPORTED_CAPABILITY。 。 。 . 宿主停机决定仍然是宿主拥有的,必须在生效前检查.

在macOS上,文本元素广告 setValue 只有当它们的 AX 值可以写时. 仅显示浏览器地址栏可能需要点击, 然后再进行新的观察 以显示可编辑字段。 使用该字段的新元素ID, 验证其值 在返回之前,并核实目的地。 设定值飞行前拒绝 已经 effect: none 并允许在同一会话中重新发表意见; 失败 在尝试写作之后,仍不确定。 屏幕截图坐标转换 在 AX 命中测试前一次窗口点. launch: false 保留其只运行的语义,包括已安装的别名: 已经运行的应用程序。 已安装的旧 Windows/ Linux 运行时间 身份分辨率为 UNSUPPORTED_CAPABILITY; 重建/包装匹配本地 能够发射的文物。 主机停机决定仍为主机所有,必须 检查效果前.

Windows 包装身份使用 AUMID; 桌面身份使用 Cononical 可执行文件 路径。 App 启动时使用 Windows Shell/应用程序激活API (原始内容存档于2018-10-21) (英语). Tital UIA Worker's kill-on-close Job Object. Linux 身份定义 桌面文件路径; XDG 用户覆盖和本地化名称得到尊重。 平板电脑 发射装置的识别名称 active 部署,所以它生存 更新; Flatpak apps 一旦会话名称变为可解析 XDG_DATA_DIRS d-Bus服务包括平板电脑出口,通常在再次登录之后。 发射 遵循每个桌面上的桌面条目规格: DBusActivatable 条目 实收 org.freedesktop.Application.Activate 在会话总线上,掉回 仅在未安装服务时执行; 其他条目运行其扩展的 Exec (引用,字段代码, Path)从运行时间分出. 执行发射选择 进程进入无障碍环境QT_LINUX_ACCESSIBILITY_ALWAYS_ON, (中文(简体) ), GNOME_ACCESSIBILITY, (中文(简体) ), ACCESSIBILITY_ENABLED),由于Qt,Firefox和Chromium否则会暴露出任何树 直到全会话启用辅助技术。 铬和电方案, 由Chrimium在程序旁边或AppImage内的资源包识别 (挂载只读,不运行其应用程序),也收到 --force-renderer-accessibility,否则他们的页面内容将隐藏。 封闭的 Snap 应用程序 只向对等者回答 AT- SPI 的 AppArmor 策略允许的, 如无限制 主持人。 终端条目未启动 。 发现联系人通过活动表的拥有者进行流程 应用程序的总线名称, 此运行时间启动的过程( 由 PID 启动) ), 启动元数据, 一个 AppImage 的图像路径, 用于运行其进程 挂载、 Flatpak 应用程序 ID 或 明确的可执行匹配 。 不可识别或 模糊的运行目标在发射后从未被猜测的名称所选择.

发送、 取消、 缺少访问或窗口超时报告 effect: possible; 不要自动重放发射。 这些 SDK 添加不 修改遗留下来的CLI/MCP启动政策或授权全球投入.