/video-screenshot

name: video-screenshot
description: 视频截图提取、滚动文字提取与证据线索精筛工具。从微信、小红书、网页、会议等录屏中以有界高召回抽取关键帧，控制截图密度并过滤切换中间态；可用本地 OCR 多锚点和无文字图像主体生成不保存原文的证据线索索引，用匿名标注私有语料建立脱敏双路径基线，再提供受预算、封闭类别、非破坏性的分类/概括包，以及只做减法且有覆盖存活门禁的去重审计包。显式滚动文字模式用本地 OCR 与保守正文裁区输出可复制 TXT/Markdown、原OCR和回源；该模式保存原文，与线索索引的隐私口径不同。抽帧、OCR与正文拼接由本地程序执行。触发词：视频截图、录屏截图、聊天记录截图、证据截图、视频证据线索、抽帧去重、关键帧提取、截图太密、过渡帧、切换页、截图审计、滚动文字提取、录屏转文字、转录页面提取。不要用于视频压缩、视频剪辑、法律证明力认定或音频提取。
version: "1.2.0"
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills
license: MIT

video-screenshot — 视频截图提取与精筛

从录屏中提取可追溯的证据截图。默认先在本地执行时间簇择优、内容增量精筛和高置信加载态过滤；只有当前模型支持图像输入且基础结果仍需精简时，才准备少量多模态审计材料。

按用户要的结果选择入口：

| 目标 | 入口与结果 | |---|---| | 截图、证据截图、关键帧精筛 | 下述截图工作流，运行`extract.py`；生成图片与`_report.json`，可继续证据线索或视觉审计 | | 把录屏页面文字提取为TXT/Markdown | 显式使用`run_scroll.py`；生成原OCR、全页/裁图、正文与回源记录 |

两条流程分别使用自己的输出目录和报告。只有用户需要可复制文字时才启动文字提取；日常截图仍按原截图入口执行。文字结果中的`receipt.json`不能代替证据线索/视觉审计需要的`_report.json`。

滚动页面文字提取（显式模式）

用户要求录屏内已有正文的可复制文字时，使用此入口。它会**保存 OCR 原文**、截图和来源路径；先选择私密、仓库外的新目录，与后述不保存原文的证据线索模式区分。

阅读[滚动文字使用说明](references/scroll-text.md)：环境准备、命令、参数、错误处理和结果核查。Apple Vision与RapidOCR的实际适配、准备和选择逻辑由`scripts/`实现，reference说明如何调用。统一入口自动找到已准备的运行环境并选择可用后端。

一次明确准备（已有 ffmpeg/ffprobe；Rapid需要已有、与运行进程架构一致的Python 3.10—3.12，Vision需要macOS已有Swift编译器）：

python3 scripts/prepare_ocr.py --engine both --install-deps

这条准备命令可从官方PyPI下载Rapid包/模型到Skill专属缓存独立venv，不改全局/user-site。未明确准备时不传`--install-deps`；正常诊断和提取不会安装。非macOS明确准备`--engine rapidocr --install-deps`。没有对应系统组件时报告缺项。

python3 scripts/run_scroll.py --check-env --deny-network
python3 scripts/run_scroll.py -i /输入/录屏.mp4 -o /私有输出/全新目录 --deny-network

默认`auto`只在源OCR前用非敏感测试图选择真正可用的本地后端：Vision优先，失败后尝试已准备的RapidOCR，最多两次；都失败明确阻塞。显式`--engine vision|rapidocr`仍可用。`--deny-network`需要macOS的sandbox-exec；其他平台省略该选项并披露网络隔离未验证。后端选定后不在正文处理中静默切换。详细依赖、显式 ROI、预算和失败语义见 [滚动文字协议](references/scroll-text.md)。

<!-- skill-lint:constraint SCROLL-TEXT-CONSERVATION --> 保留全页与真实 OCR 来源，只缓存像素完全相同的输入；自动裁区证据不足时回退全页，不按近似图像吞正文，不按同文全局合并真实独立发言。用行块序列重叠拼接，保留读数变体/无法对齐片段，不凭常识改写原 ASR。

