wjs-uploading-video

将已完成的视频推送至 YouTube。默认配置已针对该用户的实际工作流进行调优（王建硕频道、中国大陆网络环境 + 本地代理、Riverside 或多机位剪辑产出的 1080p 横屏视频）。

适用场景

• 用户已有一个或多个完成的 .mp4 文件，希望上传至 YouTube
• 用户指定一个包含多个分段视频的 final/ 目录，并附带一份 UPLOAD_META.md
• 用户需要自定义隐私设置 / 播放列表归属 / 定时发布

不适用于：

• 微信视频号上传（无公开 API；用户需通过网页手动上传）
• 抖音 / 小红书 / B 站（使用不同 API，当前尚未在此技能中实现）
• 从横屏源素材生成 YouTube Shorts 变体（请先使用 wjs-reframing-video 产出 9:16 构图裁切版本，再通过本技能上传该文件）

前置条件（每台机器仅需配置一次）

1. Google Cloud OAuth 客户端凭证：~/.config/youtube/credentials.json 文件必须存在。若缺失，请参考 references/credentials-setup.md 中的 5 分钟快速配置指南。
2. Python 依赖：pip3 install google-auth-oauthlib google-api-python-client requests（上传阶段严格只需 google-auth 和 requests，但 google-auth-oauthlib 会自动拉取这两者）。
3. 首次上传会自动打开浏览器完成 Google 授权流程，并写入 ~/.config/youtube/token.json；后续运行将静默复用该 token。

工作原理（以及为何不直接使用官方 youtube-uploader）

YouTube 的可恢复上传协议（resumable upload protocol）在完成元数据 POST 后会返回一个 Location: URL，随后通过分块 PUT 请求上传视频字节流。官方 google-api-python-client 库基于 httplib2 实现该流程，但在本用户当前的本地 SOCKS+HTTP 代理链路下，后续的 PUT 请求常因 [Errno 65] No route to host 或 socket.timeout 而失败，导致上传无限挂起。

本技能绕过 httplib2：使用 google-auth 完成 OAuth 认证，再通过 requests 手动驱动可恢复上传流程，并显式传入代理配置。采用 8 MB 分块（非默认的 256 KB），显著减少经代理的往返次数；对 socket.timeout / ConnectionError / 5xx 响应启用指数退避重试机制。

若您考虑“直接调用 YouTube API 客户端”，请勿尝试——在此环境中必然失败。

使用方法

批量上传 final/ 目录

python3 ~/.claude/skills/wjs-uploading-video/scripts/upload_youtube.py 
  --dir "/path/to/final" 
  --meta "/path/to/final/UPLOAD_META.md"

脚本执行逻辑如下：

1. 读取 UPLOAD_META.md，将每个 ## NN · filename.mp4 区块与 --dir 下对应文件匹配
2. 跳过已在 --results-file（默认为 /.youtube_upload_results.json）中记录的视频——支持失败后安全重试
3. 按顺序上传，每传输 8 MB 输出一次进度
4. 将最终生成的视频 URL 列表写入 --results-file

单文件上传

python3 ~/.claude/skills/wjs-uploading-video/scripts/upload_youtube.py 
  --video /path/to/clip.mp4 
  --title "My Title" 
  --description "Body text" 
  --tags "tag1,tag2,tag3"

常用覆盖参数

UPLOAD_META.md 格式规范

解析器预期用户采用如下标准结构：

## 01 · segment_01_no-bugs.mp4

**短标题**
代码没有错误,只有意图不一致

**视频描述**
AI 时代屎山的重新定义...

—— 王建硕 × 任鑫《...》第 1 集

#王建硕 #AI编程 #ClaudeCode

---

映射规则：

• ## NN · → 标识该区块所描述的视频文件
• **短标题**（或 **Title**）区块 → 直接作为 YouTube 视频标题（逐字保留）。短标题可用，但请注意 YouTube 标题上限为 100 字符；如需更丰富的标题（含系列名等），请直接在 **短标题** 中完整写出
• **视频描述**（或 **Description**）区块 → 直接作为 YouTube 视频描述（逐字保留），底部的 #tag 标签一并保留
• 视频描述 中所有 #word 形式的词 → 提取为 YouTube 标签（tags），以英文逗号分隔（自动去除 # 符号；根据全局指令，用户频道名 王建硕 将被自动前置）

标题中的文件名必须与 --dir 下真实存在的文件完全匹配。若某文件存在但无对应元数据区块，脚本将报错退出；此时可添加 --allow-missing-meta 参数，以文件基础名（basename）为标题、空描述进行上传。

本技能内置的合理默认值

• 隐私设置 = unlisted（不公开）：便于用户上传后先行审核，确认无误后再于 YouTube Studio 中设为公开（或直接传参 --privacy public）
• 分类 = 28（科技）：契合 王建硕 频道主要内容定位；可通过 --category 单次覆盖
• selfDeclaredMadeForKids = false：YouTube 强制要求声明；用户内容面向成人受众
• 分块大小 = 8 MB：经用户本地代理环境实测验证的有效值（256 KB 易导致挂起）
• 跳过已上传项：以 --results-file 为唯一可信来源；删除该文件可强制重新上传

频道名称 CTA 规则

若在视频元数据中撰写描述末尾、签名栏或“订阅我”类引导语，请统一使用 王建硕（即用户频道名）。切勿在此处填写嘉宾姓名——例如 任鑫 作为对话嘉宾，其姓名应仅出现在描述正文内，不得置于频道级 CTA 位置。

故障排查

上传完成后

• 结果保存至 --results-file（JSON 格式，含文件名、标题、video ID、URL）
• 以 Markdown 表格形式向用户回显 URL 列表
• 提醒用户视频默认为 unlisted 状态，并建议其在 YouTube Studio 中确认无误后切换为公开
• 若用户提及“合集”或“系列”，可主动提供创建 YouTube 播放列表并批量加入新上传视频的服务（需用户提供播放列表 ID，或由您代为新建）