| name | research-collector |
| description | Use when the user wants to collect research material for an article or topic by gathering YouTube videos and web articles into a NotebookLM notebook, then running analysis queries and saving results as markdown. Best for "收集素材"、"给我找这个话题的相关视频和文章"、"整理成 NotebookLM 分析" type requests. Combines yt-dlp YouTube search, NotebookLM `nlm` CLI research, and markdown report output. |
Research Collector
这个 skill 只做一件事:
- 为某个主题批量收集 YouTube 视频 + 网页文章,喂进 NotebookLM,跑分析查询,把结果落地到本地目录(默认
./research/<topic>/,可配置)
不负责:
- 写成品文章(交给你自己的写作工具 / skill)
- 选主标题
- 下载视频(交给本仓库里的
yt-dlp-direct skill)
- 发布到多平台(交给本仓库里的
publisher-wechatsync skill)
一句话原则:用户说"帮我收集 X 话题的素材"或"拉一批 YouTube + 文章到 NotebookLM",就走这条固定流水线,不要每次重新设计。
When To Use
适用场景:
- 用户要为某个话题写推荐/测评/观点文,需要先做背景研究
- 用户说"帮我找 X 的热门 YouTube 视频和文章"
- 用户说"收集到 NotebookLM 里分析"
- 用户说"给我整理一份 X 话题的素材研究"
不适用场景:
- 用户已经有明确素材清单,只想要总结 → 直接跑
nlm notebook query
- 用户要做的是实时对话研究,不需要持久化到 notebook → 用 WebSearch + WebFetch
- 用户只要下载单个视频 → 用
yt-dlp-direct
Preconditions
开始前必须确认:
nlm CLI 已安装且登录:nlm login --checkyt-dlp 在 PATH 中:which yt-dlp- 用户明确说明了主题和角度
- 输出目录可写(默认
./research/<topic>/,可以通过 RESEARCH_OUTPUT_DIR 环境变量或对话里直接指定其他路径)
前置不满足时:
nlm login --check 失败 → 让用户跑 nlm login,session 有效期 ~20 分钟yt-dlp 没装 → 停止并告诉用户
Working Rules
- 先和用户对齐主题、角度、量级,再动手
- 每轮 ytsearch 默认 15 条,可以根据需要调整
- NotebookLM deep research 一次只能跑一个任务,不能并发
- 添加 source 时每条之间 sleep 2 秒,避免限流
- 所有产出(原始 JSON + 汇总 markdown)落到
./research/<topic>/ 下(或用户指定的目录)
- 这个 skill 只负责收集和分析,不要擅自接着写成品文章
- 不要删 notebook,用户后面可能还要回去跑 query
Core Workflow
Phase 0: 对齐目标
在动手前必须和用户明确:
- 主题是什么(要一句话能喂给 ytsearch 的关键词)
- 角度(比如"最常用 + 个人创作" vs "最新发布 + 技术细节")
- 笔记本命名(默认
<主题> 素材)
- 量级(默认:15 油管 + deep research 自动 ~40 网页)
Phase 1: 创建笔记本 + 设 alias
nlm notebook create "<话题> 素材"
nlm alias set <short-name> <notebook-id>
alias 取短名,比如 skills-research、vps-2026,后续所有命令都用 alias。
Phase 2: yt-dlp ytsearch 找热门 YouTube
并行跑 2-3 个不同角度的搜索,每个 15 条:
yt-dlp --simulate --print "%(title)s|%(webpage_url)s|%(view_count)s|%(uploader)s" \
"ytsearch15:<关键词 A>"
yt-dlp --simulate --print "%(title)s|%(webpage_url)s|%(view_count)s|%(uploader)s" \
"ytsearch15:<关键词 B>"
输出里的 JS runtime warning 可以忽略。
从结果里按以下规则筛 top 15:
- 去重(同一视频出现在多个搜索里)
- 优先官方账号(比如 Anthropic、OpenAI 等)
- 按 view count 从高到低,但要留 2-3 个垂直向角度的中腰部视频,避免全是爆款通稿
- 每个角度至少保留 5 条
Phase 3: 把 YouTube 加为 source
用 bash 循环逐条加,每次 sleep 2 秒:
cat > /tmp/yt_urls.txt <<'EOF'
https://www.youtube.com/watch?v=XXX1
https://www.youtube.com/watch?v=XXX2
...
EOF
while IFS= read -r url; do
echo "=== Adding: $url ==="
nlm source add <alias> --url "$url" 2>&1 | tail -5
sleep 2
done < /tmp/yt_urls.txt
偶尔会遇到单条失败(视频不公开、区域限制),忽略继续,最后报告成功率。
Phase 4: 跑 NotebookLM deep research 发现网页文章
nlm research start "<英文查询,适合 web 研究>" \
--notebook-id <alias> --mode deep
deep 模式 ~5 分钟,返回 ~40 条网页源。
关键:一个 notebook 同一时间只能有一个 research 任务在跑。如果要跑第二轮,必须等第一轮 import 完或 --force。
等待完成:
nlm research status <alias> --max-wait 360
Bash 工具默认 timeout 120 秒,必须加 timeout: 400000(即 400 秒)。
Phase 5: 导入 research 结果
研究完成后从输出里拿 task-id,然后:
nlm research import <alias> <task-id> --timeout 600
Bash 工具加 timeout: 700000。
注意:用户有时会说"素材够了,不用再导入",要停下来直接进 Phase 6。
Phase 6: 跑 3 个分析查询
默认跑 3 个角度,命令直接重定向到文件避免输出过大:
mkdir -p "./research/<topic>"
nlm notebook query <alias> "<问题 1 的中文提示>" \
> "./research/<topic>/query1-<slug>-raw.json" 2>&1
nlm notebook query <alias> "<问题 2 的中文提示>" \
> "./research/<topic>/query2-<slug>-raw.json" 2>&1
nlm notebook query <alias> "<问题 3 的中文提示>" \
> "./research/<topic>/query3-<slug>-raw.json" 2>&1
每个 query 的 Bash 调用要加 timeout: 240000。
默认 3 个查询模板(按需改关键词):
- Top 清单:"基于所有 source,请列出被最多来源推荐的 Top 10 X。对每个 X 说明:(1) 名称 (2) 具体做什么 (3) 主要使用场景 (4) 推荐它的来源数量 (5) 类型分类。按推荐频率从高到低,用中文输出。"
- 目标读者向:"我要写一篇面向 <读者画像> 的文章。请筛选出对 <读者> 最有帮助的 Top 8 X,每个说明:(1) 名称 (2) 具体痛点 (3) 典型用法一句话 (4) 类型 (5) 最具体的来源编号。去掉不相关的,聚焦 <场景>,用中文。"
- 入门 + 坑:"针对 <读者> 使用 X 时,请总结:(1) 最快入门方式 (2) 去哪里获取 (3) 最容易踩的 5 个坑 (4) 什么时候其实不需要 (5) 最新的重要更新。每点配来源编号,用中文。"
Phase 7: 抽取 answer 字段,生成汇总 markdown
原始输出是 JSON 包含 answer + citations,用 Python 抽 value.answer 字段:
python3 <<'PY'
import json, pathlib
base = pathlib.Path("./research/<topic>")
files = [
("query1-<slug>-raw.json", "## Query 1:<标题>"),
("query2-<slug>-raw.json", "## Query 2:<标题>"),
("query3-<slug>-raw.json", "## Query 3:<标题>"),
]
out = ["# <话题> 素材研究", "",
"> 基于 NotebookLM 笔记本 `<notebook-name>` 的分析结果", "",
"---", ""]
for fname, heading in files:
out.append(heading)
out.append("")
raw = (base/fname).read_text()
try:
data = json.loads(raw)
out.append(data.get("value",{}).get("answer",""))
except Exception as e:
out.append(f"(解析失败: {e})")
out.append("")
out.append("---")
out.append("")
(base/"素材研究汇总.md").write_text("\n".join(out))
print("Written:", (base/"素材研究汇总.md").stat().st_size, "bytes")
PY
Output Contract
执行完要给用户报告:
- Notebook 名字 + alias + 实际 source 数量
- 3 份 raw JSON 和 1 份汇总 markdown 的落盘路径
- 失败/跳过的 source(如果有)
- 汇总文件的头部预览(前 20 行左右)
- 建议的下一步(交给用户决定下游怎么用,本 skill 到此结束)
Safety and Boundaries
- 不要默认跑 audio/video/slides 生成,这些费配额,用户没要就不碰
- 不要自动跑第二轮 research,一轮够用绝大多数场景
- 不要覆盖已有的
素材研究汇总.md,如果存在先追加 -v2
- 研究查询里不要塞用户私密信息(notebook 是可搜索的)
Troubleshooting
nlm login 失效
nlm login --check
nlm login
session 有效期约 20 分钟。
yt-dlp 搜索结果没输出
先看版本:
yt-dlp --version
如果太旧提示用户更新。JS runtime / ffmpeg 的警告可以忽略,不影响 --simulate 模式。
research 超时或卡住
单独查状态(不阻塞):
nlm research status <alias> --max-wait 0
如果 status 一直是 in_progress 超过 10 分钟,用 --force 重开:
nlm research start "..." --notebook-id <alias> --mode deep --force
query 输出太大无法直接看
所有 query 都重定向到文件,再用 Python 抽 answer,不要尝试在终端直接打印大 JSON。
source add 连续失败
- 检查是否有限流 → 增大 sleep 到 3-5 秒
- 检查 URL 格式(YouTube 要用
watch?v= 标准格式,不用 shorts/live)
- 检查登录态 →
nlm login --check
References
