企业官网建设流程全解析

如何用 cap CLI 串联录制、校验、导出与上传实现屏幕录制自动化？

【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap

Cap 的capCLI 就是为自动化设计的：每条命令都支持--json机器可读输出，错误可被程序识别，录制的 start/stop 生命周期是显式的。这篇文章描述如何用它在脚本或 Agent 环境中完成一条连续的自动化链路：准备环境 → 后台录制 → 校验.cap项目 → 导出视频 → 上传并拿到分享链接。适用于已安装 Cap Desktop 的机器（CLI 与桌面端共用同一个二进制，始终同版本），也可配合 API key 用于无浏览器环境。完整命令契约见 apps/cli/README.md 与 Agent Workflows。

前置准备：安装 CLI 并完成认证

CLI 随 Cap Desktop 一起分发。安装方式（来自 Set Up Your Agent）：

• 从 Cap Desktop：Settings → Command Line → Install CLI（把随附二进制链接到 PATH）。
• macOS / Linux：

curl -fsSL https://cap.so/install-cli.sh | sh

• Windows PowerShell：irm https://cap.so/install-cli.ps1 | iex

安装脚本会修改 PATH（必要时先安装 Cap Desktop）。如果不想让它改 shell profile / 用户 PATH，可设置CAP_NO_MODIFY_PATH；如果想强制覆盖已装的桌面端，可设置CAP_DESKTOP_FORCE_INSTALL。安装后打开新终端再验证：

cap version --json cap guide --json

认证分两种情况：

1. 本机已登录 Cap Desktop：cap upload会自动复用桌面端保存的登录态，无需配置 key。用cap auth status --json检查（输出形如{"authenticated":true,"source":"desktop","server":"…","userId":"…"}，不会打印任何密钥）。
2. 无头环境（CI、容器、远程沙箱）：在 Cap 仪表盘 Settings → Account 的 Cap CLI access 中创建 API key，注入为环境变量后验证：

export CAP_API_KEY="cap_cli_..." cap auth status --json

CAP_API_KEY或CAP_AGENT_TOKEN都可用；目标服务器取自CAP_SERVER_URL，否则用 Cap Desktop 配置的服务器，否则默认https://cap.so。

输出约定：自动化脚本如何读取结果

在串联多条命令前，先明确 CLI 的输出规则（来自 apps/cli/README.md）：

• 任意命令加全局--json，stdout 是权威结果，stderr 是人类可读日志，失败时以error: <message>行收尾；
• 失败时退出码非零。--json模式下最后一个对象/事件带error字符串字段，所以一个"error" in obj检查就能覆盖所有命令的失败检测；
• record和export在 stdout 上输出换行分隔的 JSON 事件（NDJSON），不是一次性 JSON 文档；
• clap 参数/用法错误退出码为2；运行时失败为1。

这意味着脚本里每一步都应检查退出码和 JSON 中的error字段，而不是只看进程是否退出。

主流程：录制 → 校验 → 导出 → 上传

以下是 apps/cli/README.md 给出的典型 Agent 工作流，其中<id>/<recordingId>是前一步命令返回的字段：

cap doctor --json # 验证权限与捕获就绪（退出码为 0，读 ok / captureReady 字段） cap targets --json # 发现屏幕/窗口/摄像头/麦克风，id 供后续步骤使用 cap record start --screen <id> --json --detach # 后台启动 -> {"type":"started","recordingId","pid","path"} # ... 这里执行需要被录制的操作 ... cap record stop --id <recordingId> --json # 收尾 -> {"type":"stopped","path","recordingMetaExists":true} cap project validate <path.cap> --json # 导出前确认录制完整 cap export <path.cap> --output out.mp4 --json cap upload out.mp4 --json # -> {"type":"uploaded","id","link"}

每一步的判断依据：

1. cap doctor --json：诊断权限与捕获就绪状态。该命令可能正常退出但报告能力不可用，所以必须分支判断ok/captureReady字段，captureReady为真才继续（Safety & Troubleshooting）。
2. cap targets --json：枚举屏幕、窗口、摄像头、麦克风；返回的 id 直接填入record start。也可以按需只查子命令screens/windows/cameras/mics。
3. cap record start --detach：--detach让录制备案在后台进行，返回recordingId、pid和path。保留recordingId和path，后续 stop 和校验都依赖它们。不 detach 时命令在前台运行。
4. cap record stop --id <recordingId>：停掉那一次会话。文档明确的完成条件是 stop 事件返回recordingMetaExists: true——录制只有在该字段为真时才算完整收尾，否则不要继续导出。
5. cap project validate <path.cap> --json：在导出前确认.cap项目完整。这是导出与上传之间的质量闸门。
6. cap export <path.cap> --output out.mp4 --json：把.cap项目渲染为 mp4（也支持 gif/mov；export的--format选的是容器格式）。export 输出 NDJSON 事件，Agent Workflows 的成功标准是导出到达终态完成事件；中途某事件出现error字段即失败。
7. cap upload out.mp4 --json：上传并返回{"type":"uploaded","id","link"}。分享链接以命令返回的 JSON 为准，不要自行拼接 URL。上传属于需要用户确认的动作（参见 Safety & Troubleshooting 的确认边界）。

一步完成：--export合并导出与上传

如果不需要单独的导出文件，文档提供了合并路径：

cap upload <path.cap> --export --json

该命令把.cap项目按其默认输出格式导出并直接上传，一步完成。适合“录完即传”的最短链路；需要本地留存 mp4 时仍走上面的 export + upload 两步。

无头 CI 中的完整条件

把上面的链路放进 CI 时，差异只在认证：用CAP_API_KEY（或CAP_AGENT_TOKEN）代替桌面端登录态，必要时用CAP_SERVER_URL指向自建服务器（登录前确认它指向目标服务器）。其余命令、JSON 约定与判断方式完全一致。文档建议用平台 secrets 注入 key，不要把它粘进对话或提交进仓库。

边界与常见问题

• record/export是 NDJSON 流：不要按单个 JSON 文档解析，逐行读取事件并检查终态；"error" in obj用于失败检测。
• 退出码区分：1是运行时失败（查 JSONerror字段），2是命令用法错误（应查cap <command> --help而不是重试猜参数）。
• 诊断命令可能“成功退出但能力不可用”：doctor这类命令要按ok/captureReady等字段分支，不能只看退出码。
• 权限问题：操作系统可能在首次使用屏幕、麦克风、摄像头时弹出授权，只授予实际要录制的输入。
• 自动化规则联动：CLI 与 Cap Desktop 共享 automation store，cap record结束和cap upload之后会自动执行在桌面端 Settings → Automations 配置好的规则（保存、导出、上传、webhook、执行命令等；剪贴板、OCR、通知类动作仅桌面端可用会被跳过）。可以用cap automations list --json查看当前生效的规则，避免自动化脚本触发意料之外的动作。
• 命令以二进制自述为准：flag 细节不要依赖旧文档或记忆，用cap guide --json和cap <command> --help发现当前契约（skill 文档 也是这一策略）。

验证整条链路

按 Agent Workflows 中“Record and share a bug reproduction”场景给出的成功标准，这条自动化链路完成的标志是：

1. stop 事件对应的recordingId与启动的是同一次会话；
2. stop 事件报告recordingMetaExists: true，且cap project validate通过；
3. export 到达终态完成事件，本地输出文件生成；
4. upload 返回 Cap ID 和分享链接（{"type":"uploaded","id","link"}）。

四条都满足，说明“录制 → 校验 → 导出 → 上传”这条链路在你的环境里已经可以稳定运行。

【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap