mcpField
C
capture

capture

github.com/factory-ai创意与媒体12095 次安装5 天前更新
代码仓库

关于 capture

capture 是用于记录应用交互并收集证据的工作流技能，涵盖启动目标、执行脚本操作，以及向合成阶段移交录制文件和其他产物。

主要功能

  1. 01启动目标并执行脚本交互
  2. 02录制终端、浏览器和桌面会话
  3. 03采集截图和文本快照
  4. 04记录带时间戳的按键
  5. 05移交前检查原始输出文件

适用场景

  1. 01制作产品演示录制
  2. 02采集匹配的前后分支会话
  3. 03收集交互或界面状态证据
  4. 04为视频合成阶段准备素材

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/factory-ai/factory-plugins --skill capture

安装后在 Claude Code 中输入/capture确认已加载。

详细介绍

捕获

编排器将你引导至此。此原子负责完整的录制生命周期：启动目标、执行交互脚本、收集原始输出。

你应该已经加载了一个 驱动原子（terminal-use、true-input、browser-use 或 desktop-use），还可以选择加载一个 目标原子（droid-cli）。此原子会在此基础上添加录制规范。

输入

调用你的命令应已提供：

  • 目标：要启动什么，以及在哪些分支上启动
  • 交互脚本：要执行的一系列操作
  • 要捕获的内容：录制文件（.cast/.mp4）、截图、文本快照、字节序列
  • 按键记录：是否输出按键 TSV 文件，以便后续叠加

录制生命周期

对于 desktop-use，请遵循其录制约定；不要将下面的终端命令转换为桌面命令。常规桌面快照应保持在驱动的观察/操作/验证循环中。

1. 录制前检查

开始录制前：

  • 所有会话的终端尺寸一致（--cols 120 --rows 36）
  • 浏览器视口尺寸与合成布局匹配（见下文“浏览器视口尺寸”）——宽高比不匹配会导致最终视频出现黑边
  • 分支/工作树路径和环境变量正确
  • 录制格式与驱动匹配：tuistory 使用 .cast，true-input 使用 .mp4，agent-browser 使用截图，cua-driver 使用窗口 PNG / recording.mp4
  • 如果要比较分支，两边的会话必须使用相同的终端/视口尺寸和启动参数
  • 对于 droid-dev 捕获，--repo-root 必填——不提供时，tctl 将拒绝启动
  • 已设置颜色环境变量（见下文）
浏览器视口尺寸

最终合成中的面板宽高比取决于布局。在默认的 1920×1080 输出和工厂预设边距下，剪辑渲染到的窗口边框面板大致如下：

布局面板宽高比建议的浏览器视口
single~1760×920（≈16:9 横向）1280×720 或 1440×810
side-by-side每个面板约为 ~872×920（≈8:9，接近正方形／略偏纵向）960×1000、900×1000 或 1024×1080

将 16:9 横向录制内容放入接近正方形的 side-by-side 面板，会触发 objectFit: "contain" 留黑边——内容会变成细条，上下则出现大块黑边。有两种方法可以避免：

  1. 在捕获时匹配宽高比（首选）——根据已确定的布局，从上表选择视口。
  2. 在合成时选择裁剪——在 showcase props 中传入 "objectFit": "cover"。这会裁剪剪辑边缘，而不是添加黑边。适用于相关 UI 居中且剪辑边缘可以舍弃的情况。

如果捕获时不确定布局，默认使用 960×1000——此尺寸适用于两种布局（在 single 中会有轻微的水平黑边，在 side-by-side 中则没有黑边）。

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl
# RUN_ID and RUN_DIR should already be set by the parent (see droid-control ground rule 5)
2. 启动并录制

重要：tuistory 的虚拟 PTY 默认不会声明支持颜色。 Node.js 应用（Ink/chalk）会检测到这一点，并禁用所有颜色转义码，从而生成单色录制。你必须传入 FORCE_COLOR=3 和 COLORTERM=truecolor，以强制启用完整的 24 位颜色输出。否则，agg 将没有可应用主题的内容，无论选择哪种 agg 主题，视频看起来都会灰暗、饱和度不足。

单分支：

$TCTL launch "droid-dev" -s ${RUN_ID}-demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

对比（之前/之后）：

$TCTL launch "droid-dev" -s ${RUN_ID}-before --backend tuistory \
  --repo-root /path/to/baseline-worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/before.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

