企业官网建设流程全解析

Qwen Code Computer Use 实战指南：用computer-use技能驱动桌面应用

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

Qwen Code 内置的computer-use技能教会模型如何像人类一样操作桌面应用——读取应用 UI、定位元素、点击输入，全程由模型自主编排。本文以 Qwen Code 仓库中的 computer-use.md 为骨架，结合 @qwen-code/cua-sdk/computer-use 的实现与类型定义，讲清它的组件架构、自动安装流程、macOS App 工作流、权限模型与故障排查，读完即可在自己的终端环境中跑通桌面自动化任务。

组件架构：技能 + MCP + SDK + 原生驱动的分层调用链

computer-use技能不是一个单体程序，而是一条分层的调用链，从模型侧的技能文件一直延伸到操作系统的原生无障碍（Accessibility）后端：

bundled computer-use skill -> @qwen-code/node-repl-mcp -> @qwen-code/cua-sdk/computer-use -> native cua-driver accessibility backend

各层职责如下：

关键设计点是：Qwen Code 本体并不打包 MCP 服务器、SDK 或原生驱动。技能在首次使用时自动安装缺失的外部包（见下一节），仓库中只维护技能的编排逻辑与 SDK 的 TypeScript 类型/包装层（packages/cua-driver/typescript/computer-use 目录下含 facade、App 包装与测试）。

[!warning] Computer Use 可以读取应用 UI 并控制鼠标键盘输入。请只在可信环境中使用，并仔细审查 MCP 审批请求。

自动安装：一条命令链完成引导

使用前置条件：Node.js 22 或更高版本以及 npm。

首次使用技能时，技能本身会自动执行以下两条命令完成环境引导：

qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.4 npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.6

• 第一条命令把node-replMCP 服务器以user作用域注册进 Qwen Code，模型后续通过node_repl工具执行 JavaScript；
• 第二条命令把@qwen-code/cua-sdk@0.20.6安装到当前工作区的node_modules。

两条命令的行为细节值得注意：

1. 需要重启：MCP 服务器首次添加后，必须重启 Qwen Code；重启后技能通过node_repl恢复执行桌面任务；
2. SDK 安装是"非侵入式"的：--no-save --package-lock=false保证package.json与 lockfile 不被改动，但会真实写入工作区的node_modules；
3. 原生载荷在 postinstall 下载：SDK 安装后的 postinstall 会下载并校验当前平台对应的原生 cua-driver 载荷；
4. 无降级回退：一旦移除 MCP 配置或工作区 SDK 安装，执行路径即被禁用，不存在遗留的 fallback 路径。

安装完成后可用qwen mcp list验证node_repl服务器是否在线。

使用：macOS 上的 App 工作流

让模型执行桌面任务时，直接要求 Qwen Code 使用$computer-use即可。引导完成后，在 macOS 上它会走 App 工作流，循环如下：

1. 通过computer.getApp(nameOrIdentifierOrPath)绑定应用（按名称、Bundle Identifier 或安装路径）；
2. 读取app.getState()获得紧凑的无障碍文本，随后自动获得增量更新；
3. 基于文本中的短元素 ID（short element ID）执行一个或多个动作；
4. 每次决策前重新获取最新状态；
5. 仅在不再需要其他持久状态时，才关闭 SDK 客户端并重置 REPL。

以下是从 computer-use.md 继承的最小可用示例，它展示了"绑定 → 观察 → 点击 → 输入 → 再观察"的完整闭环：

const app = await computer.getApp('Microsoft Excel'); nodeRepl.write((await app.getState()).text); // Use an element ID from the returned state. await app.click(37); await app.typeText('hello'); nodeRepl.write((await app.getState()).text);

状态观察的语义约束

• 观察即截屏：每次 App 状态刷新都会在内部捕获当前截图，默认返回时隐藏；仅当模型确实需要图像时，才用app.getState({ includeScreenshot: true })显式请求；
• 对话框后必须刷新：打开或关闭对话框、sheet 或菜单后，先重新getState()再复用元素 ID，因为进程/窗口/会话变化会使旧 ID 失效；
• 文本预算：App 文本默认上限 12000 字符，可通过maxTextChars（最小 512）调整；需要更多全文时用app.getState({ disableDiff: true, maxTextChars: 24000 })，截断时文本末尾会给出警告与截断说明。

