youtube-publisher

🔴 严格执行规则（最高优先级）

必须严格按照原文遵循本 SKILL.md 中的每条指令、步骤和检查，不得有任何偏差。

• 必须实际运行脚本：必须使用所有必需参数运行 youtube-upload.ts 脚本。不得模拟或手动构造 API 调用。
• 不得跳过或合并步骤：按照规定顺序执行身份验证、元数据清理和上传。每个步骤都必须成功后，才能开始下一步。
• 不得省略检查：必须完整执行所有元数据验证（标题 ≤100 个字符、描述 ≤5000 个字符、标签 ≤500 个字符）和上传验证。
• 必须从文件读取配置：必须从已配置的文件中读取 OAuth 凭据和默认设置。不得硬编码。

---

YouTube 发布器

首次使用？ 如果上方的 setup_complete: false，请先运行 ./SETUP.md，然后将 setup_complete: true。

上传视频到 YouTube，并全面控制元数据。

直播和编码器流

使用 youtube-live.ts 列出、检查、安排、更新、绑定、切换和删除 YouTube Live 直播及编码器流。修改命令支持 --dry-run；删除、切换直播/已完成状态以及公开流密钥均需要显式指定 --yes。常规输出会隐藏流密钥。

安全的默认做法是为每场独立节目/活动使用一个专用的命名编码器流。若要在进行中或即将开始的多个直播间有意共用流，必须指定 --allow-shared-stream。

操作直播活动前，请阅读 references/live-streaming.md。计划时间戳必须包含明确的时区（Z 或 ±HH:MM）。

除非用户要求使用干净配置，否则该技能会在创建前传入 --inherit-previous。若未显式指定此标志，原始 CLI 会保持确定性且离线运行。

youtube-upload.ts 不会在进程中断后重试视频插入操作。恢复时必须找到且仅找到一个标题相同、近期上传且已验证时长非零的视频。若持续返回 P0D，则以 42 退出，并返回 PERSISTENT_P0D_VIDEO_ID；若无法检查或检查结果不明确，则以 43 退出，并返回 AMBIGUOUS_UPLOAD_VIDEO_ID。再次插入前，请检查频道。

字幕恢复会原位更新一条语言/名称完全匹配的字幕轨道，或插入新轨道。替换字幕上传成功前，不会删除任何现有字幕。

元数据清理

• 标题/描述中的 > 会自动改写为 》
• 标题/描述中的 < 会自动改写为 《
• YouTube 因特殊字符拒绝元数据时，可使用此功能

快速开始

cd ~/.claude/skills/youtube-publisher/scripts

# First time: authenticate
npx ts-node youtube-upload.ts --auth

# Upload video
npx ts-node youtube-upload.ts \
  --video /path/to/video.mp4 \
  --title "My Awesome Video" \
  --description "Check out this amazing content!" \
  --tags "tech,ai,tutorial" \
  --privacy unlisted

# Upload as YouTube Short (vertical video)
npx ts-node youtube-upload.ts \
  --video /path/to/short.mp4 \
  --title "Quick Tip #Shorts" \
  --description "A quick tip for you!" \
  --privacy public \
  --short

选项

选项	简写	描述
--video	-v	视频文件路径（必需）
--title	-t	视频标题（必需）
--description	-d	视频描述
--tags		逗号分隔的标签
--privacy	-p	隐私设置：public、unlisted、private（默认：unlisted）
--category	-c	类别 ID（默认：22 = 人物与博客）
--thumbnail		自定义缩略图（本地路径或 URL）
--subtitles		字幕文件路径（SRT/VTT）
--subtitle-lang		字幕语言代码（默认：zh）
--subtitle-name		字幕显示名称（默认：中文）
--short		标记为 YouTube Short
--auth		运行 OAuth2 身份验证流程
--dry-run		预览但不上传

播放列表目录导出

导出经过身份验证的频道拥有的所有公开播放列表，包括有序的视频 ID 和缩略图。博客同步器会使用此确定性 JSON 构建 /series/、GitHub 系列页面和资源网站指南中心。

此命令为只读。作者会在请求最终通知前手动维护播放列表成员；export-playlists.ts 绝不能添加、移除、重新排序或推断播放列表成员。通知流水线会重新执行导出、部署博客主题页面，并在发送通知前验证其公开指纹。

cd ~/.codex/skills/youtube-publisher/scripts
npm run export:playlists -- --output /absolute/path/youtube-playlists.json

类别 ID

ID	类别
1	电影与动画
2	汽车与车辆
10	音乐
15	宠物与动物
17	体育
19	旅游与活动
20	游戏
22	人物与博客
23	喜剧
24	娱乐
25	新闻与政治
26	教程与风格
27	教育
28	科学与技术

身份验证

首次设置需要 OAuth2 身份验证：

1. 运行 npx ts-node youtube-upload.ts --auth
2. 浏览器会打开 Google 登录页面
3. 授予上传视频的权限
4. 令牌会保存到 .youtube-token.json

令牌会自动刷新。如果令牌过期，请重新运行 --auth。

环境

创建 scripts/.env：

YOUTUBE_CLIENT_ID=your_client_id
YOUTUBE_CLIENT_SECRET=your_client_secret

从 Google Cloud Console 获取凭据：