$TCTL launch "droid-dev" -s ${RUN_ID}-after --backend tuistory \
  --repo-root /path/to/candidate-worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/after.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

**浏览器：**调整视口尺寸，使其与合成布局匹配（见上表）。

# side-by-side layout → near-square panel
agent-browser open <url> --viewport 960x1000
agent-browser record start ${RUN_DIR}/demo.webm

# single layout → 16:9 panel
agent-browser open <url> --viewport 1280x720
agent-browser record start ${RUN_DIR}/demo.webm
3. 执行交互脚本

为没有上下文的观众录制。你是导演，不是操作员。

  • 先录制，再进行设置——基准状态就是第 1 幕。
  • 状态变化后停留——停留 2–3 秒，确保文字清晰可读。将 snapshot --trim 用作自然的验证节点。
  • 步骤之间进行验证——使用 wait 或 snapshot 确认状态后再继续。不要盲目按下下一个按键。
  • 验证本身就是证据。 操作后捕获实际状态，包括没有可见变化时。单独一帧画面没有变化，并不能证明会话冻结或按键未生效；请检查任务的后置条件和时间。

对于对比录制，两个分支执行完全相同的交互——只有行为不同。两边都在脚本的同一步结束：合成时完整播放最长的片段，并让较短片段停留在最后一帧，直到最长片段结束。

4. 按键记录

如果工作流需要按键叠加层，请在录制期间生成 TSV 文件。由于每次交互都是脚本化的，时间数据已知。

记录每个按键的时间戳（从录制开始算起的秒数）和易读标签：

0.5	droid --fork
1.2	Enter
2.8	Ctrl+C
4.0	Esc

使用易读的按键名称（Ctrl+C，而不是 \x03）。将文件保存在录制文件旁边（例如 ${RUN_DIR}/keys.tsv）。时间戳使用原始录制秒数；合成时设置 speed 会将时间戳转换为输出秒数，而之后对片段进行的任何裁剪都会使时间戳偏移——请在记录按键前先裁剪，或在交接说明中注明偏移量。

5. 关闭并验证原始输出
$TCTL -s "${RUN_ID}-demo" close    # terminal session owned by this run

交接前，请确认每个预期输出文件都存在且非空：

  • 录制文件（.cast、.mp4、.webm）
  • 截图文件（.png）
  • 按键 TSV（如果已提交）
  • 文本快照日志（如报告需要）

证据采集方式

证明类型采集方式
功能行为文本快照：$TCTL -s <name> snapshot --trim
视觉呈现截图：$TCTL -s <name> screenshot -o ${RUN_DIR}/proof-N.png
键盘编码PTY 字节：${DROID_PLUGIN_ROOT}/scripts/capture-terminal-bytes.py --backend <terminal> --combo <keys>
Web/Electron截图：agent-browser screenshot --annotate ${RUN_DIR}/proof-N.png
原生桌面 GUI遵循 desktop-use，以获取精确窗口或经授权的桌面状态，并确认录制器的归属
前后对比在两个分支的相同采集点运行相同序列

输出

将以下内容交给 compose 阶段：

## Capture outputs
- clips: [${RUN_DIR}/before.cast, ${RUN_DIR}/after.cast]      # .cast / .mp4 / .webm only
- screenshots: [${RUN_DIR}/proof-1.png, ${RUN_DIR}/proof-2.png]  # stills go to compose's screenshot path, never as clips
- keys: ${RUN_DIR}/keys.tsv (if keystroke logging was requested; raw recording seconds)
- driver: tuistory | true-input | agent-browser | cua-driver
- terminal_size: 120x36          # for tuistory / true-input
- viewport: 960x1000             # for agent-browser; report so compose knows the clip aspect

恢复

如果录制过程中会话卡住：

$TCTL -s <name> press esc         # bail out of stuck dialog
$TCTL -s <name> snapshot --trim   # check visible state
$TCTL -s <name> close             # hard reset

对于本次运行所拥有的隔离浏览器：agent-browser close。

对于 desktop-use，请在中断后重新获取状态，并与录制器所有者协调。不要停止共享守护进程、关闭个人应用，或重放不确定的输入来恢复录制。保留部分产物作为诊断证据；将其标记为未完成，不要声称其满足交付要求。

评论

支持 Markdown