Cua Driver 动作图标目录Action Icon Catalog深度解析为 AI 桌面代理的 54 个公开工具构建可组合的语义图标体系【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-codeCua Driver 是 qwen-code 仓库中一个运行在终端与桌面之间的开源 AI 编程代理的底层桌面驱动通过 MCP/CLI 暴露数十个可调用工具。本文围绕仓库中 packages/cua-driver/docs/action-icon-catalog.md 这份语义源目录系统讲解一个公开工具名 ≠ 一个完整动作身份这一核心设计思想以及surface.intent.target.delivery.qualifiers五段式解析模型、全部动作键的规范词汇表、54 个工具的完整清单以及首轮资产集的建设顺序。读完本文你将掌握如何为任意一个 Cua Driver 工具调用解析出唯一、可渲染、可复用的图标语义键并能把图标系统与源码中的目标归一化、能力声明、徽章渲染等实现一一对应起来。为什么公开工具名不是完整的动作身份click只是一个入口。一次真实的点击调用在 Cua Driver 中可能解析为无障碍动作AX或像素动作PX后台投递background或前台投递foreground窗口目标或整个桌面desktop左键、右键或中键单击、双击或三击。因此图标系统必须把一个调用解析成如下形式的解析后动作键surface.intent.target.delivery.qualifiers举例来自 action-icon-catalog.mdnative.click.px.background.left.single native.click.px.foreground.left.single native.click.ax.background.press native.scroll.desktop.down.page browser.click.trusted.ref browser.pointer.drag.dom_event前台与后台属于两个不同的解析动作但不应该为它们各画一套无关插图。可维护的资产系统采用四层组合式设计一个基础意图字形/动画click、type、scroll、drag一个目标处理标记ax、px、desktop、page、browser一个由宿主渲染的投递徽章background、foreground一个在改变可见手势时才出现的小限定符right、double、down、page等。这套设计在源码中有直接呼应packages/cua-driver/rust/crates/cursor-overlay/src/badge_glyphs.rs将投递与目标标记渲染为会话徽章内的宿主自绘字形BadgeGlyph::Background/Foreground/Ax/Pixel/Browser/Desktop并明确注释主题拥有动作美术宿主拥有跨平台、跨主题必须保持一致的紧凑执行上下文标记。也就是说投递/目标徽章刻意不在光标主题资产里而是由宿主统一渲染。规范变体词汇表目标TargetingToken含义如何被选中ax无障碍寻址的元素动作element_token或element_indexpx窗口局部像素动作窗口目标 x/y坐标focused作用于目标当前聚焦的控件未提供元素或点desktop屏幕绝对坐标动作scope:desktop且无窗口目标page遗留 page/DOM 动作page[action…]操作browser_trusted通过可信 CDP Input 事件的类型化浏览器动作input_route:trusted或省略browser_dom显式合成 DOM 事件input_route:dom_event投递DeliveryToken含义background定向投递不置顶/不前置目标窗口foreground短暂前置目标、执行动作然后恢复之前的置前应用persistent_foregroundbring_to_front目标保持置前fixed_background浏览器或 Linux 底层操作契约上永不前置none只读或生命周期操作无输入投递姿态公开delivery_mode的桌面输入家族是click double_click right_click drag type_text press_key hotkey scrollbrowser_dialog对accept和dismiss也暴露 background/foreground 投递而类型化浏览器指针/点击操作永不前置浏览器。源码侧delivery_mode不是装饰性字段。在 tool.rs 中advertised_capabilities_for会检查实时工具 schema 是否接受delivery_mode字段若接受则向该工具的tools/list条目追加input.delivery_mode能力 token以保证每个平台上的能力声明都如实。background_input.rs则定义了后台投递的执行/拒绝状态机见下文后台投递小节。手势限定符Gesture qualifiers维度取值按键left、right、middle点击次数single、double、tripleAX 点击动作press、show_menu、pick、confirm、cancel、open滚动方向up、down、left、right滚动单位line、page浏览器输入路径trusted、dom_event浏览器输入方式insert_text、keystrokesCommand、Control、Alt/Option、Shift 等修饰键应放进动画载荷或标签里不需要单独的基础图标。解析后的原生输入动作Resolved native input actions下表是应当驱动光标动画的动作身份。花括号中的值是有限变体不是字面资产名公开工具解析后动作键clicknative.click.ax.{background\|foreground}.{press\|show_menu\|pick\|confirm\|cancel\|open}clicknative.click.px.{background\|foreground}.{left\|right\|middle}.{single\|double\|triple}clicknative.click.desktop.{left\|right\|middle}.{single\|double\|triple}double_clicknative.double_click.{ax\|px}.{background\|foreground}right_clicknative.right_click.{ax\|px}.{background\|foreground}dragnative.drag.px.{background\|foreground}.{left\|right\|middle}dragnative.drag.desktop.{left\|right\|middle}type_textnative.type_text.{ax\|px\|focused}.{background\|foreground}type_textnative.type_text.desktoppress_keynative.press_key.{ax\|px\|focused}.{background\|foreground}press_keynative.press_key.desktophotkeynative.hotkey.{px\|focused}.{background\|foreground}hotkeynative.hotkey.desktopset_valuenative.set_value.ax.backgroundscrollnative.scroll.{ax\|px}.{background\|foreground}.{up\|down\|left\|right}.{line\|page}scrollnative.scroll.desktop.{up\|down\|left\|right}.{line\|page}move_cursoragent_cursor.move.window、native.pointer.move.desktopzoomnative.zoom.windowbring_to_frontnative.window.persistent_foreground不要把每个笛卡尔积都生成成一张完全独立的插图。例如所有native.scroll.*动作共用同一个滚动动画投递与目标是可组合的宿主渲染徽章而非主题动画。目标归一化解析动作键背后的源码事实目标维度在源码里是一个真正的归一化步骤而非仅存在于文档。packages/cua-driver/rust/crates/cua-driver-core/src/action_target.rs中的normalize_action_target在授权边界之前、每个调用一次将类型化联合目标target: {kind, ...}归一化为旧的扁平字段target: {kind: window, pid, window_id}→scopewindowpidwindow_idtarget: {kind: desktop, display_id: primary}→scopedesktop当前版本只接受display_idprimary。它同时执行fail-closed校验scope:desktop不能与pid/window_id混用target不能与遗留的scope/pid/window_id字段混用未知target.kind一律报invalid_action_target。支持类型化目标的工具清单move_cursor、click、drag、scroll、type_text、press_key、hotkey与目录中的桌面输入家族高度一致二者共同定义了一次调用如何落到确定的desktop/window目标。tools/list的 schema 侧同样由源码驱动advertised_runtime_input_schema会把便携契约中target字段的精确 tagged-union schema 合并进运行时 schema同时保留更宽的遗留scopewindow|desktop解码器。Page 复合动作Page compound actions公开的page工具包含七个操作解析后动作键效果平台说明page.get_text读取可见页面文本跨平台page.query_dom用 CSS 选择器查询元素跨平台page.execute_javascript执行 JavaScript有支持的页面后端即跨平台page.click_element点击 CSS 选中的元素跨平台page.insert_text在当前 DOM 焦点插入文本当前文档记录为 macOS 实现page.type_keystrokes派发持久化的逐字符按键事件当前文档记录为 macOS 实现page.enable_javascript_apple_events启用 Safari JavaScript 自动化仅 macOS这七个操作对应源码中 page.rs 的PageBackendtrait 方法get_text、query_dom、execute_javascript、click_element等。该文件确认了平台分派方式macOS 对 Chromium/Safari 用 Apple Events、对 Electron 用 CDP、对 WKWebView 用 AX 树兜底Windows 用 UIA TextPattern FindAll 处理get_text/query_dom、用共享 CDP 客户端处理execute_javascriptLinux 读路径用 AT-SPI、JS 执行用 CDP。enable_javascript_apple_events的默认 trait 实现在非 macOS 平台返回 not supported on this platform与目录仅 macOS的标注一致。此外page.click_element的结果ClickElementResult会回报元素中心的屏幕坐标与视口坐标供下游链式调用使用——这也解释了为什么该动作值得一个专门图标而非复用普通点击。类型化浏览器动作Typed browser actions公开工具解析后动作键get_browser_statebrowser.bind、browser.snapshot.dom_refs_v1、browser.snapshot.semantic_v2browser_preparebrowser.prepare.detect、browser.prepare.isolated_new、browser.prepare.isolated_named、browser.prepare.existing_profilebrowser_navigatebrowser.navigatebrowser_clickbrowser.click.trusted.{ref\|viewport}、browser.click.dom_event.refbrowser_typebrowser.type.insert_text、browser.type.keystrokesbrowser_dialogbrowser.dialog.inspectbrowser_dialogbrowser.dialog.accept.{background\|foreground}browser_dialogbrowser.dialog.dismiss.{background\|foreground}browser_set_input_filesbrowser.files.set_inputbrowser_downloadbrowser.downloadbrowser_pointerbrowser.pointer.{hover\|right_click\|double_click\|scroll\|drag}.{trusted\|dom_event}类型化浏览器点击与指针操作具有固定的后台姿态。trusted与dom_event两条输入路径在实现上有本质差异前者走可信 CDP Input 事件后者是显式合成 DOM 事件因此必须保持为两个互不相同的解析动作 ID而不是合并成一个图标。从能力声明看浏览器工具在 tool.rs 中声明的是独立的browser.*tokenbrowser.state、browser.prepare、browser.input.click、browser.dialog、browser.input.files等而非input.pointer.*/input.keyboard.*家族——因为它们在页面内通过 CDP 行动不在操作系统输入层上行动。这与目录把浏览器动作独立成类的做法互为印证。会话、录制、光标与维护变体Session / recording / cursor / maintenance公开工具解析后动作键start_sessionsession.start.{implicit\|named}get_sessionsession.inspect.onelist_sessionssession.inspect.listend_sessionsession.endescalate_sessionsession.legacy.escalate.desktopget_session_statesession.legacy.inspect_capturestart_recordingrecording.start.trajectory、recording.start.videostop_recordingrecording.stopget_recording_staterecording.inspectreplay_trajectoryrecording.replayset_agent_cursor_enabledagent_cursor.show、agent_cursor.hideset_agent_cursor_motionagent_cursor.configure_motionset_agent_cursor_themeagent_cursor.set_themeget_agent_cursor_stateagent_cursor.inspectcheck_permissionspermissions.inspect、permissions.requesthealth_reportsystem.health.inspectget_configconfig.inspectset_configconfig.updatecheck_for_updateupdate.inspectinstall_ffmpegdependency.ffmpeg.plan、dependency.ffmpeg.install值得注意agent_cursor.*四个操作在 tool.rs 中分别声明为agent_cursor.set_enabled、agent_cursor.set_motion、agent_cursor.set_theme、agent_cursor.state能力 token与目录中的agent_cursor.show/hide、configure_motion、set_theme、inspect一一对应而install_ffmpeg的plan/install双态也与录制功能对 ffmpeg 依赖的规划—安装两阶段一致。完整公开工具名并集54 个工具源码构建的 macOS 注册表包含 49 个工具Windows 增加debug_window_infoLinux 增加四个底层指针工具。并集为 54 个公开工具名| # | 工具 | 类别 | 平台 | 主图标意图 | | -: | ---- | ---- | ---- | ---------- | | 1 |list_apps| 检查 | 全部 | Apps/list | | 2 |list_windows| 检查 | 全部 | Windows/list | | 3 |get_window_state| 检查 | 全部 | 窗口检查可选捕获处理 | | 4 |launch_app| 应用生命周期 | 全部 | 启动 | | 5 |kill_app| 应用生命周期 | 全部 | 强制停止 | | 6 |bring_to_front| 窗口生命周期 | 全部 | 持久置前 | | 7 |click| 指针输入 | 全部 | 点击 目标/投递/按键/次数 | | 8 |double_click| 指针输入 | 全部 | 双击 目标/投递 | | 9 |right_click| 指针输入 | 全部 | 右键 目标/投递 | | 10 |drag| 指针输入 | 全部 | 拖拽 投递 | | 11 |type_text| 键盘输入 | 全部 | 输入 目标/投递 | | 12 |press_key| 键盘输入 | 全部 | 单键 目标/投递 | | 13 |hotkey| 键盘输入 | 全部 | 组合键 投递 | | 14 |set_value| 无障碍输入 | 全部 | 设置语义值 | | 15 |scroll| 指针/无障碍输入 | 全部 | 滚动 目标/投递/方向 | | 16 |get_screen_size| 检查 | 全部 | 屏幕尺寸 | | 17 |get_desktop_state| 检查 | 全部 | 桌面捕获 | | 18 |get_cursor_position| 检查 | 全部 | 光标位置 | | 19 |move_cursor| 指针/叠加输入 | 全部 | 按每次调用的目标选择代理光标或真实指针移动 | | 20 |set_agent_cursor_enabled| 代理光标 | 全部 | 显示/隐藏光标 | | 21 |set_agent_cursor_motion| 代理光标 | 全部 | 运动配置 | | 22 |set_agent_cursor_theme| 代理光标 | 全部 | 选择已安装视觉主题 | | 23 |get_agent_cursor_state| 代理光标 | 全部 | 光标检查 | | 24 |check_permissions| 权限 | 全部提示为 macOS 专属 | 权限检查/请求 | | 25 |health_report| 维护 | 全部 | 健康检查 | | 26 |get_config| 配置 | 全部 | 配置检查 | | 27 |set_config| 配置 | 全部 | 配置更新 | | 28 |get_accessibility_tree| 检查 | 全部 | 桌面无障碍检查 | | 29 |zoom| 检查 | 全部 | 缩放/裁剪 | | 30 |page| Page/DOM | 全部操作级有限制 | 使用七个 page 操作图标 | | 31 |get_browser_state| 类型化浏览器 | 全部 | 绑定或快照 | | 32 |browser_prepare| 类型化浏览器 | 全部 | 浏览器准备/配置文件 | | 33 |browser_navigate| 类型化浏览器 | 全部 | 导航 | | 34 |browser_click| 类型化浏览器 | 全部 | 浏览器点击 输入路径 | | 35 |browser_type| 类型化浏览器 | 全部 | 浏览器输入 模式 | | 36 |browser_dialog| 类型化浏览器 | 全部 | 检查/接受/关闭对话框 | | 37 |browser_set_input_files| 类型化浏览器 | 全部 | 上传/附加文件 | | 38 |browser_download| 类型化浏览器 | 全部 | 下载 | | 39 |browser_pointer| 类型化浏览器 | 全部 | 使用十个浏览器指针操作图标 | | 40 |start_recording| 录制 | 全部 | 开始轨迹/视频录制 | | 41 |stop_recording| 录制 | 全部 | 停止录制 | | 42 |get_recording_state| 录制 | 全部 | 录制检查 | | 43 |replay_trajectory| 录制 | 全部 | 回放 | | 44 |install_ffmpeg| 维护 | Windows/Linux无必要时为 no-op | 规划/安装依赖 | | 45 |start_session| 会话生命周期 | 全部 | 可选隐式或命名生命周期启动 | | 46 |get_session| 会话生命周期 | 全部 | 检查一个可见生命周期会话 | | 47 |list_sessions| 会话生命周期 | 全部 | 列出传输可见的生命周期会话 | | 48 |end_session| 会话生命周期 | 全部 | 结束会话 | | 49 |escalate_session| 遗留会话兼容 | 全部 | 已废弃的捕获范围升级 | | 50 |get_session_state| 遗留会话兼容 | 全部 | 已废弃的捕获范围检查 | | 51 |check_for_update| 维护 | 全部 | 更新检查 | | 52 |debug_window_info| 诊断 | 仅 Windows | 窗口诊断 | | 53 |mouse_button_down| 底层指针 | 仅 Linux | 按住按键 | | 54 |mouse_drag| 底层指针 | 仅 Linux | 移动按住指针 | | 55 |mouse_button_up| 底层指针 | 仅 Linux | 释放按键 | | 56 |parallel_mouse_drag| 多指针 | 仅 Linux | 并发拖拽 |表中行号为并集计数故为 1–56 中的 54 项。平台差异在注册层面是真实存在的例如tool.rs的能力映射把debug_window_info归类为window.debug_info、把 Linux 的mouse_drag/parallel_mouse_drag归为input.pointer.drag、mouse_button_down/mouse_button_up归为input.pointer.button与目录的平台列完全对应。Linux 底层指针动作键这些工具被刻意拆开因为按住的按键能跨多次调用存活且多个会话光标可以并发拖拽linux.mouse_button_down.{left|right|middle}.fixed_background linux.mouse_drag.fixed_background linux.mouse_button_up.fixed_background linux.parallel_mouse_drag.fixed_background注意它们全部使用fixed_background投递姿态——契约上永不自作主张把目标前置。别名与已移除表面Aliases and removed surfacestype_text_chars是type_text的已废弃调用时别名刻意从tools/list中隐藏应复用type_text图标。源码中该工具仍被注册但不声明terminal_safe能力tool.rs注释说明其 Linux 实现逐字符走 XSendEvent、没有终端短路逻辑契约比type_text更窄。旧的screenshot工具已移除窗口捕获由get_window_state表示全屏捕获由get_desktop_state表示。已废弃的get_window_state.capture_mode取值仍被接受但被忽略不代表独立动作不应获得图标。内部平台投递路径如cgevent、x11_atspi、msaa、key_events_fg是结果元数据而非公开请求动作可以出现在诊断信息里但不应扩充主图标目录。背景投递为何值得一个专用徽章background/foreground之所以被提升为宿主渲染徽章是因为后台投递在实现上是一整套独立的决策状态机。packages/cua-driver/rust/crates/cua-driver-core/src/background_input.rs定义了decide_background_input一次后台变更必须携带精确的(pid, CGWindowID)目标平台外壳在派发前采集该目标的实时事实然后由这个纯函数给出唯一决策——执行或返回稳定机器可读的拒绝码window_not_found、owner_pid_mismatch、off_space_or_ax_unresolved、minimized_or_hidden_window、same_pid_keyboard_ambiguity、element_outside_target_window。关键规则包括过期的或他人所有的 CGWindowID 拒绝一切变更不在新鲜 AXWindows 中的目标跨 Space 或 AX 未解析只允许观察被寻址元素必须证明属于请求窗口任何路径含语义 AX都如此最小化/隐藏目标保留精确语义 AX 动作但拒绝路由指针与原始按键进程级键盘额外要求目标进程内没有其他同 PID 键盘候选窗口因为传输寻址的是进程而非窗口。这套状态机同样解释了目录中投递是徽章而非动画的边界后台投递是否可行是运行时事实会随窗口状态改变不适合固化进主题动画。推荐的首轮资产集第一步先生成可复用的基础字形/动画inspect capture launch kill foreground click double_click right_click drag type_text press_key hotkey set_value scroll move_cursor zoom navigate dialog upload download record replay session permissions settings health update第二步再生成小型可组合处理标记ax px desktop page browser_trusted browser_dom background foreground left right middle double triple up down horizontal vertical这样做能在保持系统足够小的同时产生不同的前台/后台点击状态并随新工具加入而保持整体连贯。资产落到哪主题工件与徽章的边界主题美术最终会被编译为.cua-theme工件。packages/cua-driver/rust/crates/cursor-overlay/src/theme_artifact.rs定义了该格式固定头magicCUATHEM3/CUATHEM2 zstd 压缩的 postcard 数据渲染器从不解析Lottie、ZIP、JSON、字体、表达式、URL 或任意源路径并有严格的有界约束压缩/解压上限 24 MiB、总帧数上限 1000、每动画最多 120 帧、画布 128×128、30 FPS 等。这印证了目录可维护资产系统的主张基础意图动画进主题工件投递/目标徽章由宿主渲染。徽章渲染在 badge_glyphs.rs 中实现BadgeGlyph枚举恰好覆盖目录中的投递/目标标记Background、Foreground、Ax、Pixel、Browser、Desktop并各自拥有 tiny-skia 矢量绘制路径如 Background 画双层圆角矩形、Foreground 画带标题线的窗口、Ax 画三点连线、Pixel 画四角折线、Browser 画地球经纬线、Desktop 画屏幕加底座。结合 docs/cursor-themes.md 的说明投递徽章在前且为填充态、目标徽章在后且为描边态动作结束后 400ms 淡出徽章与上下文字形不属于主题工件因此自定义主题作者无需提供徽章美术或字体。与光标主题系统的衔接这套动作图标目录是光标主题 profile v2的语义源目录文档状态声明。主题系统侧cursor-themes.md提供了配套约束内置主题cua.default在所有平台为默认且不可移除自定义主题必须提供全部十二个动作动画idle及各类语义动作set_agent_cursor_theme选择已安装主题reduced_motion取auto/on/offauto跟随宿主无障碍偏好解析出空间目标的动作会把代理光标移动到该目标后再派发无空间目标的动作如向已聚焦的桌面应用输入保持光标原位、仅切换语义动画光标是给观察者看的视觉辅助不是安全指示器、授权提示或工具调用成功的证据——授权另行强制。这解释了目录为何如此强调解析后动作键驱动动画图标目录决定这次动作该播哪个语义动画、叠加哪些徽章而主题系统决定动画长什么样。小结如何按目录落地一个图标系统解析对任意公开工具调用按surface.intent.target.delivery.qualifiers五段式解析出唯一动作键可从delivery_mode、scope/target、button、input_route等参数推导参数校验与目标归一化由 tool_args.rs 和 action_target.rs 负责。映射用上表把动作键映射到基础意图动画 目标处理 投递徽章 手势限定符避免对每个笛卡尔积单独作图。区分层把跨主题稳定的投递/目标徽章交给宿主渲染把动作美术交给.cua-theme主题工件。维护新增工具时按能力 tokentool.rs的default_capabilities_for与解析动作键增量扩展目录保持名称—动作—资产三者的可追踪性。这套目录不只是一张图标清单它同时是一份动作身份的规范只要解析、映射、分层三步不出错无论新增多少平台工具图标系统都能保持小、连贯、可组合。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考