wehub-resource-sync
415caf51fc
22 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
notebooklm-py
全面的 NotebookLM Skill 与非官方 Python API。 通过 Python、CLI 以及 Claude Code、Codex、OpenClaw 等 AI 智能体，以编程方式完整访问 NotebookLM 的各项功能——包括 Web UI 未暴露的能力。
源码与开发：https://github.com/teng-lin/notebooklm-py
⚠️ 非官方库 — 使用风险自负
本库使用未公开的 Google API，可能随时变更且不予通知。
- 与 Google 无关联 — 这是社区项目
- API 可能失效 — Google 可随时更改内部端点
- 适用速率限制 — 大量使用可能被限流
最适合原型、研究和个人项目。调试技巧见 Troubleshooting。
你能构建什么
🤖 AI 智能体工具 — 将 NotebookLM 集成到 Claude Code、Codex 及其他 LLM 智能体中。内置根级 NotebookLM skill，支持 GitHub 与 npx skills add 发现；为 Claude Code 提供本地 notebooklm skill install 支持，以及 .agents skill 目录；仓库级 Codex 指南见 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. - 🧠 知识蒸馏 → 永久 skill — 运行 Deep 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 生成的测验评分.
为智能体赋予记忆 — 持久、有来源依据的召回：
- 💾 跨会话持久记忆 — 维护一个「Master Brain」notebook；收尾步骤将每次会话的决策与修复追加为笔记（
note create/ask --save-as-note），并在你的CLAUDE.md中用一行在下次会话开始时查询它（ask）。存储与召回依托 Google 基础设施。 - 🧩 面向编码智能体的有来源记忆 — 通过 MCP server（或普通
ask）暴露一份内部文档/RFC/架构 notebook，让智能体基于你的代码作答并附引用，而非听起来合理却错误的猜测 — 无需自建向量库与嵌入流水线的零基础设施替代方案。实战案例：将 notebook 变成编码智能体写代码前会查阅的有来源「项目大脑」. - 🪞 查询你自己的笔记/日记 — 加载多年的每日笔记、会议记录或日记，并用
ask获取带引用、贯穿你自己历史的答案 — 揭示关键词搜索无法发现的长期模式（例如从 282 条每日笔记综合而成的周报，每条论断都链接回其来源条目）。实战案例：与一年的每日笔记作为带引用知识库对话.
将来源转化为答案与产物 — 带引用的回复、生成的媒体与导出：
- 📞 有来源知识库/排障神谕（RAG） — 加载产品文档、FAQ、RFC 与历史工单，然后用
ask --json为支持、on-call 或内部问答提供有来源、带引用的答案。或让智能体指向某个快速迭代工具的完整文档 — 超出智能体上下文容量 — 作为排障神谕，在出错瞬间即可查询。实战案例：OpenClaw 驱动本库抓取docs.openclaw.ai全部 524 页，去重重复翻译，审计至 269 条干净来源（缺失/多余/重复 = 0）. - 🔁 多格式内容再利用 — 一套来源，多种格式：
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」.
无人值守、大规模或随时随地运行 — 定时、无头（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，并在 网页端 添加为自定义连接器（claude.ai Connectors，或开启 Developer Mode 的 ChatGPT）。然后在外出时通过 claude.ai 移动应用 驱动完整工具集 — 深度研究、来源摄取、Studio 生成、带引用的问答 — 并可与其他 MCP 工具串联，无需在多个应用间切换（ChatGPT 的 MCP 连接器仅支持网页端）。
这些功能组合了普通的库原语 — 参见 CLI Reference 和 Python API。agent 侧的粘合层（skills、调度、vault 布局）位于你自己的配置中，而非本软件包。每个笔记本的来源数量取决于你的 Google 账户等级 — 若触及上限，可拆分到多个笔记本。
初次使用？ 从入门 walkthrough 开始：Claude Code + NotebookLM = CHEAT CODE (视频) · 5 个演示 + 50 个用例，附 prompts.
使用方式
| 方式 | 最适合 |
|---|---|
| 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。
最快上手（CLI 用户与 AI agent）— 使用 uv tool（推荐）或 pipx 安装 CLI：
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). 还没有 uv？curl -LsSf https://astral.sh/uv/install.sh | sh（或 brew install uv / winget install astral-sh.uv）。
更喜欢纯 pip？ 在 virtualenv 内 效果相同（在 Windows 上也可直接使用，因其 Python 不受外部管理）：
python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "notebooklm-py[browser]"
作为库（嵌入你的应用 — 无需 Playwright、无需 Chromium）：
uv add notebooklm-py # or, inside a virtualenv: pip install notebooklm-py
若 playwright install chromium 在 Linux 上因 TypeError: onExit is not a function 失败，请参阅 Linux workaround。贡献者： 请参阅 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 安装：
notebooklm skill install
将 skill 安装到 ~/.claude/skills/notebooklm 与 ~/.agents/skills/notebooklm。
方案 2 — npx 安装（通过开放 skills 生态）：
npx skills add teng-lin/notebooklm-py
直接从 GitHub 获取权威的 SKILL.md。
快速开始
16 分钟会话压缩为 30 秒
CLI
# 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 命令：
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
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 - 完整命令文档
- Python API - 完整 API 参考
- MCP Guide - MCP 服务器配置、传输方式与工具参考
- REST API Server - 实验性本地 FastAPI 服务器
- Configuration - 存储与设置
- Quota & Tier Limits - 各层级的 notebook/源/studio 限制及其与
AccountLimits.tier的对应关系 - Release Guide - 发布检查清单与打包验证
- Troubleshooting - 常见问题与解决方案
- API Stability - 版本策略与稳定性保证
- Upgrading to v0.8.0 - v0.8.0 错误与返回契约的破坏性变更迁移指南
面向贡献者
- Architecture - 架构概览与设计原则
- Development Guide - 架构、测试与发布
- RPC Development - 协议捕获与调试
- RPC Reference - 载荷结构
- Changelog - 版本历史与发布说明
- Security - 安全策略与凭据处理
Star History
许可证
MIT License。详见 LICENSE。