notebooklm-py 完全指南：用 Python、CLI 与 AI Agent 深度驱动 Google Gemini Notebook

notebooklm-py 完全指南：用 Python、CLI 与 AI Agent 深度驱动 Google Gemini Notebook

【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py

本篇指南以仓库根目录 README.md 为主体脉络，系统讲解notebooklm-py这款非官方 Python 库的完整能力：从 NotebLML（现已更名为 Gemini Notebook）的自动化接入、认证与安装，到 CLI / Python API / MCP / REST 四套使用方式，再到面向 AI Agent 的 skill 集成与无人值守部署。读完本文，你将掌握如何用几行代码批量导入来源、发起带引用的 grounded 问答、生成并下载播客/视频/测验/思维导图等全类型 Studio 工件，以及如何把 Gemini Notebook 变成一个由 Agent 驱动的“零 Token 合成与记忆层”。

一、项目定位：把 Gemini Notebook 变成可编程的合成引擎

notebooklm-py是一个非官方的 Google Gemini Notebook（原 NotebookLM）自动化库，提供 Python API、CLI、MCP Server、REST Server 和 Agent Skill 五条接入路径，宣称可访问 Web 界面都未暴露的完整功能。仓库 pyproject.toml 将其描述为 "Unofficial Python library for automating Google NotebookLM"，当前版本 0.8.2，支持 Python 3.10 ~ 3.14。

风险声明（仓库原文）：该库使用未文档化的 Google API，可能随时变化；与 Google 无任何关联；存在限流风险；最适合原型、研究和个人项目。详见 docs/troubleshooting.md。

品牌说明（2026 年 7 月）：Google 已将 NotebookLM 更名为Gemini Notebook，仍是同一独立产品，现有链接自动跳转，本库驱动的底层服务不变，包名继续保留notebooklm-py。

从源码结构看，包主体位于 src/notebooklm/ 目录下，核心入口是 client.py 中的NotebookLMClient，它通过from_storage()从本地凭据目录构造客户端，并按命名空间暴露notebooks、sources、chat、research、artifacts、mind_maps、notes、settings、sharing、labels、collections共11 个公共命名空间（对应 SKILL.md 中的说明）。换句话说，整个 Web 产品能做与不能做的事，都被映射成了可脚本化、可批量的方法调用。

二、能构建什么：四类核心能力

按 README 的归纳，这套库可以支撑以下四类应用：

三、实战配方：Agent 怎么用 NotebookLM

README 给出的核心洞察是：NotebookLM 是一个 grounded 引擎——Gemini 负责大量阅读，并基于你的来源给出带引用的回答。因此最有效的模式是"让 NotebookLM 做昂贵的分析，Agent 做编排与最后一公里"，把它当作Agent 循环驱动的零 Token 合成 + 记忆层，并把结构化工件批量拉出来。以下是按用途分组的实战配方。

3.1 省 Token：让 NotebookLM 做昂贵的思考

• 零 Token 研究卸载：把 30 份文档丢进一个 notebook，让 Gemini 完成重分析，Agent 只在最终润色上花 Token。Agent 只负责编排（create→source add→ask），推理全部发生在服务端。
• 知识蒸馏成永久 Skill：用source add-research "your topic" --mode deep（见 docs/cli-reference.md#source-add-research）运行 Deep Research，或加载文档语料，让 Gemini 提炼后把结果固化成SKILL.md，Agent 启动时加载——构建一次，零运行时 Token、零网络调用复用，可 git 版本化、不受 UI 漂移影响。直接把原始文档灌进 skill 会压平层级，先让 NotebookLM 浓缩才是关键。
• 自验证 Skill：让 NotebookLM 基于来源生成评估集（quiz），用这份"地面真值"给 Agent skill 打分，而不是用自己会有偏见的手写测试题。构建 skill → 跑 NotebookLM 出的评估题 → 迭代到通过。

3.2 给 Agent 记忆：持久、可引用的记忆库

