Qwen Code Computer Use Skill 集成解析：从内建工具到 Skill + MCP 的架构转型

Qwen Code Computer Use Skill 集成解析：从内建工具到 Skill + MCP 的架构转型

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

导读

本文基于 Qwen Code 仓库中的 Computer Use Skill Integration 设计文档，系统梳理该项目将"计算机使用（Computer Use）"能力从内建工具集重构为"捆绑 Skill + 外部 MCP 服务"的完整架构决策。你将理解新的调用链（Skill → Node REPL MCP → 模型编写的 JavaScript → CUA SDK → 原生驱动）、自动引导（bootstrap）机制、运行时契约、独立版本发布流程以及范围守卫与验收标准，并看到这些决策在仓库源码中的落地证据。

一、架构决策：Qwen Code 只保留一个 Computer Use 构件

设计文档开篇即明确了本次架构调整的核心决策：Qwen Code 只捆绑一个 Computer Use 构件，即computer-useSkill，其余一切内建实现全部移除。

重构后的端到端调用链如下：

user task -> bundled computer-use skill -> skill-installed @qwen-code/node-repl-mcp -> model-authored JavaScript -> skill-installed @qwen-code/cua-sdk/computer-use -> native cua-driver accessibility backend

这条链路清晰地划定了各层职责：

1. 用户任务由捆绑的computer-useSkill 承接；
2. Skill 依赖通过skill-installed方式安装的@qwen-code/node-repl-mcp（Node REPL MCP 服务）执行模型编写的 JavaScript；
3. 模型代码通过@qwen-code/cua-sdk/computer-use的类型化接口驱动底层自动化；
4. 最终落到cua-driver 原生无障碍（accessibility）后端执行真实 GUI 操作。

与之相对，旧的内建 Computer Use 工具、设置项、Schema、下载器、权限引导逻辑和直接运行时全部被移除，且不再提供模式切换（mode switch）、捆绑 SDK、原生负载暂存（native payload staging）或回退路径（fallback path）。

佐证：仓库中保留的 2026-05-28-computer-use-built-in.md 是一份明确标注为"历史方案"的实现计划（旧架构为"内建 9 个computer_use__*工具 +npx open-computer-use薄壳"），其开头即声明"superseded by Computer Use Skill Integration，不得作为当前运行时或发布指引使用"，与本文档形成新旧架构的对照。

1.1 旧架构在配置层面的遗留痕迹

在 settingsSchema.ts 的工具延迟加载说明中仍可见旧架构的引用：工具白名单描述中提到"computer_use__*tools are unaffected"（不受工具延迟机制影响）。这属于旧内建工具时代的配置语义残留，从侧面印证了本次变更的删除范围之广——连配置 Schema 中的相关入口都需要被清理干净（见下文"范围守卫"）。

二、自动引导（Automatic Bootstrap）：Skill 自举缺失的外部依赖

既然 Qwen Code 核心不再捆绑 Node REPL 服务与 CUA SDK，那么首次使用时的依赖从何而来？答案是Skill 自身执行引导：

• 当node_repl不可用时，Skill 会运行精确版本化的qwen mcp add命令和 workspace 本地 SDK 安装命令来完成依赖安装；
• 由于添加 MCP server 会修改用户配置，且需要重启 Qwen Code 才能生效，Skill 会明确告知用户重启，并在下一个会话中继续执行桌面任务；
• SDK 从Node REPL 所使用的 workspace中解析。若node_repl已可用但动态导入（dynamic import）失败，Skill 会运行 SDK 安装命令并重试导入；
• Qwen Code 自身对这两个包（@qwen-code/node-repl-mcp与@qwen-code/cua-sdk）均无任何依赖。

2.1 边界设计意图：让安装过程对用户可见

文档强调，这种边界设计刻意将以下环节的控制权保留在用户视野内：

• 安装（install）：由 Skill 显式触发，而非随 Qwen Code 安装静默捆绑；
• 信任（trust）：外部 MCP server 是否被信任由用户决定；
• 磁盘占用（disk use）：原生下载按需发生；
• 平台权限（platform permissions）：如 macOS 的无障碍（Accessibility）与屏幕录制（Screen Recording）授权，走外部驱动自身的授权流程。

也就是说，新架构把"装什么、信什么、占多少磁盘、授予什么系统权限"这些敏感操作全部从 Qwen Code 的安装包中剥离，交给运行时按需、可见地完成。

2.2 落地包形态：独立的 Node REPL MCP 包

@qwen-code/node-repl-mcp在仓库中是一个完全独立的 workspace 包，其 package.json 显示：

