用途：agent-motion 是位于 $PATH 的 CLI，用于分析固定视角录像（屏幕录制、浏览器会话、视觉测试、渲染场景），回答视频中何时、何处发生了什么，输出可处理的 JSON，并在需要时生成图片。解码在本地由 FFmpeg 完成，不上传任何内容。手持或平移镜头会让整帧同时变化，效果明显变弱。
主要能力：timeline 给出事件时间线；activity 以 NDJSON 输出每行一个活跃区域；sheet 生成含多张带说明真实帧的 PNG；frames --at 17.62 查看指定帧；compare --at 14.9,18.5 做精确像素比较；check --max-shift-score 0.05 在超限时以非零码退出；project 生成活动图 PNG；inspect 只读取尺寸、帧率、时长与编码而不解码；mcp 通过 MCP 提供全部命令。多数问题只需 timeline 与 activity。
使用方式：先运行 agent-motion timeline recording.mp4，按顺序阅读 narrative、events（含 kind、start_seconds、end_seconds、region_xyxy、position、summary）、suitability、limits、next_steps。输出默认一个 JSON 对象，可用 --format json|yaml|jsonl 覆盖；jsonl 便于 grep。错误输出到 stderr，含 fixable_by：agent 表示改输入或参数，human 表示需安装或授权（FFmpeg 须在 PATH，或用 --ffmpeg/--ffprobe），retry 表示重试。
限制与注意：空结果不等于没发生，需先读 limits；无位移不等于没移动，位移超过区域约一半会被记为 cut 或 busy；kind 只描述变化形状而非含义，工具不识别物体、不读文字、不解释原因；suitability 非 suitable 时事件边界任意，check 通过也无意义。shift 的 moved_by_pixels 为源像素位移，layout_shift_score 仅用于排序与阈值，不是 Chrome 的 Cumulative Layout Shift。工具无法判断哪个元素移动及原因，那需要 DOM。