TG Video Check

针对 Telegram 导出场景的视频损坏检测 CLI，优先识别被中断下载导致的半截视频文件。

当前能力

• 递归扫描一个或多个目录中的常见视频扩展名
• 使用 SQLite 落盘扫描状态，并基于 path + size + mtime 复用旧结果
• stage1 使用 ffprobe 做容器级快速校验
• stage2 只对可疑文件使用 ffmpeg 做定向采样或完整确认
• 输出 JSONL / CSV 报告

基本用法

uv run tgvideo-check scan D:\Exports\ChatA D:\Exports\ChatB --profile tg-hdd

常用参数：

• --db：指定 SQLite 状态库
• --paths-file：从 txt 文件读取目录列表，一行一个目录
• --export-jsonl / --export-csv：导出结果报告
• --stage1-workers / --stage2-workers：覆盖 profile 默认 worker 数
• --queue-limit：限制单阶段批次大小，避免把待处理文件一次性堆进内存
• --full-decode-confirm：对 stage2 强制使用完整解码确认

--paths-file 规则：

• 按 UTF-8 / UTF-8 BOM 读取
• 一行一个目录
• 空行自动跳过
• 行内空格、中文、方括号、感叹号等字符按字面值保留
• 如果整行外面包了一层单引号或双引号，会自动去掉外层引号

删除已确认损坏文件

先预览：

tgvideo-check prune --db .\scan_state.db

默认行为：

• 默认 --dry-run
• 默认只处理 confirmed_broken
• 输出匹配数量、删除数量、总字节数、原因统计

确认后执行真实删除：

tgvideo-check prune --db .\scan_state.db --no-dry-run

如果后续你明确要扩大删除范围，可以传：

tgvideo-check prune --db .\scan_state.db --delete-status confirmed_broken,suspicious

但这不是默认推荐，因为 suspicious 仍然代表边界文件，不应默认直接删。

性能 Smoke

仓库内提供了 tests/test_perf_smoke.py，默认跳过，不把环境波动硬编码成普通单测。

手动运行方式：

$env:TGVIDEO_RUN_PERF_SMOKE='1'
uv run pytest tests/test_perf_smoke.py -q

这个 smoke 目前只做两件事：

• 生成一批最小测试视频
• 分别跑 stage1_workers=1 和 stage1_workers=2，确认基线采集流程可执行

它不是严格 benchmark；真正的默认参数取舍，仍应基于真实 HDD 数据集人工复核。