录屏抽帧截图（App 页面导出）
从手机录屏里把指定页面导成干净的全分辨率截图，按视频归档。
环境硬约束：本机没有系统 ffmpeg
which ffmpeg 为空，brew 也没装 ffmpeg。不要试图 brew install，不要改系统环境。
改用隔离环境里的静态 ffmpeg 7.1 二进制（含 png / mjpeg / libwebp 编码器）：
${HOME}/.workbuddy-ai/binaries/python/envs/default/lib/python3.13/site-packages/imageio_ffmpeg/binaries/ffmpeg-macos-aarch64-v7.1
缺了就跑 zsh scripts/ffmpeg.sh 自动补装（幂等）。隔离 venv 同时装了 numpy + pillow。
> 路径里的 ${HOME} 是本机家目录占位。若你的 WorkBuddy 运行时不在 ~/.workbuddy-ai/，
> 只需改 scripts/ffmpeg.sh 里的 3 处变量（其余脚本都从它取路径）。
脚本
| 脚本 | 作用 |
|---|---|
scripts/ffmpeg.sh |
输出 ffmpeg 绝对路径；缺失时自动建 venv 并装 imageio-ffmpeg |
scripts/probe.sh <video> |
时长 / 分辨率 / 帧率 + 场景切换时间点 |
scripts/stable-frames.py <video> <tmp> <sheet.jpg> [fps] [目标数] [合并阈值] |
主力工具：逐帧比对自动分段，每个页面挑一张代表帧，输出带时间戳的对照图 |
scripts/contact-sheet.sh <video> <out> [fps] [CxR] [宽] |
均匀抽帧拼缩略图（补漏用） |
scripts/extract.sh <video> <out> "名称=时间" ... |
按时间点批量导全分辨率 PNG + 自动生成 00-预览图.jpg |
scripts/build_index.py <父目录> [--app "2=Cleanup,3=Cleaner"] |
扫描已归档的截图，生成 screenshot_index.csv |
标准工作流
1. 探参数
zsh scripts/probe.sh "/path/video.mp4"
记下时长与场景切换时间点。注意：引导页的淡入淡出切换检测不到（阈值 0.3 时），
场景切换点只能当参考锚，不能当页面清单。
2. 自动分段，找页面
PY=${HOME}/.workbuddy-ai/binaries/python/envs/default/bin/python
$PY scripts/stable-frames.py "/path/video.mp4" /tmp/f /tmp/sheet.jpg 3 26 5.0
fps=3抽帧 → 算相邻帧灰度差 → 超过阈值即认为翻页 → 每段取 65% 处做代表帧。- 合并阈值要用 5.0（严格）。默认的 12 会把"版式相同、只有标题不同"的引导页并掉，
实测漏掉过整个付费墙轮播三屏。宁可多出几张重复的，也不要漏页。 - 阈值自适应：脚本从 7 开始逐级提高直到代表帧数 ≤ 目标数（默认 18，多视频建议 26）。
3. 读对照图认页面
用 Read 工具读对照图，格子顺序 = 脚本打印的清单顺序，秒数从文本清单取，别从图上认。
4. 按秒数抽帧
zsh scripts/extract.sh "/path/video.mp4" "/path/video_dir/2" \
"01-欢迎页-启动页=4.0" "02-欢迎页-欢迎使用Cleanup=7.0" "03-引导页1-删除重复照片=13.0"
5. 逐张校验（必做，不能跳）
读生成的 00-预览图.jpg，确认：页面完整、无权限弹窗遮挡、无录屏光标、文件名与内容对得上。
错位的重挑秒数重抽。校验一次能抓出 10~20% 的坏帧，这一步省不得。
6. 生成索引
$PY scripts/build_index.py "/path/to/视频目录" --app "2=Cleanup,3=Cleaner"
输出结构
<视频所在目录>/
├── screenshot_index.csv ← 索引，可直接入库
├── 2/ ← 子文件夹名 = 视频名（不含扩展名）
│ ├── 00-预览图.jpg
│ ├── 01-欢迎页-启动页.png
│ └── 02-欢迎页-欢迎使用Cleanup.png
└── 3/ ...
命名口径
格式 序号-类型-页面名.png，中文命名便于归档检索，序号保证排序 = 流程顺序。
类型按流程顺序取：
欢迎页/启动页 → 欢迎页（"欢迎使用 X"，带权限申请 + 开始使用按钮）→ 引导页N → 过渡页 → 会员订阅页 → 主界面 / 附加
- "欢迎使用 X" 算「欢迎页」，不算引导页1。 这是最容易搞错的一处，搞错会导致引导页计数全错。
- 过渡页 = "7天免费试用已启用 / 试用7天免费!" 这类订阅前置加载页，不是引导页。
- 引导页数量没有行业标准，实测 0~5 页都有，有的产品完全没有引导页。照实记录，不要硬凑。
- 同一产品有多个订阅页时用
会员订阅页、会员订阅页2、会员订阅页3编号。
抽帧质量经验
- 权限弹窗（无线数据 / 跟踪 / 照片 / 通知 / 联系人）会盖住页面，必须避开。
同一页面往往被弹窗切成好几段，选时长最长的那一段通常就是干净窗口。 - 录屏光标：后半段常出现白色光标块，避开。
- 动画页面：计数 / 进度条类页面选数字较大、进度条较满的一帧，视觉信息量最大。
- 窗口很窄时按 0.5s 步长抽一串帧挑，别猜。"欢迎使用 X"页可能只有 0.4s 是干净的。
详细资料
references/troubleshooting.md— 踩过的坑与证据（时间点偏差、漏页、超时），遇到异常先读这个。references/batch-runbook.md— 多视频批量的完整流程与命令。