<!-- skill-lint:constraint SCROLL-TEXT-LOCAL-BOUNDED --> 限定帧数、像素、布局+正文 OCR 总数、批量与少量疑点复核预算；耗尽时保留部分/待核结果，失败不能冒成功，不覆盖已有结果。输出 TXT/MD、raw、provenance、全页/裁图、疑点和真实进程记录。页面时间与 fps 推导抽样秒数分开标注，不称整场全文。

按固定分支运行：环境blocked报告缺项；提取partial保留部分/待核；不能读图保留not_reviewed；不扩大预算或语义修稿。检查 `receipt.json`、首尾和正文裁边，运行 `python3 scripts/check_scroll_text.py --verify-output <目录>`。按`review/INSTRUCTIONS.md`查看指定的相邻图；未实际查看的复核项保持`not_reviewed`。OCR 引擎零报错不证明文字全对或零遗漏。

截图提取与精筛工作流

1. 确认输入与输出

取得一个本地视频路径。支持 `.mp4`、`.mov`、`.avi`、`.mkv`、`.webm`、`.flv`、`.wmv`、`.ts`。默认输出到视频同级 `<视频名>_frames/`；如该目录可能含其他材料，显式指定新的 `-o` 目录。

<!-- skill-lint:constraint TRANSACTIONAL-OUTPUT-SAFETY --> 脚本必须先完成参数检查和视频探测，再在目标目录同级的隐藏 staging 中生成完整结果。只有帧、报告、所有权标记和可选归档全部成功后，才一次性替换旧的本工具输出；任一步失败都保留旧结果。输出根目录或其中任一文件是符号链接、目录含未知文件，或已经生成 `_evidence_leads`、`_vision_audit`、`_curated`、`_vision_review.json` 时，拒绝原地覆盖并要求使用新的 `-o`。旧版无所有权标记的结果只有在 `_report.json` 与实际基础帧清单完全一致时才允许兼容替换。

2. 运行基础精筛

# 默认：场景候选 + 自适应时间簇择优 + 图像去重
uv run scripts/extract.py -i <视频路径>

# 聊天记录等文字型录屏：增加本地 OCR 内容增量保护与去重
uv run --with rapidocr-onnxruntime scripts/extract.py -i <视频路径> --ocr-dedup

# 调试漏帧时才保存被丢弃候选；不要作为多模态默认输入
uv run scripts/extract.py -i <视频路径> --keep-drop-candidates --drop-candidate-limit 80

默认流程：

1. 用 ffmpeg 场景变化和 2 秒保底采样生成高召回候选； 2. 计算候选帧清晰度、内容质量、相似度、滚动重叠、加载态和拼接风险； 3. 按前后帧形成稳定段与连续运动段； 4. 稳定段选择清晰、完整、停留时间更长的代表帧，不机械保留第一张； <!-- skill-lint:constraint BASE-HIGH-RECALL --> 5. 前后均有稳定页的短运动段至少保留一张低置信代表帧；只有三帧像素拼合能直接证明是前后页面合成时才自动删除，持续滚动段依据相邻内容重叠自适应调整保留跨度； 6. 自动丢弃高置信居中加载浮层；疑似未完成页只有在 1.25 秒内出现同一页面骨架、主内容明显增加且完整后帧最终被基础层保留时才删除； 7. 用三帧像素拼合与分区覆盖共同估计横向、纵向或缩放切换风险；分区风险只用于提权审计，不单独自动删除； 8. 单帧 `transition` 质量标签只记录风险，不单独删除；再执行 SHA256、dHash、像素差异、SSIM、可选滚动合并和 OCR 内容增量判断。OCR 对短运动段最多检查 24 张高风险图片，并在新增金额、长编号或足量正文时否决近似去重和最小间隔删除；启用 OCR 时关闭未完成页的纯视觉自动删除。

需要调参时读取 `references/strategy-and-params.md`。依赖安装见 `references/setup.md`。

3. 检查基础结果

