nblm

NotebookLM 快速命令

查询 Google NotebookLM，获取基于来源、带有引用的答案。

环境

所有依赖和认证均由 run.py 自动处理：

• 首次运行会自动创建 .venv 并安装 Python/Node.js 依赖
• 如果 Google 认证缺失或过期，浏览器窗口会自动打开
• 无需手动前置步骤

---

用法

/nblm <command> [args]

命令

笔记本管理

命令	描述
login	使用 Google 认证
status	显示认证和库状态
accounts	列出所有 Google 账号
accounts add	添加新的 Google 账号
accounts switch <id>	切换活跃账号（按索引或邮箱）
accounts remove <id>	移除 Google 账号
accounts use <id>	设置代理特定的活跃账号（OpenClaw 隔离）
accounts clear	清除代理特定的账号覆盖
local	列出本地库中的笔记本
remote	从 NotebookLM API 列出所有笔记本
create <name>	创建新笔记本
delete [--id ID]	删除笔记本
rename <name> [--id ID]	重命名笔记本
summary [--id ID]	获取 AI 生成的摘要
describe [--id ID]	获取描述和建议主题
add <url-or-id>	将笔记本添加到本地库（自动检测 URL 或笔记本 ID）
activate <id>	设置活跃笔记本

来源管理

命令	描述
sources [--id ID]	列出笔记本中的来源
upload <file>	上传单个文件
upload <folder>	同步文件夹中的文件到 NotebookLM
upload-zlib <url>	从 Z-Library 下载并上传
upload-url <url>	添加 URL 作为来源
upload-youtube <url>	添加 YouTube 视频作为来源
upload-text <title> [--content TEXT]	添加文本作为来源
source-text <source-id>	获取完整索引文本
source-guide <source-id>	获取 AI 摘要和关键词
source-rename <source-id> <name>	重命名来源
source-refresh <source-id>	重新获取 URL 内容
source-delete <source-id>	删除来源

上传选项：

• --use-active - 上传到当前活跃笔记本
• --create-new - 创建一个以文件/文件夹命名的新笔记本
• --notebook-id <id> - 上传到指定笔记本
• --dry-run - 显示同步计划但不执行（文件夹同步）
• --rebuild - 强制重建跟踪文件（文件夹同步）

重要： 当用户运行上传而未指定目标时，先询问用户：

"您想上传到活跃笔记本，还是创建新笔记本？"
然后传递相应的标志（--use-active 或 --create-new）。

聊天与音频/媒体

命令	描述
ask <question>	查询 NotebookLM
podcast [--instructions TEXT]	生成音频播客
podcast-status <task-id>	检查播客生成状态
podcast-download [output-path]	下载最新播客
briefing [--instructions TEXT]	生成简短音频摘要
debate [--instructions TEXT]	生成辩论风格音频
slides [--instructions TEXT]	生成幻灯片
slides-download [output-path]	下载幻灯片为 PDF
infographic [--instructions TEXT]	生成信息图
infographic-download [output-path]	下载信息图
media-list [--type TYPE]	列出生成的媒体（音频/视频/幻灯片/信息图）
media-delete <id>	删除生成的媒体项

命令路由

根据 $ARGUMENTS，执行相应的命令：

