LobeHub acceptance 技能实战：原生 macOS 屏幕录制的取证方案（screencapture / ffmpeg AVFoundation）

本篇技术指南围绕 LobeHub 内置 acceptance 技能（SKILL.md）中的原生 macOS 屏幕录制参考文档展开，讲解在端到端验收（End-to-End Acceptance）流程中如何为"原生 macOS 窗口与 OS 级界面"采集时间型证据。读完你将掌握：何时必须放弃 CDP 改用宿主屏幕录制、如何用 screencapture 与 ffmpeg 输出规范的 MP4/GIF 证据、如何完成录制前的安全检查与来源标记（provenance），并理解其在跨表面证据契约中的位置。

一、这份参考文档的适用边界

recording-native-macos.md（位于 references 目录）定位非常明确——它不是通用录屏教程，而是 acceptance 技能中 Native 表面 的时间型证据采集手册：

• 只在原生表面上使用：当验收标准（criterion）所验证的对象是一个原生 macOS 窗口，或一段 CDP（Chrome DevTools Protocol）无法观测的 OS chrome（系统权限弹窗、Save 对话框、文件选择器、Dock/菜单栏交互等）时，才引用本参考。
• 不是云可移植的：录制需要真实的本地 macOS 显示会话，无法在无头服务器或云端环境运行。
• CDP 优先原则：只要 Web / Electron 目标能被 Chromium 驱动触达，就优先走 agent-browser / CDP 的录帧方案；只有 CDP 无法触达时，才降级到宿主屏幕录制。

从技能路由表（SKILL.md 中 "Pick the surface by what you changed" 一节）可以看到完整取舍：CLI 表面用 stdout 文本作证据、Web/Electron 表面走 CDP、iOS 模拟器走 simctl 帧缓冲，而 Native（非 Chromium）macOS 应用或 agent-browser 触不到的 OS chrome，才落到 osascript + screencapture。这也解释了为何同一份参考会被 surfaces/native.md 在 "Capture proof" 一步直接链接，并作为技能资源被注册进 index.ts 的 resources 映射（key 保留 .md 扩展名，保证磁盘安装副本与仓库内文件一一对应）。

二、录制宿主屏幕：优先固定时长收尾

参考文档给出的第一个原则：录制务必使用固定时长（fixed duration），让录制器能自行完成 finalize，避免依赖外部 kill。

macOS 自带 screencapture 的 -V 参数即可录制固定时长的 MP4：

screencapture -V 15 ./proof/native-flow.mp4

含义拆解：

• -V <seconds>：录制指定秒数的视频（此处为 15 秒），到点自动结束，产物写入 ./proof/native-flow.mp4；
• 因为时长固定，screencapture 会在录制窗口结束后自己落盘定稿，不需要额外的终止进程操作。

对照姊妹参考 recording-ios-simulator.md 可知，这种"让录制器自然收尾、绝不 SIGKILL"的思路是整个技能族的统一要求——simctl 录制依赖 SIGINT（Ctrl-C）触发定稿，且中断后的 shell 退出码可能非零，必须用 ffprobe 而非退出码来判断产物。

三、显式编码控制：用 ffmpeg 走 AVFoundation

当需要显式控制编码参数（帧率、编码器、码率质量）时，参考文档要求先用 AVFoundation 枚举设备，再指定设备索引录制：

# 第一步：列出可用的屏幕（与音频）设备
ffmpeg -f avfoundation -list_devices true -i ""

# 第二步：把 1 替换为探测到的屏幕设备索引
ffmpeg -y -f avfoundation -framerate 30 -i "1:none" -t 15 \
  -c:v libx264 -crf 23 -pix_fmt yuv420p ./proof/native-flow.mp4

参数逐项说明：

参数	作用	备注
-f avfoundation	使用 macOS 的 AVFoundation 采集框架	与 screencapture 走同一系统采集层
-list_devices true -i ""	枚举输入设备	需先执行以确认屏幕设备索引，避免用错设备
-i "1:none"	选择输入源：<屏幕索引>:<音频索引>	none 表示不采集音频（宿主录制原则上不应收录系统音频之外的无关声音）
-framerate 30	目标帧率	视场景可调
-t 15	固定时长 15 秒	与 screencapture 的 -V 异曲同工
-c:v libx264 -crf 23	H.264 编码 + CRF 23	CRF 越低画质越好、体积越大，23 是较通用的均衡值
-pix_fmt yuv420p	像素格式转为 yuv420p	保证 MP4 在浏览器/播放器中广泛兼容

四、内联回放优先：MP4 转 GIF

当验收页面需要内联播放（inline playback，评审时无需点开播放器）时，参考文档给出了一条完整的调色板两遍（palette-based）转换命令：

ffmpeg -y -i ./proof/native-flow.mp4 \
  -vf "fps=8,scale=900:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  ./proof/native-flow.gif

• fps=8：把帧率降到 8 fps，压缩动图体积；
• scale=900:-1:flags=lanczos：宽度缩放到 900px、高度按比例自适应，lanczos 采样保证缩放质量；
• split + palettegen + paletteuse：先生成针对该片段内容的调色板，再套用调色板输出 GIF，避免色带；
• -y：覆盖已有产物。

