/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/teng-lin/notebooklm-py) · [上游 README](https://github.com/teng-lin/notebooklm-py/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# notebooklm-py
<p align="left">
  <img src="https://raw.githubusercontent.com/teng-lin/notebooklm-py/main/notebooklm-py.png" alt="notebooklm-py logo" width="128">
</p>

**全面的 NotebookLM Skill 与非官方 Python API。** 通过 Python、CLI 以及 Claude Code、Codex、OpenClaw 等 AI 智能体，以编程方式完整访问 NotebookLM 的各项功能——包括 Web UI 未暴露的能力。

[![PyPI version](https://img.shields.io/pypi/v/notebooklm-py.svg)](https://pypi.org/project/notebooklm-py/)
[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/notebooklm-py/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/teng-lin/notebooklm-py/actions/workflows/test.yml/badge.svg)](https://github.com/teng-lin/notebooklm-py/actions/workflows/test.yml)
<p>
  <a href="https://trendshift.io/repositories/19116" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19116" alt="teng-lin%2Fnotebooklm-py | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</p>

**源码与开发**：<https://github.com/teng-lin/notebooklm-py>

> **⚠️ 非官方库 — 使用风险自负**
>
> 本库使用**未公开的 Google API**，可能随时变更且不予通知。
>
> - **与 Google 无关联** — 这是社区项目
> - **API 可能失效** — Google 可随时更改内部端点
> - **适用速率限制** — 大量使用可能被限流
>
> 最适合原型、研究和个人项目。调试技巧见 [Troubleshooting](docs/troubleshooting.md)。

## 你能构建什么

🤖 **AI 智能体工具** — 将 NotebookLM 集成到 Claude Code、Codex 及其他 LLM 智能体中。内置根级 [NotebookLM skill](SKILL.md)，支持 GitHub 与 `npx skills add` 发现；为 Claude Code 提供本地 `notebooklm skill install` 支持，以及 `.agents` skill 目录；仓库级 Codex 指南见 [`AGENTS.md`](AGENTS.md)。

📚 **研究自动化** — 批量导入来源（URL、PDF、YouTube、Google Drive），运行 Web/Drive 研究查询并自动导入，以编程方式提取洞察。构建可重复的研究流水线。

🎙️ **内容生成** — 生成 Audio Overview（播客）、视频、幻灯片、测验、闪卡、信息图、数据表、思维导图和学习指南。对格式、风格与输出拥有完整控制。

📥 **下载与导出** — 将所有生成物下载到本地（MP3、MP4、PDF、PNG、CSV、JSON、Markdown）。导出到 Google Docs/Sheets。**Web UI 不具备的功能**：批量下载、多格式测验/闪卡导出、思维导图 JSON 提取。

## 用例与配方

NotebookLM 是一个**有来源依据（grounded）**的引擎：Gemini 负责繁重阅读，并基于*你的*来源作答并附引用。制胜模式是让它承担昂贵的分析，而你的智能体（Claude Code、Codex 等）负责编排与最后一公里——将 NotebookLM 作为**智能体在循环中驱动的零 token 综合 + 记忆层**，并以批量、更丰富、可脚本化的格式将结构化产物**导出**。人们基于本库构建的配方，按他们将 NotebookLM *用作*什么而分组：

**减少 token 消耗** — 让 NotebookLM 承担昂贵的思考：

- **🪙 零 token 研究卸载** — 将 30 份文档扔进一个 notebook，让 Gemini 做繁重分析，让你的智能体仅在最终润色上消耗 token。智能体只负责编排（`create` → `source add` → `ask`）；推理在服务端完成。*实战案例：[四工作流指南：阻止 Claude Code 在 NotebookLM 上烧 token](https://x.com/hooeem/status/2042293751805329445).*
- **🧠 知识蒸馏 → 永久 skill** — 运行 [Deep Research](docs/cli-reference.md#source-add-research)（`source add-research "your topic" --mode deep`）或加载文档语料，让 NotebookLM 的 Gemini 将其浓缩，并将结果烘焙进智能体启动时加载的 `SKILL.md` — **一次构建，零运行时 token 或网络调用即可复用**，可 git 版本管理且不受 UI 漂移影响。无需手工策展来源即可打包领域专家。（把原始文档直接塞进 skill 会压平层次结构；先经 NotebookLM 浓缩才是关键。）
- **✅ 自验证 skill** — 让 NotebookLM 生成*评测集* — 直接来自你来源的测验 — 用以对照 ground truth 为智能体 skill 打分，而非你自己会带入偏见的测试题。构建 skill，对照 NotebookLM 编写的评测运行，迭代直至通过。*实战案例：[某 skill 首轮 4/10、一次迭代后 10/10，由 NotebookLM 生成的测验评分](https://x.com/nurijanian/status/2037136490157986277).*

**为智能体赋予记忆** — 持久、有来源依据的召回：

- **💾 跨会话持久记忆** — 维护一个「Master Brain」notebook；收尾步骤将每次会话的决策与修复追加为笔记（`note create` / `ask --save-as-note`），并在你的 `CLAUDE.md` 中用一行在下次会话开始时查询它（`ask`）。存储与召回依托 Google 基础设施。
- **🧩 面向编码智能体的有来源记忆** — 通过 [MCP server](docs/mcp-guide.md)（或普通 `ask`）暴露一份内部文档/RFC/架构 notebook，让智能体基于*你的*代码作答并附引用，而非听起来合理却错误的猜测 — 无需自建向量库与嵌入流水线的零基础设施替代方案。*实战案例：[将 notebook 变成编码智能体写代码前会查阅的有来源「项目大脑」](https://medium.com/@pradeep00271/every-software-project-needs-a-project-brain-5cbc33917160).*
- **🪞 查询你自己的笔记/日记** — 加载多年的每日笔记、会议记录或日记，并用 `ask` 获取**带引用**、*贯穿你自己历史*的答案 — 揭示关键词搜索无法发现的长期模式（例如从 282 条每日笔记综合而成的周报，每条论断都链接回其来源条目）。*实战案例：[与一年的每日笔记作为带引用知识库对话](https://artemxtech.substack.com/p/notebooklm-has-a-knowledge-graph).*

**将来源转化为答案与产物** — 带引用的回复、生成的媒体与导出：

- **📞 有来源知识库/排障神谕（RAG）** — 加载产品文档、FAQ、RFC 与历史工单，然后用 `ask --json` 为支持、on-call 或内部问答提供**有来源、带引用**的答案。或让智能体指向某个快速迭代工具的完整文档 — 超出智能体上下文容量 — 作为**排障神谕**，在出错瞬间即可查询。*实战案例：[OpenClaw 驱动本库抓取 `docs.openclaw.ai` 全部 524 页，去重重复翻译，审计至 269 条干净来源（缺失/多余/重复 = 0）](https://x.com/onenewbite/status/2024819940327379286).*
- **🔁 多格式内容再利用** — 一套来源，多种格式：`generate audio`（播客）、`generate video`、`generate slide-deck`，外加 `generate report` 博客草稿、`generate quiz` 与 `generate flashcards` — 将单个 notebook 扇出到各渠道。
- **📤 批量、可脚本化导出** — 将思维导图导出为 JSON，闪卡/测验导出为 JSON/Markdown/HTML，数据表导出为 CSV，报告导出为 Markdown — **批量导出到本地文件，直接进入 Anki、你的思维导图工具或仓库**（`download <type>` / `download <type> --all`）。本库程序化「把数据*取出来*」的一半，而不只是「把来源放进去」。
- **🕸️ Obsidian / 知识图谱同步** — 从 vault 根目录运行 CLI，使下载的产物（报告、思维导图 JSON、转录）作为文件落入知识图谱；基于此库构建的社区 skill 甚至会将 NotebookLM 的引用标记解析为 Obsidian `[[wikilinks]]`。搭配播客概览，为你的笔记提供音频摘要。*实战案例：[「Claude Code + NotebookLM + Obsidian = GOD MODE」](https://www.youtube.com/watch?v=kU3qYQ7ACMA).*

**无人值守、大规模或随时随地运行** — 定时、无头（headless）与远程：

- **🚨 事件 runbook 生成器** — 收到告警时，启动包含相关文档的笔记本，提出有针对性的诊断问题，并生成 briefing-doc 报告（`generate report --format briefing-doc --wait`，然后 `download report`）作为自动化 runbook。
- **📚 课程 / 学习集构建器** — 抓取教学大纲或开发者路线图，为每个主题创建一个笔记本（有意控制节奏以规避速率限制），并批量生成播客、测验和抽认卡。
- **📰 定时音频简报** — 将 `auth refresh --quiet`（cron/launchd/systemd）与 `generate audio` 配对，按计划向播客 feed 发布全新的个性化简报。
- **📱 用手机使用 NotebookLM，由 agent 驱动** — 在 Cloudflare/Tailscale 隧道后自托管 [remote MCP connector](docs/mcp-guide.md#remote-deployment-docker--a-tunnel)，并在 **网页端** 添加为自定义连接器（claude.ai Connectors，或开启 Developer Mode 的 ChatGPT）。然后在外出时通过 **claude.ai 移动应用** 驱动完整工具集 — 深度研究、来源摄取、Studio 生成、带引用的问答 — 并可与其他 MCP 工具串联，无需在多个应用间切换（ChatGPT 的 MCP 连接器仅支持网页端）。

这些功能组合了普通的库原语 — 参见 [CLI Reference](docs/cli-reference.md) 和 [Python API](docs/python-api.md)。agent 侧的粘合层（skills、调度、vault 布局）位于你自己的配置中，而非本软件包。每个笔记本的来源数量取决于你的 Google 账户等级 — 若触及上限，可拆分到多个笔记本。

**初次使用？** 从入门 walkthrough 开始：[Claude Code + NotebookLM = CHEAT CODE (视频)](https://www.youtube.com/watch?v=usTeU4Uh0iM) · [5 个演示 + 50 个用例，附 prompts](https://aiblewmymind.substack.com/p/notebooklm-claude-code-use-cases).

## 使用方式

| 方式 | 最适合 |
|--------|----------|
| **Python API** | 应用集成、异步工作流、自定义流水线 |
| **CLI** | Shell 脚本、快速任务、CI/CD 自动化 |
| **MCP Server** | Claude Desktop/Code、Codex 等 — 通过 stdio 本地使用，或作为自托管远程连接器（置于 Cloudflare/Tailscale 隧道后），可从 claude.ai 和 ChatGPT 访问，包括移动端。 |
| **REST Server** | 通过受保护的 HTTP 路由进行本地自动化，无需每次调用都启动 CLI 进程 |
| **Agent Integration** | Claude Code、Codex、LLM agent、自然语言自动化 |

## 功能

### 完整的 NotebookLM 覆盖

| 类别 | 能力 |
|----------|--------------|
| **Notebooks** | 创建、列出、重命名、删除 |
| **Sources** | URL、YouTube、文件（PDF、text、Markdown、Word、EPUB、音频、视频、图片）、Google Drive、粘贴文本；刷新、获取 guide/fulltext |
| **Chat** | 提问、对话历史、自定义 persona、建议的 starter prompts |
| **Notes** | 创建、列出、重命名、删除、保存聊天回答、保存对话历史 |
| **Source Labels** | AI 生成或手动的主题标签；添加/移除来源归属；按标签筛选来源 |
| **Research** | Web 与 Drive 研究 agent（fast/deep 模式），支持自动导入 |
| **Sharing** | 公开/私密链接、用户权限（viewer/editor）、视图级别控制 |

### 内容生成（全部制品类型）

| 类型 | 选项 | 下载格式 |
|------|---------|-----------------|
| **Audio Overview** | 4 种格式（deep-dive、brief、critique、debate），3 种时长，50+ 种语言 | MP3 |
| **Video Overview** | 4 种格式（explainer、brief、cinematic、short），8 种视觉风格（+ auto/custom），另有专用 `cinematic-video` CLI 别名 | MP4 |
| **Slide Deck** | 详细或演讲者格式，长度可调；单页幻灯片修订 | PDF、PPTX |
| **Infographic** | 3 种方向、3 个细节级别 | PNG |
| **Quiz** | 可配置数量与难度 | JSON、Markdown、HTML |
| **Flashcards** | 可配置数量与难度 | JSON、Markdown、HTML |
| **Report** | briefing doc、study guide、blog post 或自定义 prompt | Markdown |
| **Data Table** | 通过自然语言自定义结构 | CSV |
| **Mind Map** | 层级节点树 — **两种类型**：note-backed JSON 或较新的交互式 studio map（`--kind` / `MindMapKind`） | JSON |

### 超越 Web UI

API/CLI 让程序化、批量与本地文件能力变得简单 — 其中多项以更丰富格式或更大规模提供，优于在 Web 应用中点击操作：

- **批量下载** - 一次性下载某类型的全部制品
- **Quiz/Flashcard 导出** - 获取结构化 JSON、Markdown 或 HTML 文件
- **思维导图数据提取** - 导出供可视化工具使用的层级 JSON
- **数据表 CSV 导出** - 将结构化表格下载为电子表格
- **幻灯片导出为 PPTX 或 PDF** - 下载可编辑的 PowerPoint 或 PDF 文件
- **幻灯片修订** - 用自然语言 prompt 修改单页幻灯片
- **报告模板自定义** - 向内置格式模板追加额外说明
- **将聊天历史保存为笔记** - 将整段问答对话（不仅是单个回答）持久化为笔记本笔记
- **来源全文访问** - 检索任意来源的已索引文本内容
- **程序化分享** - 无需 UI 即可管理权限

## 安装

完整安装指南 — 六种角色（agent、end-user、library、headless、contributor、power-user）、可选附加组件矩阵、平台说明 — 见 **[docs/installation.md](docs/installation.md)**。

**最快上手**（CLI 用户与 AI agent）— 使用 `uv tool`（推荐）或 `pipx` 安装 CLI：

```bash
uv tool install "notebooklm-py[browser]"   # or: pipx install "notebooklm-py[browser]"
notebooklm login                           # first run auto-downloads Chromium (~170 MB), then Google sign-in
notebooklm auth check --test --json        # verify: expect "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](https://peps.python.org/pep-0668/)). 还没有 `uv`？`curl -LsSf https://astral.sh/uv/install.sh | sh`（或 `brew install uv` / `winget install astral-sh.uv`）。

**更喜欢纯 `pip`？** 在 **virtualenv 内** 效果相同（在 Windows 上也可直接使用，因其 Python 不受外部管理）：

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

**作为库**（嵌入你的应用 — 无需 Playwright、无需 Chromium）：

```bash
uv add notebooklm-py                    # or, inside a virtualenv: pip install notebooklm-py
```

若 `playwright install chromium` 在 Linux 上因 `TypeError: onExit is not a function` 失败，请参阅 [Linux workaround](docs/troubleshooting.md#linux)。**贡献者：** 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。


### 认证与访问

面向本地开发、无头服务器与多租户设置的灵活认证：

- **三种获取 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）的认证模型。
- **多账户配置** - 无需重新认证即可在多个 Google 账户间切换。

### Agent 配置

**方案 1 — CLI 安装**：

```bash
notebooklm skill install
```

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

**方案 2 — `npx` 安装**（通过开放 skills 生态）：

```bash
npx skills add teng-lin/notebooklm-py
```

直接从 GitHub 获取权威的 [SKILL.md](SKILL.md)。

## 快速开始

<p align="center">
  <a href="https://asciinema.org/a/767284" target="_blank"><img src="https://asciinema.org/a/767284.svg" width="600" /></a>
  <br>
  <em>16 分钟会话压缩为 30 秒</em>
</p>

### CLI

```bash
# 1. Authenticate (opens browser)
notebooklm login
# Or use Microsoft Edge (for orgs that require Edge for SSO)
# notebooklm login --browser msedge
# Or reuse cookies from an already-logged-in browser session
# notebooklm login --browser-cookies chrome
# notebooklm login --browser-cookies 'chrome::Profile 1'  # one Chromium profile
# (combine with --profile to populate a specific profile;
#  use --account / --all-accounts after auth inspect when several
#  Google accounts are signed in)

# 2. Create a notebook and add sources
notebooklm create "My Research"
notebooklm use <notebook_id>
notebooklm source add "https://en.wikipedia.org/wiki/Artificial_intelligence"
notebooklm source add "./paper.pdf"

# 3. Chat with your sources
notebooklm ask "What are the key themes?"
notebooklm ask --prompt-file ./long_question.txt  # Read question from file

# 4. Generate content (use --prompt-file for long prompts)
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                       # interactive studio map (default); --kind note-backed for the JSON tree
notebooklm generate data-table "compare key concepts"

# 5. Download artifacts
notebooklm download audio ./podcast.mp3
notebooklm download video ./overview.mp4
notebooklm download cinematic-video ./documentary.mp4
notebooklm download quiz --format markdown ./quiz.md
notebooklm download flashcards --format json ./cards.json
notebooklm download slide-deck ./slides.pdf
notebooklm download infographic ./infographic.png
notebooklm download mind-map ./mindmap.json
notebooklm download data-table ./data.csv
```

其他实用 CLI 命令：

```bash
notebooklm auth check --test         # Diagnose auth/cookie issues
notebooklm auth refresh --quiet      # One-shot cookie keepalive (for cron / launchd / systemd)
notebooklm auth refresh --browser-cookies chrome  # Re-extract and repair account routing
notebooklm auth inspect --browser 'chrome::Profile 1'  # Preview one Chromium profile
notebooklm agent show codex          # Print bundled Codex instructions
notebooklm agent show claude         # Print bundled Claude Code skill template
notebooklm language list             # List supported output languages
notebooklm metadata --json           # Export notebook metadata and sources
notebooklm share status              # Inspect sharing state
notebooklm source add-research "AI" --import-all  # web research + import found sources
notebooklm skill status              # Check local agent skill installation
notebooklm profile list              # List all Google account profiles
notebooklm profile switch work       # Switch active account profile
```

将 `--prompt-file PATH` 与 `ask`、基于 prompt 的 `generate` 命令以及 `source add-research` 配合使用，当文本过长无法放入 shell 命令行时尤为适用。该方式从文件读取 prompt/查询文本，与 `source add ./file.pdf` 不同——后者仍会将该文件作为 NotebookLM 源上传。

### Python API

```python
import asyncio
from notebooklm import NotebookLMClient, MindMapKind

async def main():
    async with NotebookLMClient.from_storage() as client:
        # Create notebook and add sources
        nb = await client.notebooks.create("Research")
        await client.sources.add_url(nb.id, "https://example.com", wait=True)

        # Chat with your sources
        result = await client.chat.ask(nb.id, "Summarize this")
        print(result.answer)

        # Generate content (podcast, video, quiz, etc.)
        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.mp3")

        # Generate quiz and download as 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")

        # Generate a mind map via the unified client.mind_maps API (issue #1256) —
        # two kinds: the newer MindMapKind.INTERACTIVE studio map (shown; polled to
        # completion by default) or MindMapKind.NOTE_BACKED JSON. Both export via:
        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())
```

## 文档

- **[CLI Reference](docs/cli-reference.md)** - 完整命令文档
- **[Python API](docs/python-api.md)** - 完整 API 参考
- **[MCP Guide](docs/mcp-guide.md)** - MCP 服务器配置、传输方式与工具参考
- **[REST API Server](docs/installation.md#rest-api-server)** - 实验性本地 FastAPI 服务器
- **[Configuration](docs/configuration.md)** - 存储与设置
- **[Quota & Tier Limits](docs/quota-limits.md)** - 各层级的 notebook/源/studio 限制及其与 `AccountLimits.tier` 的对应关系
- **[Release Guide](docs/releasing.md)** - 发布检查清单与打包验证
- **[Troubleshooting](docs/troubleshooting.md)** - 常见问题与解决方案
- **[API Stability](docs/stability.md)** - 版本策略与稳定性保证
- **[Upgrading to v0.8.0](docs/upgrading-to-0.8.0.md)** - v0.8.0 错误与返回契约的破坏性变更迁移指南

### 面向贡献者

- **[Architecture](docs/architecture.md)** - 架构概览与设计原则
- **[Development Guide](docs/development.md)** - 架构、测试与发布
- **[RPC Development](docs/rpc-development.md)** - 协议捕获与调试
- **[RPC Reference](docs/rpc-reference.md)** - 载荷结构
- **[Changelog](CHANGELOG.md)** - 版本历史与发布说明
- **[Security](SECURITY.md)** - 安全策略与凭据处理

## Star History

[![Star History Chart](https://api.star-history.com/image?repos=teng-lin/notebooklm-py&type=timeline&legend=top-left)](https://www.star-history.com/?repos=teng-lin%2Fnotebooklm-py&type=timeline&legend=top-left)

## 许可证

MIT License。详见 [LICENSE](LICENSE)。