notebooklm

Gemini Notebook 自动化

在 Agent 工作流中使用 notebooklm CLI。优先使用 --json 和明确的 ID，确保每项操作都可检查，且在并发情况下安全。仅当用户请求应用程序代码，或 CLI 无法表达该工作流时，才使用带类型的异步 Python API。以下就绪状态、身份、授权和凭据处理规则适用于这两种接口。

设置和身份验证

需要 Python 3.10+。在用户现有的环境中安装该软件包；除非用户提出要求，否则不要创建单独的环境：

pip install "notebooklm-py[browser]"
pip install "notebooklm-py[cookies]"  # optional browser-cookie extraction

如果系统 pip 报告 externally-managed-environment，不要使用 --break-system-packages。仅使用 CLI 时，可提供 uv tool install "notebooklm-py[browser]" 或等效的 pipx 命令；编写应用程序代码时，使用用户当前启用的项目环境。

对于无人值守或无头工作，优先使用持久的、基于配置文件的主令牌身份验证，而不是复制 Cookie 快照。安装 pip install "notebooklm-py[headless]"；一次性自动 OAuth 捕获还需要 [browser]。在可信工作站上运行 notebooklm login --master-token --account <email>，然后将 master_token.json（而非 storage_state.json）部署到选定的配置文件中。NOTEBOOKLM_HOME 用于选择私有基础目录，NOTEBOOKLM_PROFILE 用于选择其配置文件；默认路径为 ~/.notebooklm/profiles/default/master_token.json。

在 CI 中，NOTEBOOKLM_MASTER_TOKEN_JSON 是一种传递密钥的约定，而不是软件包会直接读取的环境变量。将其确切值以 0600 权限写入选定配置文件中的 master_token.json，然后取消设置该变量，并运行 notebooklm auth refresh 以生成 storage_state.json。同目录下的主令牌可以自动重新生成过期的文件型 Cookie。内联的 NOTEBOOKLM_AUTH_JSON 仅作为短期备用方案；它无法使用此恢复路径。

使用 PyPI 或发布标签，不要使用尚未发布的 main 分支检出版本。如有可用版本，请参阅安装指南。

在执行工作流之前，请验证实际身份验证状态，而不只是解析 Cookie 文件：

notebooklm auth check --test --json

要求 .status == "ok" 且 .checks.token_fetch == true。如果验证失败：

• 如果有显示器，运行 notebooklm login 并重新验证。
• 在无头环境中，安装 [cookies] 并使用 notebooklm login --browser-cookies <browser>。如果不确定要选择哪个账号，请先运行 notebooklm auth inspect --browser <browser>。
• 如果此前有效的 Cookie 已失效，请尝试 notebooklm auth refresh；在浏览器中重新登录后，使用 notebooklm auth refresh --browser-cookies <browser>。

常规的 --test 预检可能会修复并保存刷新的 Cookie。如果检查必须严格只读（包括下文的故障诊断工作流），请添加 --passive。

notebooklm status 报告的是所选笔记本的上下文，而不是身份验证状态。

将这两个身份验证文件都视为持有者凭据：切勿打印、记录或提交它们。主令牌是持久的完整账号凭据，即使密码变更也不会失效；请使用专用账号，在密钥存储中保护该令牌，并确保磁盘上的文件权限为 0600；如果令牌泄露，请明确撤销。

操作不变量

1. 使用 --json 执行发现和修改操作，然后保留返回的完整 UUID。重要的信封字段包括 create 返回的 .notebook.id、source add 返回的 .source.id，以及异步生成器返回的 .task_id。generate mind-map 则返回 mind_map、note_id 和 kind；两种类型都会返回已完成的结果，无需任务 ID 或单独的 artifact wait 步骤。
2. 在自动化或并发工作中，每个笔记本范围的命令都传入 -n/--notebook <id>。不要依赖 notebooklm use。每次并发运行还要设置唯一的 NOTEBOOKLM_PROFILE=agent-<id>，以隔离上下文和配置文件写入。新配置文件没有凭据：使用前将 master_token.json 复制到该配置文件中，并为其生成存储。切勿让多个 Agent 共用同一个可写的 storage_state.json。
3. 添加来源后，保留每个 .source.id，然后对每个来源运行 source wait，再进行聊天或生成。添加操作返回的信封没有状态信息。必须确保等待命令以 0 退出，且 status == "ready"；让等待程序处理特定媒体的暂时性 error 行。
4. 异步生成器返回任务 ID 或工件 ID 后，将其作为位置参数传给 artifact wait，并传入 -n <notebook_id>。使用 -a <artifact_id> -n <notebook_id> 下载该确切工件；切勿选择最新的可见工件。思维导图生成会直接返回已完成的结果，无需 artifact wait。
5. 对于重叠的研究运行，始终传入 --run-id <research_run_id>。
6. 仅在主机确实提供后台功能时才使用。将等待命令和依赖它的下载命令放在同一个顺序任务中，并且仅在等待命令以 0 退出后才下载。否则，在前台运行，或向用户返回绑定到确切 ID 的命令。

