/video-screenshot

Changelog

[0.8.2] - 2026-08-30

修复

• 修复损坏视频、无效参数或处理中途失败时可能先清理上一轮基础帧与 _report.json 的问题：输入和参数现在先完成预检，新结果完整生成前旧目录保持不变
• 修复输出根目录符号链接会在 resolve() 后被跟随的问题；输出根、候选目录或目录项含符号链接时一律失败关闭
• 将 _evidence_leads 纳入基础抽帧的下游产物保护，避免重跑后留下与新基础帧不匹配的旧证据线索

新增

• 新增同级 staging + 备份恢复的事务性提交：帧、候选、报告、所有权标记和可选归档全部成功后才替换旧结果，提交异常会恢复旧目录
• 新增 _video_screenshot_output.json 所有权标记，以报告 SHA256、目录内容聚合 SHA256 和根目录清单约束安全重跑；旧版输出通过 _report.json 逐帧 SHA256 一致性保守兼容
• 新增 transactional-output 真实 CLI 回归，覆盖损坏视频、非法参数、未知文件、下游产物、输出符号链接、成功替换和提交故障回滚

改进

• CLI 参数在启动 ffmpeg 前统一校验数值范围和裁剪组合，避免无效值运行到中途才失败
• 归档目录名加入微秒级唯一后缀，避免同名视频在同一秒内复测时复用既有归档目录

文档完善

• 更新工作流、输出清单、安装边界、参数 reference 和权限说明，明确输出目录所有权、失败保持与安全重跑条件

[0.8.1] - 2026-08-13

改进

• archive 改为仅保留元数据：归档时只复制 _report.json + extraction_meta.json 到 Skill archive/，不再复刻 frames/ 与 _review_candidates/ 下的截图与丢弃候选帧，避免 archive 重复占用大量磁盘
• 原始截图以用户原输出目录为准，原始视频保持在用户原路径，archive 只承载纯文本溯源记录
• archive_validation 字段改为 metadata_only 模式（report_copied + frame_count_in_report），不再比对 frames/ 文件名清单
• extraction_meta.json 的 drop_candidates_archived 固定为 False，避免后续误以为 archive 里有复核候选

技术优化

• 新增 metadata-only 归档回归：领域回归扩展为 21 个命名用例，断言归档只含两份 JSON、不会复制基础帧或丢弃候选，并强化 weak 审计只生成基础保留目标的减法任务

文档完善

• 同步安装、参数、证据线索和视觉审计 reference：明确实际基础输出目录与元数据归档的边界，并删除弱模型可恢复丢弃候选的歧义

[0.8.0] - 2026-08-13

新增

• 新增独立 _evidence_leads/ 证据线索包：对全部基础帧生成价值排序索引，并用最多 24 张、4 页、默认 2 列大图联系表降低人工与弱多模态筛选成本
• 新增八类本地 OCR 多锚点分类：覆盖主体/账号/资质、商品/作品/服务、交易履行、沟通承诺、公开陈述、评论争议、传播时间线和文书记录；单个宽泛词或单一正则不触发类别
• 新增无文字图像主体识别：用连续中间调/色彩区域和场景新增信号保护商品外观、包装标识、作品画面、缺陷状态、场所及行为类线索，不把 OCR 为空等同于无意义
• 新增弱多模态封闭复核合同与应用器：只允许分类、可见事实和可能用途，拒绝自由类别及“足以证明”等法律结论

改进

• 联系表在价值与时间覆盖排序后，再用 dHash 抑制近重复画面；重复帧仍保留在完整索引，不重复消耗视觉模型预算
• OCR、视觉主体、来源上下文和时间连续性改为并列信号；证据线索低分不得反向删除基础帧
• 证据线索准备、模型答案与应用结果分别绑定基础报告、分类配置、索引及逐帧 SHA256；已填写模板和既有复核结果拒绝被重建覆盖

技术优化

• check_pipeline.py 新增多锚点/单词反例、无文字图像/空白页、非破坏性线索包、合法复核和法律结论越界用例
• 指令稳定性合同新增 EVIDENCE-LEADS-NON-DESTRUCTIVE 硬约束及隔离变异夹具，独立检查器可阻断证据线索层修改基础帧
• 真实 54 张小红书截图复测：纯视觉路径由首版 54 张几乎全高优先收紧为 3 张高优先、27 张中优先；首张联系表稳定聚焦商品外观、详情与标识
• RapidOCR 路径完成全量运行，证据索引检索不到样本主体名、商品名、价格、招聘正文或 OCR 原文

