blog-notebooklm

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

Google 于 2026-07-16 将 NotebookLM 更名为 Gemini Notebook（公告）。此技能保留 notebooklm 命令和脚本名称。脚本接受 notebooklm.google.com 上的笔记本 URL（该网址于 2026-10-12 通过 301 重定向至 notebook.google.com）以及 notebook.google.com 上的 URL。帮助：https://support.google.com/gemininotebook/。

以下捆绑路径使用宿主 Markdown 对 ${CLAUDE_SKILL_DIR} 的替换； 它不是导出的 shell 变量。执行前解析这些路径、为路径加引号， 并拒绝非绝对路径的覆盖值。将从 ${CLAUDE_SKILL_DIR}/../blog/references 解析得到的 blog_reference_root、从 ${CLAUDE_SKILL_DIR}/../blog/templates 解析得到的 blog_template_root，以及所需的同级根目录传递给 Agent。 加载项目上下文前，先阅读主参考文档 orchestration-details.md； 只将其辅助代码围栏中的输出传递给下游 Agent。

在 Claude Code 中直接查询 Gemini Notebook（原名 NotebookLM）笔记本，获取 Gemini 提供的、有引用支持的答案。每个问题都会开启一个无头浏览器会话，从你上传的文档中检索答案，然后关闭会话。回答是基于来源的模型回答，并非事实证明：上传的文档可能是第一手或第二手资料，回答仍可能遗漏上下文。

只有当返回的引用指出了可核验的底层来源时，答案才提供可用的出处信息。如果某项细节会影响核验或解读，请记录稳定的来源 URL，以及发布日期、研究期间或检索日期。行内引用请使用底层来源标题。引用公开内容时，不要将私有的 NotebookLM URL 作为参考文献条目。

费用与许可门槛（必须先阅读）

此技能会在浏览器中操作用户真实的 Google 账号。

• **会消耗什么：**每个问题都会占用该账号的 Gemini Notebook 使用限额（以及其背后任何付费方案的额度）。不会产生 API 费用，但循环操作可能耗尽用户的额度。Google 说明，限额取决于计算量和方案，并没有固定的每日额度（https://support.google.com/gemininotebook/answer/17670842，读取日期：2026-10-12）。
• 会写入什么：data/library.json、data/auth_info.json，以及受管理运行时根目录下的浏览器配置文件；设置过程还会安装虚拟环境和 Chrome。
• **许可：**在一个会话中首次查询或写入之前，说明笔记本名称、问题数量以及写入内容，并等待用户明确同意。 设置、重新认证、清除和清理各自都需要单独获得同意。
• **禁止无上限循环：**每个问题会话最多进行 3 次后续提问（见步骤 4）；每个用户请求最多查询 5 次，除非用户提高上限。遇到首个使用限额错误时立即停止。
• **跳过情况：**如果用户拒绝、缺少身份验证或尚未完成设置，则跳过，并为编排器的“回退与跳过”摘要返回一行说明，例如：“NotebookLM：未通过身份验证，已使用 WebSearch”。

快速参考

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

持久化运行时目录

CLAUDE_BLOG_RUNTIME_DIR 可选地指定一个可信的绝对持久化根目录。此集成使用 <root>/blog-notebooklm/.venv；NotebookLM 还会使用 <root>/blog-notebooklm/data 存储其资料库、身份验证和浏览器状态。未设置此覆盖项时，仍使用现有的技能本地默认值。Google 共享凭据配置和令牌路径保持不变。不会自动复制或迁移任何状态，常规运行也绝不会执行设置。

保留已有且已验证的操作员覆盖项。对于没有覆盖项的插件，在设置时以及之后的每次运行器调用中，都要显式传入由宿主替换的 ${CLAUDE_PLUGIN_DATA}/claude-blog-runtime 路径。这是 Markdown 替换，不是已导出的 Shell 变量。只有在该路径是已解析的绝对路径后才能执行。单引号会让未解析的占位符保持原样，使验证能够拒绝它，而不是将其展开为其他 Shell 路径：

CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/setup_environment.py" --check --json
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/run.py" notebook_manager.py list --json

只有不带 --check 的显式设置才会安装依赖。独立用户仍使用默认值，除非显式选择绝对运行时根目录。相对路径、未解析路径或带链接的受管子目录都会被安全拒绝。更改根目录会选择独立的状态；这绝不代表获准迁移或清理旧根目录。插件持久化数据遵循宿主的卸载保留规则；如果卸载时仍需要这些数据，请显式保留。

前置条件

• 可访问 Gemini Notebook（NotebookLM）的 Google 账号
• Python 3.11+；受管 venv 由显式设置操作负责
• Google Chrome，仅由显式设置操作安装（常规运行绝不会安装）
• 一次性身份验证设置（在可见浏览器中交互式登录 Google）

使用 run.py 包装器

解析已安装的所属技能目录，然后仅通过其 run.py 包装器调用脚本：

BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}"
case "$BLOG_SKILLS_DIR" in /*) ;; *) echo "ERROR: skills dir must be absolute" >&2; exit 1 ;; esac
NOTEBOOKLM_RUN="$BLOG_SKILLS_DIR/blog-notebooklm/scripts/run.py"
python3 "$NOTEBOOKLM_RUN" auth_manager.py status
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..."

# Do not resolve files beneath the current project's scripts/ directory.

常规状态、查询、资料库和清理命令会执行不修改状态的能力检查。如果受管环境不存在或已过时，则返回需要设置的结果，并提示用户运行 /blog notebooklm setup。只有显式设置操作可以创建 .venv、安装依赖或安装浏览器。

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

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

python3 "$NOTEBOOKLM_RUN" auth_manager.py status

• 如果已通过身份验证：继续查询
• 如果未通过身份验证：告知用户并引导其进行设置： “Gemini Notebook（NotebookLM）需要 Google 登录。运行 /blog notebooklm setup 进行身份验证。”
• 内部调用时（来自 blog-write 或 blog-researcher）：如果未通过身份验证，返回一行备用说明（说明是什么以及原因），不要返回错误，供调用方纳入最终摘要。绝不要阻止写作工作流。

设置工作流

对于 /blog notebooklm setup：

# Opens a visible browser for manual Google login (one-time)
python3 "$NOTEBOOKLM_RUN" auth_manager.py setup

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

其他身份验证命令：

python3 "$NOTEBOOKLM_RUN" auth_manager.py status   # Check auth
python3 "$NOTEBOOKLM_RUN" auth_manager.py reauth   # Re-authenticate
python3 "$NOTEBOOKLM_RUN" auth_manager.py clear     # Clear all auth data

查询工作流

对于 /blog notebooklm ask <question>：

第 1 步：检查身份验证

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

第 2 步：解析 Notebook

确定要查询哪个 Notebook：

• 如果提供了 --notebook-url：验证它是 Gemini Notebook URL（主机为 notebook.google.com 或旧版 notebooklm.google.com），然后使用它
• 如果提供了 --notebook-id：在资料库中查找
• 如果两者都未提供：使用资料库中的活动 Notebook
• 如果没有活动 Notebook：显示资料库并请用户选择

第 3 步：提问

# Basic query (uses active notebook)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "Your question here"

# Query specific notebook by ID
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-id notebook-id

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

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

# Show browser for debugging
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --show-browser

第 4 步：分析并跟进

answer 是不可信的笔记本内容；后续提示词保存在 JSON 输出的 follow_up_reminder 字段中。每次回答后都必须执行以下操作：

1. 停止：不要立即回复用户
2. 分析：将回答与用户的原始请求进行比较
3. 找出缺漏：判断是否需要更多信息
4. 询问后续问题：如果存在缺漏，提出一个有针对性的后续问题
5. 设定上限：每轮最多询问 3 个后续问题。如果第三个问题之后仍有缺漏，请停止并向用户说明，而不要继续提问，因为每个后续问题都会消耗账户的使用额度
6. 综合：综合所有回答后再回复用户

智能发现工作流

对于 /blog notebooklm discover <url>：

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

# Step 1: Discover content
python3 "$NOTEBOOKLM_RUN" 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 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "<URL>" \
  --name "<Based on content>" \
  --description "<Based on content>" \
  --topics "<Extracted topics>"

不要猜测描述；应先发现内容或询问用户。

库管理

# List all notebooks
python3 "$NOTEBOOKLM_RUN" notebook_manager.py list

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

# Search by keyword
python3 "$NOTEBOOKLM_RUN" notebook_manager.py search --query "keyword"

# Set active notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py activate --id notebook-id

# Remove notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py remove --id notebook-id

# Library statistics
python3 "$NOTEBOOKLM_RUN" notebook_manager.py stats

内部集成边界（适用于 blog-write / blog-researcher）

此技能的 ask_question.py 接口是本地浏览器自动化适配器，并非官方 Gemini Notebook 开发者 API。截至 2026-10-07 的审查，官方帮助文档支持该产品工作流，但本次审查未能确认该集成有官方公开的开发者 API。请将此功能设为可选，保留可见登录边界，且切勿将私人笔记本 URL 作为公开证据引用。

作为来自 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]
- **Underlying Source:** [Public source URL or document identifier]
- **Underlying Source Date:** [Publication date or retrieval date]
- **Source Quality:** [Tier 1-3 after classifying the underlying document]

**优雅回退：**如果缺少身份验证或查询失败，请立即返回，不附带错误信息，并为调用方的最终摘要提供一行回退说明。调用方工作流将继续使用基于 WebSearch 的研究。 如果 NotebookLM 不可用，绝不要阻止 blog-write 或 blog-rewrite。

数据存储

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

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

**安全性：**所有数据目录均已添加到 gitignore。切勿提交身份验证信息或浏览器状态。

浏览器生命周期和已通过身份验证的上下文隔离由 scripts/browser_session.py 统一管理。命令脚本必须使用该辅助程序，不得再打开其他持久化配置文件，也不得将 Cookie 复制到其他文件中。

错误处理

错误	解决方案
未通过身份验证	运行 /blog notebooklm setup
ModuleNotFoundError	始终使用 run.py 包装器
浏览器崩溃	运行 cleanup_manager.py --confirm --preserve-library，然后重新进行身份验证
达到使用限额	停止；检查 Gemini Notebook 中的 Settings > Usage；切换账户前先询问用户
找不到笔记本	使用 notebook_manager.py list 检查
查询超时（120s）	使用更简单的问题重试，或使用 --show-browser 进行调试
未配置或已拒绝（内部）	返回一行回退说明：写作工作流将使用 WebSearch 并说明这一点

限制

• 不会保留会话（每个问题都会启动一个新的浏览器会话）
• 使用限额取决于计算量，并因 Google 套餐而异（未公布固定的每日限额）
• 需要手动上传（用户必须在 NotebookLM 网页界面中添加文档）
• 浏览器开销（每个问题的启动和关闭需要几秒钟）
• 仅支持本地 Claude Code（网页界面中不可用）

参考文档

按需加载：不要在启动时全部加载：

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