$IF($ARGUMENTS,
从 "$ARGUMENTS" 解析命令：

login → python scripts/run.py auth_manager.py setup --service google

accounts → python scripts/run.py auth_manager.py accounts list

accounts add → python scripts/run.py auth_manager.py accounts add

accounts switch <id> → python scripts/run.py auth_manager.py accounts switch "<id>"

accounts remove <id> → python scripts/run.py auth_manager.py accounts remove "<id>"

accounts use <id> → python scripts/run.py auth_manager.py accounts use "<id>"

accounts clear → python scripts/run.py auth_manager.py accounts clear

status → 同时运行：

• python scripts/run.py auth_manager.py status
• python scripts/run.py notebook_manager.py list

local → python scripts/run.py notebook_manager.py list

remote → python scripts/run.py nblm_cli.py notebooks

create <name> → python scripts/run.py nblm_cli.py create "<name>"

delete [--id ID] → python scripts/run.py nblm_cli.py delete <args>

rename <name> [--id ID] → python scripts/run.py nblm_cli.py rename "<name>" <args>

summary [--id ID] → python scripts/run.py nblm_cli.py summary <args>

describe [--id ID] → python scripts/run.py nblm_cli.py describe <args>

add <url-or-id> → 智能添加工作流（自动检测 URL 或笔记本 ID）

activate <id> → python scripts/run.py notebook_manager.py activate --id "<id>"

sources [--id ID] → python scripts/run.py nblm_cli.py sources <args>

upload <file> → 先询问用户：“上传到活跃笔记本还是创建新笔记本？”然后：
- 活跃：python scripts/run.py source_manager.py add --file "<file>" --use-active
- 新建：python scripts/run.py source_manager.py add --file "<file>" --create-new

upload <folder> → 同步文件夹：
- 先询问用户：“同步到活跃笔记本、创建新笔记本，还是指定笔记本？”
- 活跃：python scripts/run.py source_manager.py sync "<folder>" --use-active
- 新建：python scripts/run.py source_manager.py sync "<folder>" --create-new
- 指定：python scripts/run.py source_manager.py sync "<folder>" --notebook-id ID
- 试运行：python scripts/run.py source_manager.py sync "<folder>" --dry-run
- 重建：python scripts/run.py source_manager.py sync "<folder>" --rebuild

upload-zlib <url> → 先询问用户：“上传到活跃笔记本还是创建新笔记本？”然后：
- 活跃：python scripts/run.py source_manager.py add --url "<url>" --use-active
- 新建：python scripts/run.py source_manager.py add --url "<url>" --create-new

upload-url <url> → python scripts/run.py nblm_cli.py upload-url "<url>"

upload-youtube <url> → python scripts/run.py nblm_cli.py upload-youtube "<url>"

upload-text <title> → python scripts/run.py nblm_cli.py upload-text "<title>" <args>

source-text <id> → python scripts/run.py nblm_cli.py source-text "<id>"

source-guide <id> → python scripts/run.py nblm_cli.py source-guide "<id>"

source-rename <id> <name> → python scripts/run.py nblm_cli.py source-rename "<id>" "<name>"

source-refresh <id> → python scripts/run.py nblm_cli.py source-refresh "<id>"

source-delete <id> → python scripts/run.py nblm_cli.py source-delete "<id>"

ask <question> → python scripts/run.py nblm_cli.py ask "<question>"

podcast → python scripts/run.py artifact_manager.py generate --format DEEP_DIVE <args>

podcast-status <task-id> → python scripts/run.py artifact_manager.py status --task-id "<task-id>"

podcast-download [output-path] → python scripts/run.py artifact_manager.py download "<output-path>"

briefing → python scripts/run.py artifact_manager.py generate --format BRIEF <args>

debate → python scripts/run.py artifact_manager.py generate --format DEBATE <args>

slides → python scripts/run.py artifact_manager.py generate-slides <args>

slides-download [output-path] → python scripts/run.py artifact_manager.py download "<output-path>" --type slide-deck

infographic → python scripts/run.py artifact_manager.py generate-infographic <args>

infographic-download [output-path] → python scripts/run.py artifact_manager.py download "<output-path>" --type infographic

media-list [--type TYPE] → python scripts/run.py artifact_manager.py list <args>

media-delete <id> → python scripts/run.py artifact_manager.py delete "<id>"

如果命令无法识别，显示使用帮助。,

显示可用命令，使用 /nblm（无参数）
)

播客选项

/nblm podcast --length DEFAULT --wait --output ./podcast.mp3
/nblm podcast --instructions "关注关键发现"
/nblm briefing --wait --output ./summary.mp3
/nblm debate --instructions "比较两种方法"

选项	值
--length	SHORT, DEFAULT, LONG
--instructions	自定义内容说明
--wait	等待生成完成
--output	下载路径（需要 --wait）

幻灯片选项

/nblm slides --format DETAILED_DECK --wait --output ./presentation.pdf
/nblm slides --instructions "关注关键图表" --format PRESENTER_SLIDES

选项	值
--format	DETAILED_DECK, PRESENTER_SLIDES
--length	SHORT, DEFAULT
--instructions	自定义内容说明
--wait	等待生成完成
--output	下载路径（需要 --wait）

信息图选项

/nblm infographic --orientation LANDSCAPE --wait --output ./visual.png
/nblm infographic --instructions "突出比较" --detail-level DETAILED

