电脑操作桥接 fishcg/cua-computer-use

cua-computer-use

把 Cua Driver 的 MCP 服务器接入 DeepSeek Harness，让 Harness 真正拥有「操作电脑」的能力。

Cua Driver 自带一个 MCP 服务器（cua-driver mcp），对外提供一套无障碍（accessibility）优先的 GUI 自动化能力：窗口发现、无障碍树快照、绑定快照的元素令牌、像素坐标兜底、原生菜单、浏览器标签页、录制与回放。本插件负责定位 cua-driver 可执行文件，把这个服务器接到 Harness 内置的 MCP 客户端上，将约 60 个工具注册为 mcp__cua-driver__，并附带一个教会模型正确工作流的 Harness 技能。

插件不重复实现任何自动化逻辑，也没有任何运行时依赖。

为什么需要插件，而不是手写一行 MCP 配置

手工在 profile 里加一行 MCP 当然可行，但会踩到两个坑：

1. Harness 宿主进程没有你 shell 的 PATH。 macOS 上桌面端由 launchd 启动，它的 PATH 里没有 ~/.local/bin——而这正是 Cua Driver 安装器放可执行文件的地方。MCP 行里写裸命令 cua-driver 会直接启动失败，且报错信息毫无指向性。本插件会解析出绝对路径、按平台搜索常见安装目录，并在失败时把尝试过的每个路径都列出来。
2. 只有工具、没有指引，模型会用错。 注册 60 个工具并不够——模型需要知道：快照会让令牌失效、 since: "latest" 才是最省的复读方式、浏览器页面应该交给 browser_ 工具而不是桌面指针。插件自带的技能和一句常驻提示词就是干这个的。

前置条件

- DeepSeek Harness 0.2.0-rc.2 及以上。
- 首次运行不需要其它准备。cua-driver 缺失时插件会自己装，见首次运行。如果你想自己装、或者想在启动 Harness 之前先装好：

macOS / Linux
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"

Windows
irm https://cua.ai/driver/install.ps1 | iex

- macOS 需要「辅助功能」和「屏幕录制」权限。插件会检查并一步步引导你授权，不需要你额外做什么。

首次运行

插件会自己完成下面两步，而且两步都不会阻止 Harness 启动。

一、可执行文件。 查找顺序是：配置项 → $CUA_DRIVER_BIN → 标准安装目录 → PATH。都没有时，插件用官方文档里的同一条命令安装，然后再找一次。

安装器通过环境变量驱动而不是命令行参数——这是官方文档承诺稳定的接口，而且在 Windows 上没有 shell 引号问题。有三个默认值需要知道，因为开机启动没有人点「同意」，而手敲 curl … | bash 的人是自己同意了：

| 环境变量 | 默认值 | 原因 |
| CUA_DRIVER_RS_NO_MODIFY_PATH | 1 | 插件会把绝对路径直接交给 MCP 客户端，所以往你的 ~/.zshrc 里追加 PATH 属于没人会想到去查的副作用。设 modifyPath: true 可放开。 |
| CUA_DRIVER_RS_TELEMETRY_ENABLED | 0 | 安装遥测在这里是「选择加入」，不是「选择退出」。设 installTelemetry: true 才发送。 |
| CUA_DRIVER_RS_INSTALL_DIR | 未设置 | 设 installDir 可装到 ~/.local/bin 以外的地方。 |

安装器写入的每个文件都会校验发布包的 SHA256SUMS，macOS 的 app bundle 在建立软链之前会校验签名。设 autoInstall: false，或导出 CUA_DRIVER_NO_AUTO_INSTALL=1，插件就完全不装，改为直接报错并给出手动命令。

二、macOS 权限。 服务发布一秒后，插件读取 cua-driver permissions status --json；如果有权限被拒绝，它会打印该开什么、在哪里开，并让驱动自己弹出系统授权弹窗——每种缺失的权限只弹一次，标记存在 ~/.dsh/cua-computer-use/setup.json，所以之后的启动只会告诉你还缺什么，不会反复弹窗。

权限归属于 CuaDriver，不属于 DeepSeek Harness——macOS 把这类权限记在拥有无障碍 API 的那个进程上，也就是驱动守护进程。设 permissionCheck: false 可跳过检查，设 permissionPrompt: false 则只报告、不弹窗。

安装

从 Git 仓库安装
dsh plugin --profile web add github:fishcg/cua-computer-use

安装后重启 Harness。bundle 层由 package.json 里的 dsh.bundle.patch 声明，会自动生效。

插件发布的是纯 ESM，没有构建步骤，也没有任何运行时依赖，所以从 Git 安装不需要在 profile 的 pnpm-workspace.yaml 里加 allowBuilds——根本没有东西要编译。

注册内容

