录制与回放

录制与回放让你把一段真实操作「演示」给专家：你照平时的方式做一遍，专家在后台记录事件、截图和你的语音解说，然后把这段演示变成可复用的能力。

这是桌面端专属能力：插件需要 desktop_connected: true 才激活，网页端看不到也用不了。原生事件流录制仅 macOS；Windows / Linux 走 CUA 轨迹录制。

两条路，语义完全不同

这是最容易混淆的地方——「录制」之后有两种截然不同的产物：

路径	产物	回放方式	平台
原生事件流 → 技能	一个可复用技能（skill）	语义回放：运行时重新定位元素，页面变了也能适应	仅 macOS
CUA 轨迹录制	一批 `turn-NNNNN/` 轨迹文件夹	机械回放：按记录的参数重新调用工具	macOS / Windows / Linux

选择原则：要长期复用选技能，要精确重现选轨迹。技能能适应变化但不保证逐帧一致；轨迹逐步一致但页面一变就断。

路径一：录制 → 技能（macOS）

它实际怎么工作

开始录制

你说「录一下我的操作」，专家调 event_stream_start。屏幕上出现一个悬浮「录制中」条，带停止按钮。录制是后台系统级进程：捕获所有应用、所有窗口的点击与输入。切屏、切应用、最小化聊天窗口都不会中断录制。

边做边说

如果返回 audioRecording: true，麦克风同时在录你的语音解说。这一步值得做——你说出来的意图比从点击里猜出来的更可靠，专家生成技能的质量会明显提升。

停止

点悬浮条上的停止按钮（推荐），或回到对话说「录完了」。两条路都会走到分析步骤。

专家分析并生成技能

专家读取事件文件、截图和语音转写，理解「你做了什么」和「为什么这么做」，然后用 skill_manage(action="create") 落成一个技能。这一步成功了才算录制完成。

下次直接用

新会话里直接说技能对应的任务名，专家按技能执行——它会在运行时重新定位按钮和字段，不依赖当初的坐标。

录制产出了什么

会话目录在 ~/.profy/recordings/{sessionId}/：

~/.profy/recordings/<uuid>/
├── events.jsonl        # 每行一个事件：app_switch / mouse_click / key_down / scroll …
├── session.json        # 会话元数据：起止时间、结束原因、事件条数
└── snapshots/
    ├── <时间戳>-<触发原因>.png    # 关键时刻截图
    └── <时间戳>-<触发原因>.json   # 同一时刻的窗口无障碍树（AX tree）

这些是磁盘上的普通文件，专家用 read 工具分段读取。events.jsonl 常有数千行，一次读完会撑爆上下文，所以专家会按 100 行为一段抽样（开头、结尾、中间补齐），并优先看 app_switch / mouse_click / key_down，跳过 scroll / mouse_move 这类噪声。

路径二：CUA 轨迹录制与回放（跨平台）

轨迹录制不是自动开启的——必须你明确要求。开启后，每一个动作类工具调用（click / right_click / scroll / type_text / press_key / hotkey / set_value）都会写一个编号文件夹；只读工具（截图、列窗口、取窗口状态）不记录。

cua-driver recording start ~/cua-trajectories/run-1
cua-driver recording status
cua-driver recording stop

每个动作写入 turn-NNNNN/（五位补零编号）：

文件	内容
`action.json`	工具名、完整入参、结果摘要、pid、点击坐标、ISO-8601 时间戳
`app_state.json`	动作后的无障碍树快照
`screenshot.png`	动作后的窗口截图
`click.png`	仅点击类动作：截图上用红点标出点击位置

回放用 replay_trajectory({dir})：按字典序遍历 turn-NNNNN/，读 action.json，用记录的参数重新调用同一工具。两个可调参数：delay_ms（步间节奏，默认 500）、stop_on_error（遇错即停，默认 true）。

元素寻址不能跨会话回放。cua-driver 0.17 会拒绝过期的 element_token，也直接拒绝裸 element_index。所以：

像素点击（click({pid, window_id, x, y})）和键盘操作能干净回放
元素寻址的动作需要一次新的 get_window_state，而机械回放不会重新发起

要可靠回放，就用像素 + 键盘原语组合轨迹；要适应变化，走技能（语义回放会在运行时重新解析元素）。

