youtube-digest git:20260723.57a3d39A

Immutable. This exact content is served forever at /api/v1/blob/7a4c04887f6dc5bc.

---
name: youtube-digest
description: YouTube 提文案 — 输入 YouTube 视频链接或 ID，一键提取视频文字稿（字幕/口播文案），默认输出不带时间戳的纯文案；字幕中文轨优先、无中文轨回退英文后自动翻译为中文，结果以表格（标题/时长/文案内容）呈现，支持导出 Excel、可选带时间戳版本。当用户需要提取 YouTube 视频文案、把视频转成文字稿、做视频笔记/总结/翻译/二次创作时使用。
---

# YouTube 提文案

输入 YouTube 视频链接，一键提取视频文字稿（口播文案），终端展示 + Markdown 存档 + 可导出 Excel。

**支持的链接格式（视频链接必须包含视频 ID）：**

- 完整URL：`https://www.youtube.com/watch?v=dQw4w9WgXcQ`
- 短URL：`https://youtu.be/dQw4w9WgXcQ`
- 视频ID：`dQw4w9WgXcQ`

**默认行为（重要）：**

- 默认输出**不带时间戳**的纯文案；需要带时间戳版本时加 `--timestamp`
- 字幕按 `zh,en,asr` 优先级选轨：**视频有中文字幕轨时直接输出中文**；没有中文轨时回退英文，**脚本自动将非中文字幕翻译为中文**（基于 Google Translate，批量翻译提升效率）；加 `--no-translate` 可禁用自动翻译、保留原文
- 默认自动获取视频元数据（标题/频道），无需额外参数

> 需先配置 API Key，通过环境变量 REDFOX_API_KEY 或 --api-key 参数传入。
> 文字稿来源：视频字幕轨（手动字幕 + 自动生成字幕 asr），按语言优先级选轨、中文轨优先；非中文字幕由脚本端自动翻译为中文。

---

## 使用场景

当你需要执行以下任务时，应优先使用本技能：

| 场景 | 示例 |
|------|------|
| **视频转文字稿** | 丢一个 YouTube 链接，拿到完整口播文案 |
| **学习笔记整理** | 提取教程/演讲文案后让 AI 总结成章节笔记 |
| **内容二次创作** | 提取英文视频文案 → AI 翻译改写 → 公众号文章 |
| **播客/访谈存档** | 提取访谈全文，导出 Excel 归档 |
| **竞品内容分析** | 批量提取同行视频文案，分析话术与结构 |
| **视频选题调研** | 先提文案再快速判断视频是否值得深看 |

---

## 使用方法

```bash
# 基础提取（默认：不带时间戳 + 自动获取标题等元数据）
python3 "$SKILL_PATH/scripts/extract.py" "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 支持短链和纯视频 ID
python3 "$SKILL_PATH/scripts/extract.py" "https://youtu.be/dQw4w9WgXcQ"
python3 "$SKILL_PATH/scripts/extract.py" "dQw4w9WgXcQ"

# 带时间戳版本（方便定位原片进度）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --timestamp

# 同时导出 Excel（标题/时长/视频链接/文案内容 四列）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --excel

# 带时间戳文案 + 导出 Excel（Excel 内容与当前模式一致）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --timestamp --excel

# 指定语言优先级（如只要英文字幕）
python3 "$SKILL_PATH/scripts/extract.py" "URL" --language "en"

# 输出原始 JSON / 不保存文件 / 不获取元数据
python3 "$SKILL_PATH/scripts/extract.py" "URL" --json
python3 "$SKILL_PATH/scripts/extract.py" "URL" --no-save
python3 "$SKILL_PATH/scripts/extract.py" "URL" --no-metadata
```

终端输出：视频概要（标题/语言/片段数/总时长）+ 纯文案全文。

Markdown 存档默认保存在 `~/Downloads/QoderYoutubeDigest/`，文件名 `{视频ID}_{时间戳}.md`，含视频信息头表 + 全文；Excel（.xlsx）同目录。

---

## 工作流程（AI 必须遵循）

1. **提取**：运行脚本获取文案
2. **表格展示**：按「返回结果展示规范」用表格呈现（标题/时长/文案内容），文案内容列展示**中文译文全文**（无时间戳；非中文字幕已自动翻译）
3. **收尾询问**：展示结束后，**必须主动询问用户**：
   > 「需要带时间戳的文案版本吗（方便定位原片进度）？也可以为你导出 Excel。」
   - 用户要带时间戳 → 加 `--timestamp` 重跑并展示
   - 用户要 Excel → 加 `--excel` 重跑（如需时间戳一并加 `--timestamp`），给出文件路径

> 注意：脚本默认自动将非中文字幕翻译为中文。如用户明确要求保留原文，加 `--no-translate` 重跑。

---

## 返回结果展示规范

向用户展示提取结果时，**必须**使用以下表格，不得省略字段：

