视频内容抓取器（YouTube 与 Bilibili）

开始前须知

该技能根据您的使用场景，需配置 1–3 项内容：

YouTube 最小化配置：代理 + ElevenLabs API 密钥（或本地 Whisper）
Bilibili 最小化配置：ElevenLabs API 密钥（或本地 Whisper）。Cookie 为可选项，但强烈推荐配置。

快速上手

# YouTube
python3 scripts/youtube_fetch.py "https://www.youtube.com/watch?v=VIDEO_ID" --proxy socks5h://127.0.0.1:1080

# Bilibili
python3 scripts/youtube_fetch.py "https://www.bilibili.com/video/BVxxxxxxxxxx"

回退链（Fallback Chain）

1. 字幕/转录 API（最高保真度 — 完整口语内容）
       |  若不可用
       v
2. ElevenLabs STT（默认云端方案，标点准确、识别精度高）
       |  若未提供 API 密钥或调用失败
       v
3. 本地 Whisper（自动回退，需提前本地安装）
       |  若不可用
       v
4. 视频简介（最低保真度 — 仅含创作者撰写的文字摘要）

务必向用户明确说明所采用的内容来源。若仅使用简介作为输入，须明确指出其并非完整转录文本。

平台支持

平台类型将根据 URL 自动识别。如需强制指定，可使用 --platform youtube 或 --platform bilibili 参数。

使用方法

# YouTube（带代理）
python3 scripts/youtube_fetch.py VIDEO_URL --proxy socks5h://127.0.0.1:1080

# Bilibili（获取字幕需提供 Cookie；否则自动降级至 STT 或简介）
# 重要：始终使用 @filepath 语法，避免凭据泄露至 shell 历史记录或进程列表中
python3 scripts/youtube_fetch.py "https://www.bilibili.com/video/BVxxxxxxxxxx" --cookie @~/.bilibili_cookie

# Bilibili 短链接
python3 scripts/youtube_fetch.py "https://b23.tv/xxxxxx"

# 指定字幕语言（默认：zh-Hans,zh-Hant,zh,en）
python3 scripts/youtube_fetch.py VIDEO_URL --langs "en,ja" --proxy PROXY

# 强制使用本地 Whisper 替代 ElevenLabs
python3 scripts/youtube_fetch.py VIDEO_URL --stt whisper --whisper-model medium

# 完全禁用音频转文字（STT）
python3 scripts/youtube_fetch.py VIDEO_URL --stt none

# 输出 JSON 格式
python3 scripts/youtube_fetch.py VIDEO_URL --json --proxy PROXY

# 保存结果至文件
python3 scripts/youtube_fetch.py VIDEO_URL --output /tmp/transcript.txt --proxy PROXY

依赖项

必需依赖：

• youtube-transcript-api（pip 安装）— 用于获取 YouTube 字幕
• requests（pip 安装）— 用于发起 HTTP 请求调用各类 API

语音转文字（STT）必需依赖：

• yt-dlp（pip 或 brew 安装）— 用于从 YouTube/Bilibili 下载音频

可选依赖（用于本地 Whisper，当 ElevenLabs 不可用时自动回退）：

• openai-whisper（pip 安装）— 本地音频转文字
• ffmpeg（系统级安装）— Whisper 运行所必需

可选依赖（用于 SOCKS5 代理）：

• pysocks（pip 安装）— 若使用 socks5h:// 类型代理则必需

# 必需依赖
pip install youtube-transcript-api requests

# STT 所需依赖
pip install yt-dlp

# 若使用 SOCKS5 代理
pip install pysocks

# 可选：本地 Whisper 回退支持
pip install openai-whisper
brew install ffmpeg  # 或 apt install ffmpeg

ElevenLabs STT（默认引擎）

ElevenLabs Scribe v2 是默认的语音转文字引擎。相比本地 Whisper 模型，其识别准确率显著更高，尤其在中文识别方面——可正确还原汉字、自动添加标点，并规范格式（如书名号等）。

配置方式：

# 方式一：环境变量（推荐）
export ELEVENLABS_API_KEY="sk_your_key_here"

# 方式二：密钥文件
echo "sk_your_key_here" > ~/.elevenlabs_key && chmod 600 ~/.elevenlabs_key
# 后续使用：--stt-api-key @~/.elevenlabs_key

若未提供 API 密钥，该技能将自动回退至本地 Whisper 模型。

安全性说明：与 Bilibili Cookie 相同，应始终通过环境变量或 @filepath 方式传入密钥，切勿直接在命令行中明文传递。

获取 API 密钥地址：https://elevenlabs.io/app/settings/api-keys

代理配置

YouTube 需要代理以绕过地理封锁。Bilibili 在中国大陆通常可直连访问。

• SOCKS5 代理：socks5h://127.0.0.1:1080
• HTTP 代理：http://127.0.0.1:1081

重要提示：YouTube 必须使用住宅 IP 代理。 YouTube 明确封禁数据中心/云服务器 IP。住宅宽带 IP（例如中国香港家庭宽带）稳定可靠；而 VPS/云服务器 IP 极大概率被拦截。建议仅对 YouTube 相关域名启用代理路由。

Bilibili Cookie（字幕必需）

Bilibili 字幕几乎全部由 AI 自动生成，且 必须登录后才能调用字幕接口。若未提供 Cookie，字幕 API 对绝大多数视频均返回空结果，此时技能将自动降级至 STT 或简介模式。

如何获取您的 Cookie：

1. 在浏览器中登录 bilibili.com
2. 打开开发者工具（F12）→ Application → Cookies
3. 复制 SESSDATA 和 bili_jct 两个字段的值
4. 保存至文件：echo "SESSDATA=xxx;bili_jct=xxx" > ~/.bilibili_cookie && chmod 600 ~/.bilibili_cookie
5. 调用方式：--cookie @~/.bilibili_cookie

安全警告：

• Bilibili Cookie 属于登录凭证。一旦泄露，他人可冒充您执行操作（如发布评论、发送私信等）
• 务必使用 --cookie @filepath 而非将 Cookie 字符串直接写入命令行，原因如下：
  • 命令行参数对同一台机器上的其他用户可见（ps aux）
  • 会被记录进 shell 历史（~/.zsh_history、~/.bash_history）
  • 可能出现在 Claude Code 工具调用日志中
• 设置文件权限：chmod 600 ~/.bilibili_cookie
• 若该文件位于 Git 仓库附近，请加入 .gitignore
• Cookie 会定期过期，请根据需要从浏览器重新获取

翻译与语言处理

响应语言需与用户当前对话语言保持一致。 不得硬编码默认语言。

• 若用户使用英文交流，则以英文生成摘要
• 若用户使用中文交流，则以中文生成摘要
• 若用户使用日文交流，则以日文生成摘要
• 若字幕语言与用户语言不一致，则在摘要过程中同步完成翻译

此行为无需额外配置 — Claude 可自然适配当前对话语言。

摘要生成注意事项

• 字幕/转录来源：可自由摘要 — 此类内容代表完整的口语表达
• ElevenLabs STT 来源：识别精度高、标点准确 — 可视作接近原始转录质量
• Whisper STT 来源：整体可靠，但在中文识别中可能存在个别字符错误 — 需向用户明确说明
• 简介来源：需提醒用户，此仅为创作者撰写的文字摘要，并非视频全部内容
• 对于超长转录文本（>50K 字符），应分段处理并逐步生成摘要