research-pipeline

name	research-pipeline
description	领域研究流水线。两阶段工作流：NotebookLM 批量问答（消化）→ 内容生成（表达）。前置的多源采集（喂料）见 SOP 文档。

Research Pipeline — 领域研究流水线

基于 IPO 模型的研究工作流（Digest + Express 两阶段）。 前置的内容采集（Collect）为人工操作，详见 .trellis/spec/sop/sop-research-collect.md。

When to Use This Skill

Trigger when user:

• 说"研究一下 XX 领域"、"帮我调研 XX"
• 说"research pipeline"、"研究流水线"
• 想批量向 NotebookLM 提问并保存结果
• 想基于已有 Q&A 生成内容

First Run — Onboarding (CRITICAL)

On EVERY invocation, check if .Codex/skills/research-pipeline/.setup-done exists.

• If .setup-done does NOT exist → run onboarding BEFORE doing anything else.
• If .setup-done exists → skip onboarding, proceed to requested phase.

Onboarding Steps

When .setup-done is missing, execute this sequence:

Step 1: Run setup script

bash .Codex/skills/research-pipeline/setup.sh

This auto-installs:

• notebooklm-skill — NotebookLM browser automation (GitHub: PleasePrompto/notebooklm-skill)
• video-downloader MCP — video download via yt-dlp
• whisper CLI — local speech-to-text
• yt-dlp CLI — video downloader backend

Step 2: If notebooklm-skill auth is missing, guide user through login

cd .Codex/skills/notebooklm-skill
HEADLESS=false python3 scripts/run.py auth_manager.py setup

Tell user: "A browser window will open — please log in to your Google account."

Step 3: Teach the user how to use this skill

After setup completes, print this guide:

========================================
  Research Pipeline — 快速上手指南
========================================

用 NotebookLM 做知识库，2 小时深度研究任意领域。

工作流概览:

  ┌─────────────────────────────────────────────────┐
  │  0. 采集（手动，见 SOP）                          │
  │     多源内容 → Markdown → 上传 NotebookLM        │
  └──────────────────────┬──────────────────────────┘
                         ▼
  ┌─────────────────────────────────────────────────┐
  │  1. 消化（自动）                                  │
  │     AI 生成问题 → NotebookLM 作答 → 问答存本地     │
  └──────────────────────┬──────────────────────────┘
                         ▼
  ┌─────────────────────────────────────────────────┐
  │  2. 表达（自动）                                  │
  │     问答 → 大纲 / 长文 / 口播稿 / 推文线程         │
  └─────────────────────────────────────────────────┘

命令:

  /research-pipeline digest "<主题>" --notebook-url <URL>
    → 生成 20+ 研究问题，批量查询 NotebookLM，问答存本地

  /research-pipeline express "<主题>" --format outline
    → 基于问答生成内容（格式: outline/article/script/threads/slides/all）

  /research-pipeline full "<主题>" --notebook-url <URL>
    → 消化 + 表达 两阶段串联执行

首次使用前:

  1. 围绕主题采集内容（文章、视频等）
     → 见 SOP: .trellis/spec/sop/sop-research-collect.md
  2. 将采集的 Markdown 文件上传到 NotebookLM notebook
  3. 复制 notebook URL，传给 digest 命令

已安装工具:
  ✓ notebooklm-skill  — 从 Codex 查询 NotebookLM
  ✓ video-downloader   — 下载视频（YouTube、B站、抖音等）
  ✓ whisper            — 本地语音转文字
  ✓ yt-dlp             — 视频下载后端

提示:
  • NotebookLM 免费版: 每天约 50 次查询
  • 超过 20 个问题建议分多次会话完成
  • 每个 NotebookLM notebook 最多上传 300 个文档
  • 用 AI 做研究，用人做表达 — 生成内容只是起点！

========================================

Step 4: Ask user what they'd like to research

After the guide, ask: "Setup complete! What topic would you like to research? Please provide a NotebookLM notebook URL if you have one ready."

---

Prerequisites

• notebooklm-skill 已安装并认证（auto-installed by onboarding）
• video-downloader MCP + whisper CLI（auto-installed by onboarding）
• NotebookLM 中已创建对应主题的 notebook 并上传文档（采集流程见 SOP）

Usage

/research-pipeline <phase> <topic> [options]

Phases

Phase	Command	Description
digest	/research-pipeline digest <topic> --notebook-url <URL>	批量生成问题 → NotebookLM 作答 → 存本地
express	/research-pipeline express <topic> --format <type>	基于 Q&A 生成内容
full	/research-pipeline full <topic> --notebook-url <URL>	两阶段串联执行

Data Directory

