argent-screen-recording

1. 工具

• screen-recording-start：开始将已启动设备的屏幕录制到视频文件中。帧来自 screenshot 和交互工具已使用的同一模拟器服务后端，并实时编码为 h264 mp4（恒定 30 fps，设备原生分辨率）。
• screen-recording-stop：停止录制，完成容器封装，并将视频作为可下载资源取回（对于同机部署的客户端，路径为 video.hostPath）。

每台设备一次只能进行一项录制；不同设备可以同时录制。录制不会干扰设备上的其他读取操作：预览窗口可以保持打开，并显示同一屏幕。

---

2. 重要：绝不要让录制持续运行

录制不会在达到 timeLimitSeconds 上限前自动停止，因此如果忘记停止，它就会一直录制到触发上限，占用录制会话、浪费磁盘空间，还会延迟你等待的视频（而且如果 trimStatic: false，视频开头和结尾还会带上静止画面）。请同时使用以下两项安全措施：

1. 录制一开始就为自己设置提醒。 你知道预计的录制时长（即你即将执行的交互所需时间）。screen-recording-start 返回后，立即使用你的运行环境提供的任何方式，为预计结束时间安排唤醒：如果有内置提醒／唤醒或计划任务工具，就用它；否则，在后台运行一个 sleep <expected-seconds> 命令，并让其完成通知将你唤回。提醒触发时，调用 screen-recording-stop。不要依赖自己记住。
2. 阅读工具结果中的备注。 录制进行期间，每个 argent 工具结果都会附带一条 NOTE:，提醒你录制仍在进行以及如何停止。如果备注表明录制已结束（达到时间上限），仍要调用 screen-recording-stop；该调用会将文件交给你。

---

3. 工作流

1. 确保目标设备已启动，且应用处于你希望视频开始时显示的状态（list-devices、launch-app、argent-device-interact）。
2. 调用 screen-recording-start，传入 udid 和略长于预计交互时长的 timeLimitSeconds（默认值为 180，最大值为 600）。默认会在视频中绘制轻点和滑动操作（请参阅下文的触摸可视化说明）；如果要干净的原始屏幕录制，请传入 showTouches: false。
3. 设置 §2 所述的录制结束提醒；此步骤不可省略。
4. 执行要录制的交互：手势、导航、输入（argent-device-interact）。对于紧凑的多步交互，优先使用 run-sequence，以免工具调用延迟使视频变长。
5. 使用相同的 udid 调用 screen-recording-stop。它会返回 { video, durationMs, wallClockMs?, trimmedMs?, warning? }；video 是一个资源，其解析后的路径指向已可靠保存的文件（见下文）。stop 返回时视频已完成处理（水印在录制期间加上，无需二次处理），因此停止操作不到一秒即可完成。
6. 检查 warning：它会报告因达到上限而停止、编码器提前退出、帧流丢失以及容器可能被截断等情况。将视频提供给用户前，请确认文件可以播放（或至少大小正常）。 文件保存位置（持久保存，而非临时文件）。 与大多数 argent 产物不同（它们存放在可由操作系统回收的一次性临时缓存中），完成的录制会持久保存到客户端的 <project>/.argent/recordings/ 目录中；<project> 是客户端工作目录最近的祖先目录，且该目录包含 .git、package.json 或 .argent。如果客户端不在项目内，则保存到 ~/.argent/recordings/。即使使用远程 argent link 工具服务器也是如此：mp4 文件写入客户端主机，而非服务器。可通过 recordings.directory 配置更改目标目录（默认使用全局配置：argent config set recordings.directory <dir>；若要按仓库设置，则使用 --scope project；两者都设置时，以项目配置为准）；值可以是绝对路径、以 ~ 开头的路径，或相对于项目根目录的路径，并且始终在客户端主机上解析。保存的文件名为 screen-recording-<device>-<timestamp>.mp4；如果该名称已被占用，新文件会以 … (2).mp4 的形式保存在旁边，而不会覆盖原文件。由于这些文件会留在工作树中，请告知用户文件路径（并说明它们是未跟踪文件；如果不应提交，请将其添加到 .gitignore 或清理掉）。

