notebooklm

NotebookLM 自动化

自动化使用 Google NotebookLM：创建笔记本、添加来源、与内容聊天、生成作品（播客、视频、测验）并下载结果。

安装

从 PyPI 安装（推荐）：

pip install notebooklm-py

从 GitHub 安装（使用最新发布标签，而非 main 分支）：

# Get the latest release tag (using curl)
LATEST_TAG=$(curl -s https://api.github.com/repos/teng-lin/notebooklm-py/releases/latest | grep '"tag_name"' | cut -d'"' -f4)
pip install "git+https://github.com/teng-lin/notebooklm-py@${LATEST_TAG}"

⚠️ 请勿从 main 分支安装（pip install git+https://github.com/teng-lin/notebooklm-py）。main 分支可能包含尚未发布或不稳定的更改。除非你要测试尚未发布的功能，否则请始终使用 PyPI 或指定的发布标签。

安装后，安装 Claude Code 技能：

notebooklm skill install

前置条件

重要： 使用任何命令前，必须先完成身份验证：

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

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

CI/CD、多账户和并行 Agent

用于自动化环境、多账户或并行 Agent 工作流：

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

CI/CD 设置： 将 NOTEBOOKLM_AUTH_JSON 设置为包含 storage_state.json 内容的密钥。

多账户： 为每个账户使用不同的 NOTEBOOKLM_HOME 目录。

并行 Agent： CLI 会将笔记本上下文存储在共享文件（~/.notebooklm/context.json）中。多个并发 Agent 使用 notebooklm use 时，可能会覆盖彼此的上下文。

并行工作流的解决方案：

1. 始终使用明确的笔记本 ID（推荐）：传入 -n <notebook_id>（用于 wait/download 命令）或 --notebook <notebook_id>（用于其他命令），而不要依赖 use
2. 按 Agent 隔离： 为每个 Agent 设置唯一的 NOTEBOOKLM_HOME：export NOTEBOOKLM_HOME=/tmp/agent-$ID
3. 使用完整 UUID： 在自动化中避免使用部分 ID（它们可能产生歧义）

Agent 设置验证

开始工作流前，请验证 CLI 已就绪：

1. notebooklm status → 应显示“Authenticated as: email@...”
2. notebooklm list --json → 应返回有效的 JSON（即使笔记本列表为空）
3. 如果任一命令失败 → 运行 notebooklm login

此技能的触发条件

明确触发： 用户说“/notebooklm”“use notebooklm”或提及该工具名称

意图识别： 识别以下请求：

• “为 [topic] 创建播客”
• “总结这些 URL/文档”
• “根据我的研究生成测验”
• “将此内容转换为音频概览”
• “将这些来源添加到 NotebookLM”

自主操作规则

自动运行（无需确认）：

• notebooklm status - 检查上下文
• notebooklm auth check - 诊断身份验证问题
• notebooklm list - 列出笔记本
• notebooklm source list - 列出来源
• notebooklm artifact list - 列出作品
• notebooklm artifact wait - 等待作品完成（在子 Agent 上下文中）
• notebooklm source wait - 等待来源处理完成（在子 Agent 上下文中）
• notebooklm research status - 检查研究状态
• notebooklm research wait - 等待研究完成（在子 Agent 上下文中）
• notebooklm use <id> - 设置上下文（⚠️ 仅限单 Agent；并行工作流中使用 -n 标志）
• notebooklm create - 创建笔记本
• notebooklm ask "..." - 聊天查询
• notebooklm source add - 添加来源

运行前询问：

• notebooklm delete - 有破坏性
• notebooklm generate * - 运行时间较长，且可能失败
• notebooklm download * - 会写入文件系统
• notebooklm artifact wait - 运行时间较长（在主对话中）
• notebooklm source wait - 运行时间较长（在主对话中）
• notebooklm research wait - 运行时间较长（在主对话中）

快速参考

任务	命令
身份验证	notebooklm login
诊断身份验证问题	notebooklm auth check
诊断身份验证（完整）	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"
生成播客（JSON）	notebooklm generate audio --json
生成播客（指定资源）	notebooklm generate audio -s src_id1 -s src_id2
生成视频	notebooklm generate video "instructions"
生成测验	notebooklm generate quiz
检查产物状态	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
下载抽认卡（Markdown）	notebooklm download flashcards --format markdown cards.md
删除笔记本	notebooklm notebook delete <id>

并行安全： 在并行工作流中使用明确的笔记本 ID。支持 -n 简写的命令：artifact wait、source wait、research wait/status、download *。下载命令还支持 -a/--artifact。其他命令使用 --notebook。聊天时，使用 --new 开始新对话（避免对话 ID 冲突）。

部分 ID： 使用 UUID 的前 6 个或更多字符。必须是唯一前缀（如有歧义则会失败）。适用于：use、delete、wait 命令。自动化时，建议使用完整 UUID，以避免歧义。

命令输出格式

带有 --json 的命令会返回可供解析的结构化数据：

创建笔记本：

$ notebooklm create "Research" --json
{"id": "abc123de-...", "title": "Research"}

添加资源：

$ notebooklm source add "https://example.com" --json
{"source_id": "def456...", "title": "Example", "status": "processing"}

生成产物：

$ notebooklm generate audio "Focus on key points" --json
{"task_id": "xyz789...", "status": "pending"}

带引用的聊天：

$ notebooklm ask "What is X?" --json
{"answer": "X is... [1] [2]", "conversation_id": "...", "turn_number": 1, "is_follow_up": false, "references": [{"source_id": "abc123...", "citation_number": 1, "cited_text": "Relevant passage from source..."}, {"source_id": "def456...", "citation_number": 2, "cited_text": "Another passage..."}]}

资源全文（获取索引内容）：

$ notebooklm source fulltext <source_id> --json
{"source_id": "...", "title": "...", "char_count": 12345, "content": "Full indexed text..."}

理解引用： 引用中的 cited_text 通常是片段或章节标题，而不是完整的引用段落。start_char/end_char 位置引用的是 NotebookLM 内部的分块索引，而非原始全文。使用 SourceFulltext.find_citation_context() 定位引用：

fulltext = await client.sources.get_fulltext(notebook_id, ref.source_id)
matches = fulltext.find_citation_context(ref.cited_text)  # Returns list[(context, position)]
if matches:
    context, pos = matches[0]  # First match; check len(matches) > 1 for duplicates

提取 ID： 从 JSON 输出中解析 id、source_id 或 task_id 字段。

生成类型

所有生成命令都支持：

• -s, --source，使用指定来源，而非所有来源
• --json，输出机器可读格式（返回 task_id 和 status）

类型	命令	是否可下载
播客	generate audio	是（.mp3）
视频	generate video	是（.mp4）
幻灯片	generate slide-deck	是（.pdf）
信息图	generate infographic	是（.png）
报告	generate report	是（.md）
思维导图	generate mind-map	是（.json）
数据表	generate data-table	是（.csv）
测验	generate quiz	是（.json/.md/.html）
闪卡	generate flashcards	是（.json/.md/.html）

常见工作流

从研究生成播客（交互式）

耗时： 总计 5-10 分钟

1. notebooklm create "Research: [topic]" — 如果失败：使用 notebooklm login 检查身份验证
2. 对每个 URL/文档运行 notebooklm source add — 如果有一个失败：记录警告，然后继续处理其他来源
3. 等待来源就绪：运行 notebooklm source list --json，直到所有来源的 status=READY — 生成前必须完成
4. notebooklm generate audio "Focus on [specific angle]"（出现提示时确认）— 如果遇到速率限制：等待 5 分钟，然后重试一次
5. 记下返回的制品 ID
6. 稍后运行 notebooklm artifact list 检查状态
7. 完成后运行 notebooklm download audio ./podcast.mp3（出现提示时确认）

从研究生成播客（使用子 Agent 自动执行）

耗时： 5-10 分钟，但会在后台继续运行

当用户需要全自动执行（生成并在就绪后下载）时：

1. 按常规方式创建笔记本并添加来源
2. 等待来源就绪（使用 source wait 或检查 source list --json）
3. 运行 notebooklm generate audio "..." --json → 从输出中解析 artifact_id
4. 使用 Task 工具启动后台 Agent：

   Task(
     prompt="Wait for artifact {artifact_id} in notebook {notebook_id} to complete, then download.
             Use: notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 600
             Then: notebooklm download audio ./podcast.mp3 -a {artifact_id} -n {notebook_id}",
     subagent_type="general-purpose"
   )
   

5. 主对话会在 Agent 等待期间继续进行

子 Agent 中的错误处理：

• 如果 artifact wait 返回退出代码 2（超时）：报告超时，并建议检查 artifact list
• 如果下载失败：先检查制品状态是否为 COMPLETED

优点： 不会阻塞，用户可以处理其他工作，完成后自动下载

文档分析

耗时： 1-2 分钟

1. notebooklm create "Analysis: [project]"
2. notebooklm source add ./doc.pdf（或添加 URL）
3. notebooklm ask "Summarize the key points"
4. notebooklm ask "What are the main arguments?"
5. 根据需要继续对话

批量导入

耗时： 视来源数量而定

1. notebooklm create "Collection: [name]"
2. 添加多个来源：

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

3. 运行 notebooklm source list 进行验证

来源限制： 每个笔记本最多 50 个来源 支持的类型： PDF、YouTube URL、网页 URL、Google Docs、文本文件

批量导入并等待来源处理（子 Agent 模式）

耗时： 视来源数量而定

添加多个来源后，若需等待处理完成再进行聊天/生成：

1. 添加来源时使用 --json 获取 ID：

   notebooklm source add "https://url1.com" --json  # → {"source_id": "abc..."}
   notebooklm source add "https://url2.com" --json  # → {"source_id": "def..."}
   

2. 启动后台 Agent，等待所有来源处理完成：

   Task(
     prompt="Wait for sources {source_ids} in notebook {notebook_id} to be ready.
             For each: notebooklm source wait {id} -n {notebook_id} --timeout 120
             Report when all ready or if any fail.",
     subagent_type="general-purpose"
   )
   

3. 主对话会在 Agent 等待期间继续进行
4. 来源就绪后，继续聊天或生成

为什么要等待来源处理？ 聊天或生成前必须先为来源编制索引。每个来源需要 10-60 秒。

深度网络研究（子 Agent 模式）

耗时： 2-5 分钟，在后台运行

深度研究会查找并分析有关某个主题的网络来源：

1. 创建笔记本：notebooklm create "Research: [topic]"
2. 启动深度研究（非阻塞）：

   notebooklm source add-research "topic query" --mode deep --no-wait
   

3. 启动后台 Agent，等待并导入：

   Task(
     prompt="Wait for research in notebook {notebook_id} to complete and import sources.
             Use: notebooklm research wait -n {notebook_id} --import-all --timeout 300
             Report how many sources were imported.",
     subagent_type="general-purpose"
   )
   

4. 主对话在 Agent 等待期间继续进行
5. Agent 完成后，来源会自动导入

替代方案（阻塞）： 对于简单情况，可省略 --no-wait：

notebooklm source add-research "topic" --mode deep --import-all
# Blocks for up to 5 minutes

模式选择指南：

• --mode fast：主题明确，需要快速概览（5-10 个来源，只需几秒）
• --mode deep：主题宽泛，需要全面分析（20 个以上来源，耗时 2-5 分钟）

研究来源：

• --from web：搜索网络（默认）
• --from drive：搜索 Google Drive

输出风格

进度更新： 简要说明每个步骤的状态

• “正在创建笔记本‘Research: AI’……”
• “正在添加来源：https://example.com……”
• “正在开始生成音频……（任务 ID：abc123）”

长时间操作采用启动后即返回：

• 启动生成后，立即返回产物 ID
• 在主对话中不要轮询或等待——生成需要 5-45 分钟（参见时间表）
• 用户可手动检查状态，或者使用子 Agent 执行 artifact wait

JSON 输出： 使用 --json 标志输出机器可读内容：

notebooklm list --json
notebooklm auth check --json
notebooklm source list --json
notebooklm artifact list --json

JSON 架构（关键字段）：

notebooklm list --json：

{"notebooks": [{"id": "...", "title": "...", "created_at": "..."}]}

notebooklm auth check --json：

{"checks": {"storage_exists": true, "json_valid": true, "cookies_present": true, "sid_cookie": true, "token_fetch": true}, "details": {"storage_path": "...", "auth_source": "file", "cookies_found": ["SID", "HSID", "..."], "cookie_domains": [".google.com"]}}

notebooklm source list --json：

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

notebooklm artifact list --json：

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

状态值：

• 来源：processing → ready（或 error）
• 产物：pending 或 in_progress → completed（或 unknown）

错误处理

发生故障时，请让用户选择：

1. 重试操作
2. 跳过并继续处理其他内容
3. 调查错误

错误决策树：

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

退出代码

所有命令使用一致的退出代码：

代码	含义	操作
0	成功	继续
1	错误（未找到、处理失败）	检查 stderr，参见“错误处理”
2	超时（仅适用于等待命令）	延长超时时间或手动检查状态

示例：

• 如果未找到来源或处理失败，source wait 会返回 1
• 如果达到超时时间但操作尚未完成，artifact wait 会返回 2
• 如果受到速率限制，generate 会返回 1（检查 stderr 了解详情）

已知限制

速率限制： 音频、视频、测验、抽认卡、信息图和幻灯片的生成可能因 Google 的速率限制而失败。这是 API 限制，并非错误。

可靠操作： 以下操作始终可用：

• 笔记本（列出、创建、删除、重命名）
• 来源（添加、列出、删除）
• 聊天/查询
• 思维导图、学习指南、常见问题解答、数据表格生成

不可靠操作： 以下操作可能因速率限制而失败：

• 音频（播客）生成
• 视频生成
• 测验和抽认卡生成
• 信息图和幻灯片生成

解决方法： 如果生成失败：

1. 检查状态：notebooklm artifact list
2. 等待 5-10 分钟后重试
3. 使用 NotebookLM 网页界面作为备用方案

处理时间差异很大。 对于耗时较长的操作，请使用子 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

轮询间隔： 手动检查状态时，每隔 15-30 秒轮询一次，避免过度调用 API。

故障排除

notebooklm --help              # Main commands
notebooklm auth check          # Diagnose auth issues
notebooklm auth check --test   # Full auth validation with network test
notebooklm notebook --help     # Notebook management
notebooklm source --help       # Source management
notebooklm research --help     # Research status/wait
notebooklm generate --help     # Content generation
notebooklm artifact --help     # Artifact management
notebooklm download --help     # Download content

诊断身份验证： notebooklm auth check - 显示 Cookie 域、存储路径和验证状态
重新进行身份验证： notebooklm login
检查版本： notebooklm --version
更新技能： notebooklm skill install