选项	值
--orientation	LANDSCAPE, PORTRAIT, SQUARE
--detail-level	CONCISE, STANDARD, DETAILED
--instructions	自定义内容说明
--wait	等待生成完成
--output	下载路径（需要 --wait）

媒体生成

命令	描述	输出
/nblm podcast	深度音频讨论	MP3
/nblm briefing	简短音频摘要	MP3
/nblm debate	辩论风格音频	MP3
/nblm slides	幻灯片演示	PDF
/nblm infographic	视觉信息图	PNG

示例

/nblm podcast --wait --output ./deep-dive.mp3
/nblm briefing --instructions "关注第3章" --wait
/nblm debate --length LONG --wait --output ./debate.mp3
/nblm slides --instructions "包含关键图表" --format DETAILED_DECK --wait --output ./presentation.pdf
/nblm infographic --orientation LANDSCAPE --detail-level DETAILED --wait --output ./summary.png

下载与管理

/nblm podcast-download ./my-podcast.mp3
/nblm slides-download ./presentation.pdf
/nblm infographic-download ./visual.png
/nblm media-list                     # 列出所有生成的媒体
/nblm media-list --type audio        # 仅列出音频
/nblm media-delete <id>              # 删除媒体项

---

扩展文档

何时使用此技能

当用户：

• 明确提及 NotebookLM
• 分享 NotebookLM URL（https://notebooklm.google.com/notebook/...）
• 要求查询其笔记本/文档
• 想将文档添加到 NotebookLM 库
• 使用类似“询问我的 NotebookLM”、“查看我的文档”、“查询我的笔记本”等短语时触发

⚠️ 关键：添加命令 - 智能发现

添加命令现在自动发现笔记本的元数据：

# 智能添加（自动发现名称、描述、主题）
python scripts/run.py notebook_manager.py add <notebook-id-or-url>

# 可选覆盖
python scripts/run.py notebook_manager.py add <id> --name "自定义名称" --topics "自定义,主题"

智能添加的功能：

1. 从 NotebookLM API 获取笔记本标题
2. 查询笔记本内容以生成描述和主题
3. 将发现的元数据添加到本地库

支持的输入格式：

• 笔记本 ID：5fd9f36b-8000-401d-a7a0-7aa3f7832644
• 完整 URL：https://notebooklm.google.com/notebook/5fd9f36b-8000-401d-a7a0-7aa3f7832644

除非用户明确提供，否则永远不要手动指定 --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  # 没有 venv 会失败！

run.py 包装器自动：

1. 如果需要，创建 .venv
2. 安装所有依赖
3. 激活环境
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 "主题1,主题2,主题3"  # 必需 - 如果未知，询问用户！

# 按主题搜索笔记本
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

# 直接使用笔记本 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. 综合 - 在回复用户之前合并所有答案

Z-Library 集成

触发条件

• 用户提供 Z-Library URL（zlib.li, z-lib.org, zh.zlib.li）
• 用户说“将这本书下载到 NotebookLM”
• 用户说“从 Z-Library 添加这本书”

设置（一次性）

# 使用 Z-Library 认证
python scripts/run.py auth_manager.py setup --service zlibrary

命令

# 从 Z-Library 添加书籍
python scripts/run.py source_manager.py add --url "https://zh.zlib.li/book/..."

# 检查 Z-Library 认证状态
python scripts/run.py auth_manager.py status --service zlibrary

脚本参考

认证管理（auth_manager.py）

python scripts/run.py auth_manager.py setup                    # 默认：Google
python scripts/run.py auth_manager.py setup --service google
python scripts/run.py auth_manager.py setup --service zlibrary
python scripts/run.py auth_manager.py status                   # 显示所有服务
python scripts/run.py auth_manager.py status --service zlibrary
python scripts/run.py auth_manager.py clear --service zlibrary # 清除认证

# 多账号管理（Google）
python scripts/run.py auth_manager.py accounts list             # 列出所有账号
python scripts/run.py auth_manager.py accounts add              # 添加新账号
python scripts/run.py auth_manager.py accounts switch 1         # 按索引切换
python scripts/run.py auth_manager.py accounts switch user@gmail.com  # 按邮箱切换
python scripts/run.py auth_manager.py accounts remove 2         # 移除账号

笔记本管理（notebook_manager.py）

python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
# 或直接使用笔记本 ID：
python scripts/run.py notebook_manager.py add --notebook-id ID --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]

来源管理器（source_manager.py）

