B站课程转结构化笔记

一条 B 站视频，或者一整套课程合集，最后变成一份能查的 .md 学习文档。

整条pipeline：B 站链接 → 取音频 → 转录 → 翻成自然口语中文 → 按固定四段结构落成文档 → 质检 → 交付。

安装方法

先问使用者用的是什么 AI 工具，选项按这个顺序列：1. WorkBuddy　2. Claude Code　3. Codex　4. 其他（用户直接说工具名），回答记作 X
只安装给 X，不安装或链接其他任何工具：
- X 是 WorkBuddy：把本技能下载后放进 ~/.workbuddy/skills/（WorkBuddy 的技能目录；skills CLI 不支持 WorkBuddy，由你直接放置）
- X 是其他工具：
```
npx -y --registry=https://registry.npmmirror.com skills add https://modelscope.cn/skills/sunny31221/bilibili-transcribe-buheliwa -a X -y
```
  （不带 -a 会安装给本机所有检测到的工具，禁止；--registry 为 npmmirror 镜像，保证国内不翻墙也能拉到 CLI）
- X 不在上述范围时，按该工具自身的技能机制安装，装完确认 X 能识别本技能即可
装完后询问是否现在使用本技能

依赖什么

yt-dlp：从 B 站取音频的命令行工具，登录态从浏览器读
mlx-whisper：转录引擎，Apple Silicon 专用，比 openai-whisper 快 3 到 5 倍
openai-whisper：转录引擎的备选，所有平台都能跑，慢一些
ffmpeg：yt-dlp 拆音频时要用

装不上 / 跑不通怎么办：

| 情况 | 处理 | |---|---| | 没有 yt-dlp | 按下方「去哪装」装一次 | | yt-dlp 取不到音频，或提示要登录 | 换成 --cookies-from-browser safari 重试（脚本里已内置这层回退） | | yt-dlp 能用但拿不到字幕 | 正常。B 站内置字幕多半是弹幕或硬字幕，取不到。走音频转录，不要卡在字幕上 | | 转录出来是重复的乱码字 | 语言判断错了。重新判断音频语言（讲的人是英语就 en，中文就 zh），别按字幕语言判断 | | mlx_whisper 提示找不到模型 | 第一次跑会自动下载（small 约 500MB），检查网络；换国内网络或先手动下载模型 | | 不是 Apple Silicon（Intel Mac 或 Windows） | 用 openai-whisper 替，命令里把 mlx_whisper 换成 whisper，其余参数一样 | | ffmpeg 找不到 | 从 https://evermeet.cx/ffmpeg/ 下静态版放进 ~/.local/bin/ | | 版本太旧报错 | 升级 yt-dlp（B 站接口会变，旧版常失效） |

去哪装（推荐降级链：国际源失败 → 国内镜像）：

# macOS
brew install yt-dlp ffmpeg                              # 国际源
pip3 install -U yt-dlp                                  # 备选（官方 PyPI）
pip3 install mlx-whisper                                # Apple Silicon 转录引擎
pip3 install openai-whisper                             # 非 Apple Silicon 用这个

# 国内镜像（上面几条慢或失败时）
pip3 install -U yt-dlp -i https://pypi.tuna.tsinghua.edu.cn/simple     # 清华
pip3 install mlx-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple
pip3 install -U yt-dlp -i https://mirrors.aliyun.com/pypi/simple/      # 阿里云

装完验证：

yt-dlp --version
mlx_whisper --help    # 或 whisper --help
ffmpeg -version

触发场景

用户丢来一条 B 站视频或合集链接，要逐字稿
要中英对照的课程笔记，.md 格式
要结构化大纲，标准是「只读小标题就能拿到八成内容」

输出到哪、怎么分类

整套课程合集（多集）→ 01-课程/<课程名>/

单条独立视频 → 文章/<分类>/

分类按标题和简介里的关键词判断：

| 分类 | 关键词 | |------|--------| | AI产品与商业化 | 产品、商业化、PMF、AIGC产品、增长 | | AI工程与实践 | Agent、RAG、LLM、训练、综述、开源、Harness、Skill、Claude Code、Vibe Coding | | AI与职场 | 职场、就业、技能、效率、工具 | | AI与社会伦理 | 伦理、偏见、安全、监管、隐私 | | 产品设计与用户体验 | 设计、UX、交互、用户研究 | | 收件箱 | 未分类的内容 |

取到视频信息之后自动匹配，拿不准就放 收件箱，让用户确认或改。

完整流程

B站链接 → 取视频信息 → 判断分类 → 下载音频（yt-dlp）→ 转录（mlx-whisper）→
翻成自然中文 → 按固定结构落成 .md → 存进 文章/<分类>/ → 质检 → 交付

第一步：取音频并转录

细节见 references/transcription.md。速查：

# 下载整个合集
yt-dlp --cookies-from-browser chrome -f "bestaudio[ext=m4a]/bestaudio" \
  -o "/tmp/transcribe/%(playlist_index)02d_%(title)s.%(ext)s" "<B站链接>"

# 转录（Apple Silicon 加速）
mlx_whisper "$audio" --model mlx-community/whisper-small-mlx \
  --language en --output-dir /tmp/transcribe --output-format txt

