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编译器）：

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

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

```bash
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. 运行基础精筛

```bash
# 默认：场景候选 + 自适应时间簇择优 + 图像去重
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 仓库外为真实私有视频建立候选外人工标注，再运行：

```bash
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. 生成高价值证据线索包

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

```bash
# 推荐：本地 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` 原位填写模板，再应用：

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

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

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

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

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

```bash
uv run scripts/prepare_vision_audit.py \
  -i <基础输出目录> \
  --max-groups 8 \
  --max-images 24
```

<!-- skill-lint:constraint VISION-SUBTRACT-ONLY -->
脚本先要求目标与至少一个上下文通过严格的近像素一致或高质量滚动重叠校验，再按风险分数与时间覆盖选择少量组，生成 `_vision_audit/audit_manifest.json` 与联系表。多模态层只做减法，不恢复基础层漏掉或已丢弃的图片；没有安全可删题时允许生成 0 组。按照 `references/vision-audit.md` 查看同组前后帧，输出 `_vision_review.json`。默认不得突破 8 组、24 张唯一图片；确需扩大时先向用户说明成本和隐私影响。

需要每组只判断一个目标、默认6组/18张的小批量审计包时，使用现有`weak`配置：

```bash
uv run scripts/prepare_vision_audit.py \
  -i <基础输出目录> \
  --profile weak
```

<!-- skill-lint:constraint FINAL-COVERAGE-SURVIVAL -->
`weak` 默认最多 6 组、18 张唯一图片；每张联系表只有一个红框判断目标，A/B/C 角色清晰标注，并生成 `review_template.json` 与 `MODEL_INSTRUCTIONS.md`。按组逐张查看，原位填写模板。weak 与 balanced 提出的删除或替换都只有在“置信度至少 0.90 + 本地核准覆盖候选 + 本地风险信号 + 覆盖帧最终存活”同时满足时才会生效；覆盖链、覆盖环或其他不足均安全降级为保留。

### 7. 应用去重视觉审计

```bash
python3 scripts/apply_vision_review.py \
  -i <基础输出目录> \
  -r <基础输出目录>/_vision_review.json
```

应用脚本必须复算基础报告、manifest 和图片 SHA256。成功后生成 `_curated/` 与 `_curated/_curated_report.json`；不得删除或覆盖基础 `frame_*.jpg`。非法引用、过期 manifest、缺理由、哈希不符或空精选集必须失败关闭。

## 主要输出

| 文件 | 说明 |
|---|---|
| `frame_NNN_MMmSSs.jpg` | 本地算法保留的基础帧 |
| `_report.json` | 输入、参数、时间簇统计、丢弃统计、帧时间戳和 SHA256 |
| `_video_screenshot_output.json` | 不含源路径的输出所有权标记，绑定报告与目录内容哈希及根目录清单，供安全重跑校验 |
| `_review_candidates/` | 仅显式开启时保存的算法丢弃候选 |
| `_evidence_leads/evidence_index.json` | 证据线索排序、类别、信号计数、隐私声明和逐帧哈希；不含 OCR 原文 |
| `_evidence_leads/evidence_sheet_NNN.jpg` | 默认 2 列大图的高价值联系表；最多 24 张、4 页 |
| `_evidence_leads/vision_template.json` | 封闭类别、可见事实与可能用途模板 |
| `_evidence_leads/evidence_review.json` | 经应用器校验的非破坏性视觉分类结果 |
| `_vision_audit/audit_manifest.json` | 受预算限制的视觉审计清单与决策合同 |
| `_vision_audit/contact_sheet_NNN.jpg` | 同组前后帧联系表；weak 档位为一组一目标大图 |
| `_vision_audit/review_template.json` | weak 档位预填的受限答案模板 |
| `_vision_audit/MODEL_INSTRUCTIONS.md` | weak 档位逐组判断说明 |
| `_vision_review.json` | 多模态模型的结构化审计结果；weak 使用模板 schema 1.1 |
| `_curated/` | 不修改基础结果的视觉精选副本 |
| `_curated/_curated_report.json` | 精选帧来源、排除清单和全链路哈希 |
| 仓库外 `benchmark_summary.json` | 匿名真实语料的双路径召回、过渡泄漏、重复、密度与耗时汇总；不含路径、原文、标注时间点或帧名 |

## 参数选择

- 默认使用 `scene`，适合手机 App、网页和聊天录屏。
- 默认启用 `--temporal-select`；只有复现旧版行为或排查算法时才用 `--no-temporal-select`。
- 持续快速滚动担心漏页时，降低 `--motion-chunk-seconds`；结果仍过密时再提高。默认值还会按滚动重叠自动乘以 0.8、1.25 或 1.45。
- OCR 是可选增强，未安装时必须清晰提示并降级；它可能为保护新增金额或正文而比纯视觉模式多留少量帧，不能把“帧数更少”作为唯一目标。
- `--keep-drop-candidates` 只用于人工排查基础层漏帧，不等于多模态审计；多模态生产路径不会补回这些图片。
- 默认仅将 `_report.json` 与 `extraction_meta.json` 归档到 Skill `archive/`（不复刻截图与视频，避免重复占用磁盘）；批量回归或临时验证使用 `--no-archive`，不改变基础报告与原始输出目录。
- 使用 `--profile weak` 可生成每组单目标的小批量审计包；保持图片预算，对不能确认的删除选择保留。

