pp-agent-capture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Capture - Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the

agent-capture-pp-cli

binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

Install via the Printing Press installer:

bash

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

Verify:
```
agent-capture-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

If the

npx

install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):

bash

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

本技能基于

agent-capture-pp-cli

二进制文件运行。在调用本技能的任何命令前，必须先验证CLI已安装。如果未安装，请先执行以下步骤：

通过Printing Press安装器安装：

bash

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

验证安装：
```
agent-capture-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

如果

npx

安装失败（无Node环境、离线等情况），可改用Go直接安装（需要Go 1.23及以上版本）：

bash

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

如果安装后执行

--version

提示“command not found”，说明安装程序未将二进制文件添加到

$PATH

中。请在验证成功前不要执行技能相关命令。

When to Use This CLI

何时使用本CLI

Reach for this when the user wants:

screenshot a specific window or app (
```
screenshot
```
,
```
batch
```
for multiple)
record video of a window, app, display, or region (
```
record
```
)
convert a recording to an optimized GIF (
```
convert
```
)
do a full capture + record + GIF pipeline in one command (
```
pipeline
```
)
diff against a baseline screenshot (
```
diff
```
) for before/after evidence
bundle screenshots + recording + GIF as evidence for a PR or bug report (
```
evidence
```
)
find the right window by fuzzy-matching its title (
```
find
```
)
stitch multiple screenshots into an animated GIF (
```
stitch
```
)
extract text from a window using macOS Vision OCR (
```
ocr
```
)
record a terminal session via VHS tape files (
```
vhs
```
)
render Remotion compositions to video or stills (
```
remotion
```
)
monitor a UI by periodic screenshots (
```
watch
```
)
save and replay capture configs (
```
preset
```
)

Skip it on non-macOS hosts; the CLI uses ScreenCaptureKit (macOS only). On first run it will prompt for Screen Recording permission; the

permissions

command guides that flow.

当用户有以下需求时可使用本工具：

截取特定窗口或应用的截图（
```
screenshot
```
命令，批量截图使用
```
batch
```
）
录制窗口、应用、显示器或区域的视频（
```
record
```
）
将录制视频转换为优化后的GIF（
```
convert
```
）
一键完成捕获+录制+GIF转换的全流程（
```
pipeline
```
）
与基准截图对比差异，生成前后变化证据（
```
diff
```
）
将截图+录制视频+GIF打包为PR或Bug报告的证据包（
```
evidence
```
）
通过模糊匹配窗口标题找到目标窗口（
```
find
```
）
将多张截图拼接为动态GIF（
```
stitch
```
）
使用macOS Vision OCR提取窗口中的文本（
```
ocr
```
）
通过VHS文件录制终端会话（
```
vhs
```
）
将Remotion合成内容渲染为视频或静态图片（
```
remotion
```
）
通过定期截图监控UI变化（
```
watch
```
）
保存和复用捕获配置（
```
preset
```
）

非macOS主机请勿使用本工具；CLI依赖ScreenCaptureKit（仅支持macOS）。首次运行时会提示获取屏幕录制权限，

permissions

命令可引导完成权限配置流程。

Argument Parsing

参数解析

Parse

$ARGUMENTS

Empty,
help
, or
--help
-> show
```
agent-capture --help
```
Starts with
install
-> CLI installation (no MCP server ships today)
Anything else -> Direct Use (map to the best command and run it)

解析

$ARGUMENTS

规则：

空值、
help
或
--help
-> 显示
```
agent-capture --help
```
帮助信息
以
install
开头 -> 执行CLI安装操作（目前无MCP服务器配套）
其他内容 -> 直接使用（匹配最合适的命令并执行）

Direct Use

直接使用流程

Check installed:
```
which agent-capture
```
. If missing, offer CLI installation.
If permissions aren't granted, run
```
agent-capture permissions
```
first.
Use
```
agent-capture list
```
to see available capture targets (open windows, displays).
Use
```
agent-capture find <text>
```
to fuzzy-match a window title before capturing.
Execute with
```
--json
```
for structured output (agent-native default):
bash
```
agent-capture <command> [args] --json
```