检查：

• `_report.json` 中 `frames` 与实际 `frame_*.jpg` 是否一致；
• `temporal_selection` 的稳定段、运动段、自适应密度和切换丢弃统计；
• 联系表总览中是否仍有左右两页拼接、上下切换中间态或明显重复页；
• 视频开头、结尾、长滚动和关键主体/金额/地址页面是否有覆盖。

不要只因帧数减少就判定准确率提高。基础结果不调用大模型，并在报告中保留 `vision_audit_status=not_prepared`。

4. 建立可比较基线（仅算法迭代时）

<!-- skill-lint:constraint PRIVATE-BENCHMARK-NO-OVERCLAIM --> 需要比较算法版本、OCR 路径或参数时，先在 Git 仓库外为真实私有视频建立候选外人工标注，再运行：

uv run --with rapidocr-onnxruntime scripts/benchmark.py run \
  --manifest /绝对路径/私有评测/manifest.json \
  --workspace /绝对路径/私有评测/workspace \
  --profiles visual,ocr

manifest 只使用 `CASE-001` 这类匿名编号；workspace、视频、基础报告与标注不得进入仓库。脱敏汇总不保存源路径、OCR 原文、标注时间点或帧名。少于指定五类真实页面、缺少候选外标注或双路径未跑齐时，必须保持 `real_baseline_status=not_verified`；合成回归不得替代真实准确率结论。全部跑齐也只标记 `recorded_requires_human_review`，真实来源和标注语义仍由人工确认。完整协议见 `references/benchmarking.md`。

5. 生成高价值证据线索包

基础结果确认完整后，先用代码生成一个独立的高价值索引；这一步也适用于纯文字模型：

# 推荐：本地 RapidOCR 多锚点 + 无文字图像主体 + 时序信号
uv run --with rapidocr-onnxruntime scripts/prepare_evidence_leads.py \
  -i <基础输出目录>

# 未安装 OCR 时仍可运行，自动保留图像主体与时序排序
uv run scripts/prepare_evidence_leads.py \
  -i <基础输出目录> --no-ocr

脚本生成 `_evidence_leads/evidence_index.json`、最多 24 张线索组成的 4 页大图联系表，以及可直接填写的 `vision_template.json`。代码只记录主体/资质、商品/作品/服务、交易履行、沟通承诺、公开陈述、评论争议、传播时间线、文书记录等**类别和组合命中计数**；不保存 OCR 原文、企业名、商品名、价格或沟通正文。单个“商品”“消息”等宽泛词不得独立触发类别。

<!-- skill-lint:constraint EVIDENCE-LEADS-NON-DESTRUCTIVE --> OCR 不是价值总开关。商品外观、包装/标识、作品画面、缺陷状态、经营场所和人物行为等少文字画面，仍通过连续图像主体面积进入线索排序；具体含义留给多模态或人工判断。证据线索阶段只做排序、分类和概括，绝不删除、替换或覆盖基础 `frame_*.jpg`，也不认定真实性、合法性、关联性或证明力。

如果当前模型可读取图片，逐页查看 `evidence_sheet_NNN.jpg`，按 `_evidence_leads/VISION_INSTRUCTIONS.md` 原位填写模板，再应用：

python3 scripts/apply_evidence_review.py \
  -i <基础输出目录> \
  -r <填写完成的 vision_template.json>

应用器只接受封闭类别、可见事实和“可能用途”，拒绝“足以证明”等法律结论，并生成 `_evidence_leads/evidence_review.json`。使用默认 2 列大图，保持图片预算；不能读图时交付代码排序结果，并明确 `evidence_review` 未执行。详细合同见 `references/evidence-leads.md`。

6. 按能力选择去重多模态分支

如果当前模型或工具不能读取图片，停止在基础结果，明确说明视觉审计未执行。不要根据文件名或算法分数伪造图像判断。

如果支持图片，并且用户希望进一步精简，生成经济型审计包：

uv run scripts/prepare_vision_audit.py \
  -i <基础输出目录> \
  --max-