文档完善

• 新增 references/evidence-leads.md，说明四类并列信号、八类线索、隐私字段、弱模型合同及与去重审计的边界

[0.7.0] - 2026-08-13

新增

• 新增有界高召回短运动段：稳定页之间持续时间短但没有直接三帧拼合证据的区间至少保留一张 short_motion_representative，其余同段帧才按冗余丢弃
• 新增有限 OCR 短段补救：最多检查 24 张高风险图片、每组最多补回一张包含新金额、长编号或足量正文的候选；OCR 原文不写入报告
• 新增多模态本地覆盖资格与最终存活门禁：仅近像素一致或高质量滚动重叠可成为覆盖候选，覆盖链、覆盖环和已删除见证帧均安全无操作
• 新增 --no-archive 验证开关，允许批量复测跳过额外归档副本且保持默认归档兼容

改进

• 单帧 transition 内容质量标签改为只提权审计，不再独立删除非对称正文页
• 短时页面代表帧可绕过非 SHA256 近似去重和最终最小间隔，避免“时间簇先保留、后级联又吞掉”
• OCR 强新增内容可以否决最终 --min-gap；报告新增 OCR 最小间隔、短段补救与短时页面保护计数
• weak 与 balanced 统一为只做减法：不再生成丢弃候选恢复题，只审计有本地核准覆盖关系的基础目标；没有安全可删题时允许生成 0 组
• 应用器从原图重算覆盖资格，并要求 replace 的替代帧等于覆盖帧；门禁不足统一记录 safe_noop

技术优化

• check_pipeline.py 扩展为 16 个命名用例，新增短时独立页、非对称正文、OCR 短段补救、无关覆盖、balanced 门禁及覆盖链/环反例
• 新增指令稳定性合同、独立不变量检查器以及一正三负固定夹具，把“有界高召回、视觉只减、覆盖帧最终存活”映射到可执行回归证据
• 真实 213.6 秒小红书录屏复测：411 个初始候选在纯代码模式保留 54 张，仅比 v0.6.0 增加 1 张；短时页面近似保护实际触发 1 次
• 同一录屏启用 RapidOCR 后保留 57 张，实际触发 4 次 OCR 最小间隔保护、1 次短时页面间隔保护和 1 次短时页面近似保护
• 严格覆盖资格下真实 weak 包只生成 1 组、3 张图片；207.68 秒页面与 211.10 秒无关录屏页不再获得覆盖资格，避免为弱模型制造伪可删题

文档完善

• 重写基础高召回与视觉只做减法边界，补充覆盖资格、最终存活、0 组安全结果和 --no-archive 使用说明

[0.6.0] - 2026-08-13

新增

• 新增未完成页时序覆盖判断：疑似页面只有在短时间内出现同一页面骨架、主内容明显增加且完整后帧本来就会被时间簇保留时，才由代码记录为 temporal_incomplete_resolved 并删除
• 新增三帧分区覆盖风险：允许真实 App 动画中的缩放、位移和重采样，识别由前后邻帧共同解释的横向、纵向切换风险；该信号只提权视觉审计，不单独自动删除
• 新增 --profile weak 多模态档位：默认 6 组、18 张唯一图片，采用 2 列大图、单一红框目标、A/B/C/D 角色和预填 review_template.json
• 新增 weak schema 1.1 应用门禁：基础帧删除/替换与丢弃候选恢复使用不同任务类型，并记录不满足门禁的 safe_noop

改进

• weak 模型删除或替换必须同时满足置信度至少 0.90、同组基础保留帧覆盖和本地风险信号支持，模型自报置信度不能单独改变结果
• 联系表改用支持中文的字体并排除与目标超过 6 秒的伪前后帧，避免较弱模型把跨页面内容当成相邻覆盖证据
• 自动删除项携带实际覆盖后帧的源序号；该后帧会绕过后续去重、最小间隔和质量过滤并接受最终清单校验，视觉恢复题优先引用该完整帧
• 启用 OCR 时关闭未完成页的纯视觉自动删除，确保新增文字、金额或编号仍有机会否决图像去重

技术优化

