scout

用途

Scout 面向 YouTube 选题与频道调研。输入一个主题，脚本完成搜索、排序、数据整理，输出一个 Excel 工作簿（.xlsx）。官方定位是“一个主题进，一个排序好的调研工作簿出”：脚本负责全部工作，使用者只需用正确的参数运行，再把结果转述出去。

主要能力

• 主题搜索与排序：调用 YouTube Data API v3 搜索相关视频，排序方式包括 views（播放量）、engagement（互动）、likes（点赞）、recent（最新）、momentum（每日播放量）、breakout（播放量/订阅数）。
• 筛选条件：--since 支持 hour、today、week、month、year、any；--length 支持 short（4 分钟以内）、medium（4–20 分钟）、long（20 分钟以上）。
• 评论抓取：--comments [N] 抓取每个视频的前 N 条评论（默认 20），写入 Comments 工作表，并在视频行附加 Top Comment。
• 钩子与字幕探测：--hooks [SECONDS] 用 yt-dlp 逐视频探测，不消耗 API 配额，产出 Hook（字幕开头若干秒，默认 15）、Vertical、FPS、Most Replayed s、Replay Hotspots、Chapters，以及完整 Transcripts 工作表。
• 本地转写：--transcribe [MODEL] 对无字幕视频用本地 Whisper 转写（默认模型 turbo，建议 GPU），补齐 Hook、Transcript Words、Transcript Source 等字段。
• 下载：--download [N] 保存所有视频缩略图，并下载前 N 个视频的 mp4 到 ./downloads/。
• 追加合并：--into PATH 将结果追加到已有工作簿的 Videos 工作表，跳过已存在的 Video ID 并重新排序，同时创建或扩展 Comments、Transcripts 工作表；写入前会在文件旁生成带时间戳的 .backup- 备份，要求文件未在 Excel 中打开。
• 其它选项：--dry-run 只获取并打印；--json 额外以 JSON 输出行数据；--out PATH 指定新工作簿路径。

使用方式

1. 运行：

python3 "${CLAUDE_SKILL_DIR}/scripts/scout.py" <topic words> [flags]

主题词放在脚本后（引号可选，脚本会拼接）。 2. API Key 读取顺序：环境变量 YOUTUBE_API_KEY → SCOUT_ENV_FILE 指定的文件 → ~/.config/scout/.env → ./.env。若密钥在其它 env 文件，应先在环境中加载（例如 set -a; . <keyfile>; set +a），不要把密钥复制到别处，也不要回显密钥。 3. 若提示缺少 openpyxl，执行一次：

pip install -r "${CLAUDE_SKILL_DIR}/requirements.txt" --quiet

1. 参数默认值：--max 50（1–200，每 50 个视频消耗 100 次日搜索调用中的 1 次）、--since any、--length any、--sort views、--out ./scout-<topic>-<date>.xlsx；--comments、--hooks、--into、--download、--transcribe、--dry-run、--json 默认关闭。
2. 运行后转述：输出路径与工作表清单（或 --into 时的新增/跳过行数）、Top 10 表格、配额使用（每日 100 次搜索、10000 单位）与警告行；再从 Summary 表和表格中提炼两三条可行动的观察（如 Shorts 占比、高播放/订阅比的爆发创作者、反复出现的钩子模式）。

输出结构

• Videos：基础列参考 OWT-Social-Ads.xlsx（Platform、Creator、Handle、Video ID、Video Link、Posted、Views、Likes、Comments、Shares、Engagement %、Duration s、Spark Code、Local File、Sheet Views、Ad Status），新工作簿会省略整列为空的列；随后附 Performance（Title、Published、Relevance #、Format、Age d、Views/day、Views/Sub、Like %、Comment %）、Channel（Channel URL、Subscribers、Channel Videos、Channel Views、Avg Views/Video、Country、Created、Keywords、Topics）、Metadata（Category、Tags、Language、Captions、HD、Licensed、Embeddable、Made for Kids、Paid Promotion、AI Disclosure、License、Live、Topics、Blocked Regions、Description 前 300 字符、Desc Links、Location、Thumbnail）等分组。
• Channels：样本中每个频道一行，按样本播放量排序，含频道总量、国家、创建时间、样本视频数、样本播放量、平均互动、最佳视频及链接、关键词、主题，可作为创作者外联名单。
• Summary：主题、运行日期、筛选条件、配额、总量、播放量中位数与均值、平均互动、时长中位数、Shorts 占比、付费推广占比、字幕占比、发布时间范围、顶级视频、顶级频道、热门标签、分类、语言、频道国家。
• Comments（按需）：Video ID、Handle、Title、Author、Comment、Likes、Replies、Published、链接。
• Transcripts（按需）：Video ID、Handle、Title、Language、Source、Transcript Words、Hook、完整 Transcript（上限 32000 字符）、链接。 新工作簿只含 Channels 和 Summary；--into 模式不生成这两张表，因为对混合数据聚合会误导。

适用场景

内容选题调研、竞品与热门视频分析、Shorts 与长视频对比、创作者外联名单整理、钩子与字幕素材收集、按主题持续追加到既有调研表。

限制与注意事项

• 依赖 YouTube Data API，受每日 100 次搜索、10000 单位配额限制；配额用尽需等到太平洋时间午夜重置。
• Shares、Spark Code、Sheet Views、Ad Status 在 YouTube 行中保持空白：YouTube API 不提供分享数，其余为手动列。Engagement % 计算为（点赞+评论）/播放量。
• 他人视频的点击率、留存、曝光、受众人口统计不可得；--hooks 的回放热力图是公开数据中最接近留存的代理。
• YouTube 未发布热力图的视频（播放量不足）回放列留空；视频完全没有字幕时 Hook 与 Transcript 留空，部分覆盖属正常。
• --hooks 缓存 yt-dlp 探测与字幕到 ~/.cache/scout/ 7 天；字幕下载可能触发 HTTP 429，脚本以 1.5 秒间隔并退避重试，仍失败会给出计数警告，该限制按 IP 生效、可能持续数小时，可用 --transcribe 本地补齐或稍后重跑。
• 环境变量 SCOUT_CAPTION_DELAY、SCOUT_CACHE_DIR、SCOUT_DOWNLOAD_FORMAT 可覆盖抓取间隔、缓存位置与下载格式（默认 480p 视频与音频合流为 mp4）。
• 退出码：0 成功；1 参数错误；2 无 API Key；3 配额耗尽；4 API Key 无效；5 其它 API 或网络错误；6 文件错误（--into 文件缺失或未安装 openpyxl）。
• 全量演示可用 --comments --hooks --transcribe --download 10；50 个视频开启 --hooks 的完整运行需数分钟，应预留较长超时。部分字段（AI Disclosure、Live、Blocked Regions、Location、Paid Promotion）通常为空，Tags 在创作者未添加时为空。