授权边界

安全检查，以及用户明确要求的创建、添加来源、聊天和提示词建议，可以直接执行。尝试恢复之前，先使用只读命令诊断故障。

对于尚未获得明确授权的操作，执行前必须立即征求确认：

• 破坏性命令，例如删除笔记本/来源/笔记/工件/标签/配置文件、移除共享、登出、清除、取消研究，以及 ask --new；
• language set，因为默认模式会更改账户全局输出语言（优先使用生成命令的 --language 覆盖项）；
• 生成或较长时间的前台等待，这些操作可能需要数分钟，且会受到速率限制；
• 下载，因为会写入文件；
• research wait --import-all，因为会导入来源；
• ask --save-as-note 和 history --save，因为会创建笔记。

授权边界取决于用户意图，而不是 CLI 是否显示提示。获得授权后，在支持的情况下传入 --yes/-y。大多数破坏性 JSON 命令在未传入该参数时会拒绝执行，但有些命令（包括 ask --new --json 和 share remove --json）无需提示即可执行。切勿将没有提示视为已获同意。

research cancel 会立即返回，不等待结果。获得授权并取消后，使用 notebooklm research status -n <notebook_id> --run-id <research_run_id> --json 验证确切的运行状态。

命令发现

请将已安装 CLI 的帮助信息作为与版本匹配的事实来源，而不要猜测标志：

notebooklm --help
notebooklm source --help
notebooklm research --help
notebooklm generate --help
notebooklm artifact --help
notebooklm download --help

此外，请检查 notebooklm --version，并在其帮助信息与此技能不同时，深入查看确切命令的帮助信息，例如 notebooklm generate audio --help。

常见操作：

目标	命令
检查计算用量	notebooklm usage --json；notebooklm usage --categories 用于查看类别可用性和预估费用
列出或创建笔记本	notebooklm list --json；notebooklm create "Title" --json
添加来源并等待	notebooklm source add <input> -n <nb> --json；notebooklm source wait <src> -n <nb>
URL 恢复	notebooklm source add <url> --fallback-fetch
聊天	notebooklm ask "question" -n <nb> --json
研究	notebooklm source add-research "query" -n <nb> --mode fast --json（也支持 deep）
列出资料或等待资料生成	notebooklm artifact list -n <nb> --json；notebooklm artifact wait <id> -n <nb>
生成	notebooklm generate <type> ... -n <nb> --json
下载	notebooklm download <type> <path> -n <nb> -a <artifact>

如需了解完整功能，请查阅已安装命令的帮助信息，或在可用时查看 CLI 参考。 编写应用代码时，请使用以下基线，并在可用时查阅 Python API 指南。

标准的来源到资料工作流

请保留 JSON 输出中的 {notebook_id}、每个 {source_id} 和 {artifact_id}：

明确请求执行此完整工作流，即授权执行其常规前置等待、请求的生成操作以及请求的输出文件。仅对该请求尚未授权的工作进行确认。

1. notebooklm create "Research: topic" --json
2. 对每个输入运行 notebooklm source add <input> -n {notebook_id} --json。
3. 获得前台等待操作的授权后，对每个已捕获的来源运行 notebooklm source wait {source_id} -n {notebook_id} --timeout 600。
4. 获得生成操作的授权后，生成请求的类型。对于音频： notebooklm generate audio "instructions" -n {notebook_id} -s {source_id} --json。 对每个选定的来源重复使用 -s，并将 .task_id 保存为 {artifact_id}。
5. 获得前台等待操作的授权后，运行 notebooklm artifact wait {artifact_id} -n {notebook_id} --timeout 1200。
6. 获得输出写入操作的授权后，运行 notebooklm download audio ./podcast.m4a -a {artifact_id} -n {notebook_id}。

如需分析而不生成内容，请仅在所有来源就绪后，将步骤 4-6 替换为带固定 ID 的聊天命令：

notebooklm ask "Summarize the key arguments" -n {notebook_id} --json

深度研究

深度研究可能需要 15-30 分钟以上。请以非阻塞方式启动，并将 .poll_task_id // .task_id 保存为 {research_run_id}：

notebooklm source add-research "query" -n {notebook_id} --mode deep --no-wait --json

仅在获得明确授权后导入，并固定两个 ID：

notebooklm research wait -n {notebook_id} --run-id {research_run_id} \
  --import-all --timeout 1800 --json

使用 --import-all 时，--timeout 是轮询和重试导入各阶段的预算，因此此示例可能会占用主机约 3600 秒的实际运行时间。

请保留 .imported_sources[].id 中新创建的来源 ID，并在后续聊天或生成操作前等待其就绪。

Python API 基线

如果无法获取完整的 API 指南，请使用已安装的类型化 API 及其文档字符串；不要猜测方法名称。与 CLI 工作流一样，保留相同的 ID，并遵守就绪门槛：

import asyncio

from notebooklm import NotebookLMClient


