bili-md

概述

自动化从哔哩哔哩视频 URL 到结构化 Markdown 摘要的完整流程：

通过 yt-dlp 获取视频标题
下载最高质量的 m4a 音频流
使用 Coli ASR（sensevoice 模型，离线，多语言）进行转录
总结并保存为以视频标题命名的 .md 文件

环境要求

| 工具 | 安装方式 | |------|----------| | yt-dlp | pip install yt-dlp | | ffmpeg | yt-dlp 需要它进行音频格式转换 | | coli CLI | npm install -g @marswave/coli | | Node.js | coli CLI 依赖 |

Coli ASR 通过本地语音识别模型完全离线运行。无需 API key。首次转录时会自动下载 sensevoice 模型（约 155 MB）到 ~/.coli/models/。

工作流程

步骤 1 — 解析 URL 并获取视频信息

输入: B站视频 URL（bilibili.com/video/BV... 或 b23.tv/xxx）
输出: 完整视频 URL + 视频标题

# 解析短链接（如果是 b23.tv 短链）
curl -sIL "https://b23.tv/xxx" 2>&1 | Select-String -Pattern "location"

# 获取视频标题
python -m yt_dlp --get-title "<完整URL>"

步骤 2 — 下载音频

输入: 完整视频 URL + Cookie（如需要）
输出: 音频文件 .m4a

⚠️ B站下载注意：B站对直接请求返回 HTTP 412 错误，需要通过浏览器获取 Cookies 后使用 --add-header Cookie: 方式下载。

使用 yt-dlp 下载音频（完成 Cookie 认证后）：