适用场景

把重复劳动变成一句话

每周从系统导数据、整理格式、发报告？录一次，之后一句话触发。这是技能路径最典型的用法。

教专家用一个它不熟的软件

内部系统、小众工具没有公开文档，演示一遍比解释十遍有效。语音解说在这里价值最大。

回归验证

录一条轨迹作为基线，改动后重跑对比状态快照。这是轨迹路径的主场——它本来就是为回归 diff 设计的。

训练数据采集

每个 turn 文件夹天然是一个 (状态, 动作, 新状态) 三元组。

内置应用技能

插件自带 6 个常用应用的操作技能：时钟、Numbers、Spotify、Notion、音乐、iPhone 镜像。这些不用你自己录。

关键数值

项目	数值
单次录制最长时长	30 分钟（到点自动停止，结束原因记为 `timeout`）
同时录制数	1 个（已有录制在跑时不能再起一个）
轨迹回放步间延迟	500 毫秒（默认，可调）
轨迹回放遇错行为	立即停止（默认，可调）
事件文件读取粒度	每次 100 行（专家侧约定，防止上下文溢出）
插件自带技能数	9 个（录制回放 2 个 + CUA 驱动 1 个 + 应用技能 6 个）

失败与对策

现象	原因	对策
插件面板里没有「录制与回放」	该插件需要桌面端连接（`desktop_connected: true`）	用 Profy 桌面端；网页端不提供
「recorder tools require the Profy Desktop app」	sidecar 未连接	确认桌面端在运行且已登录
提示只支持 macOS	原生事件流（profy-event-tap）是 macOS 专有	Windows / Linux 用 CUA 轨迹录制
录制启动后 `events.jsonl` 是空的 / 报「Capture process exited」	辅助功能权限未授予——捕获进程起不来	系统设置 → 隐私与安全性 → 辅助功能，勾选 Profy，重新开始
「A recording is already in progress」	同时只允许一个录制	用当前那个，或先停掉再录
录制自己停了，结束原因是 timeout	到了 30 分钟上限	把长流程拆成几段分别录
专家说录制内容不足以生成技能	事件里看不出意图（比如全是滚动和移动）	重录一遍并开语音解说，边做边说为什么
回放到某一步就断，报元素过期	元素寻址不能跨会话回放	改用像素 + 键盘原语，或走技能路径
回放太快，界面还没反应就点下一步	默认步间 500 毫秒不够	让专家调大 `delay_ms`
密码步骤回放不了	录制不明文保留密码	回放前手动输入，或用系统密码管理器填充

回放会在你的真实桌面上执行真实操作。涉及第三方系统时先确认你有权限，正式跑之前先试运行一次——它不会替你判断这个操作是否可逆。

计费

录制本身不消耗积分（捕获在本机进行）。产生消耗的是专家分析录制内容和执行回放时的模型调用——读事件文件、看截图都是 token，长录制的分析成本明显高于短录制，这也是建议分段录的另一个理由。

核对日期 2026-08-12。来源：services/agent-runtime/src/plugins/builtin/record-and-replay/（plugin.json、tools/event_stream.py、skills/record-replay.md、skills/cua-recording.md）、apps/desktop/src/main/lib/recorder/event-stream.ts。

电脑操作

了解专家如何操作桌面应用

技能

了解技能怎么存、怎么被调用

开始使用

核心概念

使用指南

平台与账户

深入了解

两条路，语义完全不同

路径一：录制 → 技能（macOS）

它实际怎么工作

录制产出了什么

路径二：CUA 轨迹录制与回放（跨平台）

适用场景

关键数值

失败与对策

计费

相关

电脑操作

技能

​两条路，语义完全不同

​路径一：录制 → 技能（macOS）

​它实际怎么工作

​录制产出了什么

​路径二：CUA 轨迹录制与回放（跨平台）

​适用场景

​关键数值

​失败与对策

​计费

​相关

电脑操作

技能

两条路，语义完全不同

路径一：录制 → 技能（macOS）

它实际怎么工作

录制产出了什么

路径二：CUA 轨迹录制与回放（跨平台）

适用场景

关键数值

失败与对策

计费

相关