/research-collector

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

开始前必须确认:

1. `nlm` CLI 已安装且登录:`nlm login --check` 2. `yt-dlp` 在 PATH 中:`which yt-dlp` 3. 用户明确说明了主题和角度 4. 输出目录可写(默认 `./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: 对齐目标

在动手前必须和用户明确:

1. **主题是什么**(要一句话能喂给 ytsearch 的关键词) 2. **角度**(比如"最常用 + 个人创作" vs "最新发布 + 技术细节") 3. **笔记本命名**(默认 `<主题> 素材`) 4. **量级**(默认:15 油管 + deep research 自动 ~40 网页)

Phase 1: 创建笔记本 + 设 alias

nlm notebook create "<话题> 素材"
# 从输出提取 ID,然后:
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 个查询模板(按需改关键词):

1. **Top 清单**:"基于所有 source,请列出被最多来源推荐的 Top 10 X。对每个 X 说明:(1) 名称 (2) 具体做什么 (3) 主要使用场景 (4) 推荐它的来源数量 (5) 类型分类。按推荐频率从高到低,用中文输出。" 2. **目标读者向**:"我要写一篇面向 <读者画像> 的文章。请筛选出对 <读者> 最有帮助的 Top 8 X,每个说明:(1) 名称 (2) 具体痛点 (3) 典型用法一句话 (4) 类型 (5) 最具体的来源编号。去掉不相关的,聚焦 <场景>,用中文。" 3. **入门 + 坑**:"针对 <读者> 使用 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

执行完要给用户报告:

1. Notebook 名字 + alias + 实际 source 数量 2. 3 份 raw JSON 和 1 份汇总 markdown 的落盘路径 3. 失败/跳过的 source(如果有) 4. 汇总文件的头部预览(前 20 行左右) 5. 建议的下一步(交给用户决定下游怎么用,本 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,不要