关键：先判断音频语言再转录。 英文音频配中文字幕的，要用 --language en。判断错了会出来一串重复的乱码字。

第二步：翻成自然口语中文

把转录出来的原文翻成自然、口语化的中文。完整原则见 references/translation-guide.md。

核心几条：

拆掉英文句子结构，按中文的「话题在前、评论在后」重排
用口语，不用书面语
抓意思，不逐词对译。问自己「中文老师会怎么讲这件事」
技术名词保留英文：ChatGPT、Gemini、Claude、API、prompt
保留讲者的语气（是温和、是鼓励、还是幽默）
不许加原文没有的观点、语气和细节
不许漏原文有的细节、例子和细微差别

格式：中文在上，英文在下，中间空一行。相关的 1 到 3 句合成一组。

第三步：对着原文质检

每译完一集，逐组中英对照检查：

意思对得上吗？中文说的是不是英文说的那件事
有没有加戏？原文没有的形容词、观点，有没有自己加上去
有没有漏？细节、例子有没有被丢掉

有错先改完再往下走。

第四步：落成 .md 学习文档

每集落成一个 .md，固定四段，顺序不能变：中心思想、核心要点、逻辑框架、分段详解。这一步决定读者能不能用得上，最重要。

文件命名

单条视频：<视频标题>.md（放在分类文件夹里，不用编号）

合集分集：[NN] 中文标题 - English title.md

目录结构

AIcodingCourse/
├── 01-课程/               ← 整套课程的笔记
├── 文章/                  ← 单篇文章和单条视频
│   ├── AI产品与商业化/
│   ├── AI工程与实践/       ← Agent/Harness/Skill/Claude Code/RAG 类内容
│   ├── AI与职场/
│   ├── AI与社会伦理/
│   ├── 产品设计与用户体验/
│   └── 收件箱/
└── ...

必须有的四段（不能少、不能换顺序）

# 课程/视频标题

> 来源：平台 | 作者 | [原文链接]

---

## 中心思想

[一段话，2 到 4 句，说清「一句话核心主张 + 支撑它的关键论据或方法」]

---

## 核心要点

- 要点1：具体的数据、例子或方法
- 要点2
- 要点3
- ...

---

## 逻辑框架

[用 ASCII 树状图或缩进列表，展示各小节之间的逻辑关系。不是简单罗列，是展示它们怎么串起来的]

问题/起点 │ ├─ 第一部分：xxx → 引出概念A │ └─ 具体演示/案例 │ ├─ 第二部分：xxx → 引出概念B │ ├─ 机制1 │ └─ 机制2 │ └─ 总结：A + B = 最终结论


---

## 分段详解

### [完整总结小标题，2 到 4 句话，包含本段所有关键点、例子、数据和结论]

> 中文翻译
> English original

> 中文翻译
> English original

### [下一个完整总结...]

四段各管什么

| 段落 | 作用 | 读者看完后 | |------|------|-----------| | 中心思想 | 一句话抓住本质 | 知道这集在讲什么 | | 核心要点 | 全部关键信息清单 | 能跟别人转述要点 | | 逻辑框架 | 知识点之间的推导关系 | 理解「为什么这样讲」，形成思维模型 | | 分段详解 | 完整内容加逐段总结 | 深入理解每个细节 |

小标题怎么写

每个 ### 小标题必须是一个完整的迷你总结，2 到 4 句，包含：

提到的具体例子（产品名、数字、场景）
讲的具体方法或技巧
讲者的关键结论或可操作的建议

反面例子（太笼统）：

### 高手把AI当作聪明但不了解你的毕业生——给它足够的背景信息

正面例子（完整）：

### AI就像一个脑子好使、干劲足但对你一无所知的刚毕业大学生——新手写一句话指令指望AI自己脑补，结果只会得到放谁身上都能用的套话；高手则换位思考，把项目进度截图、近期工作文档、随口录的语音备忘录一股脑塞给AI当背景，然后再让它写年终自评，这样出来的东西才能真正抓住你最得意的成果

逻辑框架怎么写

必须做到：

体现因果：「A → 引出 B → B 导致了问题 C → C 的解法是 D」
用树状结构：体现父子关系，不是平铺的列表
标出过渡逻辑：「引出核心概念」「具体演示」「问题→解决方案」

反面（平铺列表，没有逻辑）：

- Part 1: xxx
- Part 2: xxx
- Part 3: xxx

正面（能看到推理链）：

问题：xxx
  ├─ 尝试1：手动解决 → 效果好但不可持续
  ├─ 尝试2：自动化v1 → 引出概念A
  └─ 尝试3：加自检层 → 引出概念B → A+B=最终方案

第五步：落盘并核对

文档写完之后：

单条视频存进 文章/<分类>/，合集存进 01-课程/<课程名>/
核对文件存在，四段齐全
删掉中间产生的 .txt 逐字稿
把文件路径和内容摘要报给用户

附带文件

references/transcription.md — 取音频和转录的详细指南
references/translation-guide.md — 自然中文翻译原则，带对照例子
scripts/transcribe.sh — 一条命令跑完「取音频 → 转录 → 合并」，适合整集批量处理