research-data/
└── <topic-slug>/
    ├── qa/               # Digest: 问答记录
    │   ├── questions.md  # 生成的问题列表
    │   └── answers/      # 每个问题的答案（单独文件）
    ├── output/           # Express: 产出内容
    │   ├── outline.md    # 思维导图大纲
    │   ├── article.md    # 长文
    │   ├── script.md     # 口播逐字稿
    │   └── threads.md    # 推文线程
    └── meta.json         # 项目元数据

---

Phase 1: Digest（消化）

目标: AI 生成问题 → NotebookLM 基于知识库作答 → 问答存本地。

Prerequisite: User has uploaded sources to NotebookLM and provides the notebook URL.

Step 1: Generate Questions

Based on the topic, generate 15-30 high-quality questions across these dimensions:

## 基础认知（5-8 questions）
- 这个领域的核心概念是什么？
- 主要的参与者/玩家有哪些？
- 这个领域的发展历程是怎样的？

## 深度分析（5-8 questions）
- 最常见的误区有哪些？
- 成功案例的共同模式是什么？
- 失败案例的教训有哪些？

## 实操方法（5-8 questions）
- 新手入门的最佳路径是什么？
- 有哪些可以直接复用的框架/模板？
- 最关键的 3 个决策点是什么？

## 趋势与机会（3-5 questions）
- 当前最大的变化趋势是什么？
- 有哪些被低估的机会？
- 未来 6-12 个月的预测？

Save to qa/questions.md.

Step 2: Batch Query NotebookLM

For each question, call notebooklm-skill:

cd <notebooklm-skill-dir>

# Query each question
python3 scripts/run.py ask_question.py \
  --question "<question>" \
  --notebook-url "<notebook-url>"

Save each answer to qa/answers/<number>-<short-slug>.md:

---
question: "<the question>"
answered_at: "<ISO timestamp>"
---

<NotebookLM answer>

Step 3: Compile Q&A Summary

After all questions are answered, create qa/summary.md:

# <Topic> — Research Q&A Summary

## Key Findings
- <top 5 most important insights>

## Surprising Discoveries
- <things that contradicted assumptions>

## Knowledge Gaps
- <questions NotebookLM couldn't fully answer>

## Full Q&A Index
| # | Question | Key Insight |
|---|----------|-------------|
| 1 | ... | ... |

Update meta.json with qa_count and status.

---

Phase 3: Express（表达）

目标: 基于 Q&A 生成内容，但保持人的表达框架。

Available Formats

Format	Flag	Output
思维导图大纲	--format outline	Xmind-compatible Markdown outline
长文	--format article	结构化长文
口播逐字稿	--format script	适合语音表达的逐字稿
推文线程	--format threads	5-15 条推文的线程
幻灯片大纲	--format slides	Keynote/PPT 用的逐页大纲
全部	--format all	生成以上所有格式

Content Generation Rules

1. Read all Q&A files first — load qa/summary.md + all qa/answers/*.md
2. Outline first — always generate outline before other formats
3. No fake examples — only use facts from Q&A, never fabricate experiences
4. Human voice — write as if explaining to a friend, not as a textbook
5. Cite sources — reference which Q&A the insight came from

Step 1: Generate Outline

Read all Q&A, then create output/outline.md:

# <Topic> — 内容大纲

## 核心主题: <one sentence>

### 1. <Section>
- Key point A (from Q&A #3)
- Key point B (from Q&A #7)
  - Supporting detail

### 2. <Section>
...

## 金句/Hook
- <memorable quotes or hooks for content>

Step 2: Generate Requested Format

Based on --format flag, generate content into output/.

Each output file should:

• Start with a YAML frontmatter (topic, format, generated_at, based_on)
• Reference Q&A numbers for traceability
• Include editorial notes in <!-- comments --> for human review

Step 3: Report

List all generated files and suggest:

• Review and edit the outline first (it's your framework)
• Use voice input to re-express in your own words
• The generated content is a starting point, not the final product

---

Rate Limits & Tips

• NotebookLM free tier: ~50 queries/day
• For 20+ questions, consider splitting across sessions
• Upload sources to NotebookLM in batches (max 300 docs per notebook)
• 采集流程（喂料）见 SOP: .trellis/spec/sop/sop-research-collect.md

Example Session

User: /research-pipeline full "AI Agent 开发框架" --notebook-url https://notebooklm.google.com/notebook/abc123

AI:
1. [Digest] Generating 25 research questions...
   → Querying NotebookLM... (25/25 complete)
   → Q&A summary saved to research-data/ai-agent-frameworks/qa/

2. [Express] Generating outline + article...
   → Files ready in research-data/ai-agent-frameworks/output/