微信聊天视频连续截图与页面状态完整性校验助手

从微信聊天录屏中提取连续、真实、带上下文重叠的截图，专项保留个人主页，并强制质检。目标不是生成或总结聊天记录，而是对原视频画面的提取、排序、核验与归档。

硬性红线

1. 截图必须来自原视频实际帧。严禁 AI 生成/修改聊天文字、时间、头像；严禁拼接、补写、补全原视频不存在的画面；OCR 结果单独存放，不得替代原始截图。
2. 不得把"未提取成功"标成"原视频未出现"——只有确认原视频没出现才可如此标记。
3. 文件生成成功 ≠ 任务完成，必须先跑完质检。
4. 同一问题最多 3 轮修复尝试，仍失败则如实标记"未通过"并记录原因与时间区段，不得改检查结论凑通过。
5. 执行优先级冲突时：原始真实性 > 关键内容与主页保留 > 时间顺序 > 连续性与重叠 > 数量控制。

环境（Windows，本机已验证）

• 无原生 ffmpeg。用 scripts/extract_frames.py（依赖 opencv-python cv2，已装）。
• 子代理读图不可靠：连续性/内容判读必须亲自 Read 原图，不委托子代理。
• 判读截图直接用 Read 工具看图。

工作流

第一步：输入确认与视频检查

1. 用户指定了视频就用指定文件；目录内有多个视频时，列出文件名/大小/时长与用户确认，不得擅自替换。
2. 运行 probe 记录基本信息（时长/分辨率/帧率/帧数）：

python <skill目录>/scripts/extract_frames.py probe <视频路径>

无法解码时如实报告限制，不得虚构已分析。

第二步：两轮采样提取

第一轮粗采样（固定间隔 + 画面变化检测，变化密集区自动加密）：

python <skill目录>/scripts/extract_frames.py sample <视频路径> <候选目录> --interval 2

产出候选帧缩略图 + candidates.json（时间戳+变化得分）。亲自 Read 候选缩略图，找齐九类关键事件：聊天初始状态、滚动、新消息入画、页面明显变化、点头像/昵称、进入个人主页、主页内部变化、返回聊天、结束前最后有效页面。快速滚动/短暂显示区段必要时检查相邻帧（缩短 interval 重跑或用 extract 微调时间点）。

第二轮高清提取：把确定的时间点写入 list.json（格式 [{"ts": 秒, "prefix": "CHAT|PROFILE|PAGE"}, ...]），按时间顺序编号：

python <skill目录>/scripts/extract_frames.py extract <视频路径> list.json <输出目录>

脚本在时间点帧模糊/过暗时自动向前回扫找最清晰帧（最多 0.6s），并在 extract_result.json 记录实际采用时间。个人主页只出现极短时，用其起止区间内的多个时间点重试，取最清晰完整帧。

精修（必做）：固定间隔布点与实际滚动速度不匹配，会产生视觉重复帧（慢速区）和内容跳跃（快速区）。运行：

python <skill目录>/scripts/refine_sequence.py <视频路径> list.json <工作目录>

脚本逐对模板匹配测滚动位移，自动给出合并/插入建议并输出 refined_list.json。每个动作必须人工目检核定后再采纳，已知规则：
- 合并（删一张）：相邻同类型对得分≥0.90 且 |位移|≤480px（同位置重复）；或像素几乎全同。
- 插入：|位移|>1800px，或匹配得分<0.5 且 |位移|>900px（内容跳跃），在时间中点插帧。
- 禁止合并的情形：弹窗/加载态等局部状态变化帧（像素差异小但语义不同）——必要时改归 PAGE 前缀；删除长图区间帧前必须目检确认长图被邻帧完整覆盖；低分≠跳跃（商品图渐进加载会造成假 GAP），高重叠≠可删（须确认无独有内容）。
- 页面类型切换对不参与自动合并/插入。

第三步：提取规则要点- 保留完整画面，不裁剪、不改比例、不遮挡；截图对应原视频真实帧。

• 相邻聊天截图目标重叠约 15% 有效聊天区（初始目标，可按实际调整）；以完整气泡/消息顺序为重叠参照，仅背景相同不算有效重叠。
• 长消息跨多张时优先保留展示完整消息的画面；视频里没出现完整消息就如实保留并标记，不得合并补写。
• 可剔除完全重复且无新增信息、不承担衔接作用的截图；含新消息/状态变化/关键操作的不得删。
• 静止期纯重复帧直接删除（如结尾静止帧、滚动间隙），由相邻前一帧覆盖该时间区段并在清单注明；但"从个人主页返回后的聊天画面"这类承担 A-B-D 衔接证明的状态帧必须保留，即使与进入前画面相同，并在清单异常说明列注明原因。
• 连续性不足时先查中间帧补提取；仍不足则保留真实画面并标记连续性缺口，不得为凑重叠重复保存相同画面。

