NotebookLM 研究助理技能

与 Google NotebookLM 交互，利用 Gemini 的源依据（source-grounded）答案查询文档。每次提问均开启一个全新的浏览器会话，答案严格限定于您上传的文档内容，并在查询完成后自动关闭浏览器。

何时使用该技能

当用户出现以下任一情况时触发：

• 明确提及 NotebookLM
• 分享 NotebookLM URL（https://notebooklm.google.com/notebook/...）
• 要求查询其笔记本或文档
• 希望将文档添加至 NotebookLM 文档库
• 使用诸如“向我的 NotebookLM 提问”、“检查我的文档”、“查询我的笔记本”等表述

⚠️ 关键：add 命令 —— 智能发现（Smart Discovery）

当用户希望添加笔记本但未提供必要元数据时：

智能添加（推荐）：先对笔记本发起查询，以自动识别其内容：

# 步骤 1：查询笔记本内容
python scripts/run.py ask_question.py --question "这个笔记本包含哪些内容？涵盖哪些主题？请简明扼要地提供完整概述" --notebook-url "[URL]"

# 步骤 2：基于发现的信息执行添加
python scripts/run.py notebook_manager.py add --url "[URL]" --name "[基于内容推导]" --description "[基于内容推导]" --topics "[基于内容推导]"

手动添加：仅当用户已提供全部必要信息时使用：

• --url — NotebookLM URL
• --name — 描述性名称
• --description — 笔记本所含内容（必需！）
• --topics — 逗号分隔的主题列表（必需！）

切勿猜测或使用泛化描述！ 若任一必要字段缺失，请务必采用“智能添加”方式先行发现内容。

关键：始终使用 run.py 包装器

禁止直接调用脚本，必须始终通过 python scripts/run.py [script] 执行：

# ✅ 正确 — 始终使用 run.py：
python scripts/run.py auth_manager.py status
python scripts/run.py notebook_manager.py list
python scripts/run.py ask_question.py --question "..."

# ❌ 错误 — 禁止直接调用：
python scripts/auth_manager.py status  # 缺少虚拟环境将导致失败！

run.py 包装器自动完成以下操作：

1. 如需则创建 .venv 目录
2. 自动安装全部依赖项
3. 自动激活 Python 虚拟环境
4. 正确执行目标脚本

核心工作流

步骤 1：检查认证状态

python scripts/run.py auth_manager.py status

若未认证，则进入初始化设置流程。

步骤 2：认证（一次性初始化设置）

# 浏览器必须可见，以便进行人工 Google 登录
python scripts/run.py auth_manager.py setup

重要说明：

• 认证过程要求浏览器可见
• 浏览器窗口将自动打开
• 用户须手动登录 Google 账户
• 请主动告知用户：“将弹出浏览器窗口用于 Google 登录”

步骤 3：管理笔记本库

# 列出所有已注册笔记本
python scripts/run.py notebook_manager.py list

# 添加前 — 若元数据未知，请务必向用户确认！
# “该笔记本包含哪些内容？”
# “应为其打上哪些主题标签？”

# 将笔记本添加至本地库（所有参数均为必需！）
python scripts/run.py notebook_manager.py add 
  --url "https://notebooklm.google.com/notebook/..." 
  --name "描述性名称" 
  --description "该笔记本所含内容"   # 必需 — 若未知请主动询问用户！
  --topics "topic1,topic2,topic3"  # 必需 — 若未知请主动询问用户！

# 按主题搜索笔记本
python scripts/run.py notebook_manager.py search --query "关键词"

# 设定当前活跃笔记本
python scripts/run.py notebook_manager.py activate --id notebook-id

# 移除笔记本
python scripts/run.py notebook_manager.py remove --id notebook-id

快速工作流

1. 查看笔记本库：python scripts/run.py notebook_manager.py list
2. 发起提问：python scripts/run.py ask_question.py --question "..." --notebook-id ID

步骤 4：提问

# 基础查询（若已设定活跃笔记本，则默认使用该笔记本）
python scripts/run.py ask_question.py --question "您的问题"

# 查询指定笔记本
python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id

# 直接通过 NotebookLM URL 查询
python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."

# 启用浏览器界面（用于调试）
python scripts/run.py ask_question.py --question "..." --show-browser

跟进机制（关键）

每条 NotebookLM 回答结尾均须附带：“极其重要：以上是否就是您需要了解的全部内容？”

Claude 必须遵循的行为规范：