• 跨会话持久记忆：维护一个 "Master Brain" notebook，会话收尾时把决策与修复以笔记形式追加（note create/ask --save-as-note），并在CLAUDE.md中写一行让下个会话开始时ask查询。存储与召回都在 Google 基础设施上。
• 代码 Agent 的 grounded 记忆：把内部文档/RFC/架构通过 docs/mcp-guide.md 描述的 MCP Server（或直接ask）暴露给 Agent，让它基于你的代码回答并带引用，而不是"听起来合理"的猜测——这是自己搭向量库 + embedding 流水线的零基础设施替代方案。
• 查询自己的笔记/日记：加载多年的日常笔记、会议日志或日记，用ask跨自己的历史获得带引用的回答，能浮现关键词搜索无法发现的长周期模式。

3.3 来源 → 答案与工件

• Grounded 知识库 / 排障 Oracle（RAG）：加载产品文档、FAQ、RFC 与历史工单，用ask --json获得基于来源、带引用的答案，服务于支持、on-call 或内部问答；也可让 Agent 把某个快速演进的工具的整个文档库（远超上下文容量）当作排障 oracle。
• 多格式内容再利用：一套来源、全格式输出——generate audio（播客）、generate video、generate slide-deck，外加generate report博客稿、generate quiz、generate flashcards。
• 批量、可脚本化导出：思维导图导出 JSON、闪卡/测验导出 JSON/Markdown/HTML、数据表导出 CSV、报告导出 Markdown——批量、落到本地文件，可直接进 Anki、思维导图工具或代码仓库（download <type>/download <type> --all）。这是库"把数据取出来"的一面，而不只是"把来源放进去"。
• Obsidian / 知识图谱同步：在 vault 根目录运行 CLI，让下载的工件（报告、思维导图 JSON、文稿）作为文件落进知识图谱；社区还基于本库把 NotebookLM 的引用标记解析为 Obsidian[[wikilinks]]，可配合播客概览做笔记的音频摘要。

3.4 无人值守、规模化、移动端

• 事故 Runbook 生成器：收到告警后，把相关文档放进 notebook，问几个定向诊断问题，generate report --format briefing-doc --wait再download report，自动产出简报式 runbook。
• 课程 / 学习集构建器：抓取 syllabus 或开发者路线图，按主题每主题一个 notebook（刻意放慢节奏以规避限流），批量生成播客、测验、闪卡。
• 定时音频简报：auth refresh --quiet（配合 cron / launchd / systemd）加上generate audio，定时向播客源发布新鲜简报。
• 手机端、Agent 驱动：自托管 docs/mcp-guide.md#remote-deployment-docker--a-tunnel 中的远程 MCP 连接器（Cloudflare/Tailscale 隧道），作为自定义连接器加到claude.ai 网页端（Claude.ai Connectors，或开启开发者模式的 ChatGPT），即可在claude.ai 移动 App上驱动完整工具集（深度研究、来源摄入、Studio 生成、带引用问答）。

这些配方由普通库原语组合而成，完整命令见 docs/cli-reference.md 与 docs/python-api.md；Agent 侧胶水（skill、调度、vault 布局）由使用者自己搭建。每 notebook 的来源数量取决于 Google 账户层级，触及上限时应拆分到多个 notebook（参见 docs/quota-limits.md）。

四、五种使用方式与双 API 后端

4.1 使用方式一览

三个进程入口在 pyproject.toml#L103-L106 中注册：notebooklm（CLI）、notebooklm-mcp（MCP 服务）、notebooklm-server（REST 服务）。

4.2 API 后端：Web 与 Android 双通道

默认后端是成熟的 Web（batchexecute）传输层；本版本还提供可选的Android 后端，使用 NotebookLM 移动端 gRPC 服务与 bearer 认证。CLI 用--backend android（或环境变量NOTEBOOKLM_BACKEND=android）选择；Python API 用NotebookLMClient.from_storage(backend="android")或NotebookLMClient(..., backend="android")。

pip install "notebooklm-py[android,browser]" notebooklm login --master-token --account you@example.com notebooklm --backend android list --json