第四步：个人主页专项

• 以主页实际显示为认定依据（不能只凭点击动作）。PROFILE 前缀单独保存。
• 检查项（如实记录，缺项不推测）：头像、昵称、微信号、地区及其他可见资料；主页滚动按实际状态连续提取。
• 保留时序：A 进入前聊天页 → B 主页 → C 主页内部后续状态（如有）→ D 返回后聊天页；D 之后的滚动从返回后的实际位置继续，不得跳回开头。
• 主页未成功提取时：回到出现区段 → 查候选帧 → 重提取 → 确认文件保存成功 → 重跑主页校验。画面本身模糊/被遮挡则保留可用画面并说明限制。

第五步：输出目录

在用户指定工作目录下建（用户指定了其他结构则从其指定）：

微信聊天截图输出/
├── 01_聊天截图/          # 按时间顺序的全部界面截图（含主页、页面状态截图）
├── 02_个人主页截图/       # PROFILE_ 副本
├── 03_页面状态截图/       # 需独立留存的其他页面状态
├── 04_连续性预览/         # 仅预览用，明确标记为预览文件，不替代原始截图
├── 05_截图索引/
│   ├── screenshot_manifest.csv
│   └── quality_check_report.md
└── 06_异常记录/           # 未能提取/无法辨认/连续性不足/修复失败

空文件夹不能推定相关页面未出现——先完成原视频检查再下结论。

命名：0001_CHAT_t<毫秒>.png / 0002_PROFILE_t<毫秒>.png / 0031_PAGE_t<毫秒>.png——编号为全局时间序号（不按页面类型分组），打头且全局唯一，保证文件名排序 = 原视频时间顺序，与预览图、清单行序一致；排序依据原视频时间，不依据文件生成时间。extract 脚本已按 list.json 顺序全局编号。

第六步：强制质检

1. 自动校验（文件完整性 + 相邻重叠/位移/重复检测）：

python <skill目录>/scripts/check_screenshots.py <01_聊天截图目录>

输出 qc_report.json：每对相邻截图给出 match_score、scroll_px、overlap_ratio 与状态（OK / GAP 连续性缺口 / DUP 近重复 / PAGE_SWITCH 页面切换 / WARN 无法自动估计）。判定含义：
- GAP：需回原视频补帧或人工判读。
- DUP：画面未滚动且无像素变化，可评估剔除（但含新增信息/承担衔接的不得删）。
- PAGE_SWITCH：聊天↔主页等类型切换，衔接（A-B-D 顺序）由人工判读确认。
- WARN：截取区无文字纹理，自动匹配不可行，必须人工判读。
- 近全白（无内容像素）/近全黑/损坏文件会被单列。
自动检测只覆盖像素层面；消息内容层面的连续性（有无消息跳跃、遗漏、错误排序）必须亲自逐对 Read 原图判读，不得只凭文件名/时间戳/视觉相似度下结论。

2. 清单生成（骨架预填，描述性列须判读后补填）：

python <skill目录>/scripts/make_manifest.py <01_聊天截图目录> --qc <01_聊天截图目录>/qc_report.json

manifest 12 列：编号/文件名/时间戳/页面类型/时间区段/画面客观描述/衔接情况/重叠内容/是否涉及主页进出/是否清晰/是否通过质检/异常说明。描述必须基于实际画面。

3. 主页核验清单逐项记录实际结果：是否识别到进入画面、是否保存成功、是否有清晰画面、主页内是否有变化、是否识别到返回、返回后顺序是否正确。

4. 发现问题 → 定位时间区段 → 重新提取 → 检查修复前后相邻截图 → 重跑相关质检 → 记录问题/处理/结果。每轮均如此，同一问题最多 3 轮。

第七步：最终报告（quality_check_report.md）

分项列明，不得虚报：
A. 视频基本信息；B. 实际输出截图总数；C. 聊天截图数；D. 个人主页截图数；E. 连续性检查结果（含不足区段）；F. 主页检查结果（核验清单逐项）；G. 未通过检查的截图及时间戳；H. 无法修复的问题及原因；I. 最终验收结论。

验收标准（全部满足才可标"已完成"）：视频可读取且信息已记录；截图按时间排序；相邻对已逐对检查；重叠不足/跳跃已修复或明确标记；主页已专项核验；主页前后衔接已检查；图片均可打开；文件名/编号/时间戳/清单相互对应；无未说明的关键遗漏；所有无法修复问题已记录；报告已生成。

资源

• scripts/extract_frames.py：probe / sample / extract 三个子命令。
• scripts/refine_sequence.py：滚动位移自适应精修（合并重复 / 插入补跳跃），输出 refined_list.json。
• scripts/check_screenshots.py：自动质检（完整性 + 重叠 + 重复）。
• scripts/make_manifest.py：manifest CSV 骨架生成（兼容新旧命名，按时间戳排序）。