qwen-code Cua Driver 会话轨迹录制与回放实战指南RECORDING 技能深度解析【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本文围绕 qwen-code 仓库中 cua-driverRust 实现的 RECORDING.md 技能文档展开系统讲解会话级「操作轨迹录制 回放」机制它如何在 macOS / Windows / Linux 上采集动作序列与前/后状态如何产出可供演示、回归比对和训练数据使用的 turn 目录产物以及replay_trajectory回放的边界与最佳实践。读完本文你将掌握qwen-cua-driver recording start|status|stop与 MCP 录制工具族的完整用法并理解其底层实现原理源自 recording.rs 等源码。一、功能定位会话级的轨迹录制器start_recording是一个会话作用域session-scoped的轨迹录制器。启用后每次动作类工具调用click、right_click、scroll、type_text、press_key、hotkey、set_value都会在调用方指定的输出目录下写入一个带编号的 turn 文件夹同时采集动作前后的应用可访问性状态与窗口截图。该能力适合三类典型用途演示与录屏把 turn 文件夹回放给观众精确展示 Agent 看到了什么、做了什么回归比对把同一序列在未来的构建上重跑将新轨迹与保存的旧轨迹做 diff训练数据采集每个 turn 都是一个现成的(state, action, next_state)三元组可直接用于离线学习。值得强调的是只有动作类工具会被记录。只读工具get_window_state、list_windows、screenshot、list_apps、权限探测类工具、Agent 光标 getter/setter以及录制控制工具自身不写入轨迹因此录制不会因为感知类调用而产生噪音。录制是显式开启的该技能不会自动启用录制必须由客户端在用户提出「记录本次会话」等需求时显式调用start_recording({output_dir: …})并在结束时调用stop_recording({})。若用户要求录屏但不需要视频可传入record_video: false关闭视频采集。二、跨平台视频采集后端原生 SCKit 与 ffmpeg 子进程start_recording在录制逐 turn 证据的同时还会把主显示器画面采集为output_dir/recording.mp4H.264 / 30 fps视频在stop_recording时完成收尾finalize。视频采集的后端按平台分流平台视频后端前置依赖说明macOS原生 ScreenCaptureKitSCStreamSCRecordingOutput无无需 ffmpeg要求 macOS 15.0SCRecordingOutput于 macOS 15 引入录制进程继承 daemon 的「屏幕录制」授权不会出现额外的子进程 TCC 弹窗、快速失败或第二次授权交互Windowsffmpeg 子进程gdigrab采集整块虚拟桌面ffmpeg 需在 PATHwinget install Gyan.FFmpeg缺 ffmpeg 时逐 turn 采集继续运行last_error携带安装提示Linuxffmpeg 子进程x11grab$DISPLAY环境变量缺省:0.0ffmpeg 需在 PATHapt install ffmpeg同上可用CUA_DRIVER_RS_DRAW_SYSTEM_CURSOR0隐藏真实系统指针让画面只保留合成 Agent 光标ffmpeg 后端的具体编码参数见 video_ffmpeg.rs统一使用libx264 -preset ultrafast -pix_fmt yuv420p并带-movflags faststart便于边录边播由于 yuv420p 要求偶数尺寸采集管线会先用padceil(iw/2)*2:ceil(ih/2)*2补齐奇数分辨率例如 1512×949 的 Win11 屏幕。ffmpeg 的优雅关闭方式是向其 stdin 发送q\n以收尾 moov atom若 3 秒内未退出则强制 kill此时 mp4 不可播放finalized: false会明确告知调用方启动时还有 1.5 秒的快速失败探测ffmpeg 一旦启动即崩溃错误信息会携带 stderr 尾部。macOS 侧的实现见 video_sckit.rs进程内SCStreamSCRecordingOutput以 H.264 / MP4 编码写入输出路径stop_capture()会同步收尾 moov atom启动时若发现残留的旧recording.mp4会先行清理避免追加写入。视频默认开关的细节RECORDING 文档以 CLI 视角描述「Video on by default」——CLIrecording start路径确实强制开启视频见 recording.rs 中configure()的注释。但 MCP 的start_recording工具在 recording_tools.rs 中默认record_video: false显式传true才录视频。因此实际行为取决于调用入口CLI 默认带视频MCP 默认不带。另外即使 ffmpeg 缺失或启动失败逐 turn 的截图 JSON 采集不受影响last_error会携带诊断信息。三、开始 / 停止录制两套等价入口录制有两个等价的操作面MCP 工具start_recording/stop_recording/get_recording_state/replay_trajectory和更友好的CLI 子命令组qwen-cua-driver recording start|stop|status对工具做了人性化输出包装。CLI 子命令方式qwen-cua-driver recording start ~/cua-trajectories/run-1 # … 运行工作流 … qwen-cua-driver recording status # - enabled / disabled, next_turn, output_dir qwen-cua-driver recording stop # - Recording stopped. (video → recording.mp4)原始 MCP 工具方式qwen-cua-driver start_recording {output_dir:~/cua-trajectories/run-1} qwen-cua-driver get_recording_state qwen-cua-driver stop_recording {}关于这两种方式有几条关键语义可从 cli.rs 的run_recording_cmd与 recording_tools.rs 的invoke实现得到印证需要运行中的 daemonrecording子命令要求先启动qwen-cua-driver serve 因为录制状态是**进程内per-process**的。daemon 未运行时会提示Start it first with: qwen-cua-driver serve并退出唯一的例外是recording render子命令纯文件到文件的渲染无需 daemon见下文第七节。路径处理output_dir支持~展开代码中手动替换HOME目录不存在时连同中间层级一起创建。turn 编号每次重新启用录制turn 编号都从1重新开始与目录中已有内容无关编号为五位零填充turn-00001/。状态仅存内存daemon 重启后录制状态重置为 disabled磁盘上不会残留“启用”标记。停止的幂等性stop_recording对已停止的会话是无操作no-op不会报错带视频时返回last_video_path指向已收尾的 mp4。手动停止是无条件的无论录制由哪个会话开启手动stop_recording都会停掉当前激活的录制而「某客户端断开连接只能回收自己发起的录制」这一按会话归属的回收逻辑由 daemon 的session_end生命周期钩子调用stop_owner(sid)完成而不是由该工具承担防止会话 A 断开时误停会话 B 后来开启的录制。四、每个 turn 文件夹的产物结构每次动作调用都会产生一个turn-NNNNN/文件夹五位零填充计数器其中包含以下文件文件含义before_state.json/after_state.json动作执行前后、目标应用的可访问性状态快照字段形态与get_window_state的tree_markdown、element_count一致before.png/after.png动作执行前后目标窗口的图像即使窗口被其他窗口遮挡窗口级采集仍限定在目标窗口范围内evidence.json每个阶段before/after/click的采集状态清单期望的采集缺失时会有明确的分类而不是从 turn 中消失详见下文app_state.json/screenshot.png兼容别名分别等价于after_state.json与after.png供旧版轨迹读取器使用action.json动作核心记录工具名、完整输入参数、结果摘要、结果错误标志、pid、点击点如适用、ISO-8601 时间戳click.png仅 click 家族动作click、double_click、right_click产生在before.png副本上用红色标记绘制点击点click.png 的两种寻址模式click.png对两种寻址模式都做了覆盖这是文档强调的实现细节显式x, y像素点击直接使用调用传入的坐标element_index寻址点击通过实时的 AX/UIA 缓存把元素索引解析为元素中心点再换算为窗口局部截图像素resolve_click_point的实现见 recording.rs其坐标空间与get_window_state返回的 PNG 完全一致。此外有两个「负向」分类需要理解当 driver 在目标解析前拒绝了一次点击没有对准任何输入click.png不生成并在evidence.json中显式分类为not_applicableaction_refused_before_target_resolution而一次已派发的点击若无法解析或渲染标记则会被计为证据失败evidence failure两者语义严格区分。evidence.json采集状态的显式分类evidence.json使用cua-turn-evidence/v1schema见 recording.rs 的write_evidence_manifest对 before/after 的 state 与 screenshot、以及 click 分别给出captured/unavailable/not_applicable三种状态captured期望的产物已成功采集unavailable采集失败或回调未注册携带classification如capture_failed、capture_hook_unavailable、privacy_suppressednot_applicable本就不该采集如无目标 pid、非点击动作、目标解析前被拒绝的点击。这一设计让「缺失」成为可审计的分类事件而不是从轨迹中悄悄消失。五、action.json 字段与底层写入路径action.json是回放的核心输入其 schema与 Swift/Windows 参考实现保持一致如下{ tool: click, arguments: { pid: 844, window_id: 10725, element_index: 14 }, result_summary: …, result_error: false, timestamp: 1789000000.123, t_ms_from_session_start: 12345, t_start_ms_from_session_start: 12340, click_point: { x: 320.0, y: 240.0 } }字段说明tool为工具名arguments为完整输入参数内部注入的下划线前缀键会被剥离——例如 daemon 注入的_session_id绝不会泄漏进持久化轨迹见strip_internal_keysresult_summary为结果摘要result_error为结果错误标志timestamp为 ISO-8601 时间戳实现上输出为带毫秒的小数 Unix 秒t_ms_from_session_start与t_start_ms_from_session_start为会话起点锚定的毫秒时间供回放与渲染对齐时序click_point在点击类动作适用时写入。录制器的工作方式是先保留、后落盘的两阶段模型begin_turn在工具派发前立即预留 turn 目录并采集 before 阶段→ 工具执行 →finish_turn派发后采集 after 阶段并一次性写入全部产物。这样即使调用乱序完成before/after 也共享同一个稳定的turn-NNNNN目录。每个会话还共享一个单调时钟锚点session_monotonic_start让视频、光标采样与action.json的毫秒时间线彼此对齐。此外录制会话会在输出目录额外生成两个代码级产物文档未展开但源码可证session.json启动时写入含schema_version、started_at_monotonic_ms、视频块、光标块停止时重写为最终形态视频present/path/duration_ms/finalized与光标sample_countcursor.jsonl后台光标采样线程以约 30 Hz 轮询记录光标位置为渲染器提供逐帧光标坐标见 recording.rs 的CursorSampler启动逻辑。六、轨迹回放replay_trajectoryreplay_trajectory({dir})按字典序遍历dir/turn-NNNNN/文件夹读取每个action.json并以记录的arguments重新调用对应的工具经由与 MCP/CLI 相同的派发路径见 recording_tools.rs 的ReplayTrajectoryTool。参数说明参数类型默认值说明dirstring必填此前由start_recording写出的轨迹目录支持绝对路径或~开头路径目录必须存在且至少含一个turn-文件夹delay_msinteger500每个 turn 之间的间隔毫秒数用于人类可观察的节奏schema 上限 10000stop_on_errorbooleantrue遇到首个工具调用错误是否停止设为false可尽力跑完整个轨迹典型用法qwen-cua-driver recording start ~/cua-trajectories/demo1 # … 运行工作流 … qwen-cua-driver recording stop # 之后针对新构建回放 qwen-cua-driver replay_trajectory {dir:~/cua-trajectories/demo1,delay_ms:500}回放完成后的结构化结果包含attempted/succeeded/failed计数、stop_on_error、每个 turn 的ok与result_summary以及首个失败点first_failure.turn/first_failure.tool/first_failure.error。回放即回归录制期间的再录制语义如果回放时录制仍然处于启用状态回放本身也会被录进当前输出目录——这正是文档明确设计的回归-diff 工作流在新构建上录制一次回放然后把两条轨迹做比对。若单个turn-NNNNN/action.json缺失或解析失败回放会将其记为失败并在stop_on_error: true时中断。七、回放的边界与注意事项element_index 无法跨会话存活这是回放最重要的 caveatelement_index不跨会话存活。索引在每次get_window_state快照时都会重新分配并以(pid, window_id)为键昨天录制的click({pid, window_id, element_index: 14})今天无法解析——pid 通常不同window_id 则总是不同。调用会返回Invalid element_index或No cached AX state。与之相对像素点击click({pid, x, y})与键盘类工具press_key、hotkey、不含element_index的type_text可以干净地回放。element-indexed 动作需要一次实时快照而回放目前不会重新产出快照只读工具如get_window_state本身不被录制recording_tools.rs 的工具描述也明确指出回放不会重新填充按(pid, window_id)键控的元素缓存。因此可靠的回放策略是二选一用像素 键盘原语组合轨迹保证可重放性把轨迹当作回归产物对比不同构建之间的成功/失败模式而不是当作可反复驱动的脚本。另外注意delay_ms存在上限schema 中maximum: 10000invoke 中.min(10_000)二次兜底。八、配套轨迹渲染与 ffmpeg 安装工具除录制/回放外还有两个相关的辅助能力qwen-cua-driver recording render纯文件到文件的渲染子命令cli.rs 在 daemon 检查之前先行派发不需要运行中的 daemon。其加载逻辑见 recording_loader.rs读取session.json必需、recording.mp4必需缺失则硬错误VideoMissing、cursor.jsonl可选缺失退化为空向量与各 turn 的action.json产出SessionMetadata、按时间排序的ClickEvent/CursorSample/ActionSpan。点击坐标的恢复按优先级依次取arguments.{x,y}→click_point→ 从result_summary文本中解析(screen (X,Y))模式保证 element_index 工作流下缩放渲染仍可用。install_ffmpeg确认门控的 ffmpeg 安装工具见 recording_tools.rs。不带confirm时只报告将执行的安装命令只读预览confirm: true才真正执行ffmpeg 已在 PATH 时直接提示无需安装。它被标记为destructive open_world符合规范的 MCP 客户端也会把它放在人工审批之后。Linux 下支持 apt/dnf/pacman/zypper/apk/snap 等包管理器macOS 建议brew install ffmpegWindows 用winget install Gyan.FFmpegffmpeg 以独立进程方式被调用从不链接进 driver。九、源码导航若想深入机制以下文件是直接的阅读入口技能文档本体RECORDING.md本文主题其上层使用规范见同目录 SKILL.md录制会话核心状态机start/stop/owner、turn 预留与落盘、evidence 清单、session.json 写入recording.rs四个录制/回放工具的定义与参数 schemastart_recording/stop_recording/get_recording_state/replay_trajectory/install_ffmpegrecording_tools.rs轨迹目录读取与渲染输入装配session.json/cursor.jsonl/ turn 解析recording_loader.rsWindows/Linux ffmpeg 子进程后端gdigrab / x11grab / libx264 参数与优雅关闭video_ffmpeg.rsmacOS 原生 ScreenCaptureKit 后端SCStream SCRecordingOutputvideo_sckit.rsCLIrecording start|stop|status|render子命令实现cli.rs十、小结何时用、怎么用一句话总结录制能力的使用决策要演示/录屏CLIrecording start dir默认带视频 → 跑工作流 →recording stopturn 文件夹与 mp4 一起交付要做回归录制一条基线轨迹换构建后开启录制再replay_trajectory两条轨迹 diff 即回归结果回放会被再录制正是为此设计要采集训练数据每个 turn 都是天然的(state, action, next_state)三元组action.jsonbefore/after状态与图像就是完整样本要可靠重放轨迹尽量由像素点击 键盘原语构成避免 element-indexed 动作涉及敏感内容如已登录浏览器配置时代码还提供了抑制视觉/可访问性采集的私有 turn 路径privacy_suppressed分类保证动作元数据与结构化结果可审计、而页面或对话框内容不被持久化。无论从哪个入口启用请记住三条不变式录制必须显式开启、output_dir会~展开并自动创建、录制状态只存活于 daemon 进程内——重启即回到 disabled。【免费下载链接】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 会话轨迹录制与回放实战指南：RECORDING 技能深度解析
qwen-code Cua Driver 会话轨迹录制与回放实战指南RECORDING 技能深度解析【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本文围绕 qwen-code 仓库中 cua-driverRust 实现的 RECORDING.md 技能文档展开系统讲解会话级「操作轨迹录制 回放」机制它如何在 macOS / Windows / Linux 上采集动作序列与前/后状态如何产出可供演示、回归比对和训练数据使用的 turn 目录产物以及replay_trajectory回放的边界与最佳实践。读完本文你将掌握qwen-cua-driver recording start|status|stop与 MCP 录制工具族的完整用法并理解其底层实现原理源自 recording.rs 等源码。一、功能定位会话级的轨迹录制器start_recording是一个会话作用域session-scoped的轨迹录制器。启用后每次动作类工具调用click、right_click、scroll、type_text、press_key、hotkey、set_value都会在调用方指定的输出目录下写入一个带编号的 turn 文件夹同时采集动作前后的应用可访问性状态与窗口截图。该能力适合三类典型用途演示与录屏把 turn 文件夹回放给观众精确展示 Agent 看到了什么、做了什么回归比对把同一序列在未来的构建上重跑将新轨迹与保存的旧轨迹做 diff训练数据采集每个 turn 都是一个现成的(state, action, next_state)三元组可直接用于离线学习。值得强调的是只有动作类工具会被记录。只读工具get_window_state、list_windows、screenshot、list_apps、权限探测类工具、Agent 光标 getter/setter以及录制控制工具自身不写入轨迹因此录制不会因为感知类调用而产生噪音。录制是显式开启的该技能不会自动启用录制必须由客户端在用户提出「记录本次会话」等需求时显式调用start_recording({output_dir: …})并在结束时调用stop_recording({})。若用户要求录屏但不需要视频可传入record_video: false关闭视频采集。二、跨平台视频采集后端原生 SCKit 与 ffmpeg 子进程start_recording在录制逐 turn 证据的同时还会把主显示器画面采集为output_dir/recording.mp4H.264 / 30 fps视频在stop_recording时完成收尾finalize。视频采集的后端按平台分流平台视频后端前置依赖说明macOS原生 ScreenCaptureKitSCStreamSCRecordingOutput无无需 ffmpeg要求 macOS 15.0SCRecordingOutput于 macOS 15 引入录制进程继承 daemon 的「屏幕录制」授权不会出现额外的子进程 TCC 弹窗、快速失败或第二次授权交互Windowsffmpeg 子进程gdigrab采集整块虚拟桌面ffmpeg 需在 PATHwinget install Gyan.FFmpeg缺 ffmpeg 时逐 turn 采集继续运行last_error携带安装提示Linuxffmpeg 子进程x11grab$DISPLAY环境变量缺省:0.0ffmpeg 需在 PATHapt install ffmpeg同上可用CUA_DRIVER_RS_DRAW_SYSTEM_CURSOR0隐藏真实系统指针让画面只保留合成 Agent 光标ffmpeg 后端的具体编码参数见 video_ffmpeg.rs统一使用libx264 -preset ultrafast -pix_fmt yuv420p并带-movflags faststart便于边录边播由于 yuv420p 要求偶数尺寸采集管线会先用padceil(iw/2)*2:ceil(ih/2)*2补齐奇数分辨率例如 1512×949 的 Win11 屏幕。ffmpeg 的优雅关闭方式是向其 stdin 发送q\n以收尾 moov atom若 3 秒内未退出则强制 kill此时 mp4 不可播放finalized: false会明确告知调用方启动时还有 1.5 秒的快速失败探测ffmpeg 一旦启动即崩溃错误信息会携带 stderr 尾部。macOS 侧的实现见 video_sckit.rs进程内SCStreamSCRecordingOutput以 H.264 / MP4 编码写入输出路径stop_capture()会同步收尾 moov atom启动时若发现残留的旧recording.mp4会先行清理避免追加写入。视频默认开关的细节RECORDING 文档以 CLI 视角描述「Video on by default」——CLIrecording start路径确实强制开启视频见 recording.rs 中configure()的注释。但 MCP 的start_recording工具在 recording_tools.rs 中默认record_video: false显式传true才录视频。因此实际行为取决于调用入口CLI 默认带视频MCP 默认不带。另外即使 ffmpeg 缺失或启动失败逐 turn 的截图 JSON 采集不受影响last_error会携带诊断信息。三、开始 / 停止录制两套等价入口录制有两个等价的操作面MCP 工具start_recording/stop_recording/get_recording_state/replay_trajectory和更友好的CLI 子命令组qwen-cua-driver recording start|stop|status对工具做了人性化输出包装。CLI 子命令方式qwen-cua-driver recording start ~/cua-trajectories/run-1 # … 运行工作流 … qwen-cua-driver recording status # - enabled / disabled, next_turn, output_dir qwen-cua-driver recording stop # - Recording stopped. (video → recording.mp4)原始 MCP 工具方式qwen-cua-driver start_recording {output_dir:~/cua-trajectories/run-1} qwen-cua-driver get_recording_state qwen-cua-driver stop_recording {}关于这两种方式有几条关键语义可从 cli.rs 的run_recording_cmd与 recording_tools.rs 的invoke实现得到印证需要运行中的 daemonrecording子命令要求先启动qwen-cua-driver serve 因为录制状态是**进程内per-process**的。daemon 未运行时会提示Start it first with: qwen-cua-driver serve并退出唯一的例外是recording render子命令纯文件到文件的渲染无需 daemon见下文第七节。路径处理output_dir支持~展开代码中手动替换HOME目录不存在时连同中间层级一起创建。turn 编号每次重新启用录制turn 编号都从1重新开始与目录中已有内容无关编号为五位零填充turn-00001/。状态仅存内存daemon 重启后录制状态重置为 disabled磁盘上不会残留“启用”标记。停止的幂等性stop_recording对已停止的会话是无操作no-op不会报错带视频时返回last_video_path指向已收尾的 mp4。手动停止是无条件的无论录制由哪个会话开启手动stop_recording都会停掉当前激活的录制而「某客户端断开连接只能回收自己发起的录制」这一按会话归属的回收逻辑由 daemon 的session_end生命周期钩子调用stop_owner(sid)完成而不是由该工具承担防止会话 A 断开时误停会话 B 后来开启的录制。四、每个 turn 文件夹的产物结构每次动作调用都会产生一个turn-NNNNN/文件夹五位零填充计数器其中包含以下文件文件含义before_state.json/after_state.json动作执行前后、目标应用的可访问性状态快照字段形态与get_window_state的tree_markdown、element_count一致before.png/after.png动作执行前后目标窗口的图像即使窗口被其他窗口遮挡窗口级采集仍限定在目标窗口范围内evidence.json每个阶段before/after/click的采集状态清单期望的采集缺失时会有明确的分类而不是从 turn 中消失详见下文app_state.json/screenshot.png兼容别名分别等价于after_state.json与after.png供旧版轨迹读取器使用action.json动作核心记录工具名、完整输入参数、结果摘要、结果错误标志、pid、点击点如适用、ISO-8601 时间戳click.png仅 click 家族动作click、double_click、right_click产生在before.png副本上用红色标记绘制点击点click.png 的两种寻址模式click.png对两种寻址模式都做了覆盖这是文档强调的实现细节显式x, y像素点击直接使用调用传入的坐标element_index寻址点击通过实时的 AX/UIA 缓存把元素索引解析为元素中心点再换算为窗口局部截图像素resolve_click_point的实现见 recording.rs其坐标空间与get_window_state返回的 PNG 完全一致。此外有两个「负向」分类需要理解当 driver 在目标解析前拒绝了一次点击没有对准任何输入click.png不生成并在evidence.json中显式分类为not_applicableaction_refused_before_target_resolution而一次已派发的点击若无法解析或渲染标记则会被计为证据失败evidence failure两者语义严格区分。evidence.json采集状态的显式分类evidence.json使用cua-turn-evidence/v1schema见 recording.rs 的write_evidence_manifest对 before/after 的 state 与 screenshot、以及 click 分别给出captured/unavailable/not_applicable三种状态captured期望的产物已成功采集unavailable采集失败或回调未注册携带classification如capture_failed、capture_hook_unavailable、privacy_suppressednot_applicable本就不该采集如无目标 pid、非点击动作、目标解析前被拒绝的点击。这一设计让「缺失」成为可审计的分类事件而不是从轨迹中悄悄消失。五、action.json 字段与底层写入路径action.json是回放的核心输入其 schema与 Swift/Windows 参考实现保持一致如下{ tool: click, arguments: { pid: 844, window_id: 10725, element_index: 14 }, result_summary: …, result_error: false, timestamp: 1789000000.123, t_ms_from_session_start: 12345, t_start_ms_from_session_start: 12340, click_point: { x: 320.0, y: 240.0 } }字段说明tool为工具名arguments为完整输入参数内部注入的下划线前缀键会被剥离——例如 daemon 注入的_session_id绝不会泄漏进持久化轨迹见strip_internal_keysresult_summary为结果摘要result_error为结果错误标志timestamp为 ISO-8601 时间戳实现上输出为带毫秒的小数 Unix 秒t_ms_from_session_start与t_start_ms_from_session_start为会话起点锚定的毫秒时间供回放与渲染对齐时序click_point在点击类动作适用时写入。录制器的工作方式是先保留、后落盘的两阶段模型begin_turn在工具派发前立即预留 turn 目录并采集 before 阶段→ 工具执行 →finish_turn派发后采集 after 阶段并一次性写入全部产物。这样即使调用乱序完成before/after 也共享同一个稳定的turn-NNNNN目录。每个会话还共享一个单调时钟锚点session_monotonic_start让视频、光标采样与action.json的毫秒时间线彼此对齐。此外录制会话会在输出目录额外生成两个代码级产物文档未展开但源码可证session.json启动时写入含schema_version、started_at_monotonic_ms、视频块、光标块停止时重写为最终形态视频present/path/duration_ms/finalized与光标sample_countcursor.jsonl后台光标采样线程以约 30 Hz 轮询记录光标位置为渲染器提供逐帧光标坐标见 recording.rs 的CursorSampler启动逻辑。六、轨迹回放replay_trajectoryreplay_trajectory({dir})按字典序遍历dir/turn-NNNNN/文件夹读取每个action.json并以记录的arguments重新调用对应的工具经由与 MCP/CLI 相同的派发路径见 recording_tools.rs 的ReplayTrajectoryTool。参数说明参数类型默认值说明dirstring必填此前由start_recording写出的轨迹目录支持绝对路径或~开头路径目录必须存在且至少含一个turn-文件夹delay_msinteger500每个 turn 之间的间隔毫秒数用于人类可观察的节奏schema 上限 10000stop_on_errorbooleantrue遇到首个工具调用错误是否停止设为false可尽力跑完整个轨迹典型用法qwen-cua-driver recording start ~/cua-trajectories/demo1 # … 运行工作流 … qwen-cua-driver recording stop # 之后针对新构建回放 qwen-cua-driver replay_trajectory {dir:~/cua-trajectories/demo1,delay_ms:500}回放完成后的结构化结果包含attempted/succeeded/failed计数、stop_on_error、每个 turn 的ok与result_summary以及首个失败点first_failure.turn/first_failure.tool/first_failure.error。回放即回归录制期间的再录制语义如果回放时录制仍然处于启用状态回放本身也会被录进当前输出目录——这正是文档明确设计的回归-diff 工作流在新构建上录制一次回放然后把两条轨迹做比对。若单个turn-NNNNN/action.json缺失或解析失败回放会将其记为失败并在stop_on_error: true时中断。七、回放的边界与注意事项element_index 无法跨会话存活这是回放最重要的 caveatelement_index不跨会话存活。索引在每次get_window_state快照时都会重新分配并以(pid, window_id)为键昨天录制的click({pid, window_id, element_index: 14})今天无法解析——pid 通常不同window_id 则总是不同。调用会返回Invalid element_index或No cached AX state。与之相对像素点击click({pid, x, y})与键盘类工具press_key、hotkey、不含element_index的type_text可以干净地回放。element-indexed 动作需要一次实时快照而回放目前不会重新产出快照只读工具如get_window_state本身不被录制recording_tools.rs 的工具描述也明确指出回放不会重新填充按(pid, window_id)键控的元素缓存。因此可靠的回放策略是二选一用像素 键盘原语组合轨迹保证可重放性把轨迹当作回归产物对比不同构建之间的成功/失败模式而不是当作可反复驱动的脚本。另外注意delay_ms存在上限schema 中maximum: 10000invoke 中.min(10_000)二次兜底。八、配套轨迹渲染与 ffmpeg 安装工具除录制/回放外还有两个相关的辅助能力qwen-cua-driver recording render纯文件到文件的渲染子命令cli.rs 在 daemon 检查之前先行派发不需要运行中的 daemon。其加载逻辑见 recording_loader.rs读取session.json必需、recording.mp4必需缺失则硬错误VideoMissing、cursor.jsonl可选缺失退化为空向量与各 turn 的action.json产出SessionMetadata、按时间排序的ClickEvent/CursorSample/ActionSpan。点击坐标的恢复按优先级依次取arguments.{x,y}→click_point→ 从result_summary文本中解析(screen (X,Y))模式保证 element_index 工作流下缩放渲染仍可用。install_ffmpeg确认门控的 ffmpeg 安装工具见 recording_tools.rs。不带confirm时只报告将执行的安装命令只读预览confirm: true才真正执行ffmpeg 已在 PATH 时直接提示无需安装。它被标记为destructive open_world符合规范的 MCP 客户端也会把它放在人工审批之后。Linux 下支持 apt/dnf/pacman/zypper/apk/snap 等包管理器macOS 建议brew install ffmpegWindows 用winget install Gyan.FFmpegffmpeg 以独立进程方式被调用从不链接进 driver。九、源码导航若想深入机制以下文件是直接的阅读入口技能文档本体RECORDING.md本文主题其上层使用规范见同目录 SKILL.md录制会话核心状态机start/stop/owner、turn 预留与落盘、evidence 清单、session.json 写入recording.rs四个录制/回放工具的定义与参数 schemastart_recording/stop_recording/get_recording_state/replay_trajectory/install_ffmpegrecording_tools.rs轨迹目录读取与渲染输入装配session.json/cursor.jsonl/ turn 解析recording_loader.rsWindows/Linux ffmpeg 子进程后端gdigrab / x11grab / libx264 参数与优雅关闭video_ffmpeg.rsmacOS 原生 ScreenCaptureKit 后端SCStream SCRecordingOutputvideo_sckit.rsCLIrecording start|stop|status|render子命令实现cli.rs十、小结何时用、怎么用一句话总结录制能力的使用决策要演示/录屏CLIrecording start dir默认带视频 → 跑工作流 →recording stopturn 文件夹与 mp4 一起交付要做回归录制一条基线轨迹换构建后开启录制再replay_trajectory两条轨迹 diff 即回归结果回放会被再录制正是为此设计要采集训练数据每个 turn 都是天然的(state, action, next_state)三元组action.jsonbefore/after状态与图像就是完整样本要可靠重放轨迹尽量由像素点击 键盘原语构成避免 element-indexed 动作涉及敏感内容如已登录浏览器配置时代码还提供了抑制视觉/可访问性采集的私有 turn 路径privacy_suppressed分类保证动作元数据与结构化结果可审计、而页面或对话框内容不被持久化。无论从哪个入口启用请记住三条不变式录制必须显式开启、output_dir会~展开并自动创建、录制状态只存活于 daemon 进程内——重启即回到 disabled。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考