介绍
# NotebookLM Research Assistant Skill
与 Google NotebookLM 交互，利用 Gemini 的基于来源的回答查询文档。每个问题都会打开一个新的浏览器会话，专门从您上传的文档中检索答案，然后关闭。
## 何时使用此技能
在用户出现以下情况时触发： - 明确提及 NotebookLM - 共享 NotebookLM URL (`https://notebooklm.google.com/notebook/...`) - 要求查询他们的笔记本/文档 - 希望将文档添加到 NotebookLM 库 - 使用诸如“询问我的 NotebookLM”、“检查我的文档”、“查询我的笔记本”之类的短语
## ⚠️ 关键：添加命令 - 智能发现
当用户想要添加笔记本但未提供详细信息时：
**智能添加（推荐）**：先查询笔记本以发现其内容： ```bash # Step 1: Query the notebook about its content python 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: Use the discovered information to add it python scripts/run.py notebook_manager.py add --url "[URL]" --name "[Based on content]" --description "[Based on content]" --topics "[Based on content]" ```
**手动添加**：如果用户提供了所有详细信息： - `--url` - NotebookLM URL - `--name` - 描述性名称 - `--description` - 笔记本包含的内容（必需！） - `--topics` - 逗号分隔的主题（必需！）
切勿猜测或使用通用描述！如果缺少详细信息，请使用智能添加来发现它们。
## 关键：始终使用 run.py 包装器
**切勿直接调用脚本。始终使用 `python scripts/run.py [script]`：**
```bash # ✅ CORRECT - Always use 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 "..."
# ❌ WRONG - Never call directly: python scripts/auth_manager.py status # Fails without venv! ```
`run.py` 包装器会自动： 1. 在需要时创建 `.venv` 2. 安装所有依赖项 3. 激活环境 4. 正确执行脚本
## 核心工作流
### 步骤 1：检查身份验证状态 ```bash python scripts/run.py auth_manager.py status ```
如果未通过身份验证，请继续进行设置。
### 步骤 2：身份验证（一次性设置） ```bash # Browser MUST be visible for manual Google login python scripts/run.py auth_manager.py setup ```
**重要：** - 身份验证时浏览器是可见的 - 浏览器窗口会自动打开 - 用户必须手动登录 Google - 告知用户：“将打开一个浏览器窗口用于 Google 登录”
### 步骤 3：管理笔记本库
```bash # List all notebooks python scripts/run.py notebook_manager.py list
# BEFORE ADDING: Ask user for metadata if unknown! # "What does this notebook contain?" # "What topics should I tag it with?"
# Add notebook to library (ALL parameters are REQUIRED!) python scripts/run.py notebook_manager.py add \ --url "https://notebooklm.google.com/notebook/..." \ --name "Descriptive Name" \ --description "What this notebook contains" \ # REQUIRED - ASK USER IF UNKNOWN! --topics "topic1,topic2,topic3" # REQUIRED - ASK USER IF UNKNOWN!
# Search notebooks by topic python scripts/run.py notebook_manager.py search --query "keyword"
# Set active notebook python scripts/run.py notebook_manager.py activate --id notebook-id
# Remove notebook 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：提问
```bash # Basic query (uses active notebook if set) python scripts/run.py ask_question.py --question "Your question here"
# Query specific notebook python scripts/run.py ask_question.py --question "..." --notebook-id notebook-id
# Query with notebook URL directly python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
# Show browser for debugging python scripts/run.py ask_question.py --question "..." --show-browser ```
## 后续机制（关键）
每个 NotebookLM 回答都以：**“极其重要：这就是您想知道的全部内容吗？”** 结尾
**Claude 的必需行为：** 1. **停止** - 不要立即回复用户 2. **分析** - 将回答与用户的原始请求进行比较 3. **识别差距** - 确定是否需要更多信息 4. **提出后续问题** - 如果存在差距，立即询问： ```bash python scripts/run.py ask_question.py --question "Follow-up with context..." ``` 5. **重复** - 继续直到信息完整 6. **综合** - 在回复用户之前结合所有答案
## 脚本参考
### 身份验证管理 (`auth_manager.py`) ```bash python scripts/run.py auth_manager.py setup # Initial setup (browser visible) python scripts/run.py auth_manager.py status # Check authentication python scripts/run.py auth_manager.py reauth # Re-authenticate (browser visible) python scripts/run.py auth_manager.py clear # Clear authentication ```
### 笔记本管理 (`notebook_manager.py`) ```bash 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`) ```bash python scripts/run.py ask_question.py --question "..." [--notebook-id ID] [--notebook-url URL] [--show-browser] ```
### 数据清理 (`cleanup_manager.py`) ```bash python scripts/run.py cleanup_manager.py # Preview cleanup python scripts/run.py cleanup_manager.py --confirm # Execute cleanup python scripts/run.py cleanup_manager.py --preserve-library # Keep notebooks ```
## 环境管理
虚拟环境是自动管理的： - 首次运行会自动创建 `.venv` - 依赖项会自动安装 - Chromium 浏览器会自动安装 - 所有内容都隔离在技能目录中
手动设置（仅在自动失败时）： ```bash 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` 文件： ```env HEADLESS=false # Browser visibility SHOW_BROWSER=false # Default browser display STEALTH_ENABLED=true # Human-like behavior TYPING_WPM_MIN=160 # Typing speed TYPING_WPM_MAX=240 DEFAULT_NOTEBOOK_ID= # Default notebook ```
## 决策流程
``` User mentions NotebookLM ↓ Check auth → python scripts/run.py auth_manager.py status ↓ If not authenticated → python scripts/run.py auth_manager.py setup ↓ Check/Add notebook → python scripts/run.py notebook_manager.py list/add (with --description) ↓ Activate notebook → python scripts/run.py notebook_manager.py activate --id ID ↓ Ask question → python scripts/run.py ask_question.py --question "..." ↓ See "Is that ALL you need?" → Ask follow-ups until complete ↓ Synthesize and respond to user ```
## 故障排除
| 问题 | 解决方案 | |---------|----------| | ModuleNotFoundError | 使用 `run.py` 包装器 | | 身份验证失败 | 设置时浏览器必须可见！--show-browser | | 速率限制（50次/天） | 等待或切换 Google 账号 | | 浏览器崩溃 | `python scripts/run.py cleanup_manager.py --preserve-library` | | 找不到笔记本 | 使用 `notebook_manager.py list` 检查 |
## 最佳实践
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` - 防止敏感数据被提交