🎬➡️📚 Video Distill Pipeline

> 把任意 mp4 / mov 视频本地蒸馏成结构化文档 —— 培训手册 · 观点摘要 · 案例集
> 零云端依赖 · 零 API Key · 零隐私泄露 · 可断网运行

为什么做这件事

最近一年，我们见过太多这样的素材——

• 老板把某场行业论坛录屏拷给秘书：「帮我转成文字稿，周末看。」
• HR 把某位专家三小时的访谈录像丢在共享盘：「谁能整理成培训手册？」
• 律师把一场客户会谈录音存进电脑：「下次遇到类似客户翻出来听听。」

这些素材，每一份都价值连城；但每一份，几乎都注定沉睡。

为什么？因为要让一段视频「可用」，至少要翻三座山：

1. 看完一遍 —— 拖进度条找关键点，本身就要一小时；
2. 转写成文字 —— 动辄 2000+ 行的转写稿，没人愿意读；
3. 提炼成方法论 —— 这一关最难，大部分人卡在「摘抄金句」，但金句不等于方法论。

而更隐秘的一道红线是——很多素材，根本不能上传云端。
客户会谈、内部会议、未公开课程、签过保密协议的商业素材……一旦上传，归属权就不再属于你。

三座山 + 一道红线，就是这个 skill 诞生的全部理由。

我们想做什么

> 让一段视频，从「看完就忘的信息」，变成「明天就能用的知识」——全程在你自己的电脑里完成。

具体而言，这个 skill 帮你做四件事：

• 🎤 本地听写 —— 用 macOS 系统级音频 API 抽音频，再用本地 Whisper 模型把语音转成文字。一个字节都不上传。
• 🧠 方法论级提炼 —— 内置 5 阶段蒸馏流程（整书理解 → 5 路提取 → 三重验证 → RIA++ → DIGEST），把零散观点变成可复用框架，不止是「压缩」。
• 📂 双发归档 —— 每段视频产出两份文件：结构化精华 + 带时间戳的原始转写。前者拿来用，后者拿来查。
• 🔒 断网可跑 —— 整个流程不联网、不需要 API Key、不留云端日志，敏感素材也能放心处理。

适合谁、什么场景

🌟 一图看懂：从视频到文档的完整流水线

🎥 mp4/mov 任意视频
        ↓
🔊 抽音频（PyObjC AVFoundation）
        ↓
📝 本地 STT（faster-whisper，CPU 即可）
        ↓
🧠 5 阶段蒸馏（方法论内置）
        ↓
📄 MD 文档  +  📄 转写原文
        ↓
📂 Obsidian 双文件同步

> 🎯 6 步端到端：视频 → 音频 → 文字 → 观点 → 文档 → 归档

🎯 5 大核心能力

🎨 输出示例

蒸馏前（原始转写片段，2400+ 行 .txt）：

[1234.5-1238.2] 大家好今天我们来讲 AI 时代的效率革命
[1238.5-1245.1] 互联网和 AI 的本质区别是什么
[1245.3-1252.8] 互联网是需求侧的市场增加，AI 是供给侧的效率革命

蒸馏后（结构化 MD 文档）：

# AI 效率革命·十五讲

## 核心观点 1：互联网 vs AI 的本质区别

> **R（阅读引子）**：大家有没有想过互联网和 AI 的差别到底是什么？

> **I（讲解）**：互联网是需求侧的市场增加（电商、外卖、打车都是凭空造出的新市场），
> 而 AI 是供给侧的效率革命（同样的产出，但用更少的人、更短的时间完成）。

> **A1（应用）**：作为企业老板，你的销售文案如果还停在 2015 年的"互联网思维"，
> 那么你会在 2025 年发现 AI 已经把你的同行甩开 10 倍效率。

🎯 4 大应用场景

• 🏢 企业内训 —— 老板讲话录音 / 行业访谈视频 / 专家分享录屏 → 培训手册
• 📚 研究整理 —— 长视频课程 / 学术讲座 / 播客节目 → 可检索笔记
• 📰 内容复用 —— 已有视频资产 / 录播课程 / 内部培训 → 公众号文章
• 🔒 隐私敏感 —— 客户访谈 / 内部会议 / 商业机密 → 永远不联网

