video-minutes · diff
git:20260830.ad65525 to git:20260925.32ce6c0
113 added, 690 removed. Audit A to A.
---
name: video-minutes
- description: |
- 智能视频纪要生成器 - 自动提取视频语音、生成字幕、智能分类总结，输出结构化纪要文档
-
- **MUST use this skill when user mentions:**
- - 处理视频、生成视频纪要、视频转文字、视频总结
- - 会议录像整理、网课笔记、视频内容提取
- - "帮我总结这个视频"、"提取视频字幕"、"视频转笔记"
- - 录屏整理、直播回放分析、培训视频归档
-
- **支持的视频类型 (auto-detected):**
- - meeting: 会议录像 → 待办事项 + 决议 + 负责人
- - lecture: 课程/讲座 → 知识点图谱 + 时间戳
- - interview: 访谈/采访 → Q&A 整理 + 观点对比
- - presentation: 演讲/汇报 → 核心论点 + 数据可视化
- - podcast: 播客/对话 → 金句摘录 + 话题索引
- - tutorial: 教程/演示 → 步骤清单 + 关键截图提示
-
- **支持的数据源:**
- - 本地视频文件 (.mp4/.mov/.mkv/.avi)
- - Zoom 录制自动扫描
- - 腾讯会议/钉钉录制
- - YouTube/B站链接 (yt-dlp)
- - 网盘分享链接 (阿里云盘/百度网盘)
-
- **Do NOT use when:**
- - 仅需视频转文字无总结需求 (直接用 whisper)
- - 视频无音频轨道或音频质量极差
- - 实时视频流处理 (需先录制)
- - 视频时长超过 4 小时 (建议分段处理)
-
- **触发关键词:** video, 视频, 纪要, 字幕, 总结, meeting, 会议, 课程
- ---
-
- # Video Minutes Skill
-
- 智能视频纪要生成器，支持多类型视频自动分类、智能总结、任务分发。
-
- ## 核心特性
-
- - 🤖 **AI 自动分类**: 自动识别视频类型（会议/课程/访谈等），应用对应模板
- - 📝 **智能总结**: 提取核心要点、行动项、关键决策
- - 🏷️ **任务分发**: 通过 @tags 将待办分发给其他 skill 执行
- - 🔗 **多源支持**: 本地文件、Zoom/腾讯会议录制、在线视频链接
- - 🌐 **多语言**: 自动检测语言，支持中英日等 99+ 语言
- - 📊 **多种输出**: Markdown/Obsidian/Notion/飞书文档
-
- ---
-
- ## 首次设置 (First-Time Setup)
-
- **配置优先级检测**:
-
- ```bash
- # 检测配置文件存在性
- test -f "video-minutes/config.yaml" && echo "project"
- test -f "$HOME/.ai-agent/skills/video-minutes/config.yaml" && echo "user"
- test -f "$HOME/.video-minutes-config.json" && echo "legacy"
- ```
-
- | 结果 | 操作 |
- |------|------|
- | 找到 YAML | 读取并应用 |
- | 找到 legacy JSON | 迁移到 YAML 格式 |
- | 未找到 | **执行首次设置向导** (阻塞操作) |
-
- ### 首次设置向导 (BLOCKING)
-
- **⚠️ CRITICAL**: 未检测到配置文件时，**必须**先完成设置向导，**阻塞**后续所有视频处理操作。
-
- 使用 `AskUserQuestion` 一次性呈现所有问题，等待用户回答后再继续。
-
- ---
-
- **🎬 Video Minutes 配置向导**
-
- ```
- 让我为您配置视频纪要生成的默认偏好：
-
- **1. 默认输出语言**
- 视频语音通常为哪种语言？
- - 🌐 自动检测 (推荐)
- - 🇨🇳 中文
- - 🇺🇸 英文
- - 🇯🇵 日文
- - 其他: __________
-
- **2. Whisper 模型选择**
- 语音转文字精度 vs 速度偏好？
- - ⚡ Tiny (最快，适合快速预览)
- - 🚀 Base (推荐，平衡速度质量)
- - 🎯 Small (更精准，慢 2x)
- - 🏆 Medium (高精度，慢 4x)
- - 💎 Large (最佳质量，慢 8x，需 GPU)
-
- **3. 输出格式偏好**
- 纪要文档保存为哪种格式？
- - 📝 Markdown (推荐，通用)
- - 📔 Obsidian (带双链和标签)
- - 📊 Notion (自动同步到数据库)
- - 🚀 飞书文档 ( Lark )
-
- **4. 输出内容选项**
- 纪要包含哪些内容？(多选)
- - ✅ 内容摘要 (一句话总结)
- - ✅ 核心要点 (分点列出)
- - ✅ 详细时间线 (带时间戳)
- - ✅ 行动项追踪 (TODO 列表)
- - ✅ 完整字幕 (可选折叠)
- - ✅ 发言人识别 (如果可区分)
-
- **5. 自动扫描路径** (可选)
- 自动监控哪些目录的新视频？
- - 📹 Zoom 录制文件夹
- - 📹 腾讯会议录制
- - 📹 钉钉会议录制
- - 📂 自定义路径: __________
-
- **6. 任务分发集成**
- 检测到行动项时如何分发？
- - ❓ 先问我确认 (推荐)
- - 🤖 自动分发到对应 skill
- - 📋 仅汇总列出，不分发
-
- **7. 视频类型偏好**
- 您最常处理的视频类型？
- - 💼 会议录像 (提取 TODO)
- - 📚 课程讲座 (知识笔记)
- - 🎙️ 访谈播客 (Q&A 整理)
- - 🎤 演讲汇报 (观点提炼)
- - 🛠️ 教程演示 (步骤清单)
- ```
-
- **配置保存路径**: `~/.claude/skills/video-minutes/config.yaml`
-
- ```yaml
- # config.yaml 示例
- version: "1.1.0"
-
- output:
- language: auto # auto/zh/en/ja
- format: obsidian # markdown/obsidian/notion/lark
- directory: "~/Documents/video-minutes"
- filename_template: "{date}-{type}-{title}"
-
- content:
- include_summary: true
- include_key_points: true
- include_timeline: true
- include_action_items: true
- include_transcript: true
- transcript_collapsed: true # 默认折叠
- speaker_identification: true
- max_summary_points: 10
-
- whisper:
- model: base # tiny/base/small/medium/large/large-v1/large-v2/large-v3
- device: auto # auto/cpu/cuda/mps
- compute_type: int8 # int8/int8_float16/float16/float32
- language: null # null=auto
-
- classification:
- enabled: true
- confidence_threshold: 0.7
-
- dispatch:
- confirm_before_dispatch: true
- auto_dispatch_tags: ["@reminder"] # 自动分发的标签
-
- scanning:
- enabled: true
- interval_minutes: 60
- paths:
- - "~/Documents/Zoom"
- - "~/Documents/腾讯会议"
-
- integrations:
- obsidian_vault: "~/Obsidian/VideoNotes"
- notion_database_id: null
- lark_webhook: null
- ```
-
- ---
-
- ## 使用方法
-
- ### 命令行用法
-
- ```bash
- # 基本用法
- python video-minutes/generate_minutes.py <视频路径>
-
- # 指定类型 (跳过自动分类)
- python video-minutes/generate_minutes.py meeting.mp4 --type meeting
-
- # 指定输出
- python video-minutes/generate_minutes.py lecture.mp4 -o ~/Notes/课程.md
-
- # 指定语言
- python video-minutes/generate_minutes.py interview.mp4 --language zh
-
- # 使用更高精度模型
- python video-minutes/generate_minutes.py presentation.mp4 --model medium
-
- # 仅提取字幕不生成纪要
- python video-minutes/generate_minutes.py video.mp4 --transcript-only
-
- # 批量处理目录
- python video-minutes/generate_minutes.py ~/Recordings/ --batch
- ```
-
- ### 自动扫描
-
- ```bash
- # 扫描配置路径中的新视频
- python video-minutes/scripts/scan-and-process.py
-
- # 扫描指定目录
- python video-minutes/scripts/scan-and-process.py ~/Downloads --since-hours 24
-
- # 查看待处理队列
- python video-minutes/scripts/queue.py --list
-
- # 查看处理统计
- python video-minutes/scripts/queue.py --stats
- ```
-
- ---
-
- ## 视频类型分类系统
-
- ### 自动分类逻辑
-
- ```
- 视频文件
- ↓
- 音频指纹分析 + 内容采样
- ↓
- 分类模型 (Gemini/本地模型)
- ↓
- 类型判断 + 置信度评分
- ↓
- 选择对应模板生成纪要
- ```
-
- ### 分类维度
-
- | 维度 | 检测指标 | 影响 |
- |------|----------|------|
- | **说话人数量** | 单/双/多人 | note/podcast vs meeting/interview |
- | **对话模式** | 独白/问答/讨论 | lecture vs interview vs meeting |
- | **内容特征** | 任务/知识点/观点 | 提取 TODO vs 知识图谱 vs 金句 |
- | **视觉线索** | PPT/白板/屏幕分享 | presentation vs tutorial |
- | **时长** | <15min/15-60min/>60min | 详略程度 |
-
- ### 7 种视频类型
-
- #### 1. Meeting (会议录像)
- **特征**: 多人参与、任务分配、决策讨论
- **输出重点**:
- - 参会人员列表
- - 核心决议清单
- - 行动项追踪表（含负责人、截止日期）
- - 待跟进事项
-
- **模板**: `templates/meeting.md`
-
- ```markdown
- # 会议纪要: {{title}}
-
- ## 📋 会议信息
- - **日期**: {{date}}
- - **时长**: {{duration}}
- - **参会人**: {{participants}}
- - **视频**: {{video_path}}
-
- ## 🎯 核心决议
- {{decisions}}
-
- ## ✅ 行动项
- | 任务 | 负责人 | 截止日期 | 优先级 |
- |------|--------|----------|--------|
- {{action_items}}
-
- ## 📍 关键时间节点
- {{timeline}}
-
- ## 💬 重要讨论摘要
- {{discussion_summary}}
-
- ---
- {{#if include_transcript}}
- <details>
- <summary>📝 完整字幕 (点击展开)</summary>
-
- {{transcript}}
- </details>
- {{/if}}
- ```
-
- #### 2. Lecture (课程/讲座)
- **特征**: 单/双主讲人、结构化内容、知识点密集
- **输出重点**:
- - 课程大纲/目录
- - 核心概念图谱
- - 重点摘录（带时间戳）
- - 延伸阅读建议
-
- **模板**: `templates/lecture.md`
-
- ```markdown
- # 📚 课程笔记: {{title}}
-
- ## 📖 课程信息
- - **讲师**: {{speaker}}
- - **时长**: {{duration}}
- - **主题**: {{topics}}
-
- ## 🗺️ 知识图谱
- ```mermaid
- {{knowledge_graph}}
- ```
-
- ## ⏱️ 章节速览
- {{chapters}}
-
- ## 📝 核心概念
- {{key_concepts}}
-
- ## 💡 重点摘录
- {{key_quotes}}
-
- ## ❓ 疑问与思考
- {{questions}}
-
- ## 🔗 延伸阅读
- {{references}}
- ```
-
- #### 3. Interview (访谈/采访)
- **特征**: 问答形式、双方观点、深入探讨
- **输出重点**:
- - Q&A 结构化整理
- - 双方核心观点对比
- - 金句摘录
- - 话题索引
-
- **模板**: `templates/interview.md`
-
- #### 4. Presentation (演讲/汇报)
- **特征**: PPT 辅助、数据展示、观点阐述
- **输出重点**:
- - 核心论点（金字塔结构）
- - 关键数据/图表描述
- - 结论与建议
- - 演讲技巧点评（可选）
-
- **模板**: `templates/presentation.md`
-
- #### 5. Podcast (播客/对话)
- **特征**: 轻松对话、话题跳跃、金句频出
- **输出重点**:
- - 话题时间索引
- - 金句摘录
- - 推荐片段（高光时刻）
- - 相关资源链接
-
- **模板**: `templates/podcast.md`
-
- #### 6. Tutorial (教程/演示)
- **特征**: 步骤演示、操作指导、屏幕录制
- **输出重点**:
- - 步骤清单（可勾选）
- - 关键截图提示
- - 常见问题/踩坑点
- - 快捷键/命令汇总
-
- **模板**: `templates/tutorial.md`
-
- #### 7. Note (个人录屏/语音备忘)
- **特征**: 自言自语、快速记录、想法片段
- **输出重点**:
- - 清理格式化文本
- - 想法归类标签
- - 待办提取
- - 关联笔记链接
-
- **模板**: `templates/note.md`
-
- ---
-
- ## 任务分发系统 (@tags)
-
- > **分发为可选能力**：下方 @tags 对应的 `content-publisher` / `cron` / `gcal` / `calendar` / `image-gen` / `agent-swarm` / `transcribe` 等兄弟技能在多数环境未安装。当目标技能不可用时，AI 仅将行动项整理为**本地 TODO 清单（Markdown）**，不强制分发；仅当对应技能确实可用时才尝试派发。
-
- ### 提取标签规则
-
- AI 从视频中提取行动项时，自动识别并添加 @tags:
-
- | Tag | 触发条件 | 分发给 |
- |-----|----------|--------|
- | `@user` | 指派给具体人员 | 用户通知 |
- | `@assistant` | 需要 AI 执行 | 内置工具 |
- | `@dev` | 代码相关任务 | 开发助手 |
- | `@design` | 设计/前端任务 | 设计助手 |
- | `@article` | 需要写文章 | content-publisher |
- | `@reminder` | 需要提醒 | cron/gcal |
- | `@research` | 需要调研 | web_search |
- | `@design` | 需要设计稿 | image-gen |
- | `@meeting` | 需要安排会议 | calendar |
- | `@review` | 需要审核 | 通知相关人员 |
-
- ### 确认机制流程
-
- ```
- 视频处理完成
- ↓
- 提取行动项 + 自动标记 @tags
- ↓
- 向用户展示提取结果
- ↓
- 用户确认/修改/取消
- ↓
- 分发到对应 skill 执行
- ↓
- 更新任务追踪状态
- ```
-
- ### 示例交互
-
- **AI**: 已从会议视频中提取以下行动项：
-
- ```markdown
- ### @dev
- - [ ] 实现用户认证模块的 JWT 刷新机制 (deadline: 周五)
- - [ ] 优化数据库查询性能，目标 QPS > 1000
-
- ### @article
- - [ ] 撰写"微服务架构实践"技术博客 (deadline: 下周四)
-
- ### @reminder
- - [ ] cron: 0 10 * * 1 周报提醒
- - [ ] 2026-04-01 跟进 Q2 OKR 进度
-
- ### @meeting
- - [ ] 安排下周与产品团队的评审会
- ```
-
- **用户**: 第1项改成 @张三，第2项优先级降低
-
- **AI**: ✅ 已更新，确认分发吗？
-
- **用户**: 确认
-
- **AI**: 🚀 正在分发任务...
- - ✅ @Codex 任务已发送至 agent-swarm
- - ✅ @article 草稿已创建在 ~/Drafts/
- - ✅ @reminder 已添加到 cron
- - ✅ @meeting 会议邀请已发送到日历
-
- ---
-
- ## 数据源集成
-
- ### 已支持
-
- | 来源 | 接入方式 | 自动扫描 |
- |------|----------|----------|
- | 本地视频文件 | 直接路径 | ❌ |
- | Zoom 录制 | `~/Documents/Zoom` | ✅ |
-
- ### 计划中
-
- | 来源 | 接入方式 | 状态 |
- |------|----------|------|
- | 腾讯会议 | `~/Documents/腾讯会议` | 🔜 |
- | 钉钉会议 | 自定义路径 | 🔜 |
- | YouTube | yt-dlp + URL | 🔜 |
- | Bilibili | yt-dlp + URL | 🔜 |
- | 阿里云盘 | 分享链接解析 | 🔜 |
- | 百度网盘 | 分享链接解析 | 🔜 |
- | Google Drive | API 集成 | 🔜 |
-
- ---
-
- ## 输出格式详情
-
- ### Markdown (默认)
-
- 标准 Markdown 格式，兼容所有编辑器。
-
- ### Obsidian
-
- ```markdown
- ---
- date: {{date}}
- type: {{video_type}}
- tags: [video-minutes, {{type_tag}}]
- source: {{video_path}}
- duration: {{duration}}
- ---
-
- # {{title}}
-
- ## 关联笔记
- - [[相关笔记1]]
- - [[相关笔记2]]
-
- ## 内容
- {{content}}
-
- ## 行动项
- - [ ] #task 任务1 @{{assignee}}
- ```
-
- ### Notion
-
- 自动创建数据库条目，包含：
- - 标题、日期、类型、时长
- - 内容块（Toggle 列表）
- - 行动项（Checkbox）
- - 嵌入视频链接
-
- ### 飞书文档
-
- 调用 Lark API 创建文档，支持：
- - 富文本格式
- - @提及用户
- - 插入任务清单
-
- ---
-
- ## 依赖安装
-
- ### 必需依赖
-
- ```bash
- # ffmpeg
- brew install ffmpeg # macOS
- sudo apt install ffmpeg # Ubuntu
- winget install Gyan.FFmpeg # Windows
-
- # Python 依赖
- pip install -r requirements.txt
- ```
-
- ### requirements.txt
-
- ```
- # 🚀 insanely-fast-whisper (高性能转录)
- faster-whisper>=1.0.0
-
- # 其他依赖
- ffmpeg-python>=0.2.0
- pyyaml>=6.0
- requests>=2.31.0
- notion-client>=2.2.1
- yt-dlp>=2023.12.30
- onnxruntime>=1.16.0
- torch>=2.0.0
- ```
-
+ description: "智能视频纪要生成器：从视频音频生成结构化纪要 —— 提取语音、生成字幕、自动分类（会议/课程/访谈/演讲/播客/教程/备忘），输出核心要点、行动项与 @tags 任务分发，支持 Markdown/Obsidian/Notion/飞书。支持本地视频 (.mp4/.mov/.mkv/.avi)、Zoom/腾讯会议录制、YouTube/B站链接。触发词：处理视频、生成视频纪要、视频纪要、视频转文字、视频总结、提取视频字幕、视频转笔记、总结这个视频、会议录像整理、网课笔记、视频内容提取、录屏整理、直播回放分析、培训视频归档。Do NOT use when：仅需视频转文字无总结（直接用 whisper）、视频无音频轨道或音频质量极差、需要实时视频流处理（须先录制）、视频时长超过 4 小时（建议先分段）。"
---
- ## 性能优化
-
- ### insanely-fast-whisper 优势
-
- 基于 [faster-whisper](https://github.com/SYSTRAN/faster-whisper)，比原始 Whisper **快 2-4 倍**：
-
- | 特性 | openai-whisper | faster-whisper |
- |------|----------------|----------------|
- | **速度** | 1x (基准) | 2-4x ⚡ |
- | **内存** | 较高 | 降低 50% 💾 |
- | **精度** | 标准 | 相同 ✓ |
- | **量化** | float32 | int8/int16 🔧 |
- | **VAD** | 无 | 内置 🎙️ |
-
- ### 模型选择建议
-
- | 模型 | 显存需求 | 适合场景 |
- |------|----------|----------|
- | `tiny` | ~1GB | 快速预览、实时测试 |
- | `base` | ~1GB | **推荐**，平衡速度质量 |
- | `small` | ~2GB | 更精准，慢 2x |
- | `medium` | ~5GB | 高精度，慢 4x |
- | `large-v3` | ~10GB | 最佳质量，慢 8x |
-
- ### 设备与精度配置
-
- ```yaml
- whisper:
- device: auto # auto/cpu/cuda/mps
- compute_type: int8 # int8/int8_float16/float16/float32
- ```
+ # video-minutes: 智能视频纪要生成器
- - **int8**: 最快，内存占用最小，质量损失极小
- - **float16**: 更快，需要 GPU
- - **float32**: 标准精度
+ ## Purpose
- ---
+ 把一段视频转成一份可直接使用的结构化纪要：提取音轨、ASR 转录、按视频类型套用模板，
+ 产出要点、时间线与行动项，并把行动项按 `@tags` 派发给对应 skill。技能的价值在于
+ **分类正确、模板选对、行动项可追踪**，而不是把语音原样抄成文字。
- ## 目录结构 (更新)
+ ## When to Use
- ```
- video-minutes/
- ├── SKILL.md # 本文件
- ├── config.yaml # 默认配置模板
- ├── README.md # 快速开始指南
- ├── requirements.txt # Python 依赖 ⭐
- ├── scripts/
- │ ├── generate_minutes.py # 主入口 ⭐
- │ ├── insanely_fast_transcriber.py # 高性能转录器 ⭐ NEW
- │ ├── video_processor.py # 视频处理
- │ ├── classifier.py # 视频类型分类
- │ ├── config_manager.py # 配置管理
- │ └── dispatcher.py # 任务分发
- ├── templates/ # 类型特定模板
- │ ├── meeting.md
- │ ├── lecture.md
- │ ├── interview.md
- │ ├── presentation.md
- │ ├── podcast.md
- │ ├── tutorial.md
- │ └── note.md
- └── references/
- └── config/
- └── config-schema.md # 配置 schema
- ```
+ - 用户给出视频/录屏/录音文件，或会议录像、网课、访谈、播客、直播回放，要求整理成笔记或纪要。
+ - 用户要"总结这个视频""提取字幕""视频转笔记""会议纪要""网课笔记"。
+ - 需要从视频里抽出待办事项、决议、负责人，并希望后续自动跟进。
+ - 触发词：视频纪要、视频总结、视频转文字、提取视频字幕、录屏整理、培训视频归档、
+ meeting minutes、video summary、transcribe video。
- ---
+ ## When NOT to Use
- ## 配置参考
+ - 只想把语音转成文字、不需要总结或分类 -> 直接用 whisper，不必走本技能。
+ - 需要把视频翻译并配上配音/双语字幕 -> 交给 `video-dubbing`。
+ - 需要给视频生成封面或配图 -> 交给 `image-design` / `mckinsey-cover`。
+ - 视频无音轨、或音轨损坏到无法识别。
+ - 需要实时/流式转写（本技能是离线批处理，须先录制）。
+ - 时长超过 4 小时的视频，先分段再处理。
- ### 完整配置项
+ ## Workflow
- | 配置项 | 类型 | 默认值 | 说明 |
- |--------|------|--------|------|
- | `output.language` | string | "auto" | 输出语言 |
- | `output.format` | string | "markdown" | 输出格式 |
- | `output.directory` | string | "~/video-minutes" | 输出目录 |
- | `whisper.model` | string | "base" | 转录模型 |
- | `whisper.device` | string | "auto" | 计算设备 |
- | `classification.enabled` | bool | true | 启用分类 |
- | `dispatch.confirm_before_dispatch` | bool | true | 分发前确认 |
- | `scanning.enabled` | bool | true | 启用自动扫描 |
- | `scanning.interval_minutes` | int | 60 | 扫描间隔 |
+ 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` |
- **Q: Whisper 下载模型失败**
- A: 设置镜像 `export WHISPER_MIRROR=https://hf-mirror.com`
+ 其余分流：
- **Q: 视频无音频**
- A: 检查视频编码 `ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of default=noprint_wrappers=1 input.mp4`
+ - 分类置信度低于阈值，或分类结果为空 -> 回退 `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`。
- **Q: 分类不准确**
- A: 手动指定类型 `--type meeting` 或调整 `classification.confidence_threshold`
+ ## Constraints
- **Q: 处理超时**
- A: 长视频建议分段 `--segment-duration 1800` (30分钟一段)
+ - **配置未就绪不得继续**：未检测到配置文件时，首次设置是阻塞步骤，禁止跳过或臆造默认值。
+ - **不得编造内容**：要点、时间戳、决议、行动项必须可追溯到 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
- ## 相关 Skill
+ 1. 首次设置阻塞 > 一切处理动作：配置未就绪时，任何转写请求都先被向导拦住。
+ 2. 类型准确性 > 处理速度：分类不确定时宁可问用户或降级到 `note`，不要套错模板。
+ 3. 用户确认 > 自动分发：确认机制永远优先于自动派发，除非标签在自动白名单内。
+ 4. 内容忠实 > 输出完整度：宁可缺项并标注，也不要补写视频里没有的内容。
- > 以下为可选兄弟技能，本仓库快照未包含；缺失时不影响核心纪要功能，相关行动项降级为本地 TODO。
+ ## Verification
- | Skill | 关系 |
- |-------|------|
- | `task-dispatcher` | 接收 `@dev` `@design` 代码/设计任务 |
- | `content-publisher` | 接收 `@article` 文章任务 |
- | `cron` / `gcal` | 接收 `@reminder` 提醒任务 |
- | `elyfinn-voice-notes` | 语音备忘录处理 (姊妹 skill) |
- | `transcribe` | 纯转录功能 (无总结) |
+ 交付前逐项确认：
- ---
+ - [ ] 配置已加载，或首次设置向导已完成（未命中配置时）。
+ - [ ] 视频类型与置信度已向用户说明，或已按 `--type` 显式指定。
+ - [ ] `output_path` 存在且可打开；类型、时长与文件名一致。
+ - [ ] 行动项已展示，分发前已获得确认（或命中自动白名单）。
+ - [ ] 未安装的兄弟技能没有被谎报为"已分发"，降级路径为本地 TODO。
+ - [ ] 长视频未一次性硬跑，已按需分段。
- ## 版本历史
+ ## Output
- ### v2.0.0 (2026-03-25) - 当前
- - 🚀 **新增 insanely-fast-whisper 支持** - 基于 faster-whisper，速度提升 2-4 倍
- - ⚡ **性能优化** - 支持 int8 量化、VAD 过滤、词级时间戳
- - 💾 **内存优化** - 显存占用降低 50%
- - 🔧 **新配置项** - `compute_type` 支持多种精度模式
+ - **Outcome**：一份结构化 Markdown 纪要（默认落到 `output.directory`，默认
+ `~/Documents/video-minutes`），含摘要、要点、时间线、行动项与可选折叠字幕。
+ - **Done when**：纪要文件已生成并可读、类型判定有依据、行动项已展示、分发（如需）已确认。
+ - **Evidence**：`output_path` 实际存在；内容可回溯到 ASR 字幕；文首记录类型与置信度；
+ 未分发项以本地 TODO 形式列出。
- ### v1.2.0 (2026-03-21)
- - ✅ 新增视频类型自动分类系统 (7种类型)
- - ✅ 新增任务分发集成 (@tags)
- - ✅ 新增 Obsidian/Notion/飞书多格式输出
- - ✅ 新增首次设置向导
- - ✅ 新增自动扫描队列系统
- - ✅ 新增发言人识别
+ ## References
- ### v1.1.0 (2026-03-15)
- - 🔧 重构配置系统 (YAML 格式)
- - 🔧 支持多语言自动检测
- - 🔧 优化 Whisper 模型选择逻辑
+ 按需加载，不要预先全读：
- ### v1.0.0 (2026-03-01)
- - 🎉 初始版本
- - ✅ 基础视频转文字
- - ✅ Markdown 纪要生成
- - ✅ 命令行接口
+ - `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
- ## Roadmap
+ - `<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`。
- - [ ] 实时转录 (直播场景)
- - [ ] 多模态分析 (PPT 内容提取)
- - [ ] 视频摘要生成 (短视频)
- - [ ] 团队协作功能 (共享队列)
- - [ ] 移动端支持 (iOS Shortcuts)
+ ## Troubleshooting
- ---
+ - 模型下载失败 -> 设 `HF_ENDPOINT=https://hf-mirror.com` 后重试。
+ - 视频无音频 -> 用 `ffprobe` 检查音轨；确认 ffmpeg 已安装。
+ - 分类不准 -> 手动 `--type`，或调整 `classification.confidence_threshold`。
+ - 处理超时 -> `--segment-duration 1800`。
+ - 更多失败模式与参数细节见 `references/transcription-engine.md`。
- ## 备选方案
+ ## Related Skills
- - **多模态视频理解**：对于 2 小时以内的短视频，当前多模态模型可直接理解视频内容并生成纪要，无需完整的 ASR→转录→LLM 流水线。适合快速预览和简单总结场景。长视频（>2h）或需要精确字幕的场景仍推荐使用本技能的完整处理流程。
+ - `video-dubbing` — 视频翻译 + 配音 + 双语字幕，本技能不做配音。
+ - `transcribe` — 纯转录、无总结；只需文字时优先它。
+ - `mlx-tts` — 本机 TTS，可为纪要生成语音摘要。
+ - `content-publisher` / `cron` / `gcal` / `agent-swarm` — 可选分发目标，缺失时降级为本地 TODO。