yt-dlp --no-warnings `
  --add-header "$COOKIE_HEADER" `
  --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" `
  --referer "https://www.bilibili.com" `
  -f "bestaudio[ext=m4a]/bestaudio" `
  -o "<output_dir>/%(title)s.%(ext)s" `
  "<B站视频URL>"

步骤 3 — 使用 Coli ASR 转录

输入: 音频文件 .m4a
输出: 转录文本

# 对于长视频（>15 分钟），先分段以避免内存问题
ffmpeg -i "<audio.m4a>" -f segment -segment_time 600 -c copy "<output_dir>/part_%03d.m4a"

# 转录每个分段
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
coli asr "<output_dir>/part_000.m4a" --model sensevoice

步骤 4 — 总结并写入 MD 文件

输入: 转录文本
输出: Markdown 摘要文件 .md

转录完成后，按照以下格式将内容整理成 Markdown 文件。

步骤 5 — 清理临时文件

输入: 临时文件列表
输出: 仅保留最终 Markdown 文件

# 删除已下载的音频和转录文件
rm "<output_dir>/<title>.m4a"
rm "<output_dir>/<title>_transcript.txt"

# 删除音频分段文件（长视频情况下）
# 重要提示：必须先 cd 到目录，否则通配符在 Windows 上不会展开
cd "<output_dir>" && rm -f segment_*.m4a

Windows 注意事项：

rm -f /path/to/segment_*.m4a 不起作用，因为通配符不会展开

Python glob.glob() 在中文路径下可能因编码问题失败

解决方案：使用 os.listdir() 扫描目录并按文件名模式过滤

只保留最终的 Markdown 摘要文件。

MD 文件格式

# <视频标题>

> **来源：** [B站视频](<url>)  
> **时长：** <预估时长>  
> **核心主题：** <一行总结>

---

## 核心论点

<主要论点的 2-3 句概述>

## 主要内容

### 一、<章节标题>
<内容>

### 二、<章节标题>
<内容>

...

## 总结

<简明的结论段落>

---
*本文根据视频音频自动转录并整理*

异常处理

| 错误场景 | 解决方案 | |---------|----------| | HTTP 412 错误 | 使用 agent-browser 获取实时 Cookie | | 格式 30280 不可用 | 回退到 bestaudio[ext=m4a]/bestaudio | | Coli 模型下载失败 | 手动解压：cd ~/.coli/models/ && tar -xjf *.tar.bz2 | | 长视频内存错误 | 使用 ffmpeg 将音频分成 10 分钟分段 | | SSL 证书错误 | 设置 NODE_TLS_REJECT_UNAUTHORIZED=0 | | 找不到 ffmpeg | 确保 ffmpeg 在 PATH 中或设置 FFMPEG_BIN 环境变量 | | 路径包含特殊字符 | 通过删除 \ / : * ? " < > | 字符清理标题 | | 中文路径编码问题 | 使用 PowerShell 通配符动态获取文件路径 |

Windows 平台常见问题

以下问题已在实际运行中遇到及解决：

grep 命令不可用
```
grep : 无法将 grep 项识别为 cmdlet...
```
Windows PowerShell 原生没有 grep，在 PowerShell 环境中改用 Select-String 或 Where-Object 代替。
coli CLI 不支持 --version
```
error: unknown option '--version'
```
coli CLI 不支持 --version 参数，可直接使用 coli asr 命令，无需检查版本。

中文路径编码导致文件找不到（File not found）

Error: File not found: E:\1-工程仓库\bili-md\霍尔木兹海峡开关与石油冲击（下）...

原因：Windows 控制台编码问题，下载的文件名在磁盘上实际存储为乱码，但控制台显示中文路径传递给 coli 时无法正确解析。解决方案：使用 PowerShell 通配符动态获取文件路径。

# 错误写法（中文路径编码问题）
coli asr "E:/1-工程仓库/bili-md/霍尔木兹海峡开关与石油冲击（下）.m4a"

# 正确写法（动态获取文件）
$m4aFile = Get-ChildItem "E:/1-工程仓库/bili-md/*.m4a" | Select-Object -First 1
coli asr $m4aFile.FullName --model sensevoice

mkdir 失败但下载仍成功
```
Out-File : 找不到路径...\E:\dev\null...
```
PowerShell 的 2>/dev/null 重定向在 Windows 上不生效，可安全忽略。yt-dlp 会自动创建子目录，下载仍会成功。

音频/转录文件删除后缀名问题

# 错误：-replace 在 PowerShell 中是基于正则匹配
$mdPath = $m4aFile.FullName -replace '.m4a', '.md'  # 如果有多个 .m4a 会出问题

# 正确：使用 [System.IO.Path]::ChangeExtension
$mdPath = [System.IO.Path]::ChangeExtension($m4aFile.FullName, '.md')

B站下载认证问题（重要）

B站对直接请求返回 HTTP Error 412: Precondition Failed，需要通过以下方式解决：

方法一：通过浏览器获取 Cookies 后下载（推荐）

步骤 1 — 解析短链接（如果是 b23.tv 短链）

# 解析短链接获取完整 URL
curl -sIL "https://b23.tv/xxx" 2>&1 | grep -i location

步骤 2 — 用浏览器打开视频页面获取 Cookies

# 用浏览器打开视频页面（确保页面完全加载）
agent-browser open "https://www.bilibili.com/video/<BV号>"
agent-browser wait 5000

# 提取 Cookies 为 HTTP Header 格式
COOKIE_HEADER=$(agent-browser cookies get 2>&1 | paste -sd ';' - | sed 's/^/Cookie: /')

步骤 3 — 用 Cookie Header 下载音频

yt-dlp --no-warnings \
  --add-header "$COOKIE_HEADER" \
  --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" \
  --referer "https://www.bilibili.com" \
  -f "bestaudio[ext=m4a]/bestaudio" \
  -o "<output_dir>/%(title)s.%(ext)s" \
  "<完整B站URL>"

⚠️ 注意：--cookies 参数的 Netscape 格式文件在此环境下可能无法通过 yt-dlp 校验，因此使用 --add-header Cookie: 方式传递 Cookies。

方法二：直接用 yt-dlp（偶发成功）

# 如果 Cookie 认证仍然失败，尝试添加更多请求头
yt-dlp --no-warnings \
  --add-header "Cookie: <your_cookie_string>" \
  --add-header "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" \
  --add-header "Referer: https://www.bilibili.com" \
  -f "bestaudio[ext=m4a]/bestaudio" \
  -o "<output_dir>/%(title)s.%(ext)s" \
  "<B站视频URL>"

说明：B站的认证机制可能随时变化，如果 412 错误持续出现，请优先使用方法一（通过浏览器获取实时 Cookies）。

检查点设计

⚠️ 重要：在关键步骤前必须暂停，确认用户意图后再继续

检查点 1：Cookie 认证确认

在下载音频前，必须确认用户是否已完成浏览器登录：

[检查点] 确认是否需要 Cookie 认证？
- 用户已提供有效 Cookie → 直接下载
- 用户没有 Cookie → 提示使用 agent-browser 打开浏览器获取

检查点 2：输出目录确认

在开始下载前，确认输出目录是否正确：

[检查点] 输出目录: <dir>
确认继续？ (y/n)

检查点 3：长视频分段确认

如果视频时长 > 15 分钟，提示分段处理：

[检查点] 视频时长 {duration} 分钟，将自动分段转录
确认继续？ (y/n)

快速检查清单

[ ] URL 是有效的哔哩哔哩链接（bilibili.com/video/BV... 或 b23.tv/xxx）
[ ] 如果使用 b23.tv 格式，需解析短链接
[ ] 在浏览器中打开视频页面并获取 cookies（如果出现 412 错误）
[ ] 使用 yt-dlp + Cookie 认证下载音频
[ ] 使用 coli ASR 转录（如果 >15 分钟则分段处理）
[ ] 编写结构化的 Markdown 摘要
[ ] 删除临时文件（音频、转录文本、分段文件）
[ ] 展示结果

Bili Md 参考文档

这是详细的参考文档占位符。如有需要，用实际的参考内容替换或删除不需要的部分。

其他 skill 的参考文档示例：

product-management/references/communication.md - 状态更新综合指南
product-management/references/context_building.md - 收集上下文深入探讨
bigquery/references/ - API 参考和查询示例

参考文档的适用场景

参考文档适用于：

全面的 API 文档
详细的工作流程指南
复杂的多步骤流程
内容过长不适合放在主 SKILL.md 中的信息
仅在特定用例中需要的内容

结构建议

API 参考示例结构

概述
认证方式
带示例的端点说明
错误代码
速率限制

工作流程指南示例结构

前置条件
分步说明
常见模式
故障排除
最佳实践