video-screenshot

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

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

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

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

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

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

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

阅读滚动文字使用说明：环境准备、命令、参数、错误处理和结果核查。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、预算和失败语义见 滚动文字协议。

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

限定帧数、像素、布局+正文 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 目录。

脚本必须先完成参数检查和视频探测，再在目标目录同级的隐藏 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. 稳定段选择清晰、完整、停留时间更长的代表帧，不机械保留第一张；

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. 建立可比较基线（仅算法迭代时）

需要比较算法版本、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 原文、企业名、商品名、价格或沟通正文。单个“商品”“消息”等宽泛词不得独立触发类别。

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-groups 8 \
  --max-images 24

スクリプトはまず、対象と少なくとも1つのコンテキストが、厳密なピクセル近似一致または高品質なスクロール重複チェックに合格することを求めます。その後、リスクスコアと時間的な網羅性に基づいて少数のグループを選び、_vision_audit/audit_manifest.json とコンタクトシートを生成します。マルチモーダル層は削減のみを行い、基本層で見落とされた画像や、すでに破棄された画像を復元しません。安全に削除できる候補がない場合は、0グループを生成してもかまいません。references/vision-audit.md に従って同じグループの前後のフレームを確認し、_vision_review.json を出力します。デフォルトでは8グループ、固有画像24枚を超えてはいけません。拡大が必要な場合は、事前にコストとプライバシーへの影響をユーザーに説明してください。

各グループで判断する対象を1つだけにし、デフォルトで6グループ／18枚の小規模監査パッケージが必要な場合は、既存のweak設定を使用します。

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

weakでは、デフォルトで最大6グループ、固有画像18枚までです。各コンタクトシートには判断対象を示す赤枠が1つだけ表示され、A/B/Cの役割が明確に示されます。また、review_template.json と MODEL_INSTRUCTIONS.md が生成されます。グループごとに画像を確認し、テンプレートの該当箇所に記入してください。weakとbalancedが提案する削除または置換は、「信頼度が少なくとも0.90」＋「ローカルで承認されたカバー候補」＋「ローカルのリスクシグナル」＋「カバーフレームが最終的に残る」のすべてを満たす場合にのみ適用されます。カバーの連鎖、カバーの循環、その他の要件不足がある場合は、安全側に倒して保持します。

7. 重複排除の視覚監査を適用する

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レベルでは、1グループにつき判断対象1つの大きな画像
_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を使用します。モバイルアプリ、ウェブページ、チャットの画面録画に適しています。
• デフォルトで--temporal-selectを有効にします。以前の動作を再現する場合や、アルゴリズムを調査する場合にのみ--no-temporal-selectを使用してください。
• 高速なスクロールが続き、ページの見落としが心配な場合は、--motion-chunk-secondsを小さくします。それでも結果が多すぎる場合は、さらに値を大きくします。デフォルト値はスクロールの重複に応じて、自動的に0.8、1.25、または1.45を乗じます。
• OCRは任意の機能強化です。インストールされていない場合は明確に通知し、機能を縮小して動作させる必要があります。金額や本文を保護するため、純粋な視覚モードよりも少数のフレームを多く保持する場合があります。「フレーム数を減らすこと」だけを唯一の目標にしてはいけません。
• --keep-drop-candidatesは、基本層でのフレーム見落としを手動で調査する場合にのみ使用します。マルチモーダル監査と同等ではありません。マルチモーダルの本番経路では、これらの画像は復元されません。
• デフォルトでは、Skillのarchive/に_report.jsonとextraction_meta.jsonのみをアーカイブします（スクリーンショットや動画は複製せず、ディスク容量の重複消費を避けます）。一括回帰テストまたは一時検証では--no-archiveを使用してください。基本レポートや元の出力ディレクトリは変更されません。
• --profile weakを使用すると、各グループに判断対象が1つだけある、小規模な監査パッケージを生成できます。画像の予算を守り、削除を確認できない場合は保持を選択してください。

依存関係

システム依存関係

依存関係	インストール方法
ffmpeg ≥ 5.0	macOS: brew install ffmpeg 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。