我们的承诺

> 好的蒸馏不是「压缩内容」，而是「让方法论被复用」。
> 一段视频看完就忘，是因为它停在「信息」层；提炼成可执行框架，才能进入「知识」层。

这个 skill 不止「帮你转写」，更要「帮你把视频变成方法论」。

三步上手（最快 5 分钟）

# Step 1：装环境（首次约 3 分钟）
pip install pyobjc-framework-AVFoundation faster-whisper
bash models/download_whisper.sh tiny   # 75MB，中文识别率 ~90%

# Step 2：抽音频 + 转写（本地 Whisper，CPU 即可）
python scripts/extract_audio.py your_video.mp4 audio.m4a
python scripts/transcribe.py audio.m4a > transcript.txt

# Step 3：蒸馏 + 归档到 Obsidian
python scripts/distill.py all transcript.txt \
    --obsidian-dir "/path/to/Obsidian/💼工作文件/培训文件/" \
    --md-name "AI 效率革命·十五讲"

完成后你会看到：

💼工作文件/培训文件/AI 效率革命·十五讲/
├── AI 效率革命·十五讲.md           ← 结构化精华（直接可用）
└── AI 效率革命·十五讲·转写.txt      ← 原始转写（带时间戳，可追溯）

> ⚠️ 详细技术细节、踩坑、CLI 完整参数、强制交付物规则在下方各章节。
> 简要介绍见 README.md；5 阶段方法论见 methodology/；v1.3+ 强制交付物规则见 docs/DELIVERY-RULES.md。

📚 技术参考（下方为工程实现细节）

> 本节面向开发者与进阶用户，使用时直接按需查阅即可。

工具栈

mp4 → [PyObjC AVAssetExportSession] → m4a → [faster-whisper tiny int8] → 带时间戳 txt → [人工/LLM 蒸馏] → 结构化 Markdown

核心组件：

V1.2 新增：内置 5 阶段蒸馏方法论

V1.2 起，本 skill 自带完整的蒸馏方法论（不依赖任何外部 skill）：

阶段 0   整书理解（Adler 四步）              →  methodology/01-stage0-overview.md
阶段 1   5 路并行提取                        →  methodology/02-stage1-extract.md
阶段 1.5 三重验证（V1 跨域/V2 预测/V3 独特） →  methodology/03-stage1.5-verify.md
阶段 2   RIA++ 6 段构造                      →  methodology/04-stage2-ria-plus.md
阶段 5   DIGEST 精华长文交付                  →  methodology/05-stage5-deliver.md

配套资源：

工作流执行规范（v1.3.1+ 强制）

> 2026-07-23 主公亲定：蒸馏视频时必须主动、定期汇报进度，禁止静默等待。

规则 A：进度主动汇报

启动任何后台任务（抽音频 / STT 转录 / 长 LLM 蒸馏）后，必须每隔 30 秒主动用 Bash 检查一次磁盘文件进度，并把以下信息简洁呈报：

• 当前已写文件大小（如 48K）+ 已写行数（如 1342 行）
• 相对全程的预估百分比（如 ~35%）
• 预计剩余时间（如 还需 ~5.5 分钟）

> 实现要点：用 wc -l + ls -lh 读 transcript.txt 的实时变化即可；勿轮询 TaskOutput（系统会自动通知完成，但中间过程进度看不到）。

规则 B：进度静默禁止

下列行为视为违反规范：

• 启动后台转录后，主公问"完成了吗"才被动查进度
• 整段转录期间不输出任何中间状态
• 用 block=true 一次性等任务结束

规则 C：汇报模板

主公问到或亮主动汇报时，使用以下三段式：

转录进行中（已用 X 分钟 / 预估全程 Y 分钟）
- 磁盘：N 行 / M KB
- 进度：~Z%
- 预计还需 W 分钟

V1.4 新增：长视频自动分段转录流水线

> 2026-07-24 主公亲定：解决两大痛点——① 长视频（>15min）不能整段送 Whisper（内存炸、进程被杀）；② Agent 把转录放到后台后失联，主公反复问"好了没"。

一键流水线（推荐）

python scripts/transcribe_pipeline.py video.mp4 output_dir/

脚本内部自动判断短视频还是长视频：