## 依赖

### 系统依赖

| 依赖 | 安装方式 |
|---|---|
| ffmpeg ≥ 5.0 | macOS: `brew install ffmpeg`<br>Linux: `sudo apt-get install ffmpeg` |
| Swift 编译器（仅 Apple Vision helper） | 使用已安装的 macOS Command Line Tools；构建见滚动文字入口，不自动安装 |
| Python ≥ 3.10 | macOS: `brew install python` |
| uv | macOS: `brew install uv` |

### Python 包

| 包名 | 用途 | 安装命令 |
|---|---|---|
| `Pillow>=10.0.0` | 图像指标、时间簇分析和联系表 | `uv run scripts/extract.py --help` 自动准备 |
| `rapidocr-onnxruntime` | 可选 OCR 内容增量与文本去重 | `uv run --with rapidocr-onnxruntime scripts/extract.py -i <视频> --ocr-dedup` |

同一可选依赖也用于证据线索多锚点分类：`uv run --with rapidocr-onnxruntime scripts/prepare_evidence_leads.py -i <基础输出目录>`。缺失时清晰降级为视觉主体与时序排序，不影响基础抽帧。

滚动文字统一入口自动使用本Skill准备的独立Python（含Pillow）；仅Vision环境则使用当前已配置Pillow的Python。固定Rapid依赖见`config/rapidocr-requirements.txt`，由上方明确准备命令一次安装到专属venv；不经uv隐式准备。Apple Vision底层由macOS提供，Swift适配源码在Skill内。第三方包/模型保留其许可证，不提交到本技能Git。

## 验收与安全边界

- 新文字模式运行 `python3 scripts/run_scroll.py --verify-output <结果目录>` 做独立绑定检查；开发回归运行 `python3 scripts/check_scroll_text.py --case all`，再复查真实录屏输出；其自含夹具不替代 OCR 语义质量证明。
- 运行 `uv run scripts/check_pipeline.py --case all`，要求全部领域回归通过并输出 `DOMAIN_CHECKS_PASSED`。
- 评测底座可单独运行 `uv run scripts/check_pipeline.py --case benchmark`；该合成 CLI 回归只证明评测合同、FFmpeg 兼容和脱敏汇总可用，不证明真实截图准确率。
- 输出事务可单独运行 `uv run scripts/check_pipeline.py --case transactional-output`，必须覆盖坏视频、非法参数、符号链接、未知文件、下游产物保护、成功替换和提交回滚。
- 行为变化必须用代表视频复测，并通过联系表或逐图查看进行视觉抽查；静态检查或帧数减少不能单独证明准确。
- 不修改原视频，不把完整录屏默认上传云端。
- 保留基础帧和全链路 SHA256；证据线索层只能排序、分类和概括，去重视觉层只能生成非破坏性精选副本。
- 法律证据中的金额、身份、地址、承诺和关键对话不确定是否被覆盖时，选择保留并提示人工复核。

## 所需权限与安全说明

- **文字模式留存**：`scroll_text.py` 显式保存 raw/TXT/MD/来源/进程记录到仓库外新目录，仅缓存完全相同的像素。0700 staging 完整后用本机不覆盖原子提交；运行错误保留 staging/部分产物供核查。它不使用截图路径的旧目录替换/归档规则。
- **环境与本地引擎**：OCR 子进程仅继承 PATH/HOME/TMPDIR/语言等运行环境，不传云凭据；macOS `--deny-network` 实际隔离 OCR。明确prepare --install-deps才会联网下载到专属venv，正常run入口不安装。Swift/helper 或 RapidOCR 属本地受信代码，使用系统重命名接口做原子提交。
- **本地文件访问**：读取用户明确提供的视频；图片与复核 JSON 只写入显式输出目录，Skill `archive/` 仅写入 `_report.json` 与 `extraction_meta.json` 元数据副本；不扫描无关目录。
- **本地进程执行**：以参数数组调用本机 `ffmpeg`、`ffprobe` 和 Python 脚本，不使用 shell 拼接执行用户输入。
- **事务性替换**：新结果只写入目标同级 staging；成功提交前不改动旧目录。旧目录必须通过所有权标记，或通过旧版报告与实际帧清单一致性校验；若发现证据线索、视觉复核、精选结果、符号链接或未知文件，拒绝覆盖并提示改用新目录。
- **网络与依赖**：抽帧和 OCR 均可离线运行；`uv run` 首次缺少 Pillow 时可能联网下载依赖。多模态审计是否上传联系表取决于当前模型提供方，处理未脱敏证据前先确认其隐私政策。
- **凭据与环境变量**：本 Skill 不读取 API Key、Token、密码或云端凭据，也不自行调用外部视觉 API。