blog-notebooklm

Blog NotebookLM：基于文档的来源研究

直接从 Claude Code 查询 Google NotebookLM 笔记本，获取 Gemini 提供的附带引用的答案。每个问题都会启动一个无头浏览器会话，仅从你上传的文档中检索答案，然后关闭。回答质量为 Tier 1（用户自己的原始来源）：幻觉风险为零。 答案满足 FLOW 的三重证据要求：将返回的来源标题用作行内引用，并将笔记本 URL 和检索日期用作参考文献条目。这是满足 FLOW 要求的“已验证来源”标准的最高可信度途径；在任何统计数据公开之前，都必须达到这一标准。

快速参考

命令	功能
/blog notebooklm ask <question>	查询笔记本，获取基于来源的答案
/blog notebooklm discover <url>	编目之前智能发现笔记本内容
/blog notebooklm library list	列出库中的所有笔记本
/blog notebooklm library add <url>	将笔记本添加到库中
/blog notebooklm library search <query>	按关键词搜索笔记本
/blog notebooklm library remove <id>	从库中移除笔记本
/blog notebooklm setup	一次性 Google 身份验证（浏览器可见）
/blog notebooklm status	检查身份验证状态
/blog notebooklm cleanup	清理浏览器状态（保留库）

前提条件

• 可访问 NotebookLM 的 Google 账号
• Python 3.11+（由 run.py 自动管理 venv）
• Google Chrome（首次运行时通过 Patchright 自动安装）
• 一次性身份验证设置（在可见浏览器中交互式登录 Google）

始终使用 run.py 封装器

绝不要直接调用脚本。始终使用 python3 scripts/run.py [script]：

# CORRECT:
python3 scripts/run.py auth_manager.py status
python3 scripts/run.py ask_question.py --question "..."

# WRONG -- fails without venv:
python3 scripts/auth_manager.py status

run.py 封装器会自动创建 .venv、安装依赖项、设置 Chrome 并执行目标脚本。

身份验证检查（门控模式）

在执行任何查询操作之前，检查身份验证状态：

python3 scripts/run.py auth_manager.py status

• 如果已通过身份验证：继续查询
• 如果尚未通过身份验证：告知用户并引导其完成设置： “NotebookLM 需要 Google 登录。运行 /blog notebooklm setup 进行身份验证。”
• 内部调用时（来自 blog-write 或 blog-researcher）：如果尚未通过身份验证，则静默返回，不报错。绝不要阻止写作工作流。

设置工作流

对于 /blog notebooklm setup：

# Opens a visible browser for manual Google login (one-time)
python3 scripts/run.py auth_manager.py setup

告知用户：“浏览器窗口即将打开。请登录你的 Google 账号。” 身份验证会通过浏览器配置文件和 Cookie 注入（混合方式）持久保存。

其他身份验证命令：

python3 scripts/run.py auth_manager.py status   # Check auth
python3 scripts/run.py auth_manager.py reauth   # Re-authenticate
python3 scripts/run.py auth_manager.py clear     # Clear all auth data

查询工作流

对于 /blog notebooklm ask <question>：

第 1 步：检查身份验证

运行身份验证检查（见上方门控模式）。如果尚未通过身份验证，引导用户完成设置。

第 2 步：确定笔记本

确定要查询哪个笔记本：

• 如果提供了 --notebook-url：直接使用
• 如果提供了 --notebook-id：在库中查找
• 如果两者都未提供：使用库中的活动笔记本
• 如果没有活动笔记本：显示库并让用户选择

第 3 步：提问

# Basic query (uses active notebook)
python3 scripts/run.py ask_question.py --question "Your question here"

# Query specific notebook by ID
python3 scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

# Query by URL directly
python3 scripts/run.py ask_question.py --question "..." --notebook-url "https://..."

# JSON output (for internal/programmatic use)
python3 scripts/run.py ask_question.py --question "..." --json

# Show browser for debugging
python3 scripts/run.py ask_question.py --question "..." --show-browser

