notebooklm

NotebookLM 自动化

以编程方式完整访问 Google NotebookLM，包括网页界面未公开的功能。创建笔记本，添加来源（URL、YouTube、PDF、音频、视频、图像），与内容聊天，生成所有类型的制品，并以多种格式下载结果。

前提条件

安装

uv tool install notebooklm-py

身份验证（一次性）

notebooklm login          # Opens browser for Google OAuth
notebooklm list           # Verify authentication works

如果命令因身份验证错误而失败，请重新运行 notebooklm login。

验证设置

notebooklm --version
notebooklm status         # Shows "Authenticated as: email@..."
notebooklm list --json    # Should return valid JSON

CI/CD 和并行 Agent

变量	用途
NOTEBOOKLM_HOME	自定义配置目录（默认：~/.notebooklm）
NOTEBOOKLM_AUTH_JSON	内嵌身份验证 JSON——无需写入文件

并行 Agent： CLI 会将笔记本上下文存储在 ~/.notebooklm/context.json 中。多个并发 Agent 使用 notebooklm use 时会相互覆盖对方的上下文。请改用显式的 -n <notebook_id> 或 --notebook <notebook_id> 标志，或者为每个 Agent 设置唯一的 NOTEBOOKLM_HOME。

快速参考

任务	命令
身份验证	notebooklm login
诊断身份验证	notebooklm auth check --test
列出笔记本	notebooklm list
创建笔记本	notebooklm create "Title"
设置上下文	notebooklm use <notebook_id>
显示上下文	notebooklm status
添加 URL 来源	notebooklm source add "https://..."
添加文件	notebooklm source add ./file.pdf
添加 YouTube	notebooklm source add "https://youtube.com/..."
列出来源	notebooklm source list
等待来源	notebooklm source wait <source_id>
网络研究（快速）	notebooklm source add-research "query"
网络研究（深入）	notebooklm source add-research "query" --mode deep --no-wait
检查研究状态	notebooklm research status
等待研究完成	notebooklm research wait --import-all
聊天	notebooklm ask "question"
聊天（新对话）	notebooklm ask "question" --new
聊天（指定来源）	notebooklm ask "question" -s src_id1 -s src_id2
聊天（包含引用）	notebooklm ask "question" --json
获取来源全文	notebooklm source fulltext <source_id>
获取来源指南	notebooklm source guide <source_id>
生成播客	notebooklm generate audio "instructions"
生成视频	notebooklm generate video "instructions"
生成测验	notebooklm generate quiz
生成信息图	notebooklm generate infographic
生成幻灯片	notebooklm generate slide-deck
生成报告	notebooklm generate report
生成思维导图	notebooklm generate mind-map
生成数据表	notebooklm generate data-table "description"
生成闪卡	notebooklm generate flashcards
检查产物状态	notebooklm artifact list
等待完成	notebooklm artifact wait <artifact_id>
下载音频	notebooklm download audio ./output.mp3
下载视频	notebooklm download video ./output.mp4
下载报告	notebooklm download report ./report.md
下载思维导图	notebooklm download mind-map ./map.json
下载数据表	notebooklm download data-table ./data.csv
下载测验	notebooklm download quiz quiz.json
下载测验（Markdown）	notebooklm download quiz --format markdown quiz.md
下载闪卡	notebooklm download flashcards cards.json
下载信息图	notebooklm download infographic ./infographic.png
下载幻灯片	notebooklm download slide-deck ./slides.pdf
列出语言	notebooklm language list
设置语言	notebooklm language set zh_Hans
部分 ID： 使用 UUID 的前 6 个或更多字符。前缀必须唯一。自动化时优先使用完整 UUID。

自主运行规则

无需确认即可运行：

• status、auth check、list、source list、artifact list、language list/get/set
• use <id>、create、ask "..."、source add
• source wait、artifact wait、research wait/status（在子 Agent 上下文中）

运行前需要确认：

• delete — 有破坏性
• generate * — 运行时间较长，可能会因速率限制而失败
• download * — 会写入文件系统
• artifact wait、source wait、research wait — 运行时间较长（在主对话中）

生成类型

所有生成命令均支持：

• -s, --source 使用指定来源，而非全部来源
• --language 覆盖输出语言
• --json 输出机器可读格式（返回 task_id 和 status）
• --retry N 指数退避并自动重试

类型	命令	主要选项	下载格式
播客	generate audio	--format [deep-dive|brief|critique|debate]、--length [short|default|long]	.mp3
视频	generate video	--format [explainer|brief]、--style [auto|classic|whiteboard|kawaii|anime|watercolor|retro-print|heritage|paper-craft]	.mp4
幻灯片	generate slide-deck	--format [detailed|presenter]、--length [default|short]	.pdf
信息图	generate infographic	--orientation [landscape|portrait|square]、--detail [concise|standard|detailed]	.png
报告	generate report	--format [briefing-doc|study-guide|blog-post|custom]	.md
思维导图	generate mind-map	(同步，即时)	.json
数据表	generate data-table	需要提供描述	.csv
测验	generate quiz	--difficulty [easy|medium|hard]、--quantity [fewer|standard|more]	.json/.md/.html
闪卡	generate flashcards	--difficulty [easy|medium|hard]、--quantity [fewer|standard|more]	.json/.md/.html

Web 界面之外的功能

