notebooklm-py (NotebookLM 接入)
Google NotebookLM 的非官方 Python API 与 agentic skill：通过 CLI/MCP/REST 程序化建笔记本、灌来源、带引用问答、生成播客视频测验等全部产物并批量下载，含 Web UI 没有的功能；认证自愈状态机 + 幂等分类学解决非官方 API 的 cookie 过期与重试问题。
仓库：teng-lin/notebooklm-py
热度证据：18,669 star,NotebookLM 类工具最热开源项目
五维评分
热度5/5
质量5/5
创新4/5
易用4/5
文档5/5
优秀点拆解
- SKILL.md 把 agent 使用协议写成一等公民：约 40 条命令按『自动执行/先询问』分级的自主权限表，destructive 命令要求 --yes 并返回结构化确认错误，agent 零试错即可知道边界
- 认证生命周期状态机：auth check --test 网络级验证防假阳性（bare --json 只证明 cookie 文件可解析），auth refresh 服务端 SIDTS 刷新可 cron 保活，--browser-cookies 从已登录浏览器提取，master-token 无头自愈，NOTEBOOKLM_AUTH_JSON 内联注入 CI/沙箱
- 幂等性分类学（ADR-0005）：每个 RPC 在 IdempotencyRegistry 登记五类重试安全策略，重试安全是 RPC 的属性而非调用点属性，测试强制每条降级理由文档化，解决 commit-lost 下重复 notebook/重复生成的分布式难题
- 三适配器（CLI/MCP/REST）共享传输中立 _app 核心，errors.classify 是唯一失败分类源，模块边界由 lint 测试锁死；一条业务逻辑三种入口：脚本、桌面 agent、claude.ai/ChatGPT 远程移动端
- 长任务 fire-and-forget + 子代理 wait 编排：generate 立即返回 task_id，SKILL.md 明文禁止主会话轮询，提供 Task 工具模板让后台子代理 artifact wait 后自动下载，10-45 分钟任务不阻塞主对话
- 对不稳定外部协议的防御：safe_index 严格解码（ADR-0011）把 Google 改协议变成类型化报错而非静默错数据，统一退出码 0/1/2（timeout=2）让 agent 可按码分支处理
可复用的设计模式
- 不稳定外部 API 分类学化封装：重试安全（幂等分类）、响应形状（严格解码）、失败分类（单一来源）都做成声明式注册表 + 测试强制
- 认证状态机模板：交互登录 → 网络级验证 → 服务端保活刷新（可 cron）→ 无头自愈 → 凭据内联注入，配凭据 0600/不进日志的安全红线
- SKILL.md 三件套：意图激活清单 + 自主权限分级表 + 错误决策树，配 --json schema 与退出码约定
- 长任务 fire-and-forget + 后台子代理 wait：接口立即返回 task_id，主会话不轮询，Task 工具派子代理完成 wait + download
适用场景
研究自动化：批量灌入 URL/PDF/YouTube/Drive 来源，fast/deep 网络研究自动导入，带引用多轮问答内容生成流水线：一个来源集扇出播客/视频/幻灯片/测验/闪卡/信息图/报告并批量下载（含 JSON/CSV/PPTX 导出）零 token 研究卸载与记忆层：让 NotebookLM 的 Gemini 做重活，agent 只做润色；Master Brain notebook 跨会话读写无人值守自动化：cron + auth refresh 做定时音频简报、告警 runbook 生成
边界与注意：非官方库，逆向未公开 API，有 ToS/合规风险，仅适合原型/研究/个人项目；生成类操作受 Google 限流可能失败需重试，依赖账号套餐额度（source 上限 50-600）；交互登录需要浏览器，MCP/REST 适配器标记 experimental。
完整拆解分析文档
本页为摘要版，完整精读分析（核心机制、逐条优秀点拆解、写作过程）见本地 Markdown 文档：
analysis/community-notebooklm-py.md