Android 后端从所选 profile 读取master_token.json并按需铸造短期移动端 bearer token，因此类型化命名空间调用不依赖浏览器 cookie 会话、Web 构建标签或 Web RPC ID；全部 11 个公共命名空间均可用，不回落 Web 传输层。由于持久化 master token 是强大的全账户凭据，务必使用专用账户并妥善保护 profile。协议细节见 docs/android/README.md（Android 运行时需显式安装，有意不包含在allextra 中）。

后端解析优先级（见 docs/configuration.md#backend-preference）固定为：显式 SDK/CLI/MCP/REST 选项 →NOTEBOOKLM_BACKEND→ 默认web；偏好值在客户端构造时固定。

五、功能全景：完整覆盖 + 全类型内容生成

5.1 完整 NotebookLM 覆盖

这些能力在源码中均有对应实现，例如 _sources.py 的add_url/add_file/add_drive/get_fulltext/wait_until_ready，_chat.py 的ask/save_answer_as_note/get_history，_labels.py 的generate/add_sources，_sharing.py 的set_public/add_user，以及 _research.py 的start/poll/wait_for_completion/import_sources。

5.2 内容生成（全工件类型）

对应实现位于 _artifacts.py（generate_audio、generate_video、generate_quiz、generate_slide_deck、revise_slide、download_*系列与export_*系列）和 _mind_maps_api.py（generate，通过MindMapKind.INTERACTIVE/MindMapKind.NOTE_BACKED区分两种思维导图）。

5.3 超越 Web UI 的能力

• 批量下载——一次下载某类型全部工件
• Quiz/Flashcard 导出——获得结构化 JSON、Markdown 或 HTML 文件
• 思维导图数据抽取——导出层级 JSON 供可视化工具使用
• 数据表 CSV 导出——以电子表格形式下载结构化表格
• 幻灯片 PPTX/PDF——下载可编辑的 PowerPoint 或 PDF
• 幻灯片修订——用自然语言提示修改单张幻灯片
• 报告模板定制——向内置格式模板追加额外指令（CLI 中为--append，仅作用于内置报告格式）
• 聊天历史存为笔记——把整段问答对话（不止单条回答）持久化为 notebook 笔记
• 来源全文访问——取回任意来源的已索引文本内容
• 程序化分享——无需 UI 管理权限

六、安装与认证

完整安装指南（六种人设、可选 extras 矩阵、平台说明）见 docs/installation.md。以下是 README 的速通路径。

6.1 最快开始（CLI 用户与 AI Agent）

uv tool install "notebooklm-py[browser]" # 或: pipx install "notebooklm-py[browser]" notebooklm login # 首次运行自动下载 Chromium (~170 MB)，然后 Google 登录 notebooklm auth check --test --json # 验证: 期望 "status": "ok"

为什么推荐uv tool/pipx？它们把 CLI 装进独立隔离环境并把notebooklm放到PATH上——不与其他工具冲突依赖、一行升级（uv tool upgrade notebooklm-py）或卸载；关键是，它们在现代 macOS（Homebrew Python）和 Debian/Ubuntu 上可用，因为这些系统上系统级pip install会被error: externally-managed-environment（PEP 668）拦截。

偏好原生pip？在virtualenv 内（以及 Windows 上，Python 不受 external-managed 限制）同样可用：

python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install "notebooklm-py[browser]"

作为库嵌入（不需要 Playwright 与 Chromium）：

uv add notebooklm-py # 或, 在 virtualenv 内: pip install notebooklm-py

如果 Linux 上playwright install chromium报TypeError: onExit is not a function，参见 docs/troubleshooting.md#linux 的 Linux 解决方法。

6.2 可选 Extras 矩阵

来源：pyproject.toml#L42-L101 的[project.optional-dependencies]。基础依赖仅 4 个：httpx、click、rich、filelock（pyproject.toml#L29-L34），所有 RPC 操作与除login外的全部 CLI 命令都只需基础安装。

6.3 认证与访问