检查是否安装：
```
which agent-capture
```
。如果未安装，提供CLI安装指引。
如果未获取权限，先执行
```
agent-capture permissions
```
。
使用
```
agent-capture list
```
查看可用捕获目标（打开的窗口、显示器）。
在捕获前，使用
```
agent-capture find <text>
```
通过模糊匹配查找窗口标题。
执行命令时添加
```
--json
```
参数以获取结构化输出（Agent原生默认格式）：
bash
```
agent-capture <command> [args] --json
```

Notable Commands

重点命令说明

Command	What it does
`screenshot`	Capture a window, app, display, or region
`record`	Record video of a window, app, display, or region
`pipeline`	Record + convert + optimize in one command
`convert`	Video -> optimized GIF (two-pass palette)
`diff`	Capture + diff against a baseline
`evidence`	Full bundle (screenshots + recording + GIF) for a PR
`batch`	Screenshot multiple apps in one invocation
`find`	Fuzzy search open window titles
`list`	List available capture targets
`ocr`	Extract text from a window using macOS Vision
`stitch`	Combine screenshots into an animated GIF
`vhs`	Run a VHS tape file for terminal recording
`remotion`	Render Remotion compositions
`watch`	Periodic capture for UI monitoring
`preset`	Save / load capture configs
`permissions`	Guide Screen Recording permission setup
`health`	Machine-readable CI / agent preflight

Run any command with

--help

for full flag documentation.

命令	功能
`screenshot`	捕获窗口、应用、显示器或区域
`record`	录制窗口、应用、显示器或区域的视频
`pipeline`	一键完成录制+转换+优化流程
`convert`	将视频转换为优化后的GIF（双通调色板）
`diff`	捕获截图并与基准截图对比差异
`evidence`	生成包含截图+录制视频+GIF的完整PR证据包
`batch`	一次截取多个应用的截图
`find`	模糊搜索已打开窗口的标题
`list`	列出所有可用捕获目标
`ocr`	使用macOS Vision提取窗口文本
`stitch`	将多张截图拼接为动态GIF
`vhs`	通过VHS文件录制终端会话
`remotion`	渲染Remotion合成内容
`watch`	定期捕获截图以监控UI变化
`preset`	保存/加载捕获配置
`permissions`	引导完成屏幕录制权限配置
`health`	生成机器可读的CI/Agent预检报告

执行任何命令时添加

--help

可查看完整的参数文档。

Agent Mode

Agent模式

Add

--agent

to any command. Expands to:

--json --compact --no-input --no-color --yes

Pipeable — JSON on stdout, errors on stderr
Filterable —
```
--select
```
keeps a subset of fields, with dotted-path support (see below)
Previewable —
```
--dry-run
```
shows the request without sending
Cacheable — GET responses cached for 5 minutes, bypass with
```
--no-cache
```
Non-interactive — never prompts, every input is a flag

在任何命令后添加

--agent

参数，等效于添加：

--json --compact --no-input --no-color --yes

。

可管道传输 —— 标准输出为JSON格式，错误信息输出到标准错误流
可过滤 ——
```
--select
```
参数可保留指定字段，支持点路径语法（详见下文）
可预览 ——
```
--dry-run
```
参数可显示请求内容但不执行
可缓存 —— GET请求响应会缓存5分钟，添加
```
--no-cache
```
可绕过缓存
非交互式 —— 从不弹出提示，所有输入均通过参数传递

Filtering output

输出过滤

--select

accepts dotted paths to descend into nested responses; arrays traverse element-wise:

bash

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

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

--select

参数接受点路径以遍历嵌套响应；数组会逐个元素遍历：

bash

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

使用该功能可将庞大的响应内容精简为实际需要的字段——这在处理深度嵌套的API响应时至关重要。

Exit Codes

退出码说明

Code	Meaning
0	Success
2	Usage error (wrong arguments)
3	Target not found (no matching window or display)
4	Permissions missing (Screen Recording not granted)
5	Capture error (ScreenCaptureKit failure, ffmpeg failure)

代码	含义
0	执行成功
2	使用错误（参数不正确）
3	未找到目标（无匹配的窗口或显示器）
4	权限缺失（未授予屏幕录制权限）
5	捕获错误（ScreenCaptureKit执行失败、ffmpeg执行失败）