youtube-video-search

用途

youtube-video-search 的核心目标是检索公开的 YouTube 视频，用于主题或领域发现。它通过显式的查询字符串执行搜索，并支持可选的频道过滤与发布时间窗口过滤。检索到的视频可以使用 videos.list 补充元数据与统计数据。技能返回机器可读的 JSON，并可选地保存 JSONL 候选视频产物。执行过程通过结构化日志和可选日志文件保持可观测。

主要能力

使用 search.list 搜索公开 YouTube 视频。
支持基于灵活查询字符串的领域发现，并可附加可选的频道与时间过滤条件。
使用 videos.list 的元数据与统计数据对发现的视频进行 enrichment（补充信息）。
返回机器可读的 JSON，并可选保存 JSONL 候选产物。
通过结构化日志与可选日志文件保持执行可观测。
内置健壮性机制：对瞬时失败进行指数退避重试；遵守 Retry-After，并在其超过配置上限时快速失败；通过最小请求间隔限制请求速率；执行运行安全上限（最大页数、最大结果数、最大 enrichment 视频数）；对传输进行校验（JSON 内容类型、UTF-8 解码、JSON 对象解析）；对结构进行校验（搜索响应结构、videoId 是否存在及 datetime 字段、详情批次的完整性及重复 ID）。
输出 JSON 结果，同时将操作日志写入 stderr 与可选日志文件。

使用方式

必需环境

通过环境变量配置运行时（参见 references/env.md）。从 assets/config.example.env 开始，并将真实密钥保存在 assets/config.env 中。运行命令前加载环境变量：

set -a
source assets/config.env
set +a

工作流

校验有效配置：

python3 scripts/youtube_video_search.py check-config --pretty

先对搜索计划做 dry-run：

python3 scripts/youtube_video_search.py search \
  --query "climate change pollution" \
  --published-after 2026-03-01 \
  --published-before 2026-03-08 \
  --order date \
  --max-pages 2 \
  --max-results 50 \
  --dry-run \
  --pretty

运行领域搜索并保存候选视频，供下游评论抓取使用：

python3 scripts/youtube_video_search.py search \
  --query "climate change pollution" \
  --published-after 2026-03-01 \
  --published-before 2026-03-08 \
  --order date \
  --max-pages 4 \
  --max-results 120 \
  --comment-count-min 20 \
  --output-dir ./data/youtube-videos \
  --log-level INFO \
  --log-file ./logs/youtube-video-search.log \
  --pretty

OpenClaw 调用兼容性

将触发元数据保留在 name、description 和 agents/openai.yaml 中。
使用 $youtube-video-search 调用。
保持技能原子化：每次调用只执行一个查询。
使用脚本参数设置检索条件（--query、发布时间窗口、频道过滤、上限）。
将其 JSONL 输出通过 --video-ids-file 直接喂给 $youtube-comments-fetch。

OpenClaw 提示模板可直接在 OpenClaw 中使用，只需替换方括号中的占位符。

Recon（查询计划检查）模板：

Use $youtube-video-search.
Run:
python3 scripts/youtube_video_search.py search \
  --query "[QUERY_STRING]" \
  --published-after [YYYY-MM-DDTHH:MM:SSZ] \
  --published-before [YYYY-MM-DDTHH:MM:SSZ] \
  --order date \
  --max-pages [N] \
  --max-results [M] \
  --dry-run \
  --pretty
Return only the JSON result.

Search（候选视频）模板：

Use $youtube-video-search.
Run:
python3 scripts/youtube_video_search.py search \
  --query "[QUERY_STRING]" \
  --published-after [YYYY-MM-DDTHH:MM:SSZ] \
  --published-before [YYYY-MM-DDTHH:MM:SSZ] \
  --order date \
  --max-pages [N] \
  --max-results [M] \
  --comment-count-min [K] \
  --output-dir [OUTPUT_DIR] \
  --pretty
Return only the JSON result.

Chain（为下游评论抓取做准备）模板：

Use $youtube-video-search.
Run:
python3 scripts/youtube_video_search.py search \
  --query "[QUERY_STRING]" \
  --published-after [YYYY-MM-DDTHH:MM:SSZ] \
  --published-before [YYYY-MM-DDTHH:MM:SSZ] \
  --order date \
  --max-pages [N] \
  --max-results [M] \
  --output-dir [OUTPUT_DIR] \
  --pretty
Take artifacts.output_jsonl and pass it to $youtube-comments-fetch as --video-ids-file.
Return JSON plus the artifact path.

范围决策

保持单一原子操作：公开视频发现加上可选的详情 enrichment。
由 OpenClaw 决定查询策略，并通过重复调用来迭代。
不在本技能中嵌入调度/轮询循环或评论抓取。

参考

references/env.md
references/youtube-search-api-notes.md
references/youtube-limitations.md
references/openclaw-chaining-templates.md
scripts/youtube_video_search.py

适用场景与限制

适用于按主题或领域检索公开 YouTube 视频、按发布时间窗口与频道过滤筛选候选视频、为下游评论抓取准备视频 ID 列表，以及在 OpenClaw 中以多次原子调用组合检索流程。限制方面：单次调用只执行一个查询，不包含调度/轮询循环与评论抓取；具体收费、价格、平台支持范围与效果等事实暂未提供。