NotebookLM-Py 架构图集40 张可视化图纸从 JSON 源到 GitHub Pages 的完整工作流【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py本文围绕 notebooklm-py 仓库的docs/diagrams/目录展开讲解这套由 40 张「JSON 源 自包含 HTML 查看器」组成的架构图集如何组织、如何按主题检索、如何通过 GitHub Pages 托管发布以及如何用 Archify 工具链验证并更新一张图纸。读完之后你将掌握该图集的分类体系、五种图纸类型的 JSON 结构约定、部署校验逻辑以及一条可复制的「validate → deliver → visual-check」更新流程。图集定位架构文档的可视化配套docs/diagrams/README.md开篇即说明这些图是 docs/architecture.md 的可视化配套visual companion。首次成功部署到 GitHub Pages 之后目录中的Explore链接会在托管查看器中打开对应图纸查看器自带浅色/深色主题、引导式聚焦模式guided focus modes、搜索与导出能力Pages 站点始终反映main分支最近一次成功部署而旁边的Source链接则打开可编辑的 JSON 源文件。原文档还特别强调不要手工编辑生成的 HTML。从目录实际内容看共 80 个文件28408 字节级大小分布均匀图集遵循一个严格的文件配对约定每张图有两份文件NN-名称.类型.json源与NN-名称.类型.html交付物编号从 01 到 40HTML 查看器是自包含的单个文件约 700 KB由 Archify 生成。从 01-system-overview.html 的头部元信息可见生成器版本被标记为archify 2.16.0-dev.0并且包含首屏防闪烁的主题解析脚本仓库只提交 JSON 源与交付 HTML 两类文件不提交中间产物。五种图纸类型与 JSON 结构JSON 源使用统一的 schema。以 19-client-resource-lifecycle.lifecycle.json 为例其结构为schema_version: 固定为1diagram_type: 图纸类型共五种——architecture架构、workflow工作流、sequence时序、dataflow数据流、lifecycle生命周期文件名中的类型后缀即来源于此meta: 元信息包含title、locale、quality_profile该仓库统一为showcase、viewBox画布尺寸以及views数组——每个 view 定义一个「引导式聚焦」focus列出该视角高亮的节点 idnote说明该视角回答的问题类型专属的主体元素lifecycle 图有lanes泳道、states状态带type/sublabel/tag、transitions转移带variant/route路由控制workflow 图如 20-retry-policy-workflow.workflow.json有phases与mainPathsequence 图如 07-rpc-call-path.sequence.json有participants。以 19 号图根客户端资源生命周期为例其views定义了三个聚焦视角——「Generation rail」「Graceful shutdown」「Rollback and reopen」分别高亮不同状态子集这正是目录中 Explore 查看器「引导式聚焦模式」的数据来源。目录总览40 张图的主题分组目录将 40 张图分为五个主题区块每张图附「它回答什么问题」。以下完整继承目录的分类并给出各图源文件在仓库中的路径。托管部署成功后每张编号 HTML 都可通过项目 Pages 站点的 hosted viewer 打开未部署或站点暂不可用时直接打开本地 checkout 中已提交的 HTML 查看器即可。系统与边界System and boundaries#图回答的问题源文件01System overview库调用以及 CLI、MCP、REST 适配器如何到达两个后端docs/diagrams/01-system-overview.architecture.json02Adapters and application layer哪些职责属于前端适配器、哪些属于_app/docs/diagrams/02-adapters-and-app-layer.architecture.json03Client runtime and transportSharedRuntime 与所选后端包如何持有 dispatch、transport 与兼容逻辑docs/diagrams/03-client-runtime-and-transport.architecture.json05Feature servicessources、artifacts、chat 背后是哪些有状态服务docs/diagrams/05-feature-services.architecture.json06Web and Android backends哪些机制是中性的WebRuntime 与 AndroidRuntime 在哪里分叉docs/diagrams/06-backends-web-and-android.architecture.json23Runtime class modelSharedRuntime、WebRuntime、AndroidRuntime 与懒加载 sidecar 如何关联docs/diagrams/23-runtime-class-model.architecture.json27Capability contracts哪些实现满足 RPC、loop 与单消费者契约docs/diagrams/27-capability-contracts.architecture.json28Profile, auth, and backend selection每个后端构造哪些 auth、runtime、raw 适配器与兼容资源docs/diagrams/28-profile-auth-backend-selection.workflow.json29Organization and sharing哪些 API 跨越 account 与 notebook 作用域sharing 与 membership 在哪里docs/diagrams/29-organization-and-sharing.architecture.json30Transfer security boundariesWeb 与 Android 传输平面如何围栏 URL、凭据、清理与发布docs/diagrams/30-transfer-security-boundaries.dataflow.json34Client ownership boundaries哪些资源归配置、构造、单个 client 实例、单次操作所有docs/diagrams/34-client-ownership-boundaries.architecture.json35Client construction and lifecycle handoff直接构造与延迟构造如何收敛到同一个已安装的 CLOSED 图docs/diagrams/35-client-construction-and-lifecycle.lifecycle.json认证Authentication#图回答的问题源文件04Authenticationrefresh 如何分派到 Web cookie 恢复或 Android bearer 重铸docs/diagrams/04-authentication.architecture.json10Login workflow交互式登录、浏览器 cookie 导入与 master-token 引导有何不同docs/diagrams/10-login-workflow.workflow.json24Authentication class model哪些类型化值、存储与协调器拥有凭据状态与恢复逻辑docs/diagrams/24-auth-class-model.architecture.json31Cold authentication recovery冷启动的 Web 档案如何经 refresh 命令、无头引导与路径序列化的 L4 重铸恢复docs/diagrams/31-cold-auth-recovery.sequence.json调用、数据流与生命周期Calls, data flows, and lifecycles#图回答的问题源文件07RPC call pathsWeb、Android 与被废弃的兼容调用如何到达所选 runtimedocs/diagrams/07-rpc-call-path.sequence.json11Chat ask sequence锁、流式、会话恢复与结果组装分别归谁所有docs/diagrams/11-chat-ask-sequence.sequence.json12Source ingest文件字节与无字节输入如何成为就绪的 grounding 源docs/diagrams/12-source-ingest-dataflow.dataflow.json13Artifact lifecycle生成如何经过 pending、complete、failed 与 retry 状态docs/diagrams/13-artifact-lifecycle.lifecycle.json15Android call pathAndroid 命名空间调用到 protobuf 投影之间发生了什么docs/diagrams/15-android-call-path.sequence.json19Client resource lifecycle构造之后open、bind、drain、close、rollback、reopen 如何影响受管资源docs/diagrams/19-client-resource-lifecycle.lifecycle.json20Retry policy两个后端如何保持重试对等并诚实地暴露含糊的写入docs/diagrams/20-retry-policy-workflow.workflow.json21Deep research lifecycle研究任务如何经历轮询、完成、导入、失败或取消docs/diagrams/21-deep-research-lifecycle.lifecycle.json32MCP client providerMCP 适配器如何打开、复用、失效并恢复其共享 clientdocs/diagrams/32-mcp-client-provider.sequence.json33MCP detached chat task分离式 chat 任务如何从创建走到轮询、终态观察与 TTL 过期docs/diagrams/33-mcp-detached-chat-task.lifecycle.json36Operation deadline and cancellation一个操作预算如何跨越嵌套工作同时保留调用方取消docs/diagrams/36-operation-deadline-and-cancellation.sequence.json37Operation journal and recovery尝试证据如何成为提交确定性与安全的恢复动作docs/diagrams/37-operation-journal-and-recovery.dataflow.json38Adapter prepare, confirm, and execute规范资源 ID 或 notebooksharing 操作数如何在跨越人为延迟后被确认执行docs/diagrams/38-adapter-prepare-confirm-execute.workflow.json领域模型与适配器Domain models and adapters#图回答的问题源文件08Artifacts class modelartifact 契约、服务、轮询与公开结果类型如何关联docs/diagrams/08-artifacts-class-model.architecture.json09Exception hierarchy适配器可以分类哪些公开异常与下载 auth 元数据docs/diagrams/09-exception-hierarchy.architecture.json14Android subsystem凭据、session、transfers、phenotype、retry 与 epoch 机制如何组成 AndroidRuntimedocs/diagrams/14-android-backend.architecture.json16CLI subsystemClick 命令、服务、_app/与渲染器如何分工docs/diagrams/16-cli-subsystem.architecture.json17MCP subsystemMCP 工具如何共享中性内核与变更确认策略docs/diagrams/17-mcp-subsystem.architecture.json18REST subsystem路由、认证、限额、pending 状态与 client 生命周期如何协同docs/diagrams/18-rest-server-subsystem.architecture.json25Sources class modelsource 契约、upload/add 服务与公开 source 值如何关联docs/diagrams/25-sources-class-model.architecture.json26Chat, notes, and mind maps对话与 note 支撑/交互式界面如何组合docs/diagrams/26-chat-notes-class-model.architecture.json测试与故障覆盖Testing and fault coverage这一区块伴随 docs/fault-injection.md 使用。目录特别说明其中的场景数量描述的是「声明的故障牌组」declared fault deck不代表穷尽的失败空间或代码覆盖率。#图回答的问题源文件22Test infrastructure单元测试、guardrails、回放、真实 loopback 故障与 live 测试如何嵌入 CIdocs/diagrams/22-testing-and-guardrails.architecture.json39Fault coverage可移植与可选的 curl 牌组覆盖了哪些故障族与后端边界docs/diagrams/39-fault-coverage.architecture.json40Fault scenario lifecycle声明的故障、公开结果、独立证据与清理如何成为一份被校验的报告docs/diagrams/40-fault-scenario-lifecycle.workflow.jsonGitHub Pages 托管pages.yml 部署管线部署由 pages.yml 工作流名为 “Deploy architecture diagrams”完成。从该工作流源码可以确认以下事实触发条件仅在push到main且改动落在.github/workflows/pages.yml或docs/diagrams/*.html路径时触发另支持workflow_dispatch手动触发。这意味着拉取请求永远不会部署到公开站点且只有图纸 HTML 变更才会触发发布。构建步骤build jobcheckout 时关闭凭据持久化persist-credentials: false权限仅contents: readpages: read核心校验pages.yml统计docs/diagrams下形如[0-9][0-9]-*.html的查看器数量与[0-9][0-9]-*.json的源文件数量要求两者都大于 0 且严格相等——这就是「JSON 源与 HTML 查看器必须成对」约定在 CI 中的强制点只把编号 HTML 复制到_site/diagrams/并把01-system-overview.html额外复制为站点根路径的index.html使系统总览图位于 Pages 站点根部通过actions/upload-pages-artifactv5上传_site产物。部署步骤deploy jobneeds: build使用actions/deploy-pagesv5依赖pages: write与id-token: write权限并绑定github-pages部署环境。一次性前置配置仓库管理员必须在首次部署前在 Settings → Pages → Build and deployment 中把 Source 选为GitHub Actions否则首次部署不会成功。并发策略concurrency.group: pages且cancel-in-progress: false即新部署排队等待而非取消在途部署避免半途中断站点。覆盖策略哪些图被生成、哪些刻意不生成目录中的 Coverage policy 一节解释了图集的边界与演进已覆盖运行时各层、两个后端图、全部十一个公开命名空间、三个前端适配器、认证、主要字节传输边界以及「顺序或状态难以仅凭文字理解」的工作流2026 年 9 月审计新增图 28–30因为后端/档案优先级、五个 organization 命名空间与逐跳传输安全是原图集的实质性缺口分支本地的汇编器、根兼容 sidecar、共享源工作流与受保护传输重构只刷新受影响图纸不引入外部系统、RPC id 或 wire 形状图 31–33补齐此前缺失的冷认证恢复时序并发与清理顺序敏感、MCP provider 打开/恢复时序与分离任务生命周期图 34–38记录客户端所有权模型、构造到生命周期交接、整操作 deadline 与取消契约、变更日志与恢复证据、以及 2026 年 9 月所有权重构引入的 adapter prepare/confirm/execute 边界图 19 则专门覆盖 runtime 的 open、drain、close、rollback、reopen 迁移与 34/35 分工明确。刻意不生成的视图原文档列了三项均给出替代去处精确的仓库树图——留在 docs/architecture.md 的 File map 章节且由 scripts/check_claude_md_freshness.py 对src/notebooklm/做新鲜度门禁逐条 RPC 载荷与每个生成的 protobuf 类型——变化快于教学价值改用 docs/rpc-reference.md、docs/rpc-development.md 与 docs/android/README.mdAndroid 证据索引逐命令/逐方法清单——保留在 docs/cli-reference.md 与 docs/python-api.md图纸解释所有权与流程不复制参考文档。更新一张图纸Archify 命令流程仓库提交 Archify JSON 源与自包含 HTML 查看器但不内嵌、不锁定生成器。目录给出的更新流程是把环境变量ARCHIFY_ROOT指向已安装的 Archify skill/包在 PR 中记录其版本并审查生成 diff。按图纸类型architecture、workflow、sequence、dataflow、lifecycle执行ARCHIFY_ROOT/path/to/archify node $ARCHIFY_ROOT/bin/archify.mjs doctor --json node $ARCHIFY_ROOT/bin/archify.mjs validate type diagram.json \ --quality showcase --json node $ARCHIFY_ROOT/bin/archify.mjs deliver type diagram.json diagram.html \ --quality showcase --json node $ARCHIFY_ROOT/bin/archify.mjs visual-check diagram.html --json关键约束与收尾步骤--repo-root $PWD参数仅可用于architecture类型且有仓库证据的候选追加到validate与deliverworkflow、sequence、dataflow、lifecycle 候选必须省略该标志visual-check会产出浅色与深色截图应人工检查后删除所有生成的*.visual-check.*文件——它们是评审证据不是仓库产物最终只提交两样东西JSON 源与交付的 HTML。这与 pages.yml 的「源/查看器数量相等」校验以及部署路径过滤只发布docs/diagrams/*.html互相呼应。图集与文档体系的咬合方式从 docs/architecture.md 的交叉引用可以看出图集在整个文档体系中的位置架构正文在描述六层所有权模型、_app/中性应用层、Android 后端拆分、chat/notes 组合、源摄入与传输安全、资源生命周期与重试策略、deadline/取消与日志恢复时分别以 Explore 链接指向图 01/02/06、09、03/23/27、14/15、11/26、12/13/30、19/20、36/37/34/35 等对应图纸。也就是说文字文档承担「规范叙述 行内锚点」图集承担「可交互的结构/时序/状态视图」参考类清单CLI、Python API、RPC则刻意留在纯 Markdown 中——三者边界清晰互为入口。对于想深入某一主题的读者最短路径是先查本目录找到对应编号的图打开 HTML 查看器用 focus 模式与搜索定位结构再回到 docs/architecture.md 或对应 ADR如 docs/adr/0038-local-fault-injection-harness.md阅读文字证据。【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLMs features—including capabilities the web UI doesnt expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考