DeepChat CUA 跨平台 Computer Use 插件：从 macOS 单平台到多平台打包的完整实施计划

DeepChat CUA 跨平台 Computer Use 插件从 macOS 单平台到多平台打包的完整实施计划【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat本文基于 DeepChat 仓库中 CUA 跨平台 Computer Use 实施计划 展开梳理了官方 CUAComputer Use Agent插件从 macOS-only 扩展到 darwin/win32/linux 多平台的完整方案设计原则、插件清单改造、上游元数据固定、运行时 staging 流水线、打包验证、CI 发布工作流与技能文档适配。读完本文你可以理解 DeepChat 如何以构建期下载、校验和固定、失败即关闭fail closed的方式集成第三方驱动二进制并能复现对应的构建与验证命令。需要说明的是该计划文档本身是一份面向 0.7.1 驱动版本的历史实施计划仓库当前的驱动固定版本与验收细节以后续 插件外部运行时生命周期架构文档 为准。背景与定位DeepChat 对 CUA 的集成模型DeepChat 把 computer use 能力作为一个官方插件交付插件位于 plugins/cua。从 插件清单 可以看到当前集成模型的核心要素插件声明了一个 Skillskills/computer-use/SKILL.md和一个内置工具服务器mcpServers中的cua-driverstdio 传输、startMode: onDemand由 DeepChat 按需启动运行时二进制通过runtime.detect候选列表定位插件本地候选优先用户在 DeepChat 中使用时不需要自行配置外部 MCP 服务器、不需要把驱动装进PATH。这个官方插件 技能 DeepChat 托管启动的模型是跨平台改造的前置约束。计划文档在设计原则中明确不改变 DeepChat 的集成模型只是把原来 macOS-only 的 Swift 构建路径替换为基于上游 Rust 驱动发布产物的多平台 staging 流水线。设计原则五条不可动摇的约束计划文档给出的设计原则是整个跨平台方案的纲领直接决定了后续每个环节的实现方式集成模型不变保持官方插件、技能、DeepChat 托管工具启动的既有架构上游产物视为不可变输入通过 tag、commit、资产名、校验和checksum四重固定上游 CUA 发布产物失败即关闭fail closed当目标运行时不可用、或归档布局与预期不符时构建必须失败而不是降级继续避免运行时网络活动所有下载都发生在构建期build time用户机器上的 DeepChat 不在运行时拉取驱动打包验证贴近产物校验对象是实际产出的.dcplugin文件而不是仅检查源码目录。其中第 4 条解释了为什么仓库里存在构建期下载脚本而不是运行时安装逻辑第 3 条则体现在 scripts/build-cua-plugin-runtime.mjs 中大量缺文件即抛错的断言上例如stageWindowsRuntime中找不到cua-driver.exe会直接抛出CUA Windows archive is missing cua-driver.exe。目标平台矩阵支持谁、隐藏谁计划将插件支持范围从 macOS-only 扩展为五个目标平台架构处理方式darwinarm64打包并验证 CUA 运行时darwinx64打包并验证 CUA 运行时win32x64打包并验证 CUA 运行时win32arm64打包并验证 CUA 运行时linuxx64打包并验证 CUA 运行时linuxarm64不支持不打包、不显示直接请求时明确报错这里有一个容易被忽略的细节可见性是 target平台架构级别的不是平台级别的。插件清单 中engines.platforms只列出操作系统维度不足以表达Linux 可用但 Linux arm64 不可用这种约束因此engines.targets显式列出五个受支持的platform/arch组合engines: { deepchat: ${app.version}, platforms: [darwin, win32, linux], targets: [darwin/arm64, darwin/x64, win32/x64, win32/arm64, linux/x64] }配套要求是为linux/arm64增加架构感知的可见性门控使其不会把 CUA 显示为可用的官方插件同时缺失的 Linux arm64 运行时在设置界面中要报告为不受支持而不是安装损坏。插件清单plugin.json的改造要点计划要求对plugins/cua/plugin.json做如下修改仓库当前清单可以印证这些要求的落地形态运行时候选改为平台感知。当前runtime.detect数组按平台给出候选路径detect: [ app-helper:DeepChat Computer Use.app/Contents/MacOS/deepchat-cua-driver, plugin:runtime/darwin/${arch}/DeepChat Computer Use.app/Contents/MacOS/deepchat-cua-driver, plugin:runtime/win32/${arch}/cua-driver.exe, plugin:runtime/linux/${arch}/cua-driver ]计划明确要求插件本地候选优先plugin-local runtime candidates first外部候选只用于诊断或开发。打包下载 URL 包含目标平台与架构。当前清单中source.url形如${github.release.download}/deepchat-plugin-cua-${app.version}-${target.platform}-${arch}.dcplugin即每个平台/架构一个独立产物。工具策略随上游版本更新。清单中toolPolicies为每个 CUA 工具显式指定allow/ask/deny策略例如list_apps、get_window_state为allowclick、type_text等为askkill_app、clipboard_read为deny计划要求这些策略与固定版本的工具面完全对齐且任何没有策略的新上游工具在测试中应视为审查失败。内部工具服务器声明仍归插件宿主所有不向用户暴露 MCP 配置入口不添加用户可见的 MCP 安装说明。上游元数据固定upstream.json计划要求在plugins/cua/vendor/cua-driver/upstream.json中把旧的 Swift 分支元数据替换为固定的 Rust 驱动发布元数据。0.7.1 时期的固定值为source上游trycua/cuatagcua-driver-rs-v0.7.1commit7caf72bee2286f47a985c3121b56aaabdebd62b9version0.7.1附带预期的资产映射asset map与校验和来源记录 Windows arm64 受支持、Linux arm64 不受支持从源码结构看scripts/build-cua-plugin-runtime.mjs 的readUpstreamMetadata()函数强制要求元数据包含sourceKind、upstreamRepo、tag、commit、version、updatedAt、releaseUrl、checksumsAsset、checksumsSha256等字段且checksumsSha256必须是合法的 64 位十六进制串每个资产都要带sha256——这正是四重固定在构建脚本中的强制校验。需要注意版本演进当前仓库 CUA 规格文档 已将固定版本推进到驱动0.19.2、内嵌契约0.6.0并同步到 插件清单 的runtime.adapterContractdriverVersion: 0.19.2、contractVersion: 0.6.0、mcpProtocolVersion: 2025-06-18。运行时 Staging 流水线十条构建步骤这是计划的核心章节。原 macOS-only 的 Swift 构建路径被替换为如下十步 staging 流水线对应 scripts/build-cua-plugin-runtime.mjs 的main()流程从 CLI 参数--platform/--arch或宿主默认值解析目标平台与架构把受支持的 DeepChat 平台/架构目标映射到上游资产名脚本中即targetAssetKeys映射表darwin/arm64 → darwin-arm64、win32/x64 → windows-x64等把上游发布归档与checksums.txt下载到缓存目录校验归档摘要脚本执行双层校验先对checksums.txt本身比对元数据中的checksumsSha256再按checksums.txt内容校验归档最后再比对资产级sha256解压到临时 staging 目录zip 用fflate在内存中解包并做路径穿越防护拒绝绝对路径、..、盘符形式的路径校验解压后的布局把规范化后的运行时文件拷入plugins/cua/runtime/platform/arch为 macOS 和 Linux 设置可执行权限chmod 0o755在宿主平台能够执行目标二进制时运行--version冒烟检查对 darwin 目标运行 macOS app bundle 与签名检查。几个值得展开的实现细节不支持的目标提前拒绝脚本的getTarget()在映射表之外直接抛出CUA plugin runtime target target is unsupported/unknown且发生在任何部分运行时被 staging 之前符合 fail closed 原则平台专属 staging 逻辑stageWindowsRuntime只拷贝cua-driver.exe并删除cua-driver-uia.exeDeepChat 不打包可选的未签名 UIAccess 辅助程序stageLinuxRuntime拷贝cua-driver并置0o755macOS 则把上游CuaDriver.app重命名规范化为DeepChat Computer Use.app、可执行文件改为deepchat-cua-driver避免与上游命名冲突同时剔除仅用于创作的cua-cursor-theme附属可执行文件并清除旧签名宿主可执行性守卫canRunTarget()只在process.platform/arch与目标一致时才真正执行--version冒烟检查否则打印跳过日志。Linux 上还专门处理了 glibc 版本不匹配的场景——isLinuxGlibcLoaderMismatch()识别GLIBC_x.x ... not found输出将其降级为警告而非构建失败保证老 glibc 的 Linux 构建机仍能完成校验和、布局、文件存在性与权限检查macOS 深度校验darwin 目标会用lipo校验架构、用otool检查链接库与 RPATH 是否只剩系统路径enforceDarwinLoadPathContract必要时用lipo -thin拆分架构逐个清洗后重新合并最后再走 scripts/sign-cua-helper.mjs 完成签名工具目录生成staging 完成后会在原生目标上执行dump-docs --type mcp生成tool-catalog.json并校验其版本与固定版本一致。静态目录让 CUA 工具在未真正打开桌面连接的情况下即可被发现。插件打包只带当前目标的运行时计划对 scripts/package-plugin.mjs 的改造要求移除 darwin-only 的 CUA 保护逻辑.dcplugin产物中只保留所选runtime/platform/arch子树而不是整个 runtime 目录把打包后清单的engines.targets收窄为该产物自身的单个platform/arch目标防止目标产物被发现在错误的架构上side-by-side artifacts cannot be discovered on the wrong architecture按目标校验必备文件macOS 校验 helper app 可执行文件Windows 校验cua-driver.exeLinux 校验cua-driver在 POSIX 归档条目上保留可执行位平台/架构维度的源码清单水合hydration必须保持确定性。这些约束有对应的自动化验证仓库中存在针对打包合同与 CUA 产物结构的脚本测试如 test/main/scripts/packagePlugin.test.ts、test/main/scripts/packageContract.test.ts 和 test/main/scripts/buildCuaPluginRuntime.test.ts以及运行时的 test/main/plugin/pluginService.test.ts。构建脚本与打包命令package.json 的脚本组织体现了计划的每个受支持平台一条显式命令的要求。CUA 专用的 staging 命令pnpm run plugin:cua:build:mac:arm64 # darwin/arm64 pnpm run plugin:cua:build:mac:x64 # darwin/x64 pnpm run plugin:cua:build:win:x64 # win32/x64 pnpm run plugin:cua:build:win:arm64 # win32/arm64 pnpm run plugin:cua:build:linux:x64 # linux/x64应用级构建脚本如build:win:arm64、build:linux:x64中内嵌了plugin:bundle -- --name cua --platform p --arch a步骤而build:linux:arm64有意不包含CUA bundle 步骤只打包 feishu 插件——这与Linux arm64 不产出、不显示 CUA的验收标准一一对应。计划还提出一条工程性要求避免重复 staging。当plugin:bundle已经调用过构建脚本时要么让构建脚本在目标运行时已是最新时保持幂等且廉价要么显式拆分 staging 与 bundling 两个阶段。CI 与发布工作流要求计划要求更新构建与发布工作流当时指向.github/workflows/build.yml与release.yml在 macOS arm64/x64 上打包并验证 CUA在 Windows x64 与 arm64 上打包并验证 CUA在 Linux x64 上打包并验证 CUA在 Linux arm64 目标被显式支持之前不请求其 CUA 产物把 CUA 验证与 Feishu 验证放在一起缺失官方插件产物时应让构建失败。CI 侧的 macOS 签名与公证配套脚本包括 scripts/verify-cua-macos-helper.mjs、scripts/sign-cua-helper.mjs 与 scripts/cua-macos-contract.mjs分别负责 helper 校验、签名与 macOS 契约常量app 名、可执行名、bundle id 与非法加载路径检测。技能文档与设置界面适配计划要求把上游技能文档改造为 DeepChat 专属版本plugins/cua/skills/computer-use/ 下有SKILL.md、RECORDING.md、WEB_APPS.md等删除上游手动安装、PATH配置与独立 MCP 设置的表述描述 DeepChat 的工具面与各平台行为增加平台注意事项macOS 权限辅助功能、屏幕录制、Windows 前台/后台派发差异、Linux 预发布限制把 Swift 时代的工具名替换为当前版本工具名例如screenshot不再是主截图工具录屏从单一set_recording拆分为start_recording/stop_recording/get_recording_state/replay_trajectory/install_ffmpeg插件支持元数据与支持的平台/架构矩阵保持一致。设置与权限 UX 的要求是保留 macOS helper-app 权限检查为 Windows/Linux 显示平台中立的运行时状态非 macOS 平台避免出现 macOS-only 的权限文案Linux arm64 的缺失运行时报告为不受支持而非安装损坏。插件发现清理不支持的兄弟产物不得破坏已安装状态这是计划中一个容易被低估的修复项官方插件发现逻辑必须保证——同一插件 id 下不受支持的兄弟产物例如当前机器是 x64 但目录里存在 arm64 产物不能把已经安装的受支持产物禁掉。只有在当次发现流程中当前平台/架构不存在任何可信候选时才清除持久化的插件状态。任务清单 中对应的 T15 记录了这个回归覆盖已经完成包括侧边放置多个 CUA 目标产物且存在活动插件工具服务器的回归测试。验证计划可复现的完整命令计划文档给出了实施完成后的验证命令。源码级检查pnpm run format pnpm run i18n pnpm run lint pnpm run typecheck pnpm test -- test/main/plugin.test.ts pnpm test -- test/main/scripts在受支持的宿主/CI 目标上按平台/架构逐一打包并验证pnpm run plugin:bundle -- --name cua --platform win32 --arch x64 pnpm run plugin:verify -- --name cua --platform win32 --arch x64 pnpm run plugin:bundle -- --name cua --platform win32 --arch arm64 pnpm run plugin:verify -- --name cua --platform win32 --arch arm64 pnpm run plugin:bundle -- --name cua --platform linux --arch x64 pnpm run plugin:verify -- --name cua --platform linux --arch x64 pnpm run plugin:bundle -- --name cua --platform darwin --arch arm64 pnpm run plugin:verify -- --name cua --platform darwin --arch arm64 pnpm run plugin:bundle -- --name cua --platform darwin --arch x64 pnpm run plugin:verify -- --name cua --platform darwin --arch x64计划还定义了三个平台级的产物验收断言Windows.dcplugin中必须包含cua-driver.exe当前版本约定为不包含cua-driver-uia.exeLinux 解压后cua-driver必须可执行macOS 必须校验 helper app 可执行路径、精确 entitlements 与签名状态。plugin:bundle/plugin:verify两个命令由 scripts/plugin.mjs 实现。任务分解与执行顺序任务清单 把计划拆成 T01–T16 十六个任务并记录了完成情况其执行顺序体现了依赖关系T01–T03 建立运行时输入与安全校验上游元数据固定、staging 重写下载、校验和验证、解压、布局校验、按目标拷贝、分平台文件验证与--version冒烟检查T04、T05、T09 对齐插件契约清单扩展、工具策略更新、技能文档适配T06、T07 让本地打包产出正确产物打包脚本去 darwin-only、按目标收窄engines.targets、保留 POSIX 可执行位构建脚本增加 Windows/Linux 支持T08、T12 对齐发布基础设施与文档CI 各 job 打包验证、插件打包指南 不再把 CUA 描述为 macOS-onlyT10、T11 收口平台 UX 与回归覆盖设置状态平台感知、pluginService.test.ts跨平台断言、linux arm64 负向测试T13、T14 验证最终产物本地验证含 Windows 宿主验证、非宿主目标跳过执行、老 glibc Linux 宿主验证加上仅 CI 可验证的目标macOS 签名、跨平台打包。其中 T16 记录了另一个细节修复CUA 驱动不实现 MCP 的可选prompts/resources能力客户端收到-32601 Unknown method时应把其视为能力缺失并缓存空列表避免重复输出错误堆栈——这与规格文档中可选能力缺失不得产生 error 级日志噪音的验收标准一致。发布注意事项Rollout Notes计划末尾给出了三条上线策略值得作为跨平台二进制集成的一般经验单一聚焦特性分支落地清单、打包、文档、CI 必须同步变更分散提交容易产生中间不一致状态上游发布审计先于版本固定如果实施开始前上游已发布新驱动需要重跑发布资产审计确认资产名、工具名、Linux 可用性之后再更新固定 tag签名问题隔离在 staging 脚本内macOS helper-app 签名失败时保留运行时更新把签名修复隔离在 staging 脚本里处理而不是改动插件宿主代码。小结这套方案的可复用模式DeepChat 的 CUA 跨平台方案本质上回答了一个通用问题Electron 应用如何安全地把第三方桌面自动化驱动带入多平台发布管线。其可复用的模式包括固定即合同tag commit 资产名 双重 SHA-256checksums.txt与资产级哈希构成不可变输入任何上游布局变化都会在 staging 阶段显式失败可见性按 target 门控平台/架构矩阵同时驱动清单engines.targets、产物engines.targets收窄、设置界面可见性与 CI job 分布四层保持一致验证贴近产物plugin:verify直接检查.dcplugin归档内容文件存在、可执行位、macOS 签名与 entitlements而不是信任源码目录运行时零安装用户视角始终只有技能 内置工具面所有下载、校验、签名都发生在构建期。当前仓库中该主题仍在演进规格文档 记录了驱动 0.19.2 时代的运行时布局、工具面与权限/安全要求后续 0.12.6 及更高版本驱动的升级、生命周期所有权与完整性工作则迁移到 插件外部运行时生命周期计划 中继续跟踪。【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考