• 版本0.1.3（独立于 cua-driver 与 cua-sdk 的发布节奏，即文档所述的"版本独立"）；
• bin入口为node-repl-mcp（dist/index.js），可被任何 MCP 客户端直接拉起；
• 要求node >= 22，仅依赖@modelcontextprotocol/sdk、tree-sitter-wasms、web-tree-sitter、zod，不依赖 qwen-code 核心包；
• 包描述明确写着"Standalone MCP server exposing a session-persistent Node.js REPL (node_repl) — independent of qwen-code core"。

从 node-repl 目录 的结构看，该包自带完整的 kernel 管理、单元转换、协议、安全策略与测试，例如kernel-manager.ts、cell-transform.ts、security-policy.ts及对应的.test.ts，并提供了scripts/mcp-smoke.mjs（真实 MCP 客户端对 stdio server 的冒烟测试）等验证脚本。

三、运行时契约：外部 MCP 服务持有内核，模型只碰类型化接口

3.1 职责边界

文档为运行时契约划定了三条硬性边界：

1. 外部 MCP server 拥有持久化 Node.js 内核及其生命周期——Qwen Code 不参与内核的创建、复用与销毁；
2. 模型只能使用动态导入（dynamic imports）和类型化的ComputerUse方法——不允许直接分发任意的驱动工具名，也没有 Qwen 特有的全局桥（global bridge）；
3. Qwen Code 仅作为 MCP 客户端接入，内核的清理（如 stdin EOF 触发 shutdown）由 Node REPL 服务自己负责。

3.2 源码佐证：Node REPL MCP 的独立生命周期管理

在 packages/node-repl/src/index.ts 的入口实现中可以看到这一契约的落地细节：

• 服务通过StdioServerTransport以 stdio 方式对外提供 MCP 能力；
• 代码显式注释了生命周期设计："A stdio MCP host signals shutdown by closing our stdin. The SDK's stdio transport only listens for 'data'/'error', so without these the server and its kernel child would survive every host restart."——即服务监听 stdin 的end/close事件主动关闭自身，并释放内核子进程；
• 同时处理SIGINT、SIGTERM、SIGHUP等信号，保证宿主重启后不会残留孤儿内核进程。

这与文档"外部 MCP server 拥有内核生命周期"的契约完全一致：内核生灭完全由独立服务自治，Qwen Code 只消费其 MCP 工具面。

3.3 引导后的工作流：与 Codex Computer Use Skill 对齐

文档明确：引导完成后，Skill 遵循与Codex Computer Use Skill相同的标准工作流：

1. 观察目标应用（observe the target application）——先获取当前 UI 状态；
2. 优先使用语义元素而非坐标（prefer semantic elements over coordinates）——基于无障碍树中的语义 token 操作，而非硬编码像素坐标；
3. 通过类型化 SDK 执行动作（act through the typed SDK）；
4. 每次变更后拉取最新状态（fetch fresh state after every mutation）——保持"快照-动作-验证"循环中的状态新鲜度；
5. 当无障碍文本不足时使用截图（use screenshots when accessibility text is insufficient）；
6. 任务结束时清理（clean up when the task finishes）。

对照佐证：cua-driver 自带的 cua-driver SKILL.md（版本 0.20.5）同样强调"snapshot-before-action invariant is not optional"（动作前快照是不容跳过的不变量），与本文档"observe → act → fetch fresh state"的工作流在底层驱动层面互相印证。

3.4 双重视角下的安全边界

文档强调安全分层：MCP approval policy（审批策略）守卫模型编写的 JavaScript；而 SDK 与原生驱动保留各自的授权与平台权限行为。移除内建运行时并不会削弱任何一层的边界——相反，两层安全机制各自独立、互不耦合：

• 第一层：Qwen Code 的 MCP 工具审批策略决定是否允许执行node_repl相关调用；
• 第二层：@qwen-code/cua-sdk/computer-use与 cua-driver 自身的授权/权限体系决定驱动层是否放行具体操作。

从 cua-driver 的 cli.rs 可以看到驱动层保留了完整的 CLI 与 MCP 双形态（如--claude-code-computer-use-compat兼容表面），说明驱动层的授权与平台权限行为确实独立于 Qwen Code 存在。

四、发布机制：独立版本、独立发布、不重建驱动

4.1 版本独立策略

@qwen-code/node-repl-mcp是一个独立的 npm 包。虽然它由现有的 CUA SDK 发布工作流负责发布，但其版本号独立于@qwen-code/cua-sdk和 cua-driver 的发布节奏（前文已见其当前版本为 0.1.3），从而允许 Node REPL 包按自身节奏演进，不随驱动升级而被迫发版。

4.2 五步发布工作流

文档给出了完整流程：

