pp-agent-capture

Agent Capture - Printing Press CLI

前置条件：安装 CLI

此技能需要使用 agent-capture-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install agent-capture --cli-only
   

2. 验证：agent-capture-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/developer-tools/agent-capture/cmd/agent-capture-pp-cli@latest

如果安装后 --version 报告“command not found”，则运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续运行技能命令。

何时使用此 CLI

在用户希望进行以下操作时使用：

• 截取特定窗口或应用的屏幕截图（多个目标使用 screenshot、batch）
• 录制窗口、应用、显示器或区域的视频（record）
• 将录制内容转换为优化后的 GIF（convert）
• 用一条命令完成完整的截取、录制和 GIF 工作流（pipeline）
• 与基准屏幕截图进行对比（diff），以提供前后对比证据
• 将屏幕截图、录制内容和 GIF 打包为 PR 或错误报告的证据（evidence）
• 通过模糊匹配窗口标题查找目标窗口（find）
• 将多张屏幕截图拼接为动画 GIF（stitch）
• 使用 macOS Vision OCR 从窗口中提取文本（ocr）
• 通过 VHS 磁带文件录制终端会话（vhs）
• 将 Remotion 合成渲染为视频或静态图像（remotion）
• 通过定期截屏监控 UI（watch）
• 保存并回放截取配置（preset）

在非 macOS 主机上请勿使用；此 CLI 使用 ScreenCaptureKit（仅限 macOS）。首次运行时会提示授予屏幕录制权限；permissions 命令会引导完成此流程。

参数解析

解析 $ARGUMENTS：

1. 为空、为 help 或 --help -> 显示 agent-capture --help
2. 以 install 开头 -> 安装 CLI（目前不提供 MCP 服务）
3. 其他任何内容 -> 直接使用（映射到最合适的命令并运行）

直接使用

1. 检查是否已安装：which agent-capture。如果未安装，提供 CLI 安装方式。
2. 如果尚未授予权限，请先运行 agent-capture permissions。
3. 使用 agent-capture list 查看可用的截取目标（已打开的窗口、显示器）。
4. 截取前，使用 agent-capture find <text> 模糊匹配窗口标题。
5. 使用 --json 执行以获取结构化输出（Agent 原生默认格式）：

   agent-capture <command> [args] --json
   

常用命令

命令	功能
screenshot	截取窗口、应用、显示器或区域
record	录制窗口、应用、显示器或区域的视频
pipeline	一条命令完成录制、转换和优化
convert	将视频转换为优化后的 GIF（双遍调色板）
diff	截取屏幕并与基准进行对比
evidence	为 PR 打包完整证据（屏幕截图 + 录制内容 + GIF）
batch	在一次调用中截取多个应用
find	模糊搜索已打开窗口的标题
list	列出可用的截取目标
ocr	使用 macOS Vision 从窗口中提取文本
stitch	将屏幕截图合并为动画 GIF
vhs	运行 VHS 磁带文件以录制终端
remotion	渲染 Remotion 合成
watch	定期截取屏幕以监控 UI
preset	保存/加载截取配置
permissions	引导完成屏幕录制权限设置
health	供 CI/Agent 使用的机器可读预检

运行任何命令时添加 --help，即可查看完整的标志说明。

Agent 模式

将 --agent 添加到任意命令。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传输 — JSON 输出到 stdout，错误输出到 stderr
• 可筛选 — --select 保留部分字段，支持点分路径（见下文）
• 可预览 — --dry-run 显示请求，但不发送
• 可缓存 — GET 响应缓存 5 分钟，使用 --no-cache 可绕过缓存
• 非交互式 — 从不提示，每项输入都必须通过标志指定

筛选输出

--select 接受点分路径，可深入嵌套响应；数组会逐元素遍历：

<cli>-pp-cli <command> --agent --select id,name
<cli>-pp-cli <command> --agent --select items.id,items.owner.name

使用此选项可将超大的载荷缩小到你实际需要的字段，尤其适用于深度嵌套的 API 响应。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到目标（没有匹配的窗口或显示器）
4	缺少权限（未授予屏幕录制权限）
5	捕获错误（ScreenCaptureKit 失败，ffmpeg 失败）