video-minutes: 智能视频纪要生成器

Purpose

把一段视频转成一份可直接使用的结构化纪要：提取音轨、ASR 转录、按视频类型套用模板， 产出要点、时间线与行动项，并把行动项按 @tags 派发给对应 skill。技能的价值在于 分类正确、模板选对、行动项可追踪，而不是把语音原样抄成文字。

When to Use

• 用户给出视频/录屏/录音文件，或会议录像、网课、访谈、播客、直播回放，要求整理成笔记或纪要。
• 用户要"总结这个视频""提取字幕""视频转笔记""会议纪要""网课笔记"。
• 需要从视频里抽出待办事项、决议、负责人，并希望后续自动跟进。
• 触发词：视频纪要、视频总结、视频转文字、提取视频字幕、录屏整理、培训视频归档、 meeting minutes、video summary、transcribe video。

When NOT to Use

• 只想把语音转成文字、不需要总结或分类 -> 直接用 whisper，不必走本技能。
• 需要把视频翻译并配上配音/双语字幕 -> 交给 video-dubbing。
• 需要给视频生成封面或配图 -> 交给 image-design / mckinsey-cover。
• 视频无音轨、或音轨损坏到无法识别。
• 需要实时/流式转写（本技能是离线批处理，须先录制）。
• 时长超过 4 小时的视频，先分段再处理。

Workflow

1. 检测配置（阻塞）：按 scripts/config_manager.py 的优先级查找 ./.opencode/skills/video-minutes/config.yaml -> ~/.opencode/skills/video-minutes/config.yaml -> legacy ~/.video-minutes-config.json。命中则读取；命中 legacy 则迁移；全部未命中时 必须先完成首次设置向导并等待用户回答，否则不得继续。详见 references/config/first-time-setup.md。
2. 确定视频类型：用户指定了 --type 就用它；否则运行分类器，把检测到的类型和置信度 明确告知用户，再继续。
3. 执行处理：运行主入口脚本，传入视频路径与所需参数（见 ## Scripts）。
4. 读取并核对输出：从返回的 output_path 打开纪要，确认要点、时间线、行动项非空且 与字幕一致；缺项时回退到类型模板补齐，不要编造视频中不存在的内容。
5. 行动项分发：把提取到的行动项与 @tags 展示给用户，等确认后再派发；目标 skill 不可用时 降级为本地 TODO 清单（见 references/task-dispatch.md）。
6. 交付：用 present_files 展示生成的纪要文件，并附一句类型、时长与输出路径说明。

Decision Rules

视频类型路由（--type auto 时由分类器判定，模板位于 references/templates/）：

其余分流：

• 分类置信度低于阈值，或分类结果为空 -> 回退 note，并向用户说明可手动指定 --type。
• 只想要字幕、不要纪要 -> 加 --transcript-only，产出 <视频名>-transcript.txt。
• 精度不够/专有名词识别差 -> 提升 --model（如 small/medium/large）。
• 时长 > 4 小时或处理频繁超时 -> 加 --segment-duration 1800 分段。
• 不确定是否需要完整流水线 -> 短视频（<= 2h）可考虑多模态直接理解，见 references/background.md。
• 用户指定输出格式 -> --format markdown|obsidian|notion|lark，落盘细节见 references/output-formats.md。

Constraints

• 配置未就绪不得继续：未检测到配置文件时，首次设置是阻塞步骤，禁止跳过或臆造默认值。
• 不得编造内容：要点、时间戳、决议、行动项必须可追溯到 ASR 字幕；不确定就标注不确定。
• 不臆造分发目标：content-publisher/cron/gcal/calendar/image-gen/agent-swarm 等兄弟技能多数环境未安装，缺失时只输出本地 TODO，不得声称已派发。
• 分发前必须确认：除非 tag 命中 dispatch.auto_dispatch_tags（默认 @reminder） 或用户显式 --skip-confirm，否则先征求确认。
• 隐私：原始视频与字幕默认不出本机，除非用户明确要求上传或同步到 Notion/飞书。
• 模板路径由代码约定：模板固定放在 references/templates/<type>.md，不要散落到别处。

Priority