1. 构建、类型检查、测试并打包Node REPL 包；
2. 干净安装 tarball 并驱动其真实 stdio MCP 表面（即对打包产物做端到端冒烟）；
3. 校验包内容；
4. 执行不可变 npm 检查（immutable npm check）并带 provenance（来源证明）发布；
5. 支持Node-REPL-only 的引导分发（bootstrap dispatch），避免为已有的不可变 cua-driver 发布重建一个发布。

最后一项的意义在于：当只需要发布 Node REPL 包时，工作流不会触碰 cua-driver 的既有发布产物，保持发布幂等与最小化。

4.3 干跑（Dry-run）行为

文档特别说明：Dry-run 只执行构建与包校验路径，不会发布任何 npm 包，也不会创建/替换 GitHub Release。这与仓库内verify-package.mjs等校验脚本的定位一致——发布前对 tarball 内容做完整性核验，杜绝"未验证即发布"。

4.4 冒烟测试佐证

node-repl 包的 package.json 中的脚本进一步印证了发布前验证矩阵：

• smoke：进程内 kernel manager + output adapter 验证；
• smoke:mcp：真实 MCP 客户端 ↔ 构建后的 stdio server；
• smoke:lifecycle：验证 stdin EOF / 信号触发时内核子进程被正确回收（reap）。

其中smoke:lifecycle直接对应上文"内核生命周期由外部服务自治"的契约，从测试层面保证宿主退出后无孤儿进程。

五、范围守卫：明确"不做"清单

为了杜绝架构回退或隐藏残留，文档用五个"不做"锁定了变更边界：

1. 不在 Qwen Code 内部注册 MCP server；
2. 不把@qwen-code/node-repl-mcp或@qwen-code/cua-sdk加入 Qwen 运行时依赖；
3. 不将 CUA 原生资源暂存进 npm、standalone、Desktop 或 VSIX 制品；
4. 不改变 cua-driver 契约或 SDK 行为（即本次是纯消费侧重构，驱动层零改动）；
5. 不保留被移除的内建 Computer Use 实现的隐藏副本。

这些约束保证了：Qwen Code 的安装包体积、依赖图、原生资产与驱动契约均不受影响；旧的computer_use__*内建工具、设置、Schema、下载器与直接运行时在代码库中彻底消失，而不是被隐藏式保留。

六、验收标准：变更何时算完成

文档给出了可操作的完成定义（Definition of Done），可作为回归测试与发布的检查清单：

1. 捆绑的 Skill 通过校验且可被发现（discoverable）；
2. 不存在任何旧的 Computer Use 工具、设置、Schema、下载器或直接运行时残留；
3. Qwen Code 的安装制品中不捆绑 Node REPL server 或 CUA SDK 负载；
4. 一个真实的桌面任务能够触发 Skill 引导缺失的外部包，然后在提示词完全不提及实现细节的情况下，完成一次真实的"观察（observe）→ 动作（action）→ 验证（verification）→ 清理（cleanup）"全流程；
5. CUA 发布工作流 dry-run能验证独立版本化的 Node REPL tarball 而不实际发布。

其中第 4 条尤其值得注意：它要求端到端测试时模型只凭自然语言完成任务，禁止在提示词中暴露node-repl-mcp、cua-sdk、cua-driver 等实现细节——这正是"Skill 封装内部实现、对用户与模型透明"这一设计目标的行为化验收。

七、总结与工程启示

本次 Computer Use Skill 集成设计体现了三个值得借鉴的工程原则：

• 职责下放与解耦：GUI 自动化能力从"Qwen Code 内建工具"下沉为"捆绑 Skill + 外部 MCP 服务 + 独立 npm 包"，Qwen Code 核心保持零依赖、零原生资产；
• 可见性与信任边界：安装、信任、磁盘占用、平台权限等敏感行为全部按需、显式地暴露给用户，而不是被安装包静默承担；
• 可验证性：从 Skill 可发现性、旧代码零残留、真实任务端到端跑通，到发布工作流 dry-run，每一项都有可操作的验收标准。

对于希望二次开发或深度集成的读者，建议按以下路径继续阅读仓库源码：

• 设计源头：docs/design/2026-08-23-computer-use-skill.md；
• 旧架构对照（已废弃）：docs/plans/2026-05-28-computer-use-built-in.md；
• 独立 MCP 包：packages/node-repl/README.md 与 packages/node-repl/src/index.ts；
• 原生驱动层：packages/cua-driver/rust/Skills/cua-driver/SKILL.md。

需要注意的是，本文描述的是当前仓库的设计与实现事实：@qwen-code/node-repl-mcp以独立包形态存在于 packages/node-repl，其运行前提为 Node.js ≥ 22；实际使用时需通过qwen mcp add或 MCP 客户端配置按需引入，并遵循各平台对自动化驱动的授权要求。

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