# 上传到活跃笔记本
python scripts/run.py source_manager.py add --file "/path/to/book.pdf" --use-active

# 为上传创建新笔记本
python scripts/run.py source_manager.py add --file "/path/to/book.pdf" --create-new

# 上传到特定笔记本
python scripts/run.py source_manager.py add --file "/path/to/book.pdf" --notebook-id NOTEBOOK_ID

# Z-Library 下载并上传
python scripts/run.py source_manager.py add --url "https://zh.zlib.li/book/..." --use-active
python scripts/run.py source_manager.py add --url "https://zh.zlib.li/book/..." --create-new

# 同步文件夹（新功能！）
python scripts/run.py source_manager.py sync "/path/to/docs" --use-active
python scripts/run.py source_manager.py sync "/path/to/docs" --create-new
python scripts/run.py source_manager.py sync "/path/to/docs" --notebook-id NOTEBOOK_ID

# 同步选项（新功能！）
python scripts/run.py source_manager.py sync "/path/to/docs" --dry-run    # 仅预览
python scripts/run.py source_manager.py sync "/path/to/docs" --rebuild   # 强制重新哈希所有文件

文件夹同步：

• 扫描文件夹中支持的类型：PDF, TXT, MD, DOCX, HTML, EPUB
• 内部跟踪同步状态（无需管理每个文件夹的跟踪文件）
• 同步策略：添加新的，更新修改的（删除并重新上传），跳过未更改的
• 多账号感知（跟踪使用了哪个 Google 账号）
  注意： --use-active、--create-new 或 --notebook-id 三者中必须指定一个。
  上传会等待 NotebookLM 处理并打印进度为 Ready: N/T。按 Ctrl+C 停止等待。
  本地文件上传使用浏览器自动化，需要 Google 认证。
  如果浏览器自动化不可用，设置 NOTEBOOKLM_UPLOAD_MODE=text 以上传提取的文本（PDF 需要 pypdf）。

数据清理（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 # 保留笔记本

看门狗状态（auth_manager.py）

python scripts/run.py auth_manager.py watchdog-status

环境管理

虚拟环境自动管理：

• 首次运行自动创建 .venv
• 依赖自动安装
• Node.js 依赖自动安装
• agent-browser 守护进程按需启动，并将浏览器状态保存在内存中
• 守护进程在 10 分钟无活动后停止（任何 agent-browser 命令都会重置计时器）
• 设置 AGENT_BROWSER_OWNER_PID 可在代理进程退出时自动停止
• scripts/run.py 默认将 AGENT_BROWSER_OWNER_PID 设置为其父 PID
• 所有内容隔离在技能目录中

手动设置（仅在自动失败时）：

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
pip install -r requirements.txt
npm install
npm run install-browsers

数据存储

所有数据存储在 ~/.claude/skills/notebooklm/data/：

• library.json - 笔记本元数据（带账号关联）
• auth/google/ - 多账号 Google 认证
  • index.json - 账号索引（活跃账号、列表）
  • <n>-<email>.json - 每个账号的凭据
• auth/zlibrary.json - Z-Library 认证状态
• agent_browser/session_id - 当前守护进程会话 ID
• agent_browser/last_activity.json - 空闲关闭的最后活动时间戳
• agent_browser/watchdog.pid - 空闲看门狗进程 ID

安全： 受 .gitignore 保护，切勿提交到 git。

配置

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

HEADLESS=false           # 浏览器可见性
SHOW_BROWSER=false       # 默认浏览器显示
STEALTH_ENABLED=true     # 类人行为
TYPING_WPM_MIN=160       # 打字速度
TYPING_WPM_MAX=240
DEFAULT_NOTEBOOK_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 "..."
    ↓
看到“这是您需要的全部内容吗？” → 追问直到完整
    ↓
综合并回复用户

故障排除

问题	解决方案
ModuleNotFoundError	使用 run.py 包装器
认证失败	设置时浏览器必须可见！--show-browser
DAEMON_UNAVAILABLE	确保安装了 Node.js/npm，运行 npm install，重试
AUTH_REQUIRED	运行 python scripts/run.py auth_manager.py setup
ELEMENT_NOT_FOUND	验证笔记本 URL 并重新运行，重新加载页面
速率限制（50/天）	等待或使用 accounts add 添加另一个 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 - 保护敏感数据不被提交