notebooklm

NotebookLM 自动化

提供对 Google NotebookLM 的完整编程访问能力——涵盖 Web 界面未暴露的诸多高级功能。你可以创建笔记本、添加数据源（URL、YouTube、PDF、音频、视频、图片）、基于内容展开对话、生成各类衍生内容（Artifacts），并以多种格式下载结果。

安装指南

通过 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

完整安装矩阵（拓展包、无头服务器、贡献者开发流程）：GitHub 安装指南。

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

# 获取最新发布版本的 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	内联认证 JSON 文本 —— 无需写文件

CI/CD 配置： 将包含 storage_state.json 内容的 Secret 赋值给环境变量 NOTEBOOKLM_AUTH_JSON。

多账号管理： 使用具名 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> 显式传递 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 / 无头环境）

在受限且无显式的沙箱 Agent 环境下 —— 例如 Claude Cowork（Anthropic 面向非开发者的桌面端 Agent）及类似无头沙箱 —— 无法运行 notebooklm login（因为需要浏览器），且环境会在会话结束后重置。只需做两处调整，其他所有功能均可正常使用：

1. 每次会话初始化（Bootstrap）。 沙箱在每次会话结束时会重置，因此需在会话启动时进行安装。此时不需要安装 [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）在每次会话重置后都会丢失，因此在作用域限定于笔记本的命令中，请显式传递 -n/--notebook <id>，而不是依赖 notebooklm use。

如果 Cowork 可以读取 ~/.claude/skills/，notebooklm skill install 会自动将本 Skill 注册至该路径；否则请在宿主机运行 notebooklm skill package 打包出可上传的压缩包（生成 notebooklm-skill.zip），再通过 Claude Settings → Capabilities 手动添加。完整步骤（依赖矩阵、无头认证、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 即可供后续所有运行复用。适用于所有带图形界面的环境。
   • 对于无法打开浏览器的无头环境，请改为使用 notebooklm login --browser-cookies <browser> —— 从系统已有 Chrome/Firefox 等浏览器中提取已登录的 Cookie（需要安装 [cookies] 拓展包；在 Python 3.13+ 上 rookiepy 可能安装失败）。使用 chrome::<profile名称或目录> 可指定某个 Chromium 用户配置，使用 firefox::<容器名称> / firefox::none 可指定某个 Firefox 容器。
   • 在选择账号前如需查看已登录的 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 邮箱重新匹配。当磁盘上的 storage_state.json 过于陈旧无法走服务端刷新路径，但你刚在浏览器中重新登录了 Google 账号时使用。对于包含多个用户配置的 Chromium 系浏览器（如 Chrome 的 Default、Profile 1 等），刷新过程会遍历所有配置来匹配邮箱 —— 该路径与 auth inspect 一致（参见 issue #571）。如果你已知确切的浏览器配置，可使用 chrome::<profile名称或目录>。
   • 两种形式都会保留相同的 --profile（不会创建新的 Profile）。

注意： notebooklm status 仅用于报告上下文状态（当前选择的笔记本），切勿用它来验证身份认证状态。

本 Skill 激活条件

显式触发： 用户输入 "/notebooklm"、"use notebooklm" 或直接提及该工具名称

意图识别： 识别符合以下诉求的请求：

• “制作关于 [主题] 的播客”
• “总结这些 URL / 文档”
• “基于我的研究生成一套测验题”
• “把这些内容转成音频概览”
• “制作复习使用的记忆卡片 (Flashcards)”
• “生成一段讲解视频”
• “制作一张信息图”
• “梳理这些概念的思维导图”
• “把测验题下载为 Markdown 格式”
• “把这些资料源添加到 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，而非新建）
• notebooklm list - 列出笔记本列表
• notebooklm source list - 列出资料源列表
• notebooklm artifact list - 列出衍生内容 (Artifacts) 列表
• 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 针对笔记本推荐的 Prompt（只读，无状态变更）
• notebooklm history - 查看对话历史（只读）
• `notebooklm sourc

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