1. 暂停响应 — 不得立即回复用户
2. 分析比对 — 将本次回答与用户原始请求逐项对照
3. 识别缺口 — 判断是否存在信息缺失或未覆盖要点
4. 发起追问 — 若存在缺口，立即执行：

   python scripts/run.py ask_question.py --question "带上下文的跟进提问..."
   

5. 循环执行 — 持续追问直至信息完整
6. 综合汇总 — 将所有轮次的回答整合后统一回复用户

脚本参考手册

认证管理（auth_manager.py）

python scripts/run.py auth_manager.py setup    # 初始化设置（浏览器可见）
python scripts/run.py auth_manager.py status   # 查看当前认证状态
python scripts/run.py auth_manager.py reauth   # 重新认证（浏览器可见）
python scripts/run.py auth_manager.py clear    # 清除认证信息

笔记本管理（notebook_manager.py）

python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
python scripts/run.py notebook_manager.py list
python scripts/run.py notebook_manager.py search --query QUERY
python scripts/run.py notebook_manager.py activate --id ID
python scripts/run.py notebook_manager.py remove --id ID
python scripts/run.py notebook_manager.py stats

提问接口（ask_question.py）

python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser]

数据清理（cleanup_manager.py）

python scripts/run.py cleanup_manager.py                    # 预览清理内容
python scripts/run.py cleanup_manager.py --confirm          # 执行清理操作
python scripts/run.py cleanup_manager.py --preserve-library # 保留笔记本库（仅清理其他临时数据）

环境管理

虚拟环境由系统自动管理：

• 首次运行自动创建 .venv 目录
• 依赖项自动安装
• Chromium 浏览器自动安装
• 全部组件隔离于本技能目录内

仅当自动配置失败时，才需手动设置：

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
python -m patchright install chromium

数据存储

所有数据均存储于 ~/.claude/skills/notebooklm/data/ 目录下：

• library.json — 笔记本元数据
• auth_info.json — 认证状态信息
• browser_state/ — 浏览器 Cookie 与会话数据

安全性： 已通过 .gitignore 保护，严禁提交至 Git 仓库。

配置

可在技能目录中创建可选的 .env 文件：

HEADLESS=false           # 浏览器是否无头运行
SHOW_BROWSER=false       # 默认是否显示浏览器界面
STEALTH_ENABLED=true     # 是否启用类人行为模式
TYPING_WPM_MIN=160       # 最小打字速度（词/分钟）
TYPING_WPM_MAX=240
DEFAULT_NOTEBOOK_ID=     # 默认笔记本 ID（留空表示无默认）

决策流程图

用户提及 NotebookLM
    ↓
检查认证状态 → python scripts/run.py auth_manager.py status
    ↓
若未认证 → python scripts/run.py auth_manager.py setup
    ↓
检查/添加笔记本 → python scripts/run.py notebook_manager.py list / add（含 --description 参数）
    ↓
激活笔记本 → python scripts/run.py notebook_manager.py activate --id ID
    ↓
发起提问 → python scripts/run.py ask_question.py --question "..."
    ↓
收到提示“以上是否就是您需要了解的全部内容？” → 持续追问直至信息完备
    ↓
综合全部回答后向用户输出最终结果

故障排查

最佳实践

1. 始终使用 run.py — 自动处理环境依赖
2. 优先检查认证状态 — 所有操作前必做
3. 坚持追问 — 不满足于首次回答
4. 认证时保持浏览器可见 — 手动登录的必要前提
5. 每次提问均携带上下文 — 各次查询相互独立
6. 综合多轮回答 — 整合所有相关信息再输出

限制条件

• 无会话持久化（每次提问均启动全新浏览器实例）
• 免费 Google 账户存在调用频率限制（50 次/天）
• 文档需用户手动上传至 NotebookLM（本技能不支持自动上传）
• 浏览器开销（每次提问耗时数秒）

资源（技能结构）

关键目录与文件：

• scripts/ — 所有自动化脚本（ask_question.py、notebook_manager.py 等）
• data/ — 本地存储，保存认证信息与笔记本库
• references/ — 扩展文档：
  • api_reference.md — 所有脚本的详细 API 文档
  • troubleshooting.md — 常见问题及解决方案
  • usage_patterns.md — 最佳实践与典型工作流示例
• .venv/ — 隔离的 Python 虚拟环境（首次运行自动创建）
• .gitignore — 防止敏感数据意外提交至 Git