qwen-code cua-driver 的 cursor-gallery 全解析：cua.default 光标渲染器的交互预览与文档素材确定性导出-北京尧图网络

qwen-code cua-driver 的 cursor-gallery 全解析cua.default 光标渲染器的交互预览与文档素材确定性导出【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本指南围绕 cursor-gallery 的 README 展开深入讲解 qwen-code 中 Cua Driver计算机使用驱动为生产级cua.default光标渲染器搭建的维护者预览工具包括它的定位、serve与export-docs两条入口命令、页面上覆盖的 12 种动作与 15 种徽标上下文以及从 Rust 原生渲染器到 WebM 预览、再到文档 GIF 的完整生成管线。读完本文你将掌握如何在本地启动该画廊、理解动作/投放/目标三层语义契约并能按需重新导出公开文档素材。一、它是什么cua.default 渲染器的维护者预览台cursor-gallery位于 packages/cua-driver/tools/cursor-gallery是 Cua Driver 为生产渲染器cua.default准备的维护者预览台maintainer preview。它不是一个独立的业务功能而是用于视觉审查、回归对照与文档素材生产的内部工具。几个关键设计约束源自 README预览即真相画廊里展示的每一帧动画都是由生产环境同一套 Rust 渲染器cursor-overlaycrate导出的精确帧而非前端重新模拟的效果因此看到的效果就是运行时叠加层实际呈现的效果。生成媒体不入库所有预览媒体WebM / 帧图都是运行时构建的产物由cursor-overlay生成并**有意不提交intentionally not committed**到仓库。因此克隆仓库后需要先执行素材导出命令才能看到完整动画。单一事实源文档 GIF 与画廊页面共用同一批渲染帧保证文档插图和交互预览在视觉上严格一致。目录中的静态骨架文件有index.html页面结构、app.js交互逻辑、styles.css视觉样式、capture-gallery.mjs无头浏览器捕获脚本以及入口脚本 cursor-gallery.sh。二、两条入口命令serve 与 export-docs在仓库根目录执行README 给出的官方用法./packages/cua-driver/scripts/cursor-gallery.sh serve ./packages/cua-driver/scripts/cursor-gallery.sh export-docs脚本还支持第三个子命令assets即只生成素材不启动服务。完整用法为cursor-gallery.sh {assets|serve|export-docs}。serve本地交互预览不自动打开浏览器启动后访问http://127.0.0.1:3001即可端口可用环境变量CURSOR_GALLERY_PORT覆盖。行为流程见 cursor-gallery.sh先调用export_assets生成全部帧与 WebM再exec python3 -m http.server $PORT --bind 127.0.0.1 --directory $GALLERY_DIR以画廊目录为根启动静态服务。由于是exec替换进程CtrlC 即可整体退出。export-docs再生成公开文档 GIFREADME 明确列出其前置依赖Chrome、支持 WebSocket 的 Node.js、Python 3、ffmpeg。对照脚本源码cursor-gallery.shexport_docs实际还会require curl与cargoexport_assets需要 Rust 工具链编译示例程序。它从同一批渲染帧出发通过无头 Chrome 截图并编码为 GIF从而确定性地再生成公开文档素材。三、页面内容纵览交互配置器 15 个徽标状态 12 个动作动画README 对页面内容有一句话概括画廊以一个覆盖全部 12 种动作、可选background/foreground投放、可选ax/pixel/browser/desktop目标的生产级光标交互配置器开场随后展示15 个徽标上下文状态与12 个隔离的主题自有动作动画。对照 index.html 可拆分为三大区块Build the final cursor运行时预览区通过 Action / Delivery / Target 三个下拉框自由组合实时预览最终光标。页面右侧同步展示**运行时解剖runtime anatomy**的四个组成部分① Pointer and action围绕指针播放的动作动画② Session会话身份标签预览中固定为Research③ Delivery实心投放徽标Filled chip④ Target描边目标徽标Outlined chip。Every delivery and target combination徽标上下文区3 种投放 × 5 种目标 15 个徽标状态按运行时徽标顺序排列。Action animations动作动画区12 个由主题持有的动作图层被隔离出来单独审查。页面顶部提供动画控制条Pause/Play、Replay全部回卷到 0 帧重放、Speed0.5×/1×/1.5×/2×与背景切换Dark/Mixed/Light/Brand 四档见 app.js便于在不同底色下检查光标对比度。页脚特别注明预览尺度为放大显示生产光标实际尺寸为 42 点——这与渲染器常量DISPLAY_SIZE: f32 42.0theme.rs一致。四、语义契约12 种动作、3 种投放、5 种目标预览页的选项并非随意定义而是对应 cua-driver 的传输无关语义契约定义于 cua-driver-contract/src/cursor.rs。契约文件开头的注释强调这些语义由工具实现作为尽力而为的视觉遥测发出从不影响授权、调度、输入投递或工具结果。12 种动作CursorActionapp.js 中维护了与契约一致的完整清单动作 id显示名描述playbackcursor.rs时长idleIdle动作之间等待Resting4.0sobserveObserve读取屏幕或界面Loop1.6sclickClick点击或选中元素OneShot0.67sdragDrag拖拽元素或选区Held1.6sscrollScroll滚动内容Loop1.6stextText键入或填充文本Held1.6skeyKey按键或快捷键OneShot1.6snavigateNavigate移动、导航或切换标签OneShot1.6sappApp管理应用或窗口OneShot1.6stransferTransfer上传、下载、复制或移动文件Loop1.6srecordRecord录制或重放轨迹Loop1.6ssystemSystem管理会话、权限或配置OneShot1.6s四种 playback 类型cursor.rsResting静止待机、OneShot播完即止到时自动回到 Idle、Held按住期间持续、Loop循环播放。在 theme.rs 的状态机中Held/Loop 动作结束时还会进入 0.4s 的 grace periodending_secs保证短工具调用结束后视觉提示至少停留一帧。投放Delivery与目标Target投放None/background后台 /foreground前台对应契约中的 CursorDelivery目标None/ax/pixel/browser/desktop对应契约中的 CursorTarget。两者在徽标中的视觉语义固定为投放实心filled徽标目标描边outlined徽标app.js。组合标签规则为两者皆无 →Session only仅其一 →X only两者皆有 →X Y。README 特别强调投放与目标字形只出现在徽标内部的权威运行时位置——即它们由宿主拥有的会话徽标绘制属于叠加层而非主题产物详见第七节。会话颜色每会话一个稳定填充色预览中会话标签Research并非写死的装饰。运行时光标默认使用 Cua 蓝#5EC0E8DEFAULT_CURSOR_FILL见 theme.rs命名会话则通过session_fill_rgba稳定哈希进 9 色调色板theme.rs使并发运行的多光标在视觉上彼此可区分且不信任 Agent 传入的样式参数。哈希策略对数字/单字母后缀有特判分别取模映射其余走 FNV 风格散列。五、帧级素材生成export_gallery_frames 示例程序预览所用的全部 WebM 素材来自 cursor-overlay 的示例程序 export_gallery_frames.rs。export_assets通过以下命令调用它cursor-gallery.shcargo run --quiet \ --manifest-path packages/cua-driver/rust/Cargo.toml \ -p cursor-overlay \ --example export_gallery_frames \ --features theme-authoring \ -- target/cursor-gallery/renderer-frames需要显式开启theme-authoringfeature输出目录为仓库根的target/cursor-gallery/renderer-frames。该示例的帧导出参数export_gallery_frames.rs参数值说明SIZE256每帧像素尺寸预览放大用FPS30帧率DURATION_SECS4每段动画时长即每状态 120 帧PREVIEW_BACKING_SCALE1.5渲染背衬缩放RUNTIME_SESSION_LABELResearch预览会话标签导出状态分为两组actions/12 个纯动作状态deliveryNone、targetNone、session_labelNone即隔离的主题自有动作动画previews/12 × 3 × 5 180 个完整组合均带Research会话标签slug 形如observe--background--browser。每帧通过RenderStateCore组装cursor_id gallery-session、idle_hide_ms 0、光标置于画布中心、朝向 45°FRAC_PI_4依次应用SetSessionLabel与BeginAction { action, delivery, target }命令后调用render_frame输出 PNGexport_gallery_frames.rs。导出使用thread::scope并行分块工作线程数取min(available_parallelism, 12)。示例程序自带两个单元测试export_gallery_frames.rs一个校验运行时预览组合Observe Background Browser Research另一个断言预览清单恰好覆盖每种运行时组合一次12 * 3 * 5个 slug 互不重复且包含observe--background--browser、idle--none--none、system--foreground--desktop。这也从测试层面印证了 README 中覆盖全部组合的承诺。六、从帧到 WebMffmpeg 编码与页面装配export_assets随后对actions与previews两组帧目录逐一执行 ffmpeg 编码cursor-gallery.shffmpeg -y -loglevel error -framerate 30 \ -i $state_dir/%04d.png \ -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 \ -crf 28 -b:v 0 -row-mt 1 \ $GENERATED_DIR/$group/$state.webm要点VP9 编码、yuva420p保留透明通道光标叠加层需要 alpha、auto-alt-ref 0与-b:v 0配合 CRF 28 保证质量优先且码率不失控row-mt 1开启行级多线程。产物写入 tools/cursor-gallery/generated 下的actions/与previews/。页面侧由 app.js 动态渲染contexts deliveries.flatMap(...)生成 15 个徽标卡片actions生成 12 个动作卡片运行时预览则按action--delivery--target拼接 WebM 路径并热切换app.js。卡片底色按 light/dark/blue 三色调轮转并在顶部背景切换按钮下支持 Dark/Mixed/Light/Brand 四态。七、文档 GIF 导出headless Chrome CDP 确定性截图export-docs的完整链路cursor-gallery.sh复用export_assets生成帧与 WebM解析 Chrome 路径按CURSOR_GALLERY_CHROME→ macOS 默认路径 →google-chrome→chromium顺序探测用随机空闲端口启动python3 -m http.server以仓库根为目录与无头 Chrome--headlessnew --disable-gpu --autoplay-policyno-user-gesture-required --window-size1600,2200 --remote-debugging-portport通过 CDP 端口执行 capture-gallery.mjs用 ffmpeg 将截图序列编码为 GIF写入脚本定义的文档目录docs/public/img/cua-driver/cursor-themes/action-animations.gif。capture-gallery.mjs 的关键实现通过 WebSocket 直连 Chrome DevTools Protocol依赖 Node 内置 WebSocketREADME 中支持 WebSocket 的 Node.js即指此需以node --experimental-websocket运行Emulation.setDeviceMetricsOverride将视口设为 1600×2200与 Chrome--window-size对应导航后等待所有.cursor-video元素readyState 2把视频元素替换为img按FRAME_URL_ROOT/group/state/NNNN.png逐帧加载渲染器原始帧从 30fps 源帧中每隔一帧取一张sourceFrame frame * 2降采样为 15fps依据区块标题与网格的getBoundingClientRect()计算截图裁剪区含 30px 边距与底部留白每帧Page.captureScreenshot输出%04d.png环境变量CDP_ENDPOINT默认http://127.0.0.1:9229、PAGE_URL默认画廊地址、FRAME_URL_ROOT默认渲染帧目录。GIF 编码采用双遍调色板cursor-gallery.shpalettegenstats_modediff生成 1080px 宽 Lanczos 缩放的调色板再以paletteuseditherbayer:bayer_scale5:diff_moderectangle输出。由于帧源、参数与视口全部固定每次export-docs都能得到视觉一致的文档素材这正是 README 所称deterministically的含义。八、主题与运行时边界cua.default 从哪里来画廊预览的cua.default并非像素贴图而是一套有界矢量主题。其权威来源与编译产物说明见 cursor-overlay/assets/README.mdcua.default.lottie是规范源档案dotLottie 格式cua.default.cua-theme是由源档案编译出的有界运行时产物特权叠加层只嵌入并解码.cua-theme运行时绝不解析 dotLottie ZIP 或 Lottie JSON产物包含有界矢量几何、画笔、变换与采样动画帧而非固定分辨率像素图集Skia 以实时显示背衬尺度光栅化这些指令。重新生成两者的命令python3 crates/cursor-overlay/assets/build_default_theme.py cargo run -p cursor-theme-cli -- build \ crates/cursor-overlay/assets/cua.default.lottie \ --output crates/cursor-overlay/assets/cua.default.cua-theme cargo run -p cursor-theme-cli -- inspect \ crates/cursor-overlay/assets/cua.default.cua-theme配色边界与画廊语义呼应源主题以 Cua 蓝为调色板键、白色为描边只有内嵌默认主题在运行时被重着色为稳定的会话填充色已安装的自定义主题保留作者配色。共享浮动动画施加于选中动作之上而投放/目标上下文由宿主拥有的会话徽标绘制、不属于主题产物——这解释了为什么画廊中徽标上下文与动作动画被分为两个独立区块。运行时配置入口可参考 lib.rs 的 CursorConfig--cursor-theme id、--cursor-reduced-motion auto|on|off、--no-overlay、--glide-ms、--dwell-ms、--idle-hide-ms等参数会在各平台后端初始化叠加窗口时生效。九、环境变量与调试速查环境变量默认值作用CURSOR_GALLERY_PORT3001serve的 HTTP 端口CURSOR_GALLERY_CHROME自动探测Chrome/Chromium 可执行文件路径CURSOR_GALLERY_EXPORT_PORT随机空闲端口export-docs的静态文件服务端口CURSOR_GALLERY_EXPORT_CDP_PORT随机空闲端口Chrome 远程调试端口CDP_ENDPOINThttp://127.0.0.1:9229捕获脚本连接的无头 Chrome 端点PAGE_URLhttp://127.0.0.1:3001/捕获脚本导航的页面地址FRAME_URL_ROOThttp://127.0.0.1:3001/target/cursor-gallery/renderer-frames渲染帧静态根常见问题排查要点页面只有静态骨架没有动画generated/目录未生成先运行serve其内部会自动执行export_assets或单独运行assets报 Chrome not found设置CURSOR_GALLERY_CHROME指向 Chrome 可执行文件node提示 WebSocket 未定义Node 版本过旧需要支持--experimental-websocket的版本端口被占用serve用CURSOR_GALLERY_PORT覆盖export-docs的 HTTP/CDP 端口会自动挑选空闲端口一般无需干预素材未提交属预期行为generated/、target/cursor-gallery/均为构建产物不应出现在版本控制中。整个画廊的价值在于预览即生产无论是手工交互审查、回归比对还是文档 GIF 的再生成所有素材都来自同一套 Rust 渲染器与同一批帧杜绝了前端模拟与真实渲染之间的视觉漂移。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

qwen-code cua-driver 的 cursor-gallery 全解析：cua.default 光标渲染器的交互预览与文档素材确定性导出

相关推荐

2026营口化工产品成分分析检测排名 TOP5 CMA 资质提供含量检测、纯度检测、元素分析联系方式推荐

Highcharts React v4.2.1 版本核心升级与优化解析

2026 AI 论文工具综合排行榜｜公正客观测评，按需求选工具不踩坑

更多资讯

Telegraf 集成 systemd 凭据存储（systemd-creds）实现安全的明文凭据注入

记住我功能的安全隐患与防御实践

SymPy 梁弯曲分析完全指南：用奇异函数求解 Beam 与 Beam3D 的支座反力、剪力弯矩与挠度

oneTBB aggregator 基础接口详解：基于操作聚合的互斥执行机制

Zoom MCP「搜索即行动」模式实战：基于 knowledge-work-plugins 的会议语义搜索、资产提取与 REST 交接指南

SymPy 丢番图方程求解指南：用 diophantine 函数求整数解与参数化通解

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？