功能	命令	说明
批量下载	download <type> --all	一次性下载某类型的全部产物
测验/闪卡导出	download quiz --format json	导出为 JSON、Markdown 或 HTML
思维导图提取	download mind-map	为可视化工具提供分层 JSON
数据表导出	download data-table	将结构化表格导出为 CSV
来源全文	source fulltext <id>	获取任意来源已索引的文本内容
程序化分享	share 命令	无需通过界面即可管理分享权限

JSON 输出格式

使用 --json 获取机器可读的输出：

创建笔记本：

{ "id": "abc123de-...", "title": "Research" }

添加来源：

{ "source_id": "def456...", "title": "Example", "status": "processing" }

生成产物：

{ "task_id": "xyz789...", "status": "pending" }

与参考资料聊天：

{
  "answer": "X is... [1] [2]",
  "conversation_id": "...",
  "references": [
    {
      "source_id": "abc123...",
      "citation_number": 1,
      "cited_text": "Relevant passage..."
    }
  ]
}

来源列表：

{
  "sources": [
    { "id": "...", "title": "...", "status": "ready|processing|error" }
  ]
}

产物列表：

{
  "artifacts": [
    {
      "id": "...",
      "title": "...",
      "type": "Audio Overview",
      "status": "in_progress|pending|completed|unknown"
    }
  ]
}

常见工作流

从研究到播客

1. notebooklm create "Research: [topic]" --json — 获取笔记本 ID
2. 对每个来源运行 notebooklm source add "https://..." --json — 获取来源 ID
3. notebooklm source list --json — 等待所有状态都变为 ready
4. notebooklm generate audio "Focus on [angle]" --json — 获取产物 ID
5. notebooklm artifact wait <artifact_id> — 阻塞等待直至完成
6. notebooklm download audio ./podcast.mp3

文档分析

1. notebooklm create "Analysis: [project]"
2. notebooklm source add ./doc.pdf
3. notebooklm ask "Summarize the key points"
4. 根据需要继续聊天

批量导入

1. notebooklm create "Collection: [name]"
2. 添加来源（每个笔记本最多 50 个）：

   notebooklm source add "https://url1.com" --json
   notebooklm source add "https://url2.com" --json
   notebooklm source add ./local-file.pdf --json
   

3. 运行 notebooklm source list --json 进行验证

**支持的来源类型：**PDF、YouTube URL、网页 URL、Google Docs、文本文件、Markdown、Word 文档、音频文件、视频文件、图片。

深度网络研究

1. notebooklm create "Research: [topic]"
2. 启动深度研究：notebooklm source add-research "topic" --mode deep --no-wait
3. 等待：notebooklm research wait --import-all --timeout 300
4. 研究完成后会自动导入来源

模式：--mode fast（5–10 个来源，数秒）与 --mode deep（20 个以上来源，2–5 分钟）。 搜索范围：--from web（默认）或 --from drive（Google Drive）。

长时间操作的子 Agent 模式

要进行非阻塞式生成，请启动后台 Agent：

1. 运行 notebooklm generate audio "..." --json — 解析 artifact_id
2. 启动 Task Agent 来等待并下载：

   Wait for artifact {artifact_id} in notebook {notebook_id} to complete.
   Use: notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 600
   Then: notebooklm download audio ./podcast.mp3 -a {artifact_id} -n {notebook_id}
   

3. Agent 等待期间，主对话可继续进行

处理时间

操作	典型耗时	建议超时时间
来源处理	30s - 10 min	600s
研究（快速）	30s - 2 min	180s
研究（深度）	15 - 30+ min	1800s
思维导图	即时（同步）	n/a
笔记	即时	n/a
测验、抽认卡	5 - 15 min	900s
报告、数据表	5 - 15 min	900s
音频生成	10 - 20 min	1200s
视频生成	15 - 45 min	2700s

错误处理

错误	原因	操作
身份验证/ Cookie 错误	会话已过期	先运行 notebooklm auth check，再运行 notebooklm login
"No notebook context"	未设置上下文	使用 -n <id> 标志或运行 notebooklm use <id>
"No result found for RPC ID"	速率限制	等待 5–10 分钟后重试
GENERATION_FAILED	Google 速率限制	等待一段时间后重试
下载失败	生成未完成	检查 artifact list 中的状态
无效的笔记本/来源 ID	ID 错误	运行 notebooklm list 进行验证
RPC 协议错误	Google 更改了 API	可能需要更新 CLI（uv tool upgrade notebooklm-py）

**退出代码：**0 = 成功，1 = 错误，2 = 超时（仅限等待命令）。

**可靠的操作：**笔记本、来源、聊天、思维导图、报告、数据表。 **可能触发速率限制：**音频、视频、测验、抽认卡、信息图、幻灯片。

语言配置

语言是影响所有笔记本的全局设置。

notebooklm language list              # 80+ supported languages
notebooklm language get               # Current setting
notebooklm language set ja            # Set globally
notebooklm generate audio --language ja  # Override per command

常见代码：en、zh_Hans、zh_Hant、ja、ko、es、fr、de、pt_BR。

限制

• 非官方 API：通过 notebooklm-py 使用浏览器自动化。如果 Google 更改 NotebookLM 内部实现，可能会失效。与 Google 无关。
• 每个笔记本最多 50 个来源：这是 NotebookLM 的硬性限制。
• 速率限制：Google 对生成端点实施速率限制。除了等待，没有其他解决办法。
• 身份验证过期：Google OAuth 会话会过期。身份验证失败时，请重新运行 notebooklm login。
• 不支持流式传输：聊天回复会一次性完整返回，而不是以流的形式返回。
• 单 Agent 上下文：notebooklm use 会写入共享文件。并行工作流请使用 -n 标志。