• check_pipeline.py 扩展为 15 个命名用例，新增时序完整页、分区切换、weak 审计包、低置信安全无操作、跨组覆盖和重复图片组成员关系正反例
• 真实 213.6 秒小红书录屏复测：411 个初始候选在纯代码模式保留 53 张；4 个未完成候选分别绑定到 2 个最终保护后帧，13.49 秒主页被 14.02 秒完整帧覆盖后删除，207.68 秒独立页面继续保留
• 同一真实录屏启用 RapidOCR 后保留 53 张，resolved_incomplete_drop_count=0，2 张近似页因新增文字/数字覆盖视觉去重，验证 OCR 优先保护路径未被纯视觉规则抢先删除
• weak 默认审计包实际生成 6 组、18 张唯一图片，覆盖 5 个 30 秒时间桶，并同时包含 2 组算法删除抽样 QA 与 4 组基础保留帧精筛题

文档完善

• 更新基础算法、弱模型使用步骤、输出合同和依赖降级说明，明确不通过扩张图片预算弥补模型能力不足

[0.5.0] - 2026-08-13

新增

• 新增滚动内容重叠驱动的自适应运动段密度：根据滚动冗余、混合滚动或内容快速变化，动态调整代表帧时间跨度，并在报告中记录模式、实际跨度和匹配比例
• 新增保守的加载态识别：高置信居中加载浮层可由本地层自动丢弃；疑似未加载完整页面只记录风险并进入视觉审计，不直接删除
• 新增 OCR 内容增量保护：比较最近页面的新增正文、金额和长编号，强内容增量可以否决视觉近似删除；报告只保存计数和相似度，不保存 OCR 原文
• 新增视觉审计时间覆盖预算：在风险优先基础上分散审计时段，manifest 记录已覆盖的 30 秒时间桶

改进

• 修复 RapidOCR 返回值解析错误：改为读取 [box, text, confidence] 中的文字字段，不再误把置信度数字当作识别文本
• OCR 增量过滤 1—2 位易变数字，避免状态栏时钟和视频时间码制造假增量；SHA256 完全重复和最小时间间隔不接受 OCR 覆盖
• 视觉审计风险原因细分为加载浮层、未加载页、低内容增量和新增证据数字，避免普通白底页面仅因亮度进入高优先级
• 复核候选达到数量上限时为加载浮层和质量过渡帧保留优先槽位，确保后段高风险删除项仍可由视觉模型审计并按需补回
• RapidOCR 推荐改用 uv run --with rapidocr-onnxruntime 按次注入，保持默认纯代码路径轻量且离线

技术优化

• check_pipeline.py 扩展为 11 组领域回归，新增 OCR 解析、内容增量、加载态保守边界、自适应密度和审计时间多样性正反例
• 真实 213.6 秒小红书录屏复测：411 个初始候选在纯代码模式保留 54 张，少于 v0.4.0 的 55 张，并自动过滤 1 张高置信加载浮层；OCR 模式保留 57 张，其中 7 张由强内容增量保护
• 默认视觉预算生成 8 组、24 张唯一图片并覆盖 5 个分散的 30 秒时间桶，其中包含高置信加载浮层专属复核组；实际应用结构化视觉审计后，基础 54 张保持不变，非破坏性精选集为 50 张

文档完善

• 更新 SKILL.md、依赖说明、参数文档与多模态审计协议，明确 OCR 可能为证据完整性多保留少量帧，不能以帧数最少作为唯一目标

[0.4.0] - 2026-08-13

新增

• 新增两遍式时间簇择优：先结合候选帧前后关系识别稳定段、短切换段和持续运动段，再在簇内选择清晰、完整、停留更稳定的代表帧
• 新增横向混合页三帧分析与纵向拼接风险指标，为滑页中间态过滤和视觉审计选组提供时序证据
• 新增经济型多模态审计包：prepare_vision_audit.py 默认最多选择 8 组、24 张唯一图片，并生成前后帧联系表和带哈希 manifest
• 新增结构化视觉决策应用器 apply_vision_review.py，支持 keep/drop/replace，以非破坏方式生成 _curated/ 和完整排除清单
• 新增 check_pipeline.py 回归检查，覆盖簇内择优、混合过渡帧、审计预算、合法审计和越界引用失败关闭

改进