进度文件机制（解决后台失联）

流水线每完成一段，自动写入 output_dir/_pipeline_progress.json：

{
  "status": "transcribing",
  "current_chunk": 5,
  "total_chunks": 24,
  "total_lines": 340,
  "total_size_kb": 17,
  "started_at": "2026-07-24T10:20:00+08:00",
  "last_update": "2026-07-24T10:21:30+08:00",
  "estimated_remaining_seconds": 420
}

Agent 工作流程：

1. run_in_background=true 启动流水线
2. 立即告诉主公："预计 N 分钟后完成，每段完成后我汇报进度"
3. 任何时候主公问进度 → cat _pipeline_progress.json → 精准三段式汇报
4. 系统通知任务完成 → 确认 status: "completed" → 直接进入蒸馏阶段

关键改进：
- 不再靠 wc -l 猜进度（中途行数可能不准）
- 不再靠 TaskOutput 轮询（只能看片段 stdout）
- estimated_remaining_seconds 由实际耗时动态计算，越来越准

边转录边合并（v1.4 新增）

长视频转录时，每段完成立即追加到 transcript.txt（加全局时间戳偏移），不再等到全部转录完才合并。好处：
- transcript.txt 始终可读（中途断掉不丢数据）
- 减少最终合并阶段的内存压力

断点续跑（v1.4 支持）

流水线会检查中间文件是否已存在：
- audio.m4a 已存在 → 跳过提取
- audio.wav 已存在 → 跳过转换
- chunks/chunk_*.wav 已存在 → 跳过切段
- 已转录的 chunk txt → 每段仍然重新转录（因为模型初始化开销远大于转录本身）

推荐：加 --cleanup 参数在完成后清理中间文件（wav + chunks），节省磁盘（示例：93min 视频中间文件 ~290MB）。

系统要求

• macOS 13.0+（AVFoundation API 需要 Ventura+）
• Python 3.10+（PyObjC 12.x 需要）
• 内存 ≥ 1GB free（tiny 模型 ~500MB，base 模型 ~1GB）
• 磁盘 ≥ 200MB（模型 + 临时文件）

安装

# 1. 创建 venv（推荐）
python3 -m venv .venv
source .venv/bin/activate

# 2. 安装 Python 依赖
pip install pyobjc-framework-AVFoundation faster-whisper

# 3. 下载模型（首次）
bash models/download_whisper.sh tiny

> 💡 lite 版说明：本 skill 发布时不携带 model.bin（避免 SkillHub 拒收大权重）。装好后请跑第 3 步从 hf-mirror.com 下载（约 75MB），脚本会断点续传、自动重试。

完整工作流

> v1.4 推荐：直接使用 scripts/transcribe_pipeline.py 一键完成步骤 1 + 2（见上文「V1.4 长视频自动分段转录流水线」）。以下为手动分步流程（调试 / 特殊场景用）。

步骤 1：抽音频

# scripts/extract_audio.py
from AVFoundation import AVURLAsset, AVAssetExportSession
from Foundation import NSURL
import threading

def extract(video_path, out_path):
    asset = AVURLAsset.alloc().initWithURL_options_(
        NSURL.fileURLWithPath_(video_path), None)
    export = AVAssetExportSession.alloc().initWithAsset_presetName_(
        asset, 'AVAssetExportPresetAppleM4A')
    export.setOutputURL_(NSURL.fileURLWithPath_(out_path))
    export.setOutputFileType_('com.apple.m4a-audio')

    sem = threading.Semaphore(0)
    export.exportAsynchronouslyWithCompletionHandler_(sem.release)
    sem.acquire()
    return export.status() == 3  # AVAssetExportSessionStatusCompleted

关键 API 选择：
- initWithAsset_presetName_:（不是 Swift 类方法 assetExportSessionWithPreset:asset:）
- preset 字符串：'AVAssetExportPresetAppleM4A'（不是 Swift 短名）
- outputFileType：'com.apple.m4a-audio'（UTI 字符串）

步骤 2：本地 STT

from faster_whisper import WhisperModel

model = WhisperModel('./models/whisper-tiny', device='cpu',
                     compute_type='int8', local_files_only=True)
segments, info = model.transcribe('audio.m4a', language='zh', beam_size=5)

