视频转写为 TXT
将完整下载的本地视频转写为带逐段起止时间的纯文本文件。单视频生成一个 .txt；多视频时每个视频独立生成一个 .txt，并在全部完成后汇总总视频时长与实际处理总耗时。
输入与输出
- 输入：一个或多个本地视频文件的绝对路径。
- 默认输出：每个视频同目录下的
<视频文件名>_整理版.txt。 - 每段格式：
［HH:MM:SS.mmm - HH:MM:SS.mmm］文本 - 输出已存在时默认停止；只有用户明确允许覆盖后才传
--force。 - 多视频完成后不生成额外汇总文件；只在回复中汇报汇总结果。
硬性规则
- 不删除、不移动、不修改源视频。
- 拒绝处理
.downloading、.part、.partial等未完成下载文件。 - 每个视频最终只保留一个 TXT；不得在视频目录生成或保留 WAV、JSON、SRT、VTT、TSV、原始 ASR TXT。
- 所有 Whisper 中间输出必须进入系统临时目录，成功或失败都要清理。
- 不编造说话人，不根据猜测强行修改人名、数字、剂量或专业术语。
- 用户未指定语言时默认中文
zh；用户明确指定时使用其语言。 - 运行前检查
uv、ffmpeg、ffprobe是否可用。 - 多视频并行必须限流；默认最多同时处理 2 个视频，资源充足且视频较短时最多 3 个。
单视频执行
uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
"/absolute/path/to/video.mp4"
指定输出：
uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
"/absolute/path/to/video.mp4" \
--output "/absolute/path/to/result.txt"
用户已明确允许覆盖时：
uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
"/absolute/path/to/video.mp4" \
--force
可选参数：
--model：Whisper 模型，默认small。--language：语言代码，默认zh。--model-dir：模型缓存目录，默认~/.cache/whisper。--force：覆盖已存在的最终 TXT，仅在用户明确允许时使用。
单视频工作流
- 校验输入文件、输出后缀和依赖工具。
- 使用
ffprobe获取视频时长。 - 创建系统临时目录。
- 用
uv run --with openai-whisper whisper转写，所有格式输出到临时目录。 - 读取临时 JSON 中的
segments。 - 将有效分段按时间顺序写成唯一最终 TXT。
- 原子替换最终输出并清理临时目录。
- 汇报最终 TXT 绝对路径、有效段落数量、视频时长、单视频处理耗时。
- 读取终端中的
SUMMARY_JSON:行作为机器可读摘要。
多视频并行工作流
当用户提供多个视频时，由主 agent 统筹，多名子 agent 分批处理：
- 主 agent 解析并列出全部视频绝对路径。
- 主 agent 先做批量预检查：路径存在、普通文件、未命中未完成下载后缀、默认输出路径不冲突、输出不存在或已获覆盖授权。
- 如果输出已存在且用户未授权覆盖，先询问用户选择：跳过已有输出、允许覆盖、或停止批处理。
- 记录批处理开始时间。
- 按并发上限分批派发子 agent：每个子 agent 只处理一个视频，只调用单视频脚本。
- 环境不支持子 agent 或并行时，降级为串行处理；仍执行同样的汇总。
- 单个视频失败不阻塞其他视频；失败原因进入最终汇总。
- 所有视频完成后记录结束时间，计算实际处理总耗时。
- 汇总成功数、失败数、每个 TXT 路径、每个视频时长、每个单视频处理耗时、总视频时长和实际处理总耗时。
子 agent 回传字段
每个子 agent 完成后必须回传：
- 源视频绝对路径。
- 输出 TXT 绝对路径。
status：success或error。- 失败原因；成功时为空。
- 视频时长秒数。
- 有效段落数。
- 单视频实际处理耗时秒数。
- 使用的模型和语言。
优先从脚本输出的 SUMMARY_JSON: 解析这些字段；解析失败时再从中文输出中提取，并说明摘要解析失败。
总时长汇报规范
用户说“总时长”但未明确含义时，默认同时汇报两类时长：
- 总视频时长：所有成功处理视频的媒体时长之和，来自
ffprobe。 - 实际处理总耗时：从主 agent 开始派发第一批任务到所有任务结束的墙钟时间。
多视频并行时，实际处理总耗时通常小于各单视频处理耗时之和；最终回复必须说明这一点。
汇总模板：
处理完成。
成功：3 个
失败：1 个
成功文件：
1. /path/a_整理版.txt
视频时长：00:10:12.350
处理耗时：00:03:05.120
段落数：96
失败文件：
1. /path/c.mp4
原因：输出已存在，未获覆盖授权
汇总：
总视频时长：00:40:00.330
实际处理总耗时：00:06:28.500
说明：因为多个视频并行处理，实际处理总耗时不是各单视频处理耗时的简单相加。
停机条件
出现以下情况时停止对应视频，不生成误导性结果：
- 输入不存在或不是普通文件。
- 输入是未完成下载文件。
- 输出不是
.txt。 - 输出已存在且未明确允许覆盖。
uv、ffmpeg或ffprobe不可用。- Whisper 失败、JSON 缺失或没有有效文本段。
依赖缺失通常影响全部视频，应停止整批处理并提示用户修复环境。单个输入或单个转写失败只停止该视频，其余视频继续。
反例黑名单
不要做以下事情：
- 不要把多个视频路径一次性传给单视频脚本。
- 不要无限制启动 agent；默认并发 2，最多 3。
- 不要在未获明确授权时传
--force。 - 不要在视频目录留下 Whisper 中间文件或批量汇总 JSON/TXT。
- 不要把失败视频计入“成功处理的总视频时长”，除非回复中明确单独说明。
- 不要根据上下文猜测说话人、人名、数字、剂量或专业术语。
- 不要把“实际处理总耗时”说成“总视频时长”；两者必须分开标注。