第 4 步：分析并跟进

每个回答都会以一个跟进提示结束。必须执行以下操作：

1. 停止：不要立即回复用户
2. 分析：将答案与用户的原始请求进行比较
3. 识别缺口：确定是否还需要更多信息
4. 跟进提问：如果存在信息缺口，立即提出后续问题
5. 重复：持续进行，直到信息完整
6. 综合：整合所有答案后再回复用户

智能发现工作流

对于 /blog notebooklm discover <url>：

添加笔记本但不了解其内容时，先查询笔记本：

# Step 1: Discover content
python3 scripts/run.py ask_question.py \
  --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" \
  --notebook-url "<URL>"

# Step 2: Add with discovered metadata
python3 scripts/run.py notebook_manager.py add \
  --url "<URL>" \
  --name "<Based on content>" \
  --description "<Based on content>" \
  --topics "<Extracted topics>"

**绝不要猜测或使用通用描述。**始终先发现内容，或询问用户。

库管理

# List all notebooks
python3 scripts/run.py notebook_manager.py list

# Add notebook (all params required -- discover or ask user!)
python3 scripts/run.py notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \
  --topics "topic1,topic2,topic3"

# Search by keyword
python3 scripts/run.py notebook_manager.py search --query "keyword"

# Set active notebook
python3 scripts/run.py notebook_manager.py activate --id notebook-id

# Remove notebook
python3 scripts/run.py notebook_manager.py remove --id notebook-id

# Library statistics
python3 scripts/run.py notebook_manager.py stats

内部 API（供 blog-write / blog-researcher 使用）

作为 blog-write 或 blog-researcher 的 Task 子 Agent 调用时：

输入（由调用技能提供）：

• question：与博客主题相关的研究问题
• notebook_id 或 notebook_url：要查询的笔记本
• context："internal"（表示启用优雅降级模式）

处理流程：

1. 检查认证状态：如果尚未通过认证，则静默返回空结果
2. 使用研究问题查询笔记本
3. 解析并返回结构化响应

输出（返回给调用技能）：

### NotebookLM Research
- **Source:** [Notebook name]
- **Question:** [What was asked]
- **Answer:** [Source-grounded response from user's documents]
- **Source Quality:** Tier 1 (user-uploaded primary documents)

**优雅降级：**如果缺少认证信息或查询失败，立即返回， 不报告错误。调用方工作流会继续使用基于 WebSearch 的研究方式。 NotebookLM 不可用时，绝不阻塞 blog-write 或 blog-rewrite。

数据存储

所有数据均存储在技能目录内：

• scripts/data/library.json：笔记本元数据和库
• scripts/data/auth_info.json：认证状态
• scripts/data/browser_state/：包含 Cookie 的 Chrome 配置文件

**安全性：**所有数据目录均已加入 Git 忽略规则。绝不要提交认证信息或浏览器状态。

错误处理

错误	解决方法
未通过认证	运行 /blog notebooklm setup
ModuleNotFoundError	始终使用 run.py 封装程序
浏览器崩溃	运行 cleanup_manager.py --confirm --preserve-library，然后重新认证
速率限制（每天 50 次）	等到太平洋标准时间午夜，或切换 Google 账号
找不到笔记本	使用 notebook_manager.py list 检查
查询超时（120 秒）	使用更简单的问题重试，或使用 --show-browser 进行调试
MCP 不可用（内部）	静默返回：写作工作流使用 WebSearch

限制

• 不保留会话（每个问题都会启动一个新的浏览器会话）
• 免费 Google 账号有速率限制（每天 50 次查询）
• 需要手动上传（用户必须在 NotebookLM 网页界面中添加文档）
• 浏览器开销（每个问题启动和关闭浏览器需要几秒钟）
• 仅限本地 Claude Code 使用（网页界面中不可用）

参考文档

按需加载：启动时切勿全部加载：

• references/commands.md：完整的 CLI 命令、参数和工作流模式
• references/troubleshooting.md：错误解决方法、恢复流程和调试