输入投递的安全边界

• 驱动是唯一计算观察差异（diff）的组件：模型代码只使用类型化 SDK 方法，不直接派发任意驱动工具名，这与设计文档 computer-use-text-operations.md 中"单一技能入口根据驱动工具清单选择平台文档"的约束一致；
• App 句柄内部持有目标窗口与对话框：它跟踪当前窗口、维护原生元素身份，并把输入委托给原生驱动，模型代码不能选择前台/后台投递模式；
• 不确认的动作绝不重放：失败、部分成功、无法验证或已取消的"可能已派发"动作不会被重放，出错时要求先重新观察再重试；
• getState()可唤醒已发现但停止的应用（通过原生后台启动器），但动作永远不会重启应用；
• Windows 和 Linux 上，既有的"精确窗口"（exact-window）API 依然可用，工作流走listApps → listWindows → observeWindow → 按 elementToken 动作的路径（完整示例见 README.md）。

权限模型：MCP 审批 + 原生授权双层机制

node-repl本身就是一个 MCP 服务器，它以普通 Node.js 权限执行模型编写的 JavaScript，其调用遵循 Qwen Code 常规的 MCP 审批流；同时 SDK 层还会再执行一次原生授权校验，形成双层防线。

操作系统层面的权限要求（macOS）：

• 无障碍（Accessibility）权限：无障碍观察与输入所必需；
• 屏幕录制（Screen Recording）权限：截图功能所需；
• macOS 可能把授权归属到启动 Qwen Code 的终端或 IDE 进程，注意在系统设置中把授权授予正确的主体；
• Windows 与 Linux 分别使用各自的平台无障碍与输入设施（对应 cua-driver 下的platform-windows、platform-linuxcrate）。

交付模式（delivery mode）在 SDK 层的解析顺序是：动作显式deliveryMode→ 环境变量QWEN_CUA_SDK_DEFAULT_DELIVERY_MODE（background/foreground）→ 默认background。环境变量适合让整个隔离进程（如测试 worker）统一使用前台投递，单动作显式值仍可覆盖它；非法环境变量值会使 facade 创建失败。

平台路由：macOS 与 Windows/Linux 的分工

设计文档 computer-use-text-operations.md 明确了平台分流的元数据机制：computer.getPlatform()返回macos、windows或linux，它来自已连接驱动的工具清单，不推断自 CLI 或 Node 宿主，也不捕获桌面；元数据缺失或非法时会显式失败。

• macOS：走 App 工作流（App 句柄 + 紧凑状态 + 文本操作）；
• Windows/Linux：保留"精确窗口"工作流（按pid+windowId+elementToken寻址）。

macOS 独占的文本操作包括app.paste(text, { format: 'text' | 'md' | 'html' })（粘贴一次，仅在仍持有剪贴板变更计数时恢复快照，外部剪贴板改动必须幸存）与app.selectText(element, text, { prefix, suffix, selection })（在可观察元素内选择唯一、区分大小写的精确匹配；selection默认为text，另有cursor_before/cursor_after放置插入点）。这两个方法在非 macOS 驱动上会在变更前直接拒绝。从源码结构看，SDK 的类型定义（index.d.ts）中PasteOptions与TextSelectionOptions与文档描述一一对应。

Troubleshooting 速查

• node_repl不可用：自动安装后仍不可用，先重启 Qwen Code，再用qwen mcp list确认服务器已注册且在线；
• SDK 导入失败：确认 Qwen Code 是在安装了 SDK 的那个工作区中启动的（SDK 安装位置是工作区node_modules，跨工作区不可见）；
• 超时/取消/重置/内核崩溃之后：重新引导 SDK 客户端并请求全新状态——旧元素 ID 已失效，不要复用。

更多关联能力可继续阅读 Skills 技能、MCP 服务器、审批模式 与沙箱 文档。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code