• 三种获取 cookie 的方式——交互式 Playwright 登录（默认）、从已登录浏览器导入（login --browser-cookies chrome，无需 Playwright）、或持久的master token。
• Master-token 认证——按需铸造新 Web cookie，无需每会话浏览器（login --master-token --account you@example.com），过期会话自动自我修复，是服务器、CI 与远程 MCP 连接器（claude.ai / ChatGPT）的认证模型。
• 多账户 Profiles——不重新认证即可切换 Google 账户。常用流程如notebooklm profile create work && notebooklm -p work login --browser-cookies edge --account work@corp.com。

主 Token 是全账户、持久凭据（写入master_token.json，权限0600），爆炸半径远大于过期的 cookie 快照，即使修改密码也仍然有效——泄露后唯一补救是显式吊销。务必只用专用/一次性 Google 账户，妥善保管（设计细节见 docs/adr/0023-master-token-headless-auth.md）。CI 场景下，把 master token 作为 secret 传入、unset环境变量，再notebooklm auth refresh --verify铸造会话即可（见 docs/installation.md#alternative-master-token-auth-no-cookie-file-to-ship-survives-expiry）。

6.4 Agent Skill 设置

方式一——CLI 安装：

notebooklm skill install

安装到~/.claude/skills/notebooklm与~/.agents/skills/notebooklm。

方式二——npx安装（开放 skill 生态）：

npx skills add teng-lin/notebooklm-py

直接获取仓库根级 SKILL.md。该 skill 文件（打包进 wheel 的notebooklm/data/SKILL.md，见 pyproject.toml#L157）面向 Agent 定义了完整操作约定：优先--json与显式 ID、每个 notebook 级命令都传-n/--notebook、并发时使用独立NOTEBOOKLM_PROFILE、source add后必须source wait、异步生成后用artifact wait与-a <artifact_id>精确下载、重叠研究必须传--run-id等（详见 SKILL.md）。同时提供notebooklm skill status --json检查安装版本，notebooklm skill package为沙箱环境打包可上传归档。

七、快速开始

7.1 CLI 全流程

# 1. 认证（打开浏览器） notebooklm login # 或使用 Microsoft Edge（适合要求 Edge SSO 的组织） # notebooklm login --browser msedge # 或复用已登录浏览器会话的 cookies # notebooklm login --browser-cookies chrome # notebooklm login --browser-cookies 'chrome::Profile 1' # 指定一个 Chromium profile # (可与 --profile 组合写入特定 profile； # 多个 Google 账户已登录时，先 auth inspect 再用 --account / --all-accounts) # 2. 创建 notebook 并添加来源 notebooklm create "My Research" notebooklm use <notebook_id> notebooklm source add "https://en.wikipedia.org/wiki/Artificial_intelligence" notebooklm source add "./paper.pdf" # 3. 与来源对话 notebooklm ask "What are the key themes?" notebooklm ask --prompt-file ./long_question.txt # 从文件读取问题 # 4. 生成内容（长提示词用 --prompt-file） notebooklm generate audio "make it engaging" --wait notebooklm generate video --style whiteboard --wait notebooklm generate cinematic-video "documentary-style summary" --wait notebooklm generate quiz --difficulty hard notebooklm generate flashcards --quantity more notebooklm generate slide-deck notebooklm generate infographic --orientation portrait notebooklm generate mind-map # 默认交互式 studio 图; --kind note-backed 为 JSON 树 notebooklm generate>notebooklm auth check --test # 诊断 auth/cookie 问题 notebooklm auth refresh --quiet # 一次性 cookie 保活 (供 cron / launchd / systemd) notebooklm auth refresh --browser-cookies chrome # 重新抽取并修复账户路由 notebooklm auth inspect --browser 'chrome::Profile 1' # 预览一个 Chromium profile notebooklm agent show codex # 打印随包 Codex 指引 notebooklm agent show claude # 打印随包 Claude Code skill 模板 notebooklm language list # 列出支持的输出语言 notebooklm metadata --json # 导出 notebook 元数据与来源 notebooklm usage # 显示实时 compute 用量与重置时间 notebooklm usage --json # 导出完整用量快照（含分类） notebooklm share status # 检查分享状态 notebooklm source add-research "AI" --import-all # web 研究 + 导入发现的来源 notebooklm skill status # 检查本地 agent skill 安装 notebooklm profile list # 列出全部 Google 账户 profiles notebooklm profile switch work # 切换活动账户 profile

