人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载本篇技术指南围绕 Kun 仓库中的 computer-use-cua-compatibility.md 展开深入解析 Kun 如何将trycua/cua-driver0.22.2contractVersion 0.7.0接入 Electron Main 进程作为computer_use工具的驱动后端。读完本文你将掌握 CUA 驱动的供应链构成、运行时边界、Kun 动作到 CUA 操作的完整映射表、帧坐标与隐私规则以及仓库现有的验证覆盖与平台发布门槛。一、背景CUA 是驱动不是第二个 Agent 运行时Kun 的computer_use工具能力入口位于 computer-use-tool-provider.ts在 Electron Main 进程中以CUA Driver0.22.2contractVersion0.7.0作为后端实现。这里有一个容易被误解的关键点CUA 只是一个驱动driver而不是第二套 Agent 运行时。换句话说Kun 完整保留了对以下环节的所有权模型调用model calls审批approvals线程threadsHTTP/SSE 事件HTTP/SSE events预算budgets工具结果tool resultsCUA 只负责两件“脏活”截取真实桌面画面和向宿主操作系统注入鼠标/键盘输入。这一分层决定了 Kun 现有的模型路由、审批流、会话预算等机制完全不受驱动更换的影响。二、供应链可选原生包与精确版本锁定trycua/cua-driver0.22.2在 package.json依赖声明于dependencies精确锁定版本号中声明了以下平台的原生可选包平台架构macOSx64 与 arm64Windowsx64 与 arm64Linux (glibc)x64 与 arm64同时它把ubjs/core与ubjs/node精确锁定到0.31.0-3。该包采用 MIT 许可证归属声明包含在仓库根目录的 THIRD_PARTY_NOTICES.md 中。从打包角度看Electron Builder 将trycua/*与ubjs/*保持在 ASAR 之外目的是让原生库和 Node 运行时能够被 Electron Main 正常加载ASAR 内打包的原生模块在dlopen阶段可能失败。这属于平台发布环节的硬性要求不能仅凭 npm 上包存在就推断运行期可用——这一点在文档的“Verification status”一节中被明确强调。三、运行时边界三层防御设计3.1 Standard 模式的懒加载创建Electron Main 在Standard 模式下懒加载创建CuaDriver.createConfigured()。在 cua-driver-controller.ts 的ensureReady()中可以看到具体配置const driver sdk.CuaDriver.createConfigured({ claudeCodeCompatibility: false, authorization: { allowedModes: [sdk.SessionPermissionMode.Standard], compatibilityMode: sdk.SessionPermissionMode.Standard, unrestrictedAcknowledged: false, maxSessionTtlSeconds: BigInt(SESSION_TTL_SECONDS), // 15 * 60 maxIdleTtlSeconds: BigInt(IDLE_TTL_SECONDS) // 5 * 60 } })从源码结构看控制器把以下参数设为恒定值见文件顶部常量SESSION_TTL_SECONDS 15 * 60会话 TTL 上限IDLE_TTL_SECONDS 5 * 60空闲 TTL 上限DEFAULT_MAX_IMAGE_DIMENSION 1280截图最长边上限MAX_STRUCTURED_JSON_BYTES 32 * 1024CUA 结构化结果字节上限MAX_SCREENSHOT_BYTES 20 * 1024 * 1024原始截图字节上限这些常量对应文档中“Unrestricted mode、capability-manifest 路径、TTL 和任意 CUA 工具名都绝不被模型参数接受”的承诺它们是代码内写死的边界而不是从模型传来的可配置参数。unrestrictedAcknowledged: false明确拒绝了非受限模式。驱动加载也采用同样的失败关闭策略loadCuaSdk()通过import(/* vite-ignore */ trycua/cua-driver)动态加载加载失败时抛出driver_unavailableensureReady()返回available: false并附上安全化后的原因信息见 cua-driver-controller.ts 与测试 cua-driver-controller.test.ts。3.2 仅有的入口GUI 持有的认证回环桥文档强调“GUI 持有的认证回环桥authenticated loopback bridge仍是 Kun 运行时唯一的入口点”。这句话在 computer-use-bridge-service.ts 中落地为非常具体的实现服务器只监听127.0.0.1端口为0由系统分配空闲端口启动时生成 32 字节随机base64urltoken仅接受POST /v1/actions且Content-Type必须是application/jsonAuthorization头使用 Bearer 方案并通过timingSafeEqual进行常数时间比较防止时序侧信道computer-use-bridge-service.ts单请求体上限 64 KB请求超时 120 秒maxHeadersCount、headersTimeout、keepAliveTimeout均有收紧。桥协议定义在 computer-use-bridge.ts契约 v2 携带sessionId/frameId上下文而v1 被暂时接受以支持迁移——v1 请求会统一落到服务端维护的legacySessionId上computer-use-bridge-service.ts。请求与响应均以contractVersion字段区分契约版本常量分别为2与1。桥支持的 operation 集合来自 zod 判别联合包括ready、capture、screen_size、cursor_position、move_to、click、drag、scroll、type_text、press_hotkey、wait。3.3 全局单飞与失败不复放两条重要的运行期保证动作全局单飞globally single-flight桥服务维护activeRequest标志当上一个请求仍在执行时新请求直接返回429 bridge_busy。实现注释写得很直白——“桌面输入天然有序绝不把无关的鼠标/键盘操作与截图请求交错执行”computer-use-bridge-service.ts。失败的副作用绝不在遗留后端上重放桥服务维护了一个请求日志request journal对每个requestId记录请求体的 SHA-256 摘要与状态started/completed/unknown。相同requestId的重复请求若摘要一致且已完成则直接返回已记录的结果幂等重放而不会再次执行副作用摘要不一致则返回409 request_id_conflict结果未知则返回409 request_outcome_unknowncomputer-use-bridge-service.ts。3.4 优雅关闭顺序shutdown语义被明确排序先关闭桥的准入bridge admission再等待 CUA 关闭。在桥的stop()中先关闭 HTTP server拒绝新请求abort 所有在途请求随后才调用controller.shutdown?.()控制器内部依次执行driver.shutdown()与uniffiDestroy?.()cua-driver-controller.ts。宿主生命周期由 computer-use-host.ts 管理设置变更如maxImageDimension变化或enabled被关闭会触发桥的重建或停止且所有生命周期操作通过lifecycleQueue串行化。四、动作兼容性Kun 动作 → CUA 操作映射Kun 将computer_use工具暴露为 12 个动作COMPUTER_USE_ACTIONS常量见 computer-use-tool-provider.tsscreenshot、cursor_position、mouse_move、left_click、right_click、middle_click、double_click、left_click_drag、scroll、type、key、wait。它们与 CUA 操作的对应关系如下完整继承自原文档Kun 动作CUA 操作备注screenshotgetDesktopStatePNG 有界且被降采样作为模型输入cursor_positiongetCursorPosition转换为最新帧坐标mouse_movemoveCursor帧坐标被解析回原生桌面坐标click / double_clickclick精确保留按键与次数left_click_dragdrag两个点必须来自同一张有效帧scrollscroll行模式line mode数量有界typetypeText文本绝不进入活动元数据keypressKey / hotkey已知修饰键从主键中拆分waitKun 定时器可中止随后跟随截图4.1 动作级实现细节截图降采样capture()调用getDesktopState后原始 PNG 超过 20 MB 会被拒绝随后用sharp将最长边缩放到maxImageDimension默认 1280以内再注册为新帧cua-driver-controller.ts。坐标解析resolvePoint()通过帧注册表把“模型看到的截图像素”映射回“原生桌面坐标”映射比例由scaleX screen_width / scaled.width、scaleY screen_height / scaled.height决定cua-driver-controller.ts。拖拽约束drag()的终点解析强制复用起点的frameId{ ...context, frameId: start.frameId }保证两点同帧cua-driver-controller.ts。滚动边界scroll()使用ScrollBy.Line行模式amount被钳制在 1–100clamp(Math.round(amount), 1, 100)方向映射到up/down/left/right四个枚举。等待可中止wait()使用 Kun 自己的定时器监听AbortSignalms被钳制在 0–60 秒cua-driver-controller.ts。4.2 不支持的能力失败关闭而非静默降级CUA0.22.2的便携式ClickInput不暴露“修饰键 点击”的原子组合。Kun 的处理方式是失败关闭fail closed当click()收到非空modifiers时直接抛出unsupported_modifier_click动作不执行cua-driver-controller.ts。桥服务将这一错误映射为 HTTP422返回给调用方。Kun绝不丢弃修饰键也不会在另一个后端上重放这次点击——这一保证同时呼应了上文“失败的副作用绝不在遗留后端上重放”的承诺。值得注意的是错误映射同样是有白名单的桥只允许stale_frame、unsupported_modifier_click、driver_unavailable、driver_error、authorization_refused、background_unavailable、background_occluded这七个错误码透出给调用方其余一律折叠为bridge_failed_closedcomputer-use-bridge-service.ts。stale_frame对应409unsupported_modifier_click对应422其余为500。五、坐标与隐私规则帧生命周期与最小化日志5.1 帧注册表Frame Registry每张截图都获得一个随机帧 IDrandomUUID()一个基于 Kun 线程/回合 ID 派生的哈希化、内容无关的会话标签session label。坐标只对那个会话与那张帧有效。帧注册表实现位于 computer-frame-registry.ts关键参数maxAgeMs 30_000帧在 30 秒后过期maxFrames 64注册表最多保留 64 帧超出后按插入顺序淘汰coordinateSpace: kun-frame-v1坐标空间版本号为将来迁移保留。resolve()的校验顺序严格且可审计帧不存在或不属于当前会话 →stale_frame帧已过期同时从注册表删除→stale_frame坐标非有限数或落在图像边界外 →stale_frame。过期、跨会话、越界坐标统一返回stale_frame并要求调用方重新截图computer-frame-registry.ts。这三类场景在 computer-frame-registry.test.ts 中均有对应的单测覆盖。5.2 隐私边界结构化字段白名单CUA 结果只投影有界且被白名单允许的结构化字段。在project()中驱动结果被规整为degraded、errorCode、verification状态/稳定性/采样数三个字段cua-driver-controller.ts。同时structuredObject()对structuredJson或回退的rawJson施加 32 KB 上限防止超大型结果进入日志链路。以下内容绝不被适配器记录这是原文档明确列举的隐私承诺rawJson截图本身键入的文本typeText的 text 参数不进入活动元数据剪贴板内容桥 token六、验证状态与平台发布门槛仓库当前的验证体系对应原文档“Verification status”通过单元/集成测试覆盖以下关键路径帧映射截图坐标到原生桌面坐标的映射正确性computer-frame-registry.test.ts帧过期过期、跨会话、越界坐标被拒绝computer-frame-registry.test.tsv1/v2 桥迁移v1 请求在桥 v2 迁移期间被保留支持computer-use-bridge-service.test.ts认证路由Bearer token 校验与请求契约校验computer-use-bridge-service.test.ts工具结果框架动作结果被规整为统一的HostActionResult结构结构化错误传播stale_frame、unsupported_modifier_click等错误码按 HTTP 状态透出幂等与单飞已完成请求从日志直接返回而非重放副作用computer-use-bridge-service.test.tsToken 不外泄成功响应中不包含桥 tokencomputer-use-bridge-service.test.ts。与此同时文档给出了非常克制的边界声明这也是读者需要特别注意的原生 fixture 与签名/公证打包应用检查仍是平台发布门槛release gates不能仅凭 npm 包存在就推断支持可用Wayland 行为与具体合成器compositor相关Kun 保留 CUA 的原始拒绝结果而不是将其包装成成功上报。七、总结一条“驱动可换、边界不变”的兼容路径Kun 的 CUA 兼容层给出了一个可复用的集成范式把第三方原生驱动限制在“截屏 注入输入”的最小职责内而把模型调用、审批、线程、事件、预算、工具结果全部保留在 Kun 自己的运行时中。围绕这条边界代码层面落实了四道防线——Standard 模式的固定授权参数、GUI 持有的认证回环桥作为唯一入口、全局单飞与失败不复放、带 TTL 的帧坐标空间与结构化白名单日志。对想深入阅读源码的读者推荐按以下顺序追踪桥协议与契约版本kun/src/contracts/computer-use-bridge.ts宿主控制器与授权参数src/main/computer-use/cua-driver-controller.ts帧注册表与坐标校验src/main/computer-use/computer-frame-registry.ts认证回环桥服务src/main/computer-use/computer-use-bridge-service.ts宿主生命周期管理src/main/computer-use/computer-use-host.ts工具面12 个动作与输入 schemakun/src/adapters/tool/computer-use-tool-provider.ts宿主控制器抽象接口kun/src/adapters/computer-use/host-control.ts对应测试cua-driver-controller.test.ts、computer-frame-registry.test.ts、computer-use-bridge-service.test.ts本文所有实现细节均以当前仓库源码为准涉及平台可用性的结论请以对应平台的签名/公证打包发布检查结果为准。赞分享人工智能AI Agent自主智能体桌面应用MCP Clients【免费下载链接】KunLocal-first AI agent workspace for coding, writing, design, research, and automation — one runtime for desktop GUI and TUI.项目地址https://gitcode.com/gh_mirrors/de/Kun点击查看免费下载相关推荐DeepChat 内置 Cua Driver 解析基于 MCP over stdio 的后台 Computer Use 驱动与 Claude Code 兼容模式DeepChat 内置 Cua Driver 解析基于 MCP over stdio 的后台 Computer Use 驱动与 Claude Code 兼容模AI Agent人工智能AI 应用桌面应用MCP ClientsClawX Computer Use CLI 验证全记录CUA 0.25.0 升级、遥测抑制与原生驱动边界ClawX Computer Use CLI 验证全记录CUA 0.25.0 升级、遥测抑制与原生驱动边界 ClawX 通过内置原生 CUA 驱动SDK 人工智能AI 应用桌面应用交互助手AIRI 桌面编排层可行性验证深度解析computer-use-mcp 的架构、安全边界与实现原理AIRI 桌面编排层可行性验证深度解析computer use mcp 的架构、安全边界与实现原理 本篇技术指南围绕 AIRI 开源仓库中 services/AI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染上一篇Quartz.NET SimpleTrigger 完全指南一次性任务、固定间隔重复与 Misfire 策略下一篇终极微信QQ防撤回补丁告别对方已撤回的遗憾创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