with open('transcript.txt', 'w') as f:
    for seg in segments:
        f.write(f'[{seg.start:.1f}-{seg.end:.1f}] {seg.text}\n')

模型选择建议：

⚠️ small 在 macOS 14 内存吃紧时会触发 OOM SIGKILL（free 内存约 1.1GB 时）。

步骤 3：蒸馏成结构化文档

可用任何 LLM（Claude / GPT / 本地 Ollama）按以下 prompt 处理：

你是一位企业培训设计专家。以下是一段访谈视频的转写文本，
请帮我提炼出 8-12 个核心观点，每个观点按以下结构整理：

## 观点 N：[一句话标题]
**核心论断**：[原话引述 1-2 句]
**详细说明**：[用自己的话重写方法论骨架]
**对企业的启示**：[可落地到企业培训 / 组织优化的建议]

要求：
1. 所有"启示"必须基于原话衍生，不杜撰
2. 保留原话中的真实案例与数据
3. 最终输出为 Markdown，可直接用作培训教材

输出后人工校对、补图、调整结构即可成稿。

踩坑记录（7 大坑）

坑 1：系统 ffmpeg SIGILL

• 病症：/Applications/VideoFusion-macOS.app/Contents/Resources/ffmpeg -version 退出码 132（SIGILL）
• 真因：universal binary 在 Intel i7-9750H 上即使设了 DYLD_LIBRARY_PATH 仍报 illegal instruction；macOS hardened runtime 限制
• 绕过：完全不用 ffmpeg，用 PyObjC AVAssetExportSession 走系统级 API

坑 2：PyObjC API 名称差异

Swift 类方法 + assetExportSessionWithPreset:asset: 在 PyObjC 中没有桥接，调用会 AttributeError。

✅ 正确写法：

export = AVAssetExportSession.alloc().initWithAsset_presetName_(
    asset, 'AVAssetExportPresetAppleM4A')

坑 3：HF 代理 502 Bad Gateway

系统的 HTTP_PROXY 把 huggingface.co 走代理 → 502。

✅ 绕过：用 HF 镜像 hf-mirror.com 直链下载，绕过代理：

curl -L -o model.bin "https://hf-mirror.com/guillaumekln/faster-whisper-tiny/resolve/main/model.bin"

坑 4：HF CAS 401 Unauthorized

hf-mirror.com 的 huggingface_hub 客户端走 CAS reconstruction → 401。

✅ 绕过：用 curl -L 直链下载 + 手动组织模型目录：

mkdir whisper-tiny && cd whisper-tiny
for f in config.json tokenizer.json vocabulary.txt model.bin; do
  curl -L -s -o "$f" "https://hf-mirror.com/guillaumekln/faster-whisper-tiny/resolve/main/$f"
done

模型目录结构：config.json + model.bin + tokenizer.json + vocabulary.txt

坑 5：Swift 工具链错配

/usr/bin/swift 版本与系统 SDK swiftlang 不匹配 → 编译失败。

$ swift --version
swift-driver version: 1.115.1 Apple Swift version 6.0.3
# 但 SDK 是 swiftlang-6.0.3.1.10，编译报：
# error: failed to build module 'CoreFoundation'

✅ 绕过：用 PyObjC 替代 Swift CLI（macOS 系统级 API 都能从 PyObjC 调用）。

坑 6：SFSpeechRecognizer 静默崩溃

即使在 PyObjC 里调用 SFSpeechRecognizer.requestAuthorization_，Python 脚本缺少 Info.plist 中的 NSSpeechRecognitionUsageDescription → 进程被 SIGABRT 杀掉，stderr 无任何输出。

✅ 绕过：完全不用 Speech.framework，用 faster-whisper 本地模型。

坑 7：mmx CLI 不支持视频

• mmx vision describe 只接图像
• mmx file upload --file xxx.mp4 → "invalid file ext for retrieval"

✅ 绕过：视频必须走本地 STT 路径（这是本项目的核心场景）。

性能基准

测试环境：macOS 14.8 / Intel i7-9750H / Python 3.13.12

短视频（直接转录）

长视频（自动分段流水线）