--prompt-file PATH用于ask、基于提示词的generate命令和source add-research中文本过长不便放在命令行时——它读取的是提示词/查询文本，与source add ./file.pdf（上传文件作为来源）是两回事。

7.2 Python API 完整示例

import asyncio from notebooklm import NotebookLMClient, MindMapKind async def main(): async with NotebookLMClient.from_storage() as client: # 创建 notebook 并添加来源 nb = await client.notebooks.create("Research") await client.sources.add_url(nb.id, "https://example.com", wait=True) # 与来源对话 result = await client.chat.ask(nb.id, "Summarize this") print(result.answer) # 生成内容（播客、视频、测验等） status = await client.artifacts.generate_audio(nb.id, instructions="make it fun") await client.artifacts.wait_for_completion(nb.id, status.task_id) await client.artifacts.download_audio(nb.id, "podcast.m4a") # 生成测验并以 JSON 下载 status = await client.artifacts.generate_quiz(nb.id) await client.artifacts.wait_for_completion(nb.id, status.task_id) await client.artifacts.download_quiz(nb.id, "quiz.json", output_format="json") # 通过统一 client.mind_maps API 生成思维导图 — # 两种类型：较新的 MindMapKind.INTERACTIVE studio 图（默认轮询至完成） # 或 MindMapKind.NOTE_BACKED JSON。两者都通过以下方式导出： mm = await client.mind_maps.generate(nb.id, kind=MindMapKind.INTERACTIVE) await client.artifacts.download_mind_map(nb.id, "mindmap.json", mm.id) asyncio.run(main())

NotebookLMClient.from_storage()是异步上下文管理器（注意：不需要await调用本身）；客户端在单事件循环上可重入但非线程安全，每个循环创建一个客户端（client.py）。完整工作流示例见 examples/quickstart.py、examples/bulk-import.py、examples/research-to-podcast.py 与 examples/refresh_browser_cookies.py。

7.3 Agent 侧的标准工作流（SKILL 约定）

SKILL.md 给出了显式请求即可自动化的规范流水线：create（记录.notebook.id）→ 逐个source add（记录.source.id）→source wait {source_id} -n {nb} --timeout 600→ 生成（如generate audio "..." -n {nb} -s {source_id} --json，记录.task_id）→artifact wait {artifact_id} -n {nb} --timeout 1200→download audio ./podcast.m4a -a {artifact_id} -n {nb}。深度研究（--mode deep）可能耗时 15–30+ 分钟，用--no-wait非阻塞启动并保留.poll_task_id为{research_run_id}，之后research wait --import-all --timeout 1800 --json在授权后导入。状态机约定：来源unknown/preparing/processing → ready|error（只在ready后继续）；工件pending/in_progress → completed|failed|removed（只在completed后下载）。

八、存储、配置与运行环境

所有数据默认存放于~/.notebooklm/，按 profile 组织（详见 docs/configuration.md）：

~/.notebooklm/ ├── config.json # 全局配置: default_profile, language ├── profiles/ │ ├── default/ # 默认 profile（自动创建） │ │ ├── storage_state.json # 认证 cookies 与会话 │ │ ├── master_token.json # 持久 headless/Android 凭据（可选） │ │ ├── context.json # CLI 上下文（活动 notebook、会话） │ │ └── browser_profile/ # 持久 Chromium profile │ ├── work/ # 命名 profile 示例 │ └── personal/

