问题发生在动作里，
截图只留下几个结果。
QA 或线上反馈经常只有一段录屏。人先复述一次，很容易把手势方向、停顿位置和回弹时刻说偏； 只截几张图，又会把连续过程压成几个静态结果。
问题时间未知，异常可能只出现几百毫秒。
从哪滑到哪、何时停手、是否回弹，很容易在转述里失真。
视觉 token 很快占满上下文，重复帧还会把异常时刻淹没。
能算的先算，只把关键画面、时间线和声音交给 AI。
从 Gemini 等多模态模型的视频接入方式可以看到，连续视频最终仍要按时间切成视觉片段。 我们让 Agent 直接接收录屏，人不再充当中间翻译；工具只在前面删掉重复信息并圈出可疑区间。
拿到的多半是重复画面，短暂出现的回弹刚好落在两帧之间。
静止段不占模型上下文，活动段保留起点、中间和终点。
先看全局，
再把可疑的几秒放大。
下面是一段虚构的 App 录屏。面板上滑后应该停在半屏， 实际却发生了回弹。进入工作台后会自动播放四步分析，也可以随时点选某一步自己查看。
一张图看完整段节奏
九宫格不负责找问题。它先回答“这段视频大致经过了哪些状态”， 让 Agent 知道后面该看哪一段。
- 输入
- 整段视频或指定区间
- 输出
- 一张带时间索引的概览图
- 适合
- 长视频、问题时间完全未知
代码先画出运动时间线
相邻帧变化超过自动阈值，才进入活动区间。下面拖动时间轴， 可以看到静止画面怎样被跳过。
- 输入
- 全片高频分析采样
- 输出
- 活动区间和少量关键帧
- 成本
- 选帧过程不调用大模型
把 0.8 秒拆成连续证据
Scan 只负责圈出“这里可疑”。Zoom 把区间收窄并提高输出密度， 直到能看清面板何时越过吸附位、又在何时回弹。
- 输入
- Scan 找到的 07.2–08.0 秒
- 输出
- 连续状态变化与准确时间
- 适合
- 手势、转场、状态切换细节
面板到达半屏后反向移动，最终停在错误位置。
画面说不出的，用声音补上
转写是可选能力。它把旁白、客诉口述或报错音频放回同一条时间线， 没有音轨或缺少依赖时直接跳过，不影响看画面。
- 输入
- 视频里的可用音轨
- 输出
- 带时间戳的文本片段
- 适合
- “我点这里后没有反应”这类口述
“我开始往上滑。”
画面：面板开始移动“这里应该停住。”
画面：面板越过吸附位后回弹“现在位置不对。”
画面：异常状态仍然保留有了参照系，模型才能判断行为是否正确；没有预期时，只客观描述画面。
整条筛选链只做数学，
不消耗模型 token。
每一步都主动丢掉不需要的精度。最后留下的不是“最好看的截图”， 而是足以还原动作过程的最小证据。
灰度 + 模糊
颜色先去掉，高频噪点和视频压缩块再被抹平。
16×16 运动指纹
整帧压成 256 个亮度块，轻微抖动被区域平均吸收。
MAD 运动分
相邻指纹逐块求绝对差，平均值就是这一刻的运动强度。
自适应阈值
用中位数抵抗切场尖峰，再设下限挡住静态噪声。
合并短暂停顿
手势中间停几十毫秒，不值得把一次动作切成几段。
只交付关键帧
静止段一帧不抽，活动段至少保留首、中、尾。
只在 CPU 里算运动边界，不保存原帧。
只在活动段落盘，控制图片数量与上下文。
让工具负责取证，
让模型负责理解。
选帧、压缩和时间映射都可以稳定地交给代码。 模型只处理代码做不了的部分：画面语义、用户意图和行为判断。
写进结构化结果，不盖在画面上
文字时间最准确，也不会遮挡 UI 或让视觉模型误读。
默认缩到模型真正用得上的大小
超高清像素最终仍会被模型缩小，提前压缩能节省带宽和上下文。
顺序扫描，内存不随时长增长
分析时只保留当前和上一枚指纹，再靠活动区间控制输出规模。
JSON 和运行日志分开输出
stdout 保持可解析，进度与诊断写到 stderr，不污染下游结果。
语音转写失败，不影响画面分析
重依赖只在真正需要时加载；没有音轨就直接跳过。
不知道预期，就只描述发生了什么
Skill 提供证据，不凭空猜测业务行为应该是什么。
适合什么
- App 滚动、手势、页面跳转和状态切换问题
- 用户录屏中「第几秒发生了什么」的定位
- 长视频先看九宫格，再缩小排查范围
- 需要把讲解音频和画面变化对齐的场景
如果不知道正确行为，Video Reader 只会客观复述画面怎么变，不会替业务下判断。把用户反馈或预期行为一起交给 Agent，才能判断哪一秒开始偏离预期。
安装
git clone https://github.com/Job-Yang/jobbyang-ai-skills.git
cp -R jobbyang-ai-skills/skills/video-reader ~/.claude/skills/video-reader装好后，不需要自己记脚本命令。把视频交给 Agent，直接说：
看一下这段录屏，第几秒开始不对？Skill 会根据视频长度和问题类型选择 grid、scan 或 zoom。底层使用 Python、OpenCV 和 NumPy，不依赖系统安装的 ffmpeg；缺少基础依赖时会先做自检。平台不允许上传视频时，也可以先压成 zip 再交给 Agent 解压。
边界
Video Reader 不判断帧率和性能卡顿。截图会抹掉帧间时间，这类问题应该使用日志、Perfetto 或其他性能数据。
它也不猜业务预期。底层只负责交付画面变化；判断行为是否正确，仍需要用户诉求或正确行为作为上下文。
翻拍视频里的手、反光和轻微抖动会被尽量过滤，但触点位置只能做定性判断。需要精确坐标时，仍应使用 UI 层级、触摸日志或自动化工具。