> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 录制与回放

> 把你在桌面上做的一遍操作，变成一个可复用的技能

录制与回放解决的是一类特定问题：**你会做，但说不清楚**。有些工作流步骤琐碎、依赖具体界面位置、口头描述比亲自做一遍还慢——那就做一遍，让专家看着，然后把它变成技能。

## 激活条件

<Note>
  `profy-record-and-replay` 是 `user_selectable: true` 且 `requires: { desktop_connected: true }`。需要在插件面板勾选，且运行 Profy 桌面端。
</Note>

<Warning>
  **原生事件流录制仅支持 macOS。** 在 Windows / Linux 上调用会直接报错：

  ```
  Native event stream recording (profy-event-tap) is only available on macOS.
  On Windows/Linux, use CUA Driver recording instead (cua-recording skill).
  ```

  底层依赖的是 macOS 的事件 tap（`profy-event-tap` 原生二进制），没有跨平台等价物。
</Warning>

## 三个工具

| 工具                    | 作用                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------- |
| `event_stream_start`  | 开始录制，返回 `sessionId`、`eventsPath`、`metadataPath`、`maxDurationMinutes`、`audioRecording` |
| `event_stream_stop`   | 结束录制并落盘，返回最终元数据（含事件数、`audioTranscriptPath`）                                           |
| `event_stream_status` | 查询是否正在录制                                                                              |

## 录制期间发生了什么

三路数据同时采集，都落在 `~/.profy/recordings/{sessionId}/`：

| 数据      | 文件                                    | 说明                                  |
| ------- | ------------------------------------- | ----------------------------------- |
| 事件流     | `events.jsonl`                        | 每行一个事件：应用名、窗口标题、动作类型、细节             |
| 截图与无障碍树 | `snapshots/{时间戳}-{触发源}.png` + `.json` | 周期 **10 秒**一次，最小间隔 **2 秒**；相邻近似帧会去重 |
| 语音旁白    | 音频 + 转写文本                             | 麦克风可用时自动开启；被拒绝则优雅降级，不影响录制           |
| 会话元数据   | `session.json`                        | 起止时间、结束原因、事件总数                      |

<Warning>
  **录制捕获整个桌面，不只是当前应用。** 所有应用、所有窗口、每一次点击和输入都会被记录。切走应用或最小化聊天窗口都不会中断录制——只有 `event_stream_stop` 或**30 分钟超时**才会结束。

  也就是说：录制期间避免处理无关的私密事务，密码输入尤其要注意。
</Warning>

## 语音旁白：录制里最有价值的一路

只有事件流的话，专家看到的是「点了坐标 (840, 312)」——它不知道你为什么点。语音转写带时间戳，和事件对齐后就补上了「为什么」这一层：

> 「现在我要把这一列筛选掉，因为上季度的数据不参与统计。」

有旁白的录制能蒸馏出**带判断条件**的技能；没旁白的只能蒸馏出**按顺序重放的步骤**。差别很大。所以：**边做边说**。

麦克风权限被拒时录制照常进行，只是少了这一路。

## 标准流程

<Steps>
  <Step title="告诉专家你要录制">
    「我要录一段操作，帮我做成技能。」专家调 `event_stream_start`，然后**结束这一轮对话**。
  </Step>

  <Step title="去做你的事，边做边说">
    切到目标应用，正常完成一遍工作流。屏幕上会有录制指示浮层。整个过程中把你的判断念出来。
  </Step>

  <Step title="回来说一声「好了」">
    专家调 `event_stream_stop`，读取事件、截图和语音转写。
  </Step>

  <Step title="确认要固化的是哪一段">
    录制里包含了所有发生过的事，包括你走的弯路、点错的地方、中途看的别的窗口。专家会先总结它理解到的工作流，**由你确认之后**再变成技能。
  </Step>

  <Step title="下次直接用">
    技能存进你的全局技能库（`user/*`），此后任何专家的对话里都能用。
  </Step>
</Steps>

<Note>
  **专家在录制期间是「结束回合」而非「等待」的。** 这是设计上的硬约束：模型持有回合时你没法演示，轮询既烧 token 又挡住了要录的东西。所以看到专家「停下不动了」是正常的——它在等你回来说完事了。
</Note>

## 随插件带的技能

除了录制本身，这个插件还打包了一组应用专属技能，用来在回放时理解具体应用的界面：

`record-replay`（录制到技能的方法论）、`cua-driver`（驱动层参考）、`cua-recording`（跨平台的驱动录制路径）、`app-clock`、`app-numbers`、`app-spotify`、`app-notion`、`app-music`、`app-iphone-mirroring`。

## 失败与对策

| 现象                                             | 原因                      | 怎么办                                  |
| ---------------------------------------------- | ----------------------- | ------------------------------------ |
| `only available on macOS`                      | 不在 macOS 上              | 用 `cua-recording` 技能走驱动录制路径          |
| `Capture process exited with code N`           | 事件 tap 没能挂上，几乎总是无障碍权限被拒 | 系统设置 → 隐私与安全性 → 辅助功能，勾选 Profy，然后重新开始 |
| `A recording is already in progress`           | 同时只允许一个录制               | 先 `event_stream_stop`                |
| `No active recording to stop.`                 | 没有正在录的会话                | 先 start                              |
| `recorder tools require the Profy Desktop app` | sidecar 没连上             | 启动桌面端                                |
| 录了但事件为 0                                       | 权限问题的另一种表现              | 同上，检查辅助功能权限                          |
| 蒸馏出来的技能步骤不对                                    | 录制里包含了弯路                | 在第 4 步确认时明确指出哪些不要，或重录一遍干净的           |

<Note>
  录制启动时会先 `waitUntilCapturing()` 确认 tap 真的挂上了才返回成功——这道校验的存在是因为权限被拒时曾经会得到一个「启动成功」但事件为空的会话，那比直接报错更难排查。
</Note>

## 与 Chrome 工作流复用的区别

两者都在解决「重复劳动」，但分工不同：

|    | 录制与回放           | Chrome 工作流（AT2T）      |
| -- | --------------- | --------------------- |
| 范围 | 整个 macOS 桌面，跨应用 | 只在 Chrome 内           |
| 产物 | 技能（自然语言 + 步骤）   | 模板（结构化步骤，可零 LLM 重放）   |
| 触发 | 你显式说要录          | 专家自动 `match_workflow` |
| 适合 | 跨应用流程、原生应用      | 单站点的重复操作              |

## 继续阅读

<CardGroup cols={2}>
  <Card title="Computer Use" href="/zh/documentation/plugins/computer">
    回放时执行操作的那一层
  </Card>

  <Card title="Chrome" href="/zh/documentation/plugins/chrome">
    浏览器内的工作流复用
  </Card>

  <Card title="技能目录" href="/zh/documentation/reference/skills-catalog">
    技能的三条归属轨道
  </Card>

  <Card title="插件全表" href="/zh/documentation/reference/plugins-catalog">
    28 个内置插件与激活条件
  </Card>
</CardGroup>