blog-notebooklm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blog NotebookLM -- Source-Grounded Research from Your Documents

Blog NotebookLM -- 基于你的文档开展有来源依据的研究

Query Google NotebookLM notebooks directly from Claude Code for citation-backed answers from Gemini. Each question opens a headless browser session, retrieves the answer exclusively from your uploaded documents, and closes. Responses are Tier 1 quality (user's own primary sources) -- zero hallucination risk. Answers satisfy the FLOW evidence triple: use the returned source title as the inline citation and the notebook URL plus retrieval date as the bibliography entry. This is the highest-confidence path to meeting the "verified source" bar that FLOW requires before any statistic goes public.

可直接通过Claude Code查询Google NotebookLM笔记本，获取由Gemini生成的带引用支持的答案。每个问题都会启动一个无头浏览器会话，仅从你上传的文档中检索答案，之后关闭会话。回复为一级质量（用户自有原始来源）——零幻觉风险。答案需符合FLOW证据三重要求：将返回的来源标题作为内联引用，将笔记本URL及检索日期作为参考文献条目。这是满足FLOW要求的最高可信度路径，确保任何公开数据都经过“已验证来源”审核。

Quick Reference

快速参考

Command	What it does
`/blog notebooklm ask <question>`	Query a notebook for source-grounded answers
`/blog notebooklm discover <url>`	Smart-discover notebook content before cataloging
`/blog notebooklm library list`	List all notebooks in library
`/blog notebooklm library add <url>`	Add a notebook to library
`/blog notebooklm library search <query>`	Search notebooks by keyword
`/blog notebooklm library remove <id>`	Remove a notebook from library
`/blog notebooklm setup`	One-time Google authentication (browser visible)
`/blog notebooklm status`	Check authentication status
`/blog notebooklm cleanup`	Clean browser state (preserves library)

命令	功能
`/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`	清理浏览器状态（保留库）

Prerequisites

前提条件

Google account with NotebookLM access
Python 3.11+ (venv managed automatically by
```
run.py
```
)
Google Chrome (installed automatically on first run via Patchright)
One-time authentication setup (interactive Google login in visible browser)

拥有NotebookLM访问权限的Google账户
Python 3.11+（
```
run.py
```
会自动管理虚拟环境）
Google Chrome（首次运行时通过Patchright自动安装）
一次性身份验证设置（在可见浏览器中进行交互式Google登录）

Always Use run.py Wrapper

务必使用run.py包装器

NEVER call scripts directly. ALWAYS use
python3 scripts/run.py [script]
:

bash

undefined

切勿直接调用脚本。请始终使用
python3 scripts/run.py [script]
：

bash

undefined

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


The `run.py` wrapper automatically creates `.venv`, installs dependencies,
sets up Chrome, and executes the target script.

python3 scripts/auth_manager.py status


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

Auth Check (Gate Pattern)

身份验证检查（网关模式）

Before any query operation, check authentication:

bash

python3 scripts/run.py auth_manager.py status

If authenticated: proceed with the query
If not authenticated: inform user and guide to setup: "NotebookLM requires Google login. Run
```
/blog notebooklm setup
```
to authenticate."
When called internally (from blog-write or blog-researcher): return silently with no error if not authenticated. Never block the writing workflow.

执行任何查询操作前，先检查身份验证：

bash

python3 scripts/run.py auth_manager.py status

已验证：继续查询
未验证：告知用户并引导至设置： "NotebookLM需要Google登录。请运行
```
/blog notebooklm setup
```
进行身份验证。"
内部调用时（来自blog-write或blog-researcher）：若未验证则静默返回空结果，切勿中断写作工作流。

Setup Workflow

设置工作流

For

/blog notebooklm setup

bash

undefined

对于

/blog notebooklm setup

：

bash

undefined

Opens a visible browser for manual Google login (one-time)

打开可见浏览器进行手动Google登录（一次性操作）

python3 scripts/run.py auth_manager.py setup


Tell the user: "A browser window will open. Please log in to your Google account."
Authentication persists via browser profile + cookie injection (hybrid approach).

Other auth commands:
```bash
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

python3 scripts/run.py auth_manager.py setup


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

其他身份验证命令：
```bash
python3 scripts/run.py auth_manager.py status   # 检查身份验证状态
python3 scripts/run.py auth_manager.py reauth   # 重新验证
python3 scripts/run.py auth_manager.py clear     # 清除所有身份验证数据

Query Workflow

查询工作流

For

/blog notebooklm ask <question>

对于

/blog notebooklm ask <question>

：

Step 1: Check Auth

步骤1：检查身份验证

Run auth check (see gate pattern above). If not authenticated, guide to setup.

执行身份验证检查（见上述网关模式）。若未验证，引导至设置。

Step 2: Resolve Notebook

步骤2：确定目标笔记本

Determine which notebook to query:

If
```
--notebook-url
```
provided: use directly
If
```
--notebook-id
```
provided: look up in library
If neither: use active notebook from library
If no active notebook: show library and ask user to select

确定要查询的笔记本：

若提供
```
--notebook-url
```
：直接使用该URL
若提供
```
--notebook-id
```
：在库中查找对应笔记本
若两者均未提供：使用库中的活动笔记本
若无活动笔记本：显示库内容并请用户选择

Step 3: Ask the Question

步骤3：发起查询

bash

undefined

bash

undefined

Basic query (uses active notebook)

基础查询（使用活动笔记本）

python3 scripts/run.py ask_question.py --question "Your question here"

python3 scripts/run.py ask_question.py --question "你的问题"

Query specific notebook by ID

通过ID查询特定笔记本

python3 scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

Query by URL directly

直接通过URL查询

python3 scripts/run.py ask_question.py --question "..." --notebook-url "https://..."

JSON output (for internal/programmatic use)

JSON格式输出（供内部/程序化使用）

python3 scripts/run.py ask_question.py --question "..." --json

Show browser for debugging

显示浏览器以调试

python3 scripts/run.py ask_question.py --question "..." --show-browser

undefined

python3 scripts/run.py ask_question.py --question "..." --show-browser

undefined

Step 4: Analyze and Follow Up

步骤4：分析与跟进

Every response ends with a follow-up prompt. Required behavior:

STOP -- do not immediately respond to the user
ANALYZE -- compare the answer to the user's original request
IDENTIFY GAPS -- determine if more information is needed
ASK FOLLOW-UP -- if gaps exist, immediately ask a follow-up question
REPEAT -- continue until information is complete
SYNTHESIZE -- combine all answers before responding to the user

每个回复结尾需包含跟进提示。必须遵循以下行为：

停止——不要立即回复用户
分析——将答案与用户原始请求对比
识别缺口——判断是否需要更多信息
提出跟进问题——若存在信息缺口，立即提出跟进问题
重复——持续操作直至信息完整
整合——整合所有答案后再回复用户

Smart Discovery Workflow

智能发现工作流

For

/blog notebooklm discover <url>

When adding a notebook without knowing its content, query it first:

bash

undefined

对于

/blog notebooklm discover <url>

：

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

bash

undefined

Step 1: Discover content

步骤1：发现内容

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>"

python3 scripts/run.py ask_question.py
--question "这个笔记本的内容是什么？涵盖哪些主题？请提供简洁完整的概述"
--notebook-url "<URL>"

Step 2: Add with discovered metadata

步骤2：使用发现的元数据添加笔记本

python3 scripts/run.py notebook_manager.py add
--url "<URL>"
--name "<Based on content>"
--description "<Based on content>"
--topics "<Extracted topics>"


**NEVER guess or use generic descriptions.** Always discover or ask the user.

python3 scripts/run.py notebook_manager.py add
--url "<URL>"
--name "<基于内容命名>"
--description "<基于内容撰写>"
--topics "<提取的主题>"


**切勿猜测或使用通用描述。务必先发现内容或询问用户。**

Library Management

库管理

bash

undefined

bash

undefined

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"

python3 scripts/run.py notebook_manager.py add
--url "https://notebooklm.google.com/notebook/..."
--name "描述性名称"
--description "本笔记本包含的内容"
--topics "主题1,主题2,主题3"

Search by keyword

按关键词搜索

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

python3 scripts/run.py notebook_manager.py search --query "关键词"

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

undefined

python3 scripts/run.py notebook_manager.py stats

undefined

Internal API (for blog-write / blog-researcher)

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

When invoked as a Task subagent from blog-write or blog-researcher:

Input (provided by calling skill):

```
question
```
: Research question relevant to the blog topic
```
notebook_id
```
or
```
notebook_url
```
: Which notebook to query
```
context
```
: "internal" (signals graceful fallback mode)

Process:

Check auth status -- if not authenticated, return empty result silently
Query the notebook with the research question
Parse and return structured response

Output (returned to calling skill):

markdown

undefined

当作为Task子代理从blog-write或blog-researcher调用时：

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

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

流程：

检查身份验证状态——若未验证，静默返回空结果
使用研究问题查询笔记本
解析并返回结构化回复

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

markdown

undefined

NotebookLM Research

NotebookLM研究结果

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


**Graceful fallback:** If auth is missing or query fails, return immediately
with no error. The calling workflow continues with WebSearch-based research.
Never block blog-write or blog-rewrite because NotebookLM is unavailable.

来源： [笔记本名称]
问题： [提出的问题]
答案： [来自用户文档的有来源依据的回复]
来源质量： 一级（用户上传的原始文档）


**优雅降级：** 若身份验证缺失或查询失败，立即返回且不报错。调用工作流将继续使用基于WebSearch的研究。切勿因NotebookLM不可用而中断blog-write或blog-rewrite工作流。

Data Storage

数据存储

All data stored inside the skill directory:

```
scripts/data/library.json
```
-- Notebook metadata and library
```
scripts/data/auth_info.json
```
-- Authentication status
```
scripts/data/browser_state/
```
-- Chrome profile with cookies

Security: All data directories are gitignored. Never commit auth or browser state.

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

```
scripts/data/library.json
```
——笔记本元数据和库信息
```
scripts/data/auth_info.json
```
——身份验证状态
```
scripts/data/browser_state/
```
——包含Cookie的Chrome配置文件

安全说明： 所有数据目录均已添加到git忽略列表。切勿提交身份验证或浏览器状态数据。

Error Handling

错误处理

Error	Resolution
Not authenticated	Run `/blog notebooklm setup`
ModuleNotFoundError	Always use `run.py` wrapper
Browser crash	`cleanup_manager.py --confirm --preserve-library` , then re-auth
Rate limit (50/day)	Wait until midnight PST or switch Google account
Notebook not found	Check with `notebook_manager.py list`
Query timeout (120s)	Retry with simpler question or `--show-browser` to debug
MCP unavailable (internal)	Return silently -- writing workflow uses WebSearch

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

Limitations

局限性

No session persistence (each question = new browser session)
Rate limits on free Google accounts (50 queries/day)
Manual upload required (user must add docs to NotebookLM web UI)
Browser overhead (few seconds per question for launch + teardown)
Local Claude Code only (not available in web UI)

无会话持久化（每个问题对应一个新浏览器会话）
免费Google账户有速率限制（每日50次查询）
需手动上传（用户必须通过NotebookLM网页UI添加文档）
浏览器开销（每个问题需几秒时间启动和关闭浏览器）
仅支持本地Claude Code（网页UI不可用）

Reference Documentation

参考文档

Load on-demand -- do NOT load all at startup:

```
references/commands.md
```
-- Full CLI commands, parameters, and workflow patterns
```
references/troubleshooting.md
```
-- Error solutions, recovery procedures, debugging

按需加载——请勿在启动时加载全部：

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