storage_state.json存 cookie 集合并可选记录notebooklm.account（authuser 与 email）；经验上SID与__Secure-1PSIDTS严格必需，OSID或APISID+SAPISID+bare LSID为次级绑定（缺失时警告）——完整 cookie 抽取由notebooklm login完成，不要手工子集化。context.json由notebooklm use/clear/ auth 命令自动管理，记录活动 notebook 及其元数据。旧版扁平布局在首次运行时自动迁移进profiles/default/，迁移在~/.notebooklm/.migration.lock的单写者filelock下进行（migration.py），并发 CLI 调用不会交错复制。

关键环境变量（完整表格见 docs/configuration.md#environment-variables）：

NOTEBOOKLM_HOME、NOTEBOOKLM_PROFILE与各并发相关的NOTEBOOKLM_*_CONCURRENCY变量（REST 服务器各处理器并发上限）为无人值守与并发 Agent 场景提供了隔离手段。

九、Agent 集成生态：MCP 与 REST

9.1 MCP Server

MCP Server 位于可选mcpextra 之后（拉入fastmcp），把 Gemini Notebook 暴露给任意 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf……）为38 个工具——管理 notebook 与来源、基于 notebook 来源对话、生成并下载 Studio 工件、运行深度研究。它是 CLI 同一业务逻辑之上的薄适配层，行为与notebooklm <command>一致（docs/mcp-guide.md）。注意其工具面不受 semver 保证，可能在版本间变化。

pip install "notebooklm-py[mcp]" # 或不安装直接运行: uvx --from "notebooklm-py[mcp]" notebooklm-mcp --help

服务器复用已存储的 profile（自己不登录），先notebooklm login一次即可。连接客户端最快的方式是自动配置命令（幂等，不覆盖其他服务器）：

notebooklm mcp install claude-desktop # 或: claude-code | cursor | windsurf

远程部署（Docker + Cloudflare/Tailscale 隧道）后，可作为自定义连接器加入 claude.ai（含移动 App）与 ChatGPT（开发者模式），实现"手机上的 NotebookLM、Agent 驱动"。安全边界与托管威胁模型见 SECURITY.md。

9.2 REST Server（实验性）

单租户 FastAPI 本地服务器，通过受保护 HTTP 路由做本地自动化，避免每次调用起一个 CLI 进程。启动入口为notebooklm-server；所有/v1请求需要NOTEBOOKLM_SERVER_TOKEN（未设置则拒绝启动），默认仅绑定 loopback，非 loopback 需显式NOTEBOOKLM_SERVER_ALLOW_EXTERNAL_BIND=1且应置于可信代理之后。

十、文档地图与后续深入

仓库还维护了一批高质量的领域文档，建议按需深入：

• docs/installation.md——六种人设完整安装、extras 矩阵、平台说明与 CI 部署配方
• docs/cli-reference.md——CLI 全命令参考
• docs/python-api.md——Python API 完整参考
• docs/mcp-guide.md——MCP 服务器、传输与工具参考
• docs/configuration.md——存储与设置、环境变量全集
• docs/quota-limits.md——各层级 notebook/来源/Studio 限额及其与AccountLimits.tier的映射
• docs/security.md——凭据处理与信任边界
• docs/stability.md——版本策略与稳定性保证
• docs/troubleshooting.md——常见问题排查
• docs/upgrading-to-0.8.0.md——v0.8.0 错误与返回契约的破坏性迁移指南
• docs/android/README.md——Android 后端设置与协议笔记
• docs/architecture.md、docs/development.md、docs/rpc-reference.md——面向贡献者的架构、开发与 RPC 载荷文档
• CHANGELOG.md——版本历史与发布说明

结语

notebooklm-py的价值在于把 Gemini Notebook 的 grounding 能力——带引用的问答、全类型 Studio 工件生成、深度研究——从浏览器点击中解放出来，变成 Python、Shell、HTTP 与 Agent 协议都能消费的编程原语。其"让 NotebookLM 做昂贵分析、Agent 只做编排与最后一公里"的定位，尤其适合构建零 Token 研究流水线、跨会话记忆层与批量内容工厂。需要再次强调的是：它建立在未文档化、随时可能变化的 Google 内部 API 之上，请只用于原型、研究与个人项目，并为认证凭据（尤其是 master token）设置严格的安全边界。

【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py