在跨表面证据契约（evidence.md）中，gif 与 video 的选用规则是：gif 用于不超过约 10 秒的短时状态并以内联渲染；video 用于较长的动画、转场、手势或多步骤流程，需要播放器与更好的压缩。这一判定由表面指南负责，但最终都走 evidence.md 的共享提交契约。

五、引用前必做：安全检查与产物核验

参考文档对"录制完直接交证据"明确说不——任何时间型产物在引用前都必须：

1. 目视检查产物：确认没有无关窗口、通知或密钥/敏感信息进入宿主屏幕捕获画面；
2. 确认产物有效：检查文件确实可播放、时长符合预期（例如用 ffprobe 读取容器/流信息），而不是"看起来和好文件一样、实际为空或截断"的坏文件。

这一点同样与证据契约的安全条款呼应：evidence.md 要求提交任何图片、片段、生成文档前先检查，严禁上传凭证、Cookie、token、私有用户数据以及无关宿主窗口/通知，并"宁取聚焦产物，不取未过滤日志或全会话录制"。宿主屏幕录制天然最容易"带出"无关内容，因此这份参考把检查列为正式步骤，而非建议。

六、来源标记（provenance）：--by cli 与 --by program

录制完成后，提交证据时必须给出来源标记。参考文档规定：

• 直接由 screencapture 产生的录制 → --by cli（命令行直接采集，产物未经改造）；
• 由 FFmpeg 派生/转换的媒体（GIF、重编码的 MP4）→ --by program（经过确定性脚本或媒体变换）。

evidence.md 进一步明确了这条规则的实质：--by 应指向所选表面指南指定的生产者，按直接采集源标记未修改产物、以 program 标记确定性测试/脚本/媒体变换，且不得凭文件扩展名推断来源。也就是说，即使同样是 ./proof/native-flow.mp4 后缀，若经由 ffmpeg 重编码过，也应标记为 program 而非 cli。

提交命令遵循共享契约（此处给出 video 类型示例，--type 依实际声明为准）：

lh acceptance run result submit --operation "$OPERATION_ID" --item "$CHECK_ITEM_ID" \
  --type video --file ./proof/native-flow.mp4 --by cli \
  --desc "Recorded host-screen native flow after the planned action, no sensitive content observed"

注意：只有当该检查声明了 requiredEvidence 的 video/gif 类型时才应提交此类产物。技能硬性要求"一个缺失必需证据类型的轮次会把交付卡在 uncertain"，反之也不得把未声明类型编造提交。

七、与相关参考的分工关系

本参考不是孤立文档，理解它在技能中的位置才能用得对：

• 输入 / 辅助操作：录制前驱动原生应用、键入、点击、读取辅助功能元素，走 computer-use.md（osascript 工具箱）；该文档在 "Capturing as evidence" 一节明确把"基于时间戳的原生行为 → OS 录屏为 MP4/GIF"指引到本参考；
• 产物契约：gif 与 video 的抉择及最终提交，走 evidence.md；
• 并列录制方案：Web/Electron 用 recording-cdp.md（走 agent-browser 渲染帧、无头安全、自动排除浏览器/Electron 窗口 chrome），iOS 模拟器用 recording-ios-simulator.md（simctl 直接采集设备像素、排除模拟器窗口 chrome）——三者共同构成 SKILL.md Reference map 中"时间型证据（temporal evidence）"一行的三条出口；
• 表面执行流：surfaces/native.md 在 Native 表面验证流程的第 3 步（捕获证据）引用本参考，并强调 Accessibility 权限缺失会让所有 System Events 调用静默失效。

从源码结构可以推断，这样的"认证资源按运行时拆分"是有意设计：引用 index.ts 的资源注册与注释可以看到，"录音/录制资源按运行时拆分，被选中的表面无需加载另一平台的说明"，因此本参考只承担"原生 macOS 宿主屏幕录制"这一个职责，不掺杂 iOS 或 CDP 内容。

八、实操小结

在 LobeHub acceptance 技能中产出原生 macOS 时间型证据的推荐落地路径：

1. 确认目标为原生窗口或 OS chrome（CDP 无法观测），且本机有真实 macOS 显示会话；
2. 用 computer-use.md 的 osascript 方法把应用驱动到目标状态；
3. 录制：固定时长首选 screencapture -V 15 ./proof/native-flow.mp4；需要显式编码控制则先用 ffmpeg -f avfoundation -list_devices true -i "" 探测设备，再按 -framerate 30 -i "1:none" -t 15 录制；
4. 需要内联回放时转 GIF（fps=8、900px 宽、palettegen/paletteuse 两遍法）；
5. 引用前逐帧目视检查，确认无无关窗口、通知或敏感信息进入画面；
6. 直接 screencapture 产物标记 --by cli，ffmpeg 派生产物标记 --by program，按 evidence.md 契约用 lh acceptance run result submit 提交并声明覆盖。

牢记本参考的三条红线：仅原生表面使用、仅限本地 macOS、绝不云移植——能用 CDP/agent-browser 触达的目标，不要走到宿主屏幕录制这条路上来。