1. 在 console.cloud.google.com 创建项目
2. 启用 YouTube Data API v3
3. 创建 OAuth2 凭据（桌面应用）
4. 下载并提取 client_id 和 client_secret

示例

上传教程视频

npx ts-node youtube-upload.ts \
  -v tutorial.mp4 \
  -t "How to Use Claude Code - Complete Guide" \
  -d "Learn everything about Claude Code in this comprehensive tutorial.

Timestamps:
00:00 Introduction
02:30 Getting Started
05:00 Advanced Features

#ClaudeCode #AI #Tutorial" \
  --tags "claude code,ai,tutorial,anthropic,coding" \
  --category 28 \
  --privacy public

上传 YouTube Short

npx ts-node youtube-upload.ts \
  -v short_video.mp4 \
  -t "Mind-blowing AI trick! #Shorts" \
  -d "This will change how you work! #AI #Tech" \
  --privacy public \
  --short

上传视频并添加缩略图和字幕

npx ts-node youtube-upload.ts \
  -v tutorial.mp4 \
  -t "Tutorial with Subtitles" \
  -d "Learn step by step with subtitles" \
  --thumbnail /path/to/cover.jpg \
  --subtitles /path/to/subtitles.srt \
  --subtitle-lang zh \
  --subtitle-name "中文" \
  --privacy public

上传视频并添加本地缩略图

npx ts-node youtube-upload.ts \
  -v video.mp4 \
  -t "My Video Title" \
  --thumbnail "/Users/m/Downloads/shell/work/cover.jpg" \
  --privacy public

仅重试失败的缩略图

如果视频已存在，且只需重新上传其自定义缩略图，请使用专用恢复命令。该命令会验证视频 ID 和本地 JPG/PNG 文件，重试临时性故障，验证目标视频可读取，并打印结构化结果标记。

npx ts-node upload-thumbnail.ts \
  --video-id VIDEO_ID \
  --thumbnail /path/to/cover.jpg \
  --attempts 3

此命令绝不会删除或上传视频。不要创建带有硬编码视频 ID 或本地路径的一次性恢复脚本。

输出

成功时返回：

• 视频 ID
• 视频 URL（https://youtu.be/VIDEO_ID）
• 状态

限制

• 最大文件大小：256GB（YouTube 限制）
• 支持的格式：MP4、MOV、AVI、WMV、FLV、3GP、MPEG
• 支持的字幕格式：SRT、VTT
• 每日上传配额：10,000 单位（通常约为每天 6 个视频）
• 标题最多：100 个字符
• 描述最多：5,000 个字符
• 标签总计最多：500 个字符

更新日志

v1.7.1 - 未知标志快速失败（2026-09-28）

• youtube-update-description.ts v1.8（2026-10-01）章节显示契约门禁：上传前校验描述里的章节块必须满足 YouTube 硬规则（首章 0:00 / 每章 ≥10 秒 / ≥3 章），违规拒绝上传并 exit 3（列出具体违规）。原因：任一条不满足时 YouTube 静默忽略整份章节列表——描述看着正常、播放轴却没有章节（2026-10-01 charles_schwab 0:00/0:01 相邻 1 秒，18 章全废）。描述里完全没有章节块时只打 WARN 不拦。修复用 duanku-youtube-publish/scripts/split_description_chapters.py（内置自愈）/ 复检 --validate。
• youtube-update-description.ts 遇到未知 -- 参数直接报错退出（exit 2），不再静默忽略。背景：当日测试 --dry-run（不存在的 flag）被静默吞掉，截断的测试文件真实上传；fail-fast 杜绝同类误操作。

v1.7.0 - 基线标题上传防护（2026-09-28）

• youtube-update-description.ts 现在会在上传前自动剥离 duanku 基线头：--description-file 内容若以 # YouTube description baseline 开头（run_pipeline v2.46+ 落盘的人工 diff 参照文件），去掉头部注释块后上传并打印 NOTE: stripped baseline header before upload (v1.7 guard)。
• 背景：9/15(tello)/9/27(capital_one)/9/28(maya) 三次 agent 驱动的描述编辑把带头的基线文件原样重传，6 行 # 注释泄漏到线上 YouTube 说明区（tello/capital_one 由用户手工清除，maya 已由本版本修复）。守卫落在上传口，此后任何调用路径都无法再把头推上线。

v1.6.0 - 安全的仅缩略图恢复（2026-07-28）

• 添加了 upload-thumbnail.ts，支持参数校验、有界重试、目标视频验证和结构化输出。
• 移除了同时删除固定视频 ID 的硬编码缩略图修复脚本。
• 扩展了生产环境 TypeScript 门禁，涵盖缩略图恢复命令。

v1.1 - 可恢复上传 + 重试（2026-04-22）

• 通过切换到带进度跟踪的可恢复上传，修复了大文件上传时的 EPIPE 错误
• 针对暂时性网络错误（EPIPE、ETIMEDOUT、ECONNRESET）添加了自动重试（最多 3 次）
• 添加了上传进度日志（每 10% 记录一次）
• 添加了 media.mimeType，以提高上传兼容性

v1.0 - 初始版本

• 支持基本的视频上传和元数据
• 支持缩略图、字幕和播放列表
• OAuth2 身份验证