长视频大纲整理 Skill
概述
把你本地已有的视频或音频文件，自动转写成文字，再由助手提炼为结构化的 Markdown 大纲。适用于：学习长课程 / 讲座、把播客 / 会议录音变成笔记、快速掌握一段长视频的要点。
核心特征
- 输入：本地视频（mp4 / mkv / mov / webm / avi / m4v …）或音频（mp3 / wav / m4a / flac …）文件
- 输出：一份 Markdown 大纲文件（.md）
- 时长：无上限，长视频按段处理
- 不联网下载任何平台内容——视频 / 音频由你事先提供
标准工作流
用户给出本地文件路径后，按以下步骤：
0. 透明告知（必须）：开始前先告诉用户——"首次使用会在你电脑上自动下载所需文件（约几百 MB～1GB，一次性，之后离线可用），请稍候，会显示进度。"不要让用户以为解压即用。
1. 依赖引导（首次运行，助手自动完成，用户无需手动安装 Python）
本技能首次运行需要两样东西，由助手在 WorkBuddy 自带 Python 环境内自动准备，不污染用户系统 Python：
- Python 包：faster-whisper + imageio-ffmpeg（一次性下载，约 300–600MB）
- 语音识别模型：首次使用某一档时下载一次（tiny≈75MB / base≈145MB / small≈500MB），之后本地缓存、离线可用
助手按此准备：
1. 定位 WorkBuddy 自带 Python：优先 $HOME/.workbuddy/binaries/python/envs/default/bin/python3；
若该 venv 不存在，则在 $HOME/.workbuddy/binaries/python/versions/ 下找任一 managed python，
用 python3 -m venv $HOME/.workbuddy/binaries/python/envs/default 创建后使用。
2. 在该 Python 中执行 pip install -r <技能目录>/requirements.txt（已装则跳过）。
3. 用这个 Python 运行转写脚本。
- 转写：运行技能内的转写脚本，把音轨转成带时间戳的逐字稿（中间产物）。
bash PY=$HOME/.workbuddy/binaries/python/envs/default/bin/python3 # 上面准备好的 WorkBuddy 自带 Python SK=<技能目录>/scripts/transcribe.py $PY $SK "<本地视频或音频路径>" "<输出逐字稿.md>" base --lang zh
- 模型可选：tiny(最快最小) /base(默认) /small(更准)，仅这三档
- 不指定--lang时自动检测语言
- 长任务会显示进度条 + 预计剩余时间，无需干等 - 提炼大纲：助手读取逐字稿，严格按下方「大纲质量框架（强制）」二次提炼，生成 Markdown 大纲，写入
.md文件。
- 逐字稿本身是中间产物，不是交付物；交付物是提炼后的大纲。
- 回读校验（交付前必做）：提炼完后，逐段回读带时间戳的逐字稿，确认每段核心已被大纲覆盖，遗漏当场补。
- 机械兜底：跑scripts/outline_coverage_check.py <逐字稿.md> <大纲.md（退出码 1 = 有遗漏，须补后再 present）。该脚本已做繁→简归一化，解决 Whisper 中文常出繁体导致误报的问题。 - 交付：用
present_files展示大纲，并询问是否保留逐字稿 / 源文件。
大纲格式
# [来源/标题] - 内容大纲
> **基本信息**
> - 类型：视频 / 音频
> - 时长：X 分钟
> - 转写模型：base
> - 转写耗时：X 分 X 秒
---
## 一句话概要
（用一两句话概括这段内容在讲什么）
## 核心内容（按章节 / 时间线）
### [00:00] 章节一标题
- 要点 1
- 要点 2
### [05:30] 章节二标题
- 要点 1
## 值得回看的亮点
| 时间段 | 亮点 |
## 小结
（这段内容适合谁看、核心价值是什么）
⚠️ 大纲质量框架（强制，所有实例一致）
> 大纲由助手（LLM）从逐字稿二次提炼。自由发挥会导致"换台机器 / 换次对话就不同、还漏要点"。
> 下面这套框架是强制结构，任何实例都须按同一套提取，禁止自由减项。
1. 强制覆盖维度（缺一不可）：
- 基本信息：类型、时长、转写模型、转写耗时
- 一句话概要：用一句大白话说清内容讲了什么
- 按时间顺序的章节核心论点：每章 ≥1 个核心要点，章节顺序与原文一致，带时间段锚点
- 关键数据 / 人名 / 术语 / 结论：原文出现的具体数字、专有名词、明确结论，逐条列出
- 行动项 / 建议 / 待办：给观众的具体做法或建议
- 遗留疑问 / 未解答点：没说清或矛盾的地方
- 亮点 / 金句：值得回看的高价值片段
- 小结 / 推荐程度：适合谁看、核心价值
2. 覆盖完整性铁律：
- 大纲须覆盖逐字稿全部时间段；任一含实质内容的连续段落，须在大纲有对应要点。
- 禁止只挑"感兴趣的"写——平淡但属主干的内容也要覆盖（可简写，不可漏）。
- 时间戳是锚点：章节要点须带原视频时间段，便于回看定位。
3. 回读校验（交付前强制，不可跳过）：
- 提炼完大纲后，助手须逐段回读带时间戳逐字稿，逐段确认"这一段的核心是否已被大纲覆盖"。
- 发现遗漏 → 当场补写到大纲对应章节，再进入呈现。
- 机械兜底：跑 scripts/outline_coverage_check.py <逐字稿.md> <大纲.md（退出码 1 = 有遗漏，须补）。该脚本是兜底、不替代人工回读。
> 以上三点写入技能即对所有实例生效；标准工作流第 3 步已强制引用。
依赖（首次由助手自动安装，用户无需手动处理）
faster-whisper（语音识别，本地模型，离线可用）imageio-ffmpeg（自带 ffmpeg，无需单独安装）
安装与启用见 README.md。
适用场景与边界
- ✅ 你自己录制的视频 / 音频
- ✅ 你已获得授权或平台明确允许下载的内容
- ✅ 开放授权内容（CC / 公有领域）
- ⚠️ 请仅用于处理你有权处理的内容；本工具不抓取任何网络平台的受保护内容。
常见问题
- 转写为空：可能是纯音乐、无人声，或音频抽取失败。
- 中文有错字：
tiny约 70%、base约 85%、small约 92%；重要内容建议用small。 - 首次转写慢 / 需下载模型：首次会用 hf-mirror 镜像下载模型（国内可访问），之后走本地缓存，离线可用。
- 长视频耗时：与音频时长成正比，CPU 上
base约为实时速度的若干倍；越长越慢但无上限。
