notebooklm-py - NotebookLM 非官方 Python API 与 Agent Skill¶

完整的 NotebookLM 程序化访问能力。通过 Python API、CLI、AI Agent 三种方式，操作 NotebookLM 的全部功能——包括网页 UI 不开放的批量下载、结构化导出等特性。win4r 的 fork 在上游基础上增加了 Hermes Agent 兼容性和安全加固。

目录¶

• 仓库信息
• 核心价值
• 功能覆盖
• 三种使用方式
• 网页端不具备的独有功能
• Hermes Agent 安装指南
• 认证方案
• Python API 速查
• CLI 速查
• 架构与风险
• 参考资料

仓库信息¶

上游 teng-lin/notebooklm-py (main, ~19k stars)
    │
    ├── PyPI v0.3.4 (落后 main ~20 commits)
    │
    └── fork: win4r/notebooklm-py
            │
            ├── v0.3.4-hermes.4 (审计标签)
            │   ├── 上游 main 全部代码
            │   ├── cherry-pick #298 (cookie 自动刷新)
            │   ├── cherry-pick #279 (Playwright venv 修复)
            │   ├── skills/notebooklm/ (Hermes skill layout)
            │   ├── SECURITY_AUDIT.md
            │   └── import_browser_cookies.py
            │
            └── main (跟踪上游 + Hermes additions)

核心价值¶

┌──────────────────────────────────────────────────────────┐
│                  没有 notebooklm-py                       │
│                                                          │
│  手动打开网页 → 上传文件 → 等待处理 → 逐个下载            │
│  ⚠ 无法批量操作  ⚠ 无法结构化导出  ⚠ 无法自动化          │
├──────────────────────────────────────────────────────────┤
│                  有了 notebooklm-py                       │
│                                                          │
│  CLI 一行命令 / Python 几行代码                           │
│  ✅ 批量创建笔记本  ✅ 批量导入来源  ✅ 自动生成内容       │
│  ✅ 批量下载产物  ✅ Agent 直接调用  ✅ CI/CD 集成        │
└──────────────────────────────────────────────────────────┘

功能覆盖¶

笔记本与来源管理¶

内容生成（全部 Studio 类型）¶

三种使用方式¶

Agent 集成选项¶

┌─────────────────────────────────────────────────┐
│  Option 1: CLI install                          │
│  notebooklm skill install                       │
│  → ~/.claude/skills/notebooklm                  │
│  → ~/.agents/skills/notebooklm                  │
├─────────────────────────────────────────────────┤
│  Option 2: npx install                          │
│  npx skills add win4r/notebooklm-py            │
│  (open skills ecosystem)                        │
├─────────────────────────────────────────────────┤
│  Option 3: Hermes Agent ← 推荐                   │
│  hermes skills tap add win4r/notebooklm-py      │
│  hermes skills install ... --force              │
│  → skills/notebooklm/ layout                   │
└─────────────────────────────────────────────────┘

网页端不具备的独有功能¶

这些功能只能通过 API/CLI 使用，NotebookLM 网页 UI 不提供：

Hermes Agent 安装指南¶

完整安装步骤（基于 win4r fork 的 v0.3.4-hermes.4）：

# 1. 注册 skill 来源并安装
hermes skills tap add win4r/notebooklm-py
hermes skills install win4r/notebooklm-py/skills/notebooklm --force

# 2. 安装 Python 包到 Hermes venv（审计标签）
VIRTUAL_ENV=~/.hermes/hermes-agent/venv uv pip install \
  "notebooklm-py[browser,cookies] @ git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
~/.hermes/hermes-agent/venv/bin/playwright install chromium

# 3. 暴露 CLI 到 PATH
mkdir -p ~/.local/bin
ln -sf ~/.hermes/hermes-agent/venv/bin/notebooklm ~/.local/bin/notebooklm

# 4. 通过 Chrome cookies 认证（跳过 Google 新设备流程）
notebooklm login --browser-cookies chrome
# macOS: Keychain 提示选 "Always Allow"

# 5. 配置自动刷新（Google 每 15-30 分钟轮换 PSIDTS）
echo 'NOTEBOOKLM_REFRESH_CMD=notebooklm login --browser-cookies chrome' >> ~/.hermes/.env

# 6. 验证
hermes skills list                    # 应包含 notebooklm
notebooklm auth check --test          # 所有行 ✓
notebooklm list                       # 列出你的笔记本

一次配置，永久运行。 步骤 5 之后，任何 Hermes session 中的 notebooklm RPC 调用如果遇到过期 cookie，会自动从 Chrome 刷新并重试。

认证方案¶

自动刷新机制¶

RPC 调用 → 过期？ ──否──→ 正常返回
                │
                是
                ▼
    执行 $NOTEBOOKLM_REFRESH_CMD
    (从 Chrome 读取新 cookies)
                │
                ▼
    重载 storage_state.json
                │
                ▼
    重试原始 RPC 调用（一次性，不会循环）
                │
                ▼
    返回结果

安全注意：~/.notebooklm/storage_state.json 包含 Google SID cookie，等同于密码。建议用专用 Google 账号，避免绑定敏感服务。

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)

        # 对话
        result = await client.chat.ask(nb.id, "Summarize this")
        print(result.answer)

        # 生成 Audio Overview
        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")

        # 生成 Quiz 并导出 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")

asyncio.run(main())

CLI 速查¶

# 认证
notebooklm login [--browser-cookies chrome|firefox|brave|edge]

# 笔记本管理
notebooklm create "名称"
notebooklm list
notebooklm use <notebook_id>

# 来源管理
notebooklm source add "https://..."          # URL
notebooklm source add "./paper.pdf"          # 本地文件
notebooklm source add-research "AI"          # Web 研究 + 自动导入

# 对话
notebooklm ask "关键主题是什么？"

# 内容生成
notebooklm generate audio "make it engaging" --wait
notebooklm generate video --style whiteboard --wait
notebooklm generate cinematic-video "documentary 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
notebooklm generate data-table "compare concepts"

# 下载
notebooklm download audio ./podcast.mp3
notebooklm download video ./overview.mp4
notebooklm download quiz --format json ./quiz.json
notebooklm download mind-map ./mindmap.json
notebooklm download data-table ./data.csv

# 诊断
notebooklm auth check --test
notebooklm metadata --json

架构与风险¶

工作原理¶

notebooklm-py
    │
    ├── 逆向工程 NotebookLM 的内部 API
    │   (undocumented Google endpoints)
    │
    ├── 模拟浏览器请求 (Playwright / cookies)
    │
    └── 提供 Python async API + CLI 封装

风险评估¶

适合：原型开发、个人研究、自动化管道 不适合：生产环境关键业务（无 SLA 保证）

使用建议¶

• 用专用 Google 账号，不绑定 Gmail/Drive 等敏感服务
• 定期检查上游更新（teng-lin/notebooklm-py main 分支）
• fork 的 SECURITY_AUDIT.md 提供了完整的审计记录
• 优先使用 --browser-cookies + 自动刷新，避免频繁 Playwright 登录

参考资料¶

• 上游仓库 (teng-lin/notebooklm-py)
• Hermes Fork (win4r/notebooklm-py)
• Reddit 讨论
• NotebookLM REST API wrapper (基于此项目)
• PyPI notebooklm-py

相关笔记¶

• Gemini 整合 NotebookLM + 多模态文件输出
• Andrew Wilkinson 六层 AI 架构