| 序号 | 字段 | 说明 |
|------|------|------|
| 1 | 标题 | 视频标题（来自元数据） |
| 2 | 时长 | 格式 `MM:SS` 或 `HH:MM:SS` |
| 3 | 文案内容 | **不带时间戳**的文案全文，非中文字幕已自动翻译为中文 |

**展示示例：**

```
| 标题 | 时长 | 文案内容 |
|------|------|----------|
| Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster) | 03:31 | 我们对爱情并不陌生 / 你知道规则，我也一样 / ……（中文译文全文） |
```

- 文案内容列：多段落文案在单元格内用「/」或换行衔接，保持完整不截断；非中文字幕已自动翻译为中文展示
- 表格后附一行存档信息：`已存档：~/Downloads/QoderYoutubeDigest/dQw4w9WgXcQ_xxx.md`

---

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `video_url` | YouTube 视频链接（完整URL/短URL/视频ID，必须含视频 ID，必填位置参数） | — |
| `--language` | 字幕语言优先级，逗号分隔（中文轨优先，`asr` 为自动生成字幕兜底；仅选轨不翻译） | `zh,en,asr` |
| `--timestamp` | 输出带 `[MM:SS]` 时间戳的文案 | 默认**不带**时间戳 |
| `--excel` | 同时导出 Excel（.xlsx，四列：标题/时长/视频链接/文案内容） | 不导出 |
| `--no-metadata` | 不获取视频元数据 | 默认获取（标题/频道） |
| `--json` | 终端输出原始 JSON 响应 | — |
| `--no-save` | 不保存 Markdown 文件 | 自动保存 |
| `--output-dir` | 输出目录 | `~/Downloads/QoderYoutubeDigest` |
| `--no-translate` | 禁用自动翻译，保留字幕原文输出 | 默认**自动翻译**非中文字幕为中文 |
| `--api-key` | 指定 RedFox API Key | — |

---

## API Key 配置

任选一种方式配置个人 Key：

| 方式 | 命令 |
|------|------|
| 环境变量（推荐） | `export REDFOX_API_KEY=ak_你的密钥` |
| 命令行参数 | `--api-key ak_你的密钥` |
| 配置文件 | `echo '{"api_key":"ak_你的密钥"}' > ~/.qoder/apis/redfox.json` |

注册地址：[redfox.hk](https://redfox.hk/settings/api-keys?source=github)

---

## 功能特点

- **三种输入格式**：完整 URL、`youtu.be` 短链、纯视频 ID，自动识别
- **默认纯文案**：不带时间戳，直接可读、可直接喂给 AI 二次加工；`--timestamp` 随时切换
- **自动翻译**：非中文字幕自动翻译为中文（基于 Google Translate），加 `--no-translate` 可保留原文
- **表格化交付**：标题/时长/文案内容三字段表格呈现，信息一目了然
- **Excel 导出**：`--excel` 一键导出 xlsx（自动换行、列宽适配），适合归档与分享
- **中文轨优先**：按 `zh,en,asr` 优先级选轨，有中文字幕直接输出中文；没有则回退英文轨并自动翻译为中文
- **稳健重试**：网络异常/状态码错误/数据为空自动递增延迟重试（0.5s→1.0s），限频（3108）自动等待 5 秒重试
- **AI 友好**：可衔接总结、翻译、改写、公众号排版发布等后续技能

---

## 依赖

```bash
pip3 install requests openpyxl deep-translator
```

（`openpyxl` 仅 Excel 导出需要；`deep-translator` 仅自动翻译需要；未安装时对应功能自动降级，其余功能不受影响）

---

## 常见问题

**Q：默认文案带时间戳吗？**
A：不带。默认输出纯文案；加 `--timestamp` 才输出 `[MM:SS]` 时间戳版本，提取结束后 AI 也会主动询问是否需要。

**Q：英文视频能直接给我中文文案吗？**
A：可以。脚本检测到非中文字幕时会自动翻译为中文（基于 Google Translate）。视频有中文轨时直接输出中文，没有中文轨时回退英文后自动翻译。如需保留原文，加 `--no-translate`。

**Q：Excel 里是什么内容？**
A：四列——标题、时长、视频链接、文案内容。文案内容与当前模式一致：加 `--timestamp` 时 Excel 内含时间戳，否则为纯文案。

**Q：为什么提取失败提示"视频可能无字幕"？**
A：文字稿来自视频字幕轨。完全无字幕（含自动生成字幕）的视频无法提取；部分受限/私享视频也不支持。

**Q：链接报错了怎么办？**
A：链接无效返回 `Invalid YouTube URL or video ID`（积分不扣除），请检查链接是否包含正确的视频 ID；Key 无效（3106/3107）请检查 API Key 配置；限频（3108）会自动等待重试。

**Q：拿到文案后能做什么？**
A：可以让 AI 直接总结成笔记、翻译成中文、改写成公众号文章（配合 gzh-design 排版、md-to-wechat 一键推送草稿）。

**Q：额度用完怎么办？**
A：前往 [redfox.hk](https://redfox.hk/settings/api-keys?source=github) 注册获取 Token。