1. 首次设置阻塞 > 一切处理动作：配置未就绪时，任何转写请求都先被向导拦住。
2. 类型准确性 > 处理速度：分类不确定时宁可问用户或降级到 note，不要套错模板。
3. 用户确认 > 自动分发：确认机制永远优先于自动派发，除非标签在自动白名单内。
4. 内容忠实 > 输出完整度：宁可缺项并标注，也不要补写视频里没有的内容。

Verification

交付前逐项确认：

• 配置已加载，或首次设置向导已完成（未命中配置时）。
• 视频类型与置信度已向用户说明，或已按 --type 显式指定。
• output_path 存在且可打开；类型、时长与文件名一致。
• 行动项已展示，分发前已获得确认（或命中自动白名单）。
• 未安装的兄弟技能没有被谎报为"已分发"，降级路径为本地 TODO。
• 长视频未一次性硬跑，已按需分段。

Output

• Outcome：一份结构化 Markdown 纪要（默认落到 output.directory，默认 ~/Documents/video-minutes），含摘要、要点、时间线、行动项与可选折叠字幕。
• Done when：纪要文件已生成并可读、类型判定有依据、行动项已展示、分发（如需）已确认。
• Evidence：output_path 实际存在；内容可回溯到 ASR 字幕；文首记录类型与置信度； 未分发项以本地 TODO 形式列出。

References

按需加载，不要预先全读：

• references/video-types.md — 需要理解或调整分类结果、查看分类维度与时长区间时读。
• references/task-dispatch.md — 要把行动项派发出去、或判断某数据源是否被支持时读。
• references/output-formats.md — 用户切换 Markdown/Obsidian/Notion/飞书，或要确认落盘路径与命名时读。
• references/transcription-engine.md — 需要换模型、调精度、排转录失败、装依赖时读。
• references/background.md — 用户问版本差异、能力边界，或要评估是否值得走完整流水线时读。
• references/config/config-schema.md — 要逐项修改 config.yaml、确认字段默认值时读。
• references/config/first-time-setup.md — 命中"未检测到配置"分支、需要执行设置向导时读。
• references/templates/meeting.md、references/templates/lecture.md、references/templates/interview.md、references/templates/presentation.md、references/templates/podcast.md、references/templates/tutorial.md、references/templates/note.md — 生成对应类型纪要时由脚本按 video_type 取用；仅在查看或修改某类型版式时人工打开。

Scripts

• <skill>/scripts/generate_minutes.py — 主入口。用法 python3 <skill>/scripts/generate_minutes.py <视频路径> [--type T] [--language zh] [--model medium] [--format obsidian] [--transcript-only] [--batch] [--segment-duration 1800] [-o 输出] [--no-dispatch|--skip-confirm] [-v]； 返回处理结果字典，含 output_path、transcript、action_items。
• <skill>/scripts/video_processor.py — 被主入口调用的流水线协调器（抽音轨 -> 转录 -> 分类 -> 套模板 -> 存盘 -> 提行动项）；一般不由人直接运行。
• <skill>/scripts/insanely_fast_transcriber.py — faster-whisper 封装； python3 <skill>/scripts/insanely_fast_transcriber.py <音频文件> 可独立转录并打印结果。
• <skill>/scripts/classifier.py — 启发式类型分类器，返回 {type, confidence, reasoning, scores}。
• <skill>/scripts/config_manager.py — 配置加载/保存/校验与录制目录探测；被主入口自动调用。
• <skill>/scripts/dispatcher.py — 行动项解析与 @tag 分发；dispatch_batch() 批量派发， 未实现的目标返回 success: false。

Troubleshooting

• 模型下载失败 -> 设 HF_ENDPOINT=https://hf-mirror.com 后重试。
• 视频无音频 -> 用 ffprobe 检查音轨；确认 ffmpeg 已安装。
• 分类不准 -> 手动 --type，或调整 classification.confidence_threshold。
• 处理超时 -> --segment-duration 1800。
• 更多失败模式与参数细节见 references/transcription-engine.md。

Related Skills

• video-dubbing — 视频翻译 + 配音 + 双语字幕，本技能不做配音。
• transcribe — 纯转录、无总结；只需文字时优先它。
• mlx-tts — 本机 TTS，可为纪要生成语音摘要。
• content-publisher / cron / gcal / agent-swarm — 可选分发目标，缺失时降级为本地 TODO。