async def main(url: str) -> None:
    async with NotebookLMClient.from_storage() as client:
        notebook = await client.notebooks.create("Research: topic")
        source = await client.sources.add_url(notebook.id, url)
        await client.sources.wait_until_ready(notebook.id, source.id, timeout=600)

        answer = await client.chat.ask(
            notebook.id, "Summarize the key arguments", source_ids=[source.id]
        )
        print(answer.answer)

        task = await client.artifacts.generate_audio(
            notebook.id,
            source_ids=[source.id],
            instructions="Focus on the key arguments",
        )
        final = await client.artifacts.wait_for_completion(notebook.id, task.task_id, timeout=1200)
        if not final.is_complete:
            raise RuntimeError(f"Generation ended with {final.status}: {final.error}")
        await client.artifacts.download_audio(
            notebook.id, "./podcast.m4a", artifact_id=task.task_id
        )


asyncio.run(main("https://example.com"))

NotebookLMClient.from_storage() 是异步上下文管理器，不应使用 await。客户端可在同一个事件循环中重复进入，但不是线程安全的；每个事件循环都应创建一个客户端。公开命名空间包括 notebooks、sources、chat、research、artifacts、mind_maps、notes、settings、sharing、labels 和 collections。执行会更改状态、长时间运行或写入文件的调用前，请遵守上述授权边界。

生成说明

可用的生成器包括 audio、video、slide-deck、infographic、report、mind-map、 data-table、quiz 和 flashcards。请查看 notebooklm generate <type> --help，因为不同类型 支持的格式、样式、来源选择、语言和重试功能各不相同。

请留意以下不明显的区别：

• 思维导图（--kind interactive，默认值）在内部是异步工作室产物，但 CLI 会轮询直至完成，并返回 {mind_map, note_id, kind}；不要运行 artifact wait。
• 思维导图（--kind note-backed）由服务器同步生成。两种类型都接受 --instructions；interactive 会可靠地应用该参数，而服务器可能会忽略 note-backed 思维导图的该参数。
• generate video --format cinematic 会忽略 --style，需要 Google AI Ultra，可能需要约 30-40 分钟。
• 幻灯片没有方向标记。请在描述中要求生成竖版内容（例如 9:16 portrait）；修订幻灯片无法更改演示文稿的方向。
• 对于自定义报告，请将提示词作为位置描述传入，并使用 --format custom；--append 仅适用于内置报告格式。

如果提示词过长或难以在 shell 引号中处理，请在 ask、source add-research 和受支持的生成器中使用 --prompt-file PATH。此文件包含提示词文本；请改用 source add 上传来源文档。

输出与引用

请使用 JSON 进行结构化处理，而非解析人类可读的输出。常见的生命周期状态包括：

• 来源：unknown/preparing/processing -> ready 或 error；仅在状态为 ready 时继续；
• 产物：pending/in_progress -> completed、failed 或 removed；not_found 可能只是短暂的列表延迟。仅在状态为 completed 时继续或下载。

聊天 JSON 包含 answer、conversation_id 和 references[].source_id。引用中的 start_char/end_char 是结构化来源文档中的 UTF-16 偏移量，而不是扁平化的 SourceFulltext.content。在 Python 中，使用 from notebooklm import resolve_chat_reference_passage，然后调用 await resolve_chat_reference_passage(client, notebook_id, reference)；它会使用文档中的精确范围，并在必要时回退到 find_citation_context()。

故障处理

发生故障时，先进行安全的只读诊断：

notebooklm auth check --test --passive --json
notebooklm list --json
notebooklm source list -n {notebook_id} --json
notebooklm artifact list -n {notebook_id} --json
notebooklm research status -n {notebook_id} --run-id {research_run_id} --json

仅检查与失败工作流相关的命令。诊断期间不要更改状态。

• 退出码 0 表示成功。预期的命令失败使用退出码 1。source wait 超时使用退出码 2；artifact wait 和 research wait 超时使用退出码 1。
• 首先根据退出码分支处理。常规的已处理 JSON 错误使用 {error, code, message}；等待命令则返回领域封装，例如 {"status": "timeout", "error": "..."}。
• 遇到身份验证失败时，重新验证 checks.token_fetch；仅当其值不是 true 时才登录。
• 等待超时时，请报告超时情况，并检查对应的确切来源、产物或研究运行。
• Google 会对生成操作进行速率限制。保留任务 ID，检查状态；只有用户授权后才能重试，不要无限循环。对于已存在的失败工作室产物，请先查看 notebooklm artifact retry <artifact_id> -n {notebook_id} --help，再原地重试。
• 遇到协议错误时，记录已安装的版本、确切命令、相关 ID 和经过脱敏处理的错误。有网络访问时，请检查项目的问题跟踪器；没有网络访问时，不要臆造变通方案。

进度更新应简短，并包含相关的返回 ID。切勿暴露凭据内容。

技能安装

如果此文件已位于 Agent 技能目录中，则该技能已安装。否则：

• notebooklm skill install 可安装或更新受支持的本地技能目标。
• notebooklm skill package 可为沙盒 Agent 环境构建可上传的归档文件。
• notebooklm skill status --json 会报告已安装的版本和 content_mismatch。