> 长视频总耗时主要受「段数 × 每段加载模型 + 推理」影响。每段首次加载模型约 0.5 秒，推理约 20-90 秒/段（取决于该段实际语音密度）。24 段 93 分钟视频实际转录耗时约 22 分钟（含模型加载），合并与进度写盘开销可忽略。

模型首次加载约 0.5 秒（已下载），CPU int8 推理。

已验证案例

案例 1：两段访谈视频（90MB + 23MB，共 ~28 分钟）
- 输入：企业老板/HR 培训用
- 输出：21.5KB / 508 行培训手册
- 内容：10 个核心观点 + 4 个工具模板 + 90 分钟 OMO 培训现场建议
- 人工整理时间：~15 分钟（含校对、视频片段剪辑建议）

案例 2：AI 提效五步法直播（838MB，64 分钟）
- 主讲：名丽明老师（腾讯云 AI 售前顾问）
- 输出：AI 提效五步法·WorkBuddy 实战.md（338 行 / 16KB）+ 转写（1809 行 / 81KB）
- 分段：17 段 × 4 分钟，tiny int8，总耗时 ~26 分钟
- 亮点：五步法（定/给/检/封/迭）+ 4 大实战场景 + 21 个可复制 prompt

案例 3：AI 求职全流程实战直播（860MB，93 分钟）
- 主讲：小军老师（WorkBuddy 产品与营销）
- 输出：AI 求职全流程实战·WorkBuddy 直播精华.md（16KB）+ 转写（2019 行 / 103KB）
- 分段：24 段 × 4 分钟，tiny int8，总耗时 ~24 分钟
- 亮点：求职 5 步闭环 + 三类人群开场法 + 12 个 prompt 模板 + 自动化规则沉淀方法

已知局限

• 中文转写偶有同音字错误（tiny 模型限制），需人工校对专有名词
• 长视频分段转录虽避免了 OOM，但每段边界处若有连续语句会被切断（可通过后期校对修正）
• 不支持带字幕轨的视频直接抽字幕（未实现）
• 多说话人场景未做说话人分离
• 单次转录只用 CPU int8，不接受 GPU 加速（本机无 NVIDIA GPU）

后续改进方向

• 尝试 base 模型做对照（精度对比）—— 需确认长视频分段后 base 内存也 hold 得住
• 支持直接抽视频字幕轨（如果有）
• 用 VAD（语音活动检测）跳过静音段提升转写效率
• 蒸馏时增加"对客户的可操作性"评估维度
• 流水线进度推送到微信/企微通知（让 Agent 不主动查也能感知完成）

依赖与安装

# Python 依赖（managed venv 推荐）
pip install pyobjc-framework-AVFoundation faster-whisper

# 模型（首次）
bash models/download_whisper.sh tiny

参考

• OpenAI Whisper 论文
• faster-whisper GitHub
• PyObjC AVFoundation 文档
• macOS AVFoundation Programming Guide

v1.3+ 强制交付物规则

> 2026-07-21 主公亲定：以下规则作为本 skill 的强制交付物规范，违反视为任务未完成。

规则 1：双发机制

每次完成视频转写后必须双交付：

1. MD 文档（按主公指定的命名）
2. 纯文本转写文件（带时间戳的 .txt，原始 STT 输出，不做修正）

两份必须同步存入主公指定的 Obsidian 文件夹。

规则 1.5：MD 文件必须含 YAML Frontmatter（2026-07-23 主公亲定）

每个 MD 文件开头必须有 YAML frontmatter，至少包含：

---
title: <文档标题>
created: YYYY-MM-DD
type: 视频蒸馏精华
source: <视频来源（直播 / 官方物料 / 第三方）>
video-duration: <时长，如 76min>
speakers:
  - <主讲 1 角色>
  - <主讲 2 角色>
distill-pipeline: video-distill-pipeline v1.3+
tags:
  - WorkBuddy       # 必有：产品/平台主标签
  - <主题标签 1>     # 视频核心议题
  - <主题标签 2>
  - ...
  - 视频蒸馏        # 必有：内容类型标签
  - <其他分类标签>
---

tag 选取原则：
- 必有 WorkBuddy / 视频蒸馏（用于全局检索）
- 视频涉及的具体产品名（如 ima知识库、腾讯电子签）
- 视频独有的核心方法论/框架（如 去用存三件套、六大积木）
- 内容分类（如 直播课、企业AI培训、OPC一人公司）
- 总数控制在 8-20 个，避免冗余