• OCR 去重不再自动禁用 SSIM；未安装 RapidOCR 时继续优雅降级到纯图像流程
• min-gap 从主要选帧机制降为时间簇后的安全限流，避免机械保留切换开始时的第一张
• 多模态默认入口由最多 200 张丢弃候选改为本地风险短名单；完整候选只用于漏帧排查
• _report.json 新增时间簇统计、选择置信度、源候选序号、拼接风险和对应丢弃计数
• 重新抽帧或准备审计包时若发现既有视觉审计、人工决策或精选目录，改为拒绝使其失效；旧候选目录也只清理可确认由本工具生成的普通文件，并拒绝跟随符号链接
• 修复稀疏长停留页可能因单候选跨度为零而被误判成短切换的问题；短切换改用两侧稳定页之间的真实时间跨度判定

文档完善

• 重写基础模式与视觉模式分支，新增 references/vision-audit.md 的预算、决策合同和失败边界
• 按项目规范补齐 MIT 许可证版权信息
• 记录 213.6 秒真实小红书录屏复测：同样 411 个初始候选，基础保留由 0.3.2 的 141 张降至 55 张；预算审计处理 8 组、23 张唯一图片，剔除 1 张加载中页、1 张未加载页和 1 张视觉重复页后生成 52 张精选帧

[0.3.2] - 2026-06-02

新增

• 新增复合复核候选帧模式：--keep-drop-candidates 会保存被去重或过滤规则丢弃的候选帧，供多模态模型回查漏帧风险
• 新增 --drop-candidate-limit 参数，限制复核候选帧保存数量，默认最多保存 200 张

改进

• _report.json 新增 review.drop_candidates、review.drop_candidate_count 和视觉复核状态字段，记录候选帧文件名、丢弃原因、时间戳和 SHA256
• 归档结果新增 _review_candidates/，与正式 frames/ 分离，避免复核候选帧污染证据清单

文档完善

• 补充复合复核模式说明：当前模型支持图像输入时才执行视觉复核；文字模型跳过复核并明确说明未做图像判断
• 校正参数文档中的场景阈值、dHash、SSIM、滚动合并和最小时间间隔默认值

[0.3.1] - 2026-05-20

修复

• 修复 archive 污染问题：归档时只复制 _report.json 中记录的有效帧，不再把输出目录内所有 JPG 残留一并复制
• 修复输出目录残留问题：每次运行前自动清理旧的 frame_*.jpg、_report.json 和工具元数据文件，避免旧帧混入新结果

技术优化

• 新增 archive 一致性校验，确保 archive/frames/ 文件名与 _report.json 的帧清单完全一致
• 报告和归档元数据新增 cleanup.stale_deleted_count、cleanup.stale_deleted_files；归档元数据新增 archive_validation 信息

[0.3.0] - 2026-05-20

改进

• 新增内容区聚焦去重：dHash、像素差异、SSIM 和滚动合并默认排除顶部状态栏、底部导航栏及左右边缘
• 新增 SSIM 结构相似度去重：--ssim-threshold 默认 0.70，作为 dHash 的补充判断
• 新增滚动帧合并：--scroll-merge 默认开启，支持 --no-scroll-merge 和 --scroll-diff-threshold 调参
• 修正 scene/keyframe/smart 模式下基于 -frame_pts 的捕获时间戳计算，优先使用视频帧率避免时间戳被输入 time_base 缩小

文档完善

• 更新 SKILL.md 和 references/strategy-and-params.md，补充内容区裁剪、SSIM、滚动合并的参数说明和调参建议

0.2.0 (2026-05-20)

• 新增模糊帧过滤：--filter-blur 可选参数，基于 Laplacian 方差检测模糊帧（默认阈值 50.0）
• 新增内容质量过滤：--filter-quality 可选参数，自动过滤空白页、启动/控制画面、页面切换过渡帧
• 去重流程扩展为六级：SHA256 → dHash → 像素差异 → 质量过滤 → 模糊过滤 → OCR 文本
• 归档元数据新增 filter_blur、blur_threshold、filter_quality 参数和 blur_drops、quality_drops 统计
• 参考：移植自 fachuan（法穿）项目，质量检测算法为新增实现

0.1.0 (2026-05-20)

• 初始版本，核心算法移植自 fachuan（法穿）项目 chat_records/services/ 模块
• 四种抽帧策略：scene（场景检测）、keyframe（关键帧）、interval（固定间隔）、smart（智能去重）
• 四级去重：SHA256 → dHash → 像素差异 → OCR 文本相似度
• 独立 Python CLI，无 Django 依赖
• 本地 RapidOCR 离线 OCR 去重
• 默认保持原始分辨率、最高 JPEG 质量，优先保证证据清晰度
• archive 归档机制：每次分析自动留存参数、报告和帧副本，便于溯源调参