静态画面剪辑（默认启用）。 屏幕画面没有变化的片段会被压缩：每段静止画面的前 1 秒会保留，让停顿显得自然；之后的未变化帧会被丢弃，直到画面再次发生变化（即使只变化了几个像素也算）。因此，录制可以跨越缓慢的操作步骤、等待或思考时间持续运行，而不会让视频夹杂无意义的静默片段：一段包含 5 秒实际操作的 40 秒会话，最终会生成约 5～7 秒的视频。若剪辑掉了任何内容，stop 还会返回 wallClockMs（实际经过的时间）和 trimmedMs（剪掉的时长）；durationMs 始终表示最终视频的实际时长。如果需要忠实记录实时过程（例如测量屏幕上某项操作耗时多久），请在 screen-recording-start 中传入 trimStatic: false。

触摸可视化（默认启用）。 argent 执行的每次交互都会直接绘制到视频中：每次点击都会显示脉冲效果，滑动和拖动会留下逐渐消退的彗星轨迹，双指操作会以成对标记显示两个触点。这样一来，录制内容无需额外说明：观看者可以看到每个手势的落点，而不只是看着界面响应一个看不见的手指。该效果由 simulator-server 渲染到帧流中（不会在主机端合成），因此不会产生额外开销，也不会出现在 screenshot 中。如果要录制没有叠加效果的原始屏幕画面（例如，精确捕捉用户实际看到的内容），请在 screen-recording-start 中传入 showTouches: false。如果 simulator-server 无法启用该效果，录制仍会成功，但 stop 会返回一条 warning，说明未显示触摸效果。

---

4. 平台说明和限制

• 可录制的内容：任何由 simulator-server 驱动的设备：iOS 模拟器、Android 模拟器和实体 Android 设备。唯一的时长限制是 timeLimitSeconds（最长 600 秒）。
• 时间线以稳定的 30 fps 播放：设备仅在屏幕发生变化时才会输出帧，因此捕获的帧会重新排布到固定时间线上，而不会集中在一起。关闭静态画面裁剪（trimStatic: false）时，时间线与实际经过时间一致：即使屏幕完全静止，返回的视频仍会保持完整时长（压缩后几乎不占空间），且 durationMs 与实际录制时长一致。开启裁剪（默认设置，见 §3）后，超过宽限窗口的静止片段会被压缩，因此 durationMs 表示裁剪后的视频时长，wallClockMs 则记录实际经过的时间。
• 每个视频只有一种尺寸：视频会采用录制开始时的屏幕尺寸。如果屏幕尺寸发生变化，argent 会保留新屏幕的比例并添加黑边。在可折叠模拟器上，请在需要以完整尺寸录制的屏幕面板上开始录制。
• Android：以设备的原生分辨率录制；安全屏幕（DRM、部分密码字段）会显示为黑屏。
• 不支持：tvOS 模拟器、实体 iPhone、Chromium 应用、Vega/Fire TV 和远程（带有 remote: 前缀）模拟器；这些设备均无法提供可读取的帧流。若只需截取单帧，请使用 screenshot；若需可重放的交互脚本，请使用 argent-create-e2e，而不是录制视频。
• 必须安装 ffmpeg：它是编码器，因此如果缺少该程序，screen-recording-start 会在开始时提示安装（macOS 上使用 brew install ffmpeg）。程序会从 PATH 以及常见的 Homebrew 安装目录中查找 ffmpeg。
• 水印：编码时会在左下角添加 Argent 徽标和“By @swmansion”，水印较淡（不透明度为 20%），并根据背景逐像素调整对比度（深色界面上使用浅色徽标，浅色界面上使用深色徽标）。默认启用；使用 argent disable video-watermark 关闭（使用 argent enable video-watermark 重新启用）。录制开始时会读取此标志。