video-minutes git:20260925.32ce6c0A

Immutable. This exact content never changes and is served at /api/v1/blob/c745175589c3bfb7.

---
name: video-minutes
description: "智能视频纪要生成器：从视频音频生成结构化纪要 —— 提取语音、生成字幕、自动分类（会议/课程/访谈/演讲/播客/教程/备忘），输出核心要点、行动项与 @tags 任务分发，支持 Markdown/Obsidian/Notion/飞书。支持本地视频 (.mp4/.mov/.mkv/.avi)、Zoom/腾讯会议录制、YouTube/B站链接。触发词：处理视频、生成视频纪要、视频纪要、视频转文字、视频总结、提取视频字幕、视频转笔记、总结这个视频、会议录像整理、网课笔记、视频内容提取、录屏整理、直播回放分析、培训视频归档。Do NOT use when：仅需视频转文字无总结（直接用 whisper）、视频无音频轨道或音频质量极差、需要实时视频流处理（须先录制）、视频时长超过 4 小时（建议先分段）。"
---

# 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/`）：

| 类型 | 识别特征 | 输出重点 | 模板 |
|------|----------|----------|------|
| `meeting` | 多人、任务分配、决策 | 决议 + 行动项负责人 + 时间节点 | `meeting.md` |
| `lecture` | 单/双主讲、知识点密集 | 知识图谱 + 章节 + 重点摘录 | `lecture.md` |
| `interview` | 问答、双方观点 | Q&A 整理 + 观点对比 | `interview.md` |
| `presentation` | PPT、数据展示 | 金字塔论点 + 关键数据 | `presentation.md` |
| `podcast` | 轻松对话、话题跳跃 | 话题索引 + 金句 + 高光片段 | `podcast.md` |
| `tutorial` | 步骤演示、屏幕录制 | 步骤清单 + 截图提示 + 踩坑点 | `tutorial.md` |
| `note` | 自言自语、碎片想法 | 格式化文本 + 标签 + 待办 | `note.md` |

其余分流：

- 分类置信度低于阈值，或分类结果为空 -> 回退 `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。