| 类型 | 名称 | 说明 |
| 工具 | mcp__cua-driver__* | 60 个工具，经 @deepseek-ai/dsh-mcp-client 桥接 |
| 技能 | cua-computer-use | 工作流、可靠性规则、故障排查 |
| 服务 | cuaComputerUse | 解析后的启动参数，供其它行消费 |
| 提示词 | tool:cua-computer-use | 三句话的常驻说明，可用 prompt: false 关闭 |

工具覆盖窗口发现（list_windows、launch_app）、状态读取（get_window_state、get_accessibility_tree）、输入（click、type_text、set_value、press_key、hotkey、scroll、drag）、校验（verify_state）、批量执行（run_steps、run_script）、原生菜单（invoke_menu）、浏览器（get_browser_state、browser_click 等）、窗口几何、录制和诊断。

配置

在 profile 的 cordis.patch.yml 里找到 cua-computer-use 那一行：

- id: cua-computer-use
config:
command: /opt/cua/cua-driver
toolCallTimeoutMs: 180000

| 选项 | 类型 | 默认值 | 说明 |
| command | string | '' | 显式指定路径或命令名。留空则自动发现。显式指定时不会静默回退到别的二进制。 |
| args | string[] | ['mcp'] | 传给可执行文件的参数。 |
| env | object | {} | 追加给 MCP 子进程的环境变量。 |
| cwd | string | '' | 子进程工作目录。留空继承宿主。 |
| toolCallTimeoutMs | number | 120000 | 单次调用超时。默认给得比较宽，因为 GUI 等待和守护进程冷启动都很慢；MCP 客户端自身的默认值是 60 秒。 |
| skill | boolean | true | 是否注册自带技能。 |
| prompt | boolean | true | 是否写入常驻系统提示词。 |
| autoInstall | boolean | true | 缺失时是否自动安装 cua-driver。关闭则直接报错并给出手动命令。 |
| installTimeoutMs | number | 300000 | 安装器超时时间。 |
| installEnv | object | {} | 追加给安装器的环境变量，优先级高于上面的默认值。 |
| installTelemetry | boolean | false | 是否允许安装器上报安装事件。 |
| modifyPath | boolean | false | 是否允许安装器往 shell 配置文件里追加 PATH。 |
| installDir | string | '' | 安装到指定目录，而非安装器默认目录。 |
| permissionCheck | boolean | true | 启动后检查一次 macOS 权限。Windows 与 Linux 会跳过。 |
| permissionPrompt | boolean | true | 是否让驱动弹出 macOS 授权弹窗，每种缺失权限只弹一次。 |

环境变量 CUA_DRIVER_BIN 可以钉死一个绝对路径，优先级高于目录搜索、低于 command。

工作原理

bundle patch 按顺序插入两行：

- insert:
- id: cua-computer-use
name: 'cua-computer-use'

- id: mcp-cua-driver
name: '@deepseek-ai/dsh-mcp-client'
inject: [cuaComputerUse]
config:
serverName: cua-driver
transport: stdio
command: !!js ctx.cuaComputerUse.command
args: !!js ctx.cuaComputerUse.args
env: !!js ctx.cuaComputerUse.env
cwd: !!js ctx.cuaComputerUse.cwd
toolCallTimeoutMs: !!js ctx.cuaComputerUse.toolCallTimeoutMs
failOnStartupError: false

第一行解析二进制路径并把它发布成一个服务；第二行 inject 该服务，因此它的 !!js 配置表达式是在路径已知之后 才求值的。failOnStartupError: false 保证 Cua Driver 装坏了也不会拖垮整个 Harness，而是由 MCP 客户端报告失败。

验证是否生效

重启后直接让模型「列出当前窗口」，或者在终端里检查：

cua-driver --version # 插件会找到的那个二进制 cua-driver doctor # 守护进程与权限健康检查

如果没有出现工具，宿主日志里会有一条 [cua-computer-use] 开头的记录：成功时给出解析到的路径，失败时列出搜索过的每个目录。找不到二进制时动静很大但不致命：插件自己那一行会带着确切的修复方法转为未激活，其余各行照常运行，MCP 行则停在 pending (waiting for service: cuaComputerUse) 而不是直接死掉——装好二进制重启即可。

首次运行应该能看到这类日志：

[cua-computer-use] cua-driver was not found; installing it with the official installer
[cua-computer-use] cua-driver installed: /Users/you/.local/bin/cua-driver
[cua-computer-use] cua-driver: /Users/you/.local/bin/cua-driver (via known-directory)
[cua-computer-use] macOS is withholding Accessibility, so the cua-driver tools will observe but not act.

开发

pnpm install # 仅开发用：TypeScript 类型
pnpm test # node --test，零依赖即可运行
pnpm typecheck

定位模块的文件探测函数和目标平台都是可注入的，因此完整的搜索顺序都能在测试里覆盖，不需要碰磁盘，也不依赖宿主平台。

许可

MIT。Cua Driver 是 trycua 的独立项目，未随本插件分发。