尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

DeepChat 内置 Cua Driver 解析:基于 MCP over stdio 的后台 Computer Use 驱动与 Claude Code 兼容模式

DeepChat 内置 Cua Driver 解析:基于 MCP over stdio 的后台 Computer Use 驱动与 Claude Code 兼容模式 DeepChat 内置 Cua Driver 解析基于 MCP over stdio 的后台 Computer Use 驱动与 Claude Code 兼容模式【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat导读Cua Driver 是一个面向任意 Agent 的“后台”电脑操作computer-use驱动它通过stdio 之上的 MCP 协议对外提供服务能够驱动原生 macOS 应用执行点击、输入、拖拽等 GUI 操作同时不抢占用户的键盘鼠标焦点。本文以 DeepChat 仓库中 vendored 的 Cua Driver 源码 README 为主线讲解其工作原理、Claude Code computer-use 兼容模式的注册与行为差异并结合 DeepChat 官方 CUA 插件 的嵌入式集成方式给出完整的实战落地路径。读完本文你将掌握如何注册一个后台 computer-use MCP 服务器、兼容模式与普通模式的本质区别、以及元素寻址、结果验证与权限策略等关键实现细节。Cua Driver 是什么面向 Agent 的后台桌面自动化驱动Cua Driver 定位为“Background computer-use driver for any agents”。所谓“后台”background体现在两个层面通信后台化Agent 不需要直接操作显示器而是通过标准 MCPModel Context Protocol工具调用来间接控制桌面交互后台化驱动原生应用时不强行抢夺前台焦点用户在操作其他窗口时Agent 仍能在目标窗口中注入输入事件。从仓库中 vendored 的源码目录结构可以清晰地看到它的分层设计plugins/cua/vendor/cua-driver/sourceSources/CuaDriverCore/核心能力层包含应用枚举Apps/AppEnumerator.swift、窗口捕获Capture/WindowCapture.swift、输入注入Input/MouseInput.swift、KeyboardInput.swift、AXInput.swift、焦点保护Focus/FocusGuard.swift、SystemFocusStealPreventer.swift、权限门禁Permissions/PermissionsGate.swift、Agent 光标渲染Cursor/AgentCursor.swift以及录制回放Recording/等模块Sources/CuaDriverServer/MCP 服务层把核心能力暴露为标准工具如ClickTool、TypeTextTool、GetWindowStateTool、ListAppsTool、ZoomTool等Sources/CuaDriverCLI/命令行入口包含ServeCommand以 MCP server 模式运行、ConfigCommand、DoctorCommand、DiagnoseCommand、RecordingCommand等子命令Tests/包含集成测试test_background_focus.py、test_background_menu_shortcut.py、test_hidden_app_capture.py等和单元测试FocusStealPreventerTests、ZoomMathTests。这套架构保证了“不抢焦点”的核心承诺输入事件通过辅助功能AccessibilityAPI 或系统事件接口直接投递给目标窗口而不是通过模拟鼠标移动/键盘激活的方式完成。通信模型MCP over stdioCua Driver 对外暴露的通信协议是MCP over stdio——即标准输入/输出作为 MCP 消息通道这使它可以被任意支持 MCP 的 Agent 宿主直接以子进程方式拉起无需网络端口、无需额外的服务管理。MCP 服务器模式的启动形态是cua-driver mcp。在 DeepChat 的插件集成中这个形态被进一步封装为带--embedded标志的嵌入式启动见 plugins/cua/mcp/cua-driver.json{ id: cua-driver, displayName: CUA Driver, transport: stdio, command: ${runtime.cua-driver.command}, args: [mcp, --embedded], startMode: onDemand, surfaces: [tools], toolCatalog: runtime/${target.platform}/${arch}/tool-catalog.json, inheritEnv: minimal }其中startMode: onDemand表示服务器在第一次工具调用时才被拉起surfaces: [tools]表明只暴露工具面不暴露 prompts / resourcesinheritEnv: minimal表示子进程只继承最小化环境变量——这些约束共同服务于安全与可控的进程生命周期管理。Claude Code computer-use 兼容模式两种注册方式原文档给出了两种 Claude Code MCP 注册方式第一种是标准的 computer-use 驱动注册claude mcp add --transport stdio cua-driver -- cua-driver mcp这条命令把名为cua-driver的 MCP 服务器注册到 Claude Code--transport stdio指定使用 stdio 传输命令本体是cua-driver mcp。第二种是 Claude Code 视觉/computer-use 风格流程的兼容模式claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat与第一种相比差异有三点服务器名改为cua-computer-use并追加了--claude-code-computer-use-compat标志。兼容模式的行为语义兼容模式并不改变 Cua Driver 的绝大多数工具面。按原文档的说明它“保留 CuaDriver 的正常 MCP 工具只改变screenshot”——改造后的screenshot工具必须携带pid和window_id两个参数只捕获指定窗口的画面window-scoped而不是全屏截图。这一行为在 vendored 源码的 ClaudeCodeComputerUseCompatTools.swift 中有完整的对应实现。该文件定义了一个专门的screenshot工具处理器其 inputSchema 声明pid目标进程 IDlist_windows或launch_app返回类型为 integerwindow_id目标 CGWindowID同样来自list_windows或launch_app类型为 integeradditionalProperties: false——不允许额外参数。实现层面该工具会先通过compatWindowContext(forPid:windowID:)在WindowEnumerator.visibleWindows()中查找匹配的“可见的 layer-0 窗口”要求layer 0、isOnScreen且宽高都大于 1找到后调用WindowCapture.captureWindow(windowID:format:quality:)以 JPEG质量 85格式抓取该窗口画面并把结果以 MCPimage内容块base64返回同时附上窗口尺寸与所属应用信息文本。若 Screen Recording 权限未授予则返回CaptureError.permissionDenied对应的错误结果。同时ToolRegistry.claudeCodeComputerUseCompat通过名字去重的方式构造兼容工具注册表先取ToolRegistry.default的所有原生处理器过滤掉与兼容screenshot同名的处理器再追加兼容screenshot。也就是说只有screenshot被替换其余全部工具click、type_text、get_window_state、zoom 等保持原样——这与文档描述完全一致。为什么要用 MCP 而非 CLI 截图原文档特别提醒Claude Code 的视觉/computer-use 风格路径应当走 MCP。原因是 Claude Code 依赖工具名为mcp__cua-computer-use__screenshot的截图作为“图像锚定”image-grounding线索虽然 CLI 截图同样可用作为 CuaDriver 调用但 CLI 方式不会暴露这个mcp__前缀的工具名因而无法被 Claude Code 识别为视觉 grounding 的入口。这是一个工具命名/发现层面的兼容性事实而非能力差异。DeepChat 中的嵌入式集成从 vendored 源码到官方插件DeepChat 并没有让用户手动安装 Cua Driver而是以官方插件 捆绑运行时的方式集成这比原文档展示的“手动注册到 Claude Code”更进一步——用户零配置即可获得 computer-use 能力。运行时钉扎runtime pinplugins/cua/vendor/cua-driver/upstream.json 记录了上游运行时钉扎信息上游仓库子目录libs/cua-driver/rusttagcua-driver-rs-v0.19.2commit20bb34b16ad7c6c56221c332e46b1875e9d8af8c版本0.19.2更新于2026-08-07支持的打包目标darwin/arm64、darwin/x64、win32/x64、win32/arm64、linux/x64明确不支持linux/arm64每个目标都钉扎了 release 归档的 SHA-256 校验和构建期按“下载 → 校验 checksums.txt → 提取 → 校验可执行身份 → 归一化权限”的流程落盘发布策略打包期 stage 上游 release 资产不运行上游安装器也不要求 PATH 中存在运行时二进制。对应的插件侧契约声明见 plugins/cua/plugin.json 的runtime.adapterContractdriverVersion: 0.19.2、contractVersion: 0.6.0、mcpProtocolVersion: 2025-06-18。插件以external-helper类型运行adapter: cua-embedded-v1并带有integrityDescriptor完整性描述文件与跨平台检测路径macOS 的DeepChat Computer Use.app、Windows 的cua-driver.exe、Linux 的cua-driver。从 MCP 到模型可见内容的两层契约在 DeepChat 的适配层中原文档描述的“普通 MCP 工具 修改后的 screenshot”只是底层形态面向模型的可见内容还经过了一层投影。相关规范 docs/architecture/cua-driver-0-17-contract-migration/spec.md 明确了关键约束快照安全寻址原生元素动作click、double_click、right_click、type_text、press_key、set_value、scroll优先使用最近一次get_window_state返回的非空不透明element_token退化方案必须是同一快照结果的element_index snapshot_id成对传入裸的element_index在派发前就被本地拒绝ActionResult 投影成功动作返回封闭的ActionResult结构包含必填的effectconfirmed/partial/unverifiable/suspected_noop/refused与route等字段。confirmed只代表驱动有动作级证据不代表用户任务完成refused即使外层传输成功也视为失败verify_state 投影只投影聚合statussatisfied/unsatisfied/unknown、stable、elapsed_ms、samples及至多 8 个谓词结果unknown永远不算成功截图受控只有调用方显式传include_screenshot: true时才发送截图用于视觉锚定常规无障碍树重索引用include_screenshot: false避免把图像数据无谓地送入模型。这些约束在原文档的兼容模式之上进一步界定了“投递 ≠ 生效 ≠ 任务完成”的三级语义是整个 computer-use 工作流可靠性的基础。完整工作流从会话开始到验证收尾仓库中随插件提供的技能文档 plugins/cua/skills/computer-use/SKILL.md 给出了标准执行循环可视为 Cua Driver 工具面的实战用法清单建立会话start_session({ session, capture_scope: auto })声明一次稳定的运行身份之后所有状态与动作调用复用同一session解析目标应用list_apps匹配本地化名称、英文名、bundle id、可执行名与常见缩写优先使用返回的稳定标识启动/复用launch_app拿到返回的pid枚举窗口必要时list_windows({ pid })获得window_id动作前快照get_window_state({ pid, window_id, session })首次或目标不明确时传include_screenshot: true执行动作click、double_click、right_click、drag、scroll、type_text、press_key、hotkey、set_value、set_window_frame、invoke_menu等读取动作结果若返回## CUA action result按其effect判定投递效果partial/unverifiable/suspected_noop/refused都不得当作成功继续动作后验证能用窗口存在/边界或原生元素存在/值/启用/选中谓词表达时用verify_state否则取新的get_window_state/get_browser_state/get_desktop_state观察可见证据收尾end_session({ session })包括错误清理路径。对 Chromium 系页面内容技能文档建议先以get_browser_state绑定精确原生窗口再使用类型化的browser_*工具browser_navigate、browser_click、browser_type等兼容性的page工具仅作过渡。录制工作流则使用start_recording/stop_recording/get_recording_state/replay_trajectoryinstall_ffmpeg仅在用户明确批准后调用。权限与安全策略Cua Driver 的权限模型分为两层。插件级工具策略plugins/cua/policies/tool-policy.json将全部工具分为三类allow自动放行只读的发现与状态类工具如list_apps、list_windows、get_window_state、verify_state、get_screen_size、check_permissions、start_session、end_session等ask需用户确认所有会产生可见影响的动作如click、type_text、press_key、hotkey、launch_app、bring_to_front、set_window_frame、invoke_menu、set_config、start_recording、replay_trajectory、browser_*系列等deny明确拒绝debug_window_info、clipboard_read、kill_app、mouse_button_down、mouse_button_up、mouse_drag。其中clipboard_read被拒绝是因为剪贴板明文属于隐私敏感数据而当前并无经过审查的模型/转写保留路径kill_app被拒绝则因其公开 schema 不包含session标准模式无法证明所有权——DeepChat 要求走协作式关闭路径如 macOS 的 Command-Q。系统级权限macOS 上通过check_permissions检查辅助功能Accessibility与屏幕录制Screen Recording授权。由于嵌入式守护进程是 DeepChat 的直接子进程权限授予对象是已签名的 DeepChat 宿主应用用户无需向第二个 helper 身份授权。集成测试与验证仓库在 plugins/cua/vendor/cua-driver/source/Tests 下提供了覆盖上述行为的测试单元测试FocusStealPreventerTests防焦点抢占、ZoomMathTests缩放坐标数学集成测试test_background_focus.py、test_background_menu_shortcut.py、test_hidden_app_capture.py后台捕获、test_click_opens_new_window.py、test_drag_slider_delivery.py投递语义、test_electron.py/test_chrome.py/test_safari.py/test_webkit_js.py各渲染引擎以及配套的harness/driver.py、monitor.py、tree.py测试框架跨平台行为规范见 docs/features/cua-cross-platform-computer-use/spec.md该文档明确了 Linux 支持仍属 pre-release部分合成器/会话/后台交互可能不可用原生 Wayland 可能拒绝语义窗口框或修改指针输入并强调“Linux arm64 在任何情况下都不视为支持”。小结Cua Driver 提供了一条务实、可落地的 Agent 桌面自动化路径stdio 之上的 MCP让任何 Agent 宿主都能零网络配置地接入后台驱动设计让它不干扰用户正在进行的操作Claude Code 兼容模式则通过只替换screenshot工具、并要求pidwindow_id的窗口级捕获精准契合 Claude Code 视觉/computer-use 流程的图像锚定需求。在 DeepChat 中这一能力被进一步封装为钉扎版本、受完整性校验、按需启动的嵌入式插件配合快照安全寻址、ActionResult 三级语义与严格的工具策略构成了一个既可用又可控的 computer-use 运行时。若要在其他 Agent 宿主中复用只需遵循claude mcp add --transport stdio ...两条注册命令之一即可而 DeepChat 内置插件则无需任何手动配置。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表