notebooklm

NotebookLM 自动化

提供对 Google NotebookLM 的完整程式化存取——包含 Web 介面未开放的功能。可建立笔记本、新增来源（URL、YouTube、PDF、音频、影片、影像）、与内容对话、产生所有类型的产物，并支援以多种格式下载结果。

安装方式

从 PyPI 安装（推荐 AI Agent 使用 — 可自动识别 Python 版本）：

pip install "notebooklm-py[browser]"   # 必须安装；错误必须向上抛出

# [cookies] (rookiepy) 为可选项目，已知在 Python 3.13+ 环境下会构建失败。
# 在 3.13+ 环境下请故意跳过，而非吞掉错误——这样才能让
# *真正的* 安装失败（如拼写错误、网络问题、PyPI 断线）显现给 Agent。
if python -c "import sys; sys.exit(0 if sys.version_info < (3, 13) else 1)"; then
    pip install "notebooklm-py[cookies]"   # 错误必须向上抛出
else
    echo "Skipping [cookies] on Python 3.13+ (rookiepy unavailable). Use 'notebooklm login' interactively."
fi

完整安装矩阵（扩展套件、Headless 服务器、贡献者流程）：GitHub 上的安装指南。

从 GitHub 安装（请使用最新 Release Tag，切勿使用 main 分支）：

# 取得最新 Release Tag（需要 curl + jq）
if ! command -v jq >/dev/null; then
    echo "jq is required to read the latest release tag" >&2
    exit 1
fi
LATEST_TAG=$(
    curl -fsSL https://api.github.com/repos/teng-lin/notebooklm-py/releases/latest |
    jq -r '.tag_name'
)
# 包含 [browser]，以便互动式 `notebooklm login` 流程正常运作。
pip install "notebooklm-py[browser] @ git+https://github.com/teng-lin/notebooklm-py@${LATEST_TAG}"