⚠️ 写入校验：MD 文件保存后必须 head -30 file.md 确认 frontmatter 完整、tag 列表正确。漏打标签视同任务未完成（2026-07-23 主公亲定）。

规则 2：转写文件命名

<MD 文件名>·转写.txt

用中点 · 分隔，与 MD 文件同名（去掉 .md 后缀，加 ·转写.txt）。

规则 3：MD 文件命名

文件名应反映实际课件内容 / 培训主题，而非讲者姓名。

禁止：把任何具体人名当作通用命名前缀（如不允许以后每条都叫"耿老师的 XXX"）。

未指定时：自动按视频内容主题提炼 3-15 字命名，主动用 请问主公是否同意此名？ 形式确认后再落地。

规则 4：默认目标目录（2026-07-23 主公亲定·含 vault 路径）

Obsidian vault 真实根目录：/Users/jiang/布拿拿MAC/布拿拿 Obsidian/（带 MAC，有 .obsidian 配置；不是 /Users/jiang/布拿拿 Obsidian/ 短路径！）

视频蒸馏默认目录（vault 下）：
- /Users/jiang/布拿拿MAC/布拿拿 Obsidian/ai培训视频蒸馏/<内容分类>/<视频文件名（去扩展名）>/

<内容分类> 命名约定（2026-07-23 长期生效）：
- WorkBuddy 法律类视频 → WorkBuddy法律/
- WorkBuddy 主题培训类（非法律）→ WorkBuddy主题培训/
- 其他分类按视频内容新建子目录

主公指定别的目录时，MD 与转写两份都同步复制到该目录，路径保持一致。

🚨 写入前必校验三步：
1. ls -la "/Users/jiang/布拿拿MAC/布拿拿 Obsidian/.obsidian" 确认 vault 存在（带 MAC）
2. 创建目标子目录
3. 写完文件后 ls vault_dir/... 校验文件实际落地

> 踩坑教训：2026-07-23 视频蒸馏时，亮一连 8+ 次 mkdir/cp/Write 全用了短路径 /Users/jiang/布拿拿 Obsidian/，导致文件落到空壳目录，Obsidian 看不到。主公提示后才查 .obsidian 目录发现 vault 在带 MAC 的长路径。修正后必须三步校验。

规则 5：CLI 一键落地（v1.3+ 推荐）

python scripts/distill.py all transcript.txt \
    --obsidian-dir "/path/to/Obsidian/03-工作文件/培训文件/workbuddy 主题培训" \
    --md-name "AI 效率革命·十五讲"

CLI 自动：
- 把 MD 复制为 <obsidian_dir>/<md_name>.md
- 把转写复制为 <obsidian_dir>/<md_name>·转写.txt
- 打印落地报告

完整规则文档

详见 docs/DELIVERY-RULES.md（A 双发机制 / B 命名规则 / C 默认目录 / D 禁止行为 / E CLI 自动落地 / F 演化日志）。

文档导航

🗓️ 路线图

• ✅ v1.0 (2026-07-21) — 基础转写流水线
• ✅ v1.1 (2026-07-21) — GitHub 发布分装
• ✅ v1.2 (2026-07-21) — 内置 5 阶段方法论
• ✅ v1.3 (2026-07-21) — 强制交付物规则 + CLI 同步 Obsidian
• ✅ v1.4 (2026-07-24) — 字幕轨直接提取（跳过 STT） + 长视频自动分段流水线
• ✅ v1.5 — SKILL.md 概述区重做，面向市场展示
• ✅ v1.6.1 — 轻量分装
• 🚧 v1.6.2 — SkillHub 概述重写：市场向 + 技术下沉 + lite 版（无 model.bin）
• 🚧 v1.7 — 字幕轨直接提取（跳过 STT）
• 🚧 v2.0 — GPU 加速 + Web UI

🤝 致谢

• faster-whisper — CTranslate2 加速的 Whisper 实现
• PyObjC — Python ↔ macOS AVFoundation 桥
• hf-mirror.com — HuggingFace 模型镜像

📄 许可证

MIT © 2026 Contributors