notebooklm-py：NotebookLM 的非官方 Python API 与 Agent 原生集成方案

Google NotebookLM 作为 RAG 驱动的研究助手，其 Web 界面虽然功能丰富，却天然排斥程序化访问 —— 这对于希望将 NotebookLM 纳入自动化工作流的开发者而言构成显著障碍。notebooklm-py 的出现填补了这一缺口：这是一个非官方 Python 封装库，通过逆向工程调用 NotebookLM 内部 API，不仅实现了完整的程序化访问，更以原生 Skill 形式接入 Claude Code、Codex 等 AI Agent 生态。

核心能力：超越 Web UI 的程序化访问

notebooklm-py 的最大价值在于暴露了 Web 界面无法触及的功能边界。除了标准的 Notebook 管理、Source 导入（URL、PDF、YouTube、Google Drive）和对话式查询外，该库支持批量下载所有生成物、以 JSON 格式导出思维导图数据、将幻灯片下载为可编辑的 PPTX 文件而非仅 PDF，以及以结构化格式（JSON/Markdown/HTML）导出测验和闪卡内容。这些能力对于需要进一步处理或集成 NotebookLM 输出至下游系统的场景至关重要。

内容生成矩阵覆盖了 NotebookLM 的全部输出类型：Audio Overview（支持 4 种格式、3 种长度、50+ 语言）、Video Overview（含专门的电影风格模式）、Slide Deck（支持单页修订）、信息图表、数据表和思维导图。每种生成品均可通过 --wait 参数同步等待完成，或异步轮询后批量下载。

Agent 原生集成：从 CLI 到自然语言自动化

该项目的独特定位在于其对 AI Agent 生态的一流支持。仓库内置 SKILL.md 文件遵循 GitHub Skills 规范，可被 npx skills add teng-lin/notebooklm-py 直接识别并安装至 Claude Code 或 Codex 环境。同时，AGENTS.md 为仓库级 Agent 提供上下文指引，而 notebooklm skill install 命令可将 Skill 部署至本地 ~/.claude/skills/ 和 ~/.agents/skills/ 目录。

这意味着开发者可以在 Claude Code 对话中直接发出自然语言指令，如 "基于当前目录的论文生成一个深度探讨风格的播客并下载"，Agent 将自动调用 notebooklm-py 完成认证检查、Source 上传、内容生成和下载的全流程，无需人工介入命令行操作。

工程实践：认证管理与多账户支持

notebooklm-py 基于 Playwright 实现浏览器自动化认证，支持多种登录策略以适应不同组织环境：

• 标准登录：notebooklm login 启动 Chromium 完成 Google OAuth
• 企业 SSO 适配：--browser msedge 指定 Edge 浏览器以满足组织策略
• Cookie 复用：--browser-cookies chrome 从已登录的浏览器会话提取 Cookie，避免重复认证
• 多 Profile 支持：chrome::Profile 1 语法可精确选择 Chromium Profile，配合 --profile 实现多 Google 账户切换

认证状态持久化至 storage_state.json，支持无头环境部署。notebooklm auth refresh 提供单点 Cookie 保活机制，可集成至 cron/systemd 定时任务。

使用模式与代码示例

CLI 快速通道：

pip install "notebooklm-py[browser]"
playwright install chromium
notebooklm login
notebooklm create "Research Project"
notebooklm source add "https://example.com/paper.pdf"
notebooklm generate audio "make it conversational" --wait
notebooklm download audio ./podcast.mp3

Python 异步 API：

import asyncio
from notebooklm import NotebookLMClient

async def main():
    async with await NotebookLMClient.from_storage() as client:
        nb = await client.notebooks.create("Research")
        await client.sources.add_url(nb.id, "https://example.com", wait=True)
        
        status = await client.artifacts.generate_quiz(nb.id, difficulty="hard")
        await client.artifacts.wait_for_completion(nb.id, status.task_id)
        await client.artifacts.download_quiz(nb.id, "quiz.json", output_format="json")

asyncio.run(main())

风险评估与使用边界

作为非官方实现，notebooklm-py 依赖未公开的 Google 内部 API，存在以下固有风险：

1. API 契约不稳定：Google 可随时变更端点或鉴权机制，导致功能失效
2. 速率限制：重度使用可能触发 Google 的限流策略
3. 服务条款：程序化访问可能违反 NotebookLM 的服务条款

建议将该工具限定于原型验证、个人研究及非生产环境自动化场景，避免用于关键业务系统。项目文档中的 docs/troubleshooting.md 提供了 API 变更时的调试指引，社区可通过 RPC 抓包持续跟进协议变动。

总结

notebooklm-py 代表了 AI 工具向 Agent 原生生态演进的一个典型案例：不仅提供底层 API 封装，更以标准化 Skill 形式融入 Claude Code、Codex 等 Agent 工作流。对于需要将 NotebookLM 的研究和内容生成能力纳入自动化管道的开发者而言，这是目前最完整的工程化方案。在享受其便利性的同时，需清醒认识非官方 API 的固有不稳定性，建立适当的降级和监控机制。

参考来源：

• GitHub: teng-lin/notebooklm-py

ai-systems