⚠️ 切勿从 main 分支安装 (pip install git+https://github.com/teng-lin/notebooklm-py)。main 分支可能包含未发布或不稳定的变更。除非你要测试未发布的功能，否则请始终使用 PyPI 或特定 Release Tag。

Skill 安装方法：

• notebooklm skill install 会将此 Skill 安装至 CLI 管理的支援本地 Agent 目录中。
• npx skills add teng-lin/notebooklm-py 会从 GitHub 存储库将此 Skill 安装至相容的 Agent Skill 目录中。
• 如果你已经在 Agent Skill 目录内部阅读此文件，代表该 Skill 已经安装完成。你只需要安装 Python 封包并完成下方的身份验证即可。

使用 CLI 管理安装：

notebooklm skill install

前置需求

重要：在执行任何命令之前，你必须先完成身份验证：

notebooklm login          # 开启浏览器进行 Google OAuth 验证
notebooklm list           # 确认身份验证正常运作

如果命令因身份验证错误而失败，请重新执行 notebooklm login。

CI/CD、多账号与并行 Agent

适用于自动化环境、多账号管理或并行 Agent 工作流程：

变数名称	用途
NOTEBOOKLM_HOME	自订设定目录（预设值：~/.notebooklm）
NOTEBOOKLM_PROFILE	作用中的 Profile 名称（预设值：default）
NOTEBOOKLM_AUTH_JSON	行内 Auth JSON — 无需写入文件

CI/CD 设定： 将 NOTEBOOKLM_AUTH_JSON 设为包含 storage_state.json 内容的 Secret。

多账号管理： 使用具名 Profile（先执行 notebooklm profile create work，再执行 notebooklm -p work login）。或者，为每个账号使用不同的 NOTEBOOKLM_HOME 目录。

并行 Agent： CLI 会按 Profile 储存笔记本上下文（~/.notebooklm/profiles/<profile>/context.json，在隐式预设 Profile 下会降级使用旧版路径 ~/.notebooklm/context.json）。若多个并发 Agent 共享同一个 Profile 且使用 notebooklm use，可能会互相覆盖彼此的上下文——请使用以下隔离策略之一。

并行工作流程的解决方案：

1. 永远使用显式笔记本 ID（推荐）：在特定笔记本范围的命令上直接传入 -n <notebook_id> / --notebook <notebook_id>，而非依赖 use
2. 透过 Profile 进行 Agent 隔离： export NOTEBOOKLM_PROFILE=agent-$ID（每个 Profile 拥有独立的上下文文件）
3. 透过 Home 目录进行 Agent 隔离： 为每个 Agent 设定唯一的 NOTEBOOKLM_HOME：export NOTEBOOKLM_HOME=/tmp/agent-$ID
4. 使用完整 UUID： 在自动化流程中避免使用部分 ID（可能会产生歧义）

沙盒化 Agent (Claude Cowork / Headless)

沙盒化且无显示器的 Agent 环境——例如 Claude Cowork（Anthropic 针对非开发者推出的桌面 Agent）及类似的 Headless 沙盒——无法执行 notebooklm login（因为它需要浏览器），且各 Session 之间会重设。只要做好以下两点调整，其他功能皆可正常运作：

1. 为每个 Session 进行引导初始化（Bootstrap）。 由于沙盒在每次 Session 都会重设，因此请在每个 Session 开始时重新安装。在此处你不需要安装 [browser] / Playwright——该扩展仅用于在宿主主机上执行的互动式 login 流程，而非在沙盒内。对话、来源管理、产物生成及下载皆可在基础安装上执行：

   pip install notebooklm-py   # 查询/生成产物无需 [browser]
   

   （这是本文件开头强制要求安装 [browser] 唯一的特例——因为你是在复用验证凭证，而不是在此处登录。）

2. 复用宿主主机生成的 storage_state.json。 先在有显示器的机器上登录一次（notebooklm login），然后将产生的 storage_state.json 复制到沙盒可存取的资料夹中，并透过以下任一方式指定：

   # 单次执行根参数（指向持久化且沙盒可存取的路径）：
   notebooklm --storage /path/to/storage_state.json list
   # 或透过环境变量行内指定（无需文件—例如来自 Cowork 保存的 Secret）：
   export NOTEBOOKLM_AUTH_JSON="$(cat /path/to/storage_state.json)"
   notebooklm list
   

   ⚠️ storage_state.json / NOTEBOOKLM_AUTH_JSON 为 Bearer 凭证—任何持有者皆能以你的 Google 账号身份进行操作。请确保文件权限设为 0600，从沙盒的 Secret 储存库载入而非提交至版本控制，绝对不要打印或记录它，且在完成后执行 unset NOTEBOOKLM_AUTH_JSON。

按照下方的 Agent 设定验证 步骤进行验证—例如：notebooklm --storage <path> auth check --test --json（必须同时满足 "status": "ok" 以及 "checks.token_fetch": true）。

上下文在环境重设后无法保留：选定的笔记本上下文 (context.json) 在每个 Session 重设后都会消失，因此在笔记本范围的命令中请显式传入 -n/--notebook <id>，而非依赖 notebooklm use。

若 Cowork 会读取 ~/.claude/skills/，notebooklm skill install 会自动将其注册至该路径；否则请在宿主主机上使用 notebooklm skill package 建立可上传的压缩包（会生成 notebooklm-skill.zip），并透过 Claude Settings → Capabilities 手动新增。完整流程（扩展矩阵、Headless 验证、CI 环境变量说明）：installation.md § AI Agent。

Agent 设定验证

在开始工作流程前，请先确认身份验证已就绪。必须使用 --test --json（而非仅用 --json）—单纯使用 --json 只能证明 Cookie 文件格式可解析；而 --test 会发起网络请求，证明 Cookie 仍可通过 Google 的身份验证。

1. notebooklm auth check --test --json → 必须同时满足 "status": "ok" 与 "checks.token_fetch": true。若仅包含 "status": "ok"（未带 --test）是假阳性陷阱—过期的 Cookie 文件也能通过解析检查。
2. notebooklm list --json → 应返回有效的 JSON（新账号可能为空）。
3. 若身份验证失败或缺失 → 先执行 notebooklm login。 这是主要的验证路径：开启浏览器，由使用者登录 Google 一次，生成的 storage_state.json 将在后续的所有执行中复用。适用于任何带有显示器的环境。
   • 对于无法开启浏览器的 Headless 环境，请改用 notebooklm login --browser-cookies <browser>—这会从 Chrome/Firefox 等提取使用者已登录的 Cookie（需要安装 [cookies] 扩展；rookiepy 可能无法在 Python 3.13+ 上安装）。可使用 chrome::<profile-name-or-directory> 指定特定的 Chromium 使用者设定档，或使用 firefox::<container-name> / firefox::none 指定特定 Firefox Container。
   • 若要在选择账号前先检视已登录的 Google 账号：notebooklm auth inspect --browser <browser>（唯读；加上 -v 参数可查看各账号属于哪个 Chromium 使用者设定档，或加上 --json 供工具整合）。包含范围限定的形式如 notebooklm auth inspect --browser 'chrome::Profile 1' 仅会检视该浏览器设定档。
   • 登录后请重新执行步骤 1 以进行确认。
4. 若身份验证原本正常但 Cookie 已过期（Google 轮替了 SIDTS，或者你在浏览器中重新登录了）→ 在原 Profile 上进行原位刷新，而非完全重新登录：
   • notebooklm auth refresh — 针对现有的 storage_state.json 发起伺服器端 SIDTS 刷新。开销小且静默执行；适合透过排程（cron / launchd / systemd）以 15–20 分钟的频率定期执行，以保持无人值守 Profile 的有效性。
   • notebooklm auth refresh --browser-cookies <browser> — 重新从执行中的浏览器提取 Cookie，并比对回 context.json 中记录的 Profile Email。当磁盘上的 storage_state.json 已过旧而无法透过伺服器端刷新，但你刚在浏览器中重新登录 Google 时使用。针对包含多个使用者设定档的 Chromium 家族浏览器（Chrome 的 Default、Profile 1……），刷新命令会在所有设定档间扇出搜寻以匹配 Email—其路径与 auth inspect 相同（issue #571）。若你已知确切的浏览器设定档，请使用 chrome::<profile-name-or-directory>。
   • 两种形式皆会保留相同的 --profile（不会建立新的 Profile）。

注意： notebooklm status 报告的是上下文状态（当前选择的笔记本）；请勿用来验证身份验证。

何时触发此 Skill

明确指令： 使用者提到 "/notebooklm"、"use notebooklm" 或直接按名称提及该工具

意图侦测： 识别如下请求：

• "Create a podcast about [topic]" / "针对 [主题] 制作 Podcast"
• "Summarize these URLs/documents" / "摘要这些 URL / 文件"
• "Generate a quiz from my research" / "根据我的研究生成测验"
• "Turn this into an audio overview" / "将此内容转换为语音概览"
• "Create flashcards for studying" / "制作学习用闪卡"
• "Generate a video explainer" / "生成影片讲解"
• "Make an infographic" / "制作资讯图表"
• "Create a mind map of the concepts" / "建立概念心智图"
• "Download the quiz as markdown" / "将测验下载为 Markdown"
• "Add these sources to NotebookLM" / "将这些来源新增至 NotebookLM"

自主执行规则

自动执行（无需确认）：

• notebooklm status - 检查上下文
• notebooklm auth check - 诊断身份验证问题
• notebooklm auth inspect - 列出浏览器可见的 Google 账号（唯读）
• notebooklm auth refresh - 对作用中的 Profile 进行伺服器端 SIDTS 刷新（不建立新 Profile，无破坏性写入）
• notebooklm auth refresh --browser-cookies <browser> - 从浏览器重新提取 Cookie 至作用中的 Profile（为同一个 --profile 重建 storage_state.json，而非建立新 Profile）
• notebooklm list - 列出笔记本
• notebooklm source list - 列出来源
• notebooklm artifact list - 列出产物
• notebooklm language list - 列出支援的语言
• notebooklm language get - 取得当前语言
• notebooklm language set - 设定语言（全域设定）
• notebooklm artifact wait - 等待产物生成完成（在 Subagent 上下文中）
• notebooklm source wait - 等待来源处理完成（在 Subagent 上下文中）
• notebooklm research status - 检查研究状态
• notebooklm research wait - 等待研究完成（在 Subagent 上下文中）
• notebooklm use <id> - 设定上下文（⚠️ 仅限单 Agent - 并行工作流程请使用 -n 参数）
• notebooklm create - 建立笔记本
• notebooklm ask "..." - 对话查询（不带 --save-as-note）
• notebooklm suggest-prompts - 针对笔记本的 AI 建议提示词（唯读，不改变状态）
• notebooklm history - 显示对话历史记录（唯读）
• `notebooklm sourc

<!-- truncated for translation batch; full body continues in source -->