Youtube Digest Agent Skill

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 归档 |

| 竞品内容分析 | 批量提取同行视频文案，分析话术与结构 |

| 视频选题调研 | 先提文案再快速判断视频是否值得深看 |

使用方法

# 基础提取（默认：不带时间戳 + 自动获取标题等元数据）
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 必须遵循）

• 提取：运行脚本获取文案
• 表格展示：按「返回结果展示规范」用表格呈现（标题/时长/文案内容），文案内容列展示中文译文全文（无时间戳；非中文字幕已自动翻译）
• 收尾询问：展示结束后，必须主动询问用户：

> 「需要带时间戳的文案版本吗（方便定位原片进度）？也可以为你导出 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

功能特点

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

依赖

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 注册获取 Token。