NotebookLM-Py 架构图集：40 张可视化图纸从 JSON 源到 GitHub Pages 的完整工作流

NotebookLM-Py 架构图集：40 张可视化图纸从 JSON 源到 GitHub Pages 的完整工作流

【免费下载链接】notebooklm-pyUnofficial Python API and agentic skill for Google Gemini Notebook. Full programmatic access to NotebookLM's features—including capabilities the web UI doesn't 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 到 40；
• HTML 查看器是自包含的（单个文件约 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: 固定为1；
• diagram_type: 图纸类型，共五种——architecture（架构）、workflow（工作流）、sequence（时序）、dataflow（数据流）、lifecycle（生命周期），文件名中的类型后缀即来源于此；
• meta: 元信息，包含title、locale、quality_profile（该仓库统一为showcase）、viewBox（画布尺寸），以及views数组——每个 view 定义一个「引导式聚焦」：focus列出该视角高亮的节点 id，note说明该视角回答的问题；
• 类型专属的主体元素：lifecycle 图有lanes（泳道）、states（状态，带type/sublabel/tag）、transitions（转移，带variant/route路由控制）；workflow 图（如 20-retry-policy-workflow.workflow.json）有phases与mainPath；sequence 图（如 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）

认证（Authentication）

调用、数据流与生命周期（Calls, data flows, and lifecycles）

领域模型与适配器（Domain models and adapters）

测试与故障覆盖（Testing and fault coverage）

这一区块伴随 docs/fault-injection.md 使用。目录特别说明：其中的场景数量描述的是「声明的故障牌组」（declared fault deck），不代表穷尽的失败空间或代码覆盖率。

GitHub Pages 托管：pages.yml 部署管线

部署由 pages.yml 工作流（名为 “Deploy architecture diagrams”）完成。从该工作流源码可以确认以下事实：

1. 触发条件：仅在push到main且改动落在.github/workflows/pages.yml或docs/diagrams/*.html路径时触发，另支持workflow_dispatch手动触发。这意味着拉取请求永远不会部署到公开站点，且只有图纸 HTML 变更才会触发发布。
2. 构建步骤（build job）：
   • checkout 时关闭凭据持久化（persist-credentials: false），权限仅contents: read+pages: 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-artifact@v5上传_site产物。
3. 部署步骤（deploy job）：needs: build，使用actions/deploy-pages@v5，依赖pages: write与id-token: write权限，并绑定github-pages部署环境。
4. 一次性前置配置：仓库管理员必须在首次部署前，在 Settings → Pages → Build and deployment 中把 Source 选为GitHub Actions，否则首次部署不会成功。
5. 并发策略：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 分工明确。
• 刻意不生成的视图（原文档列了三项，均给出替代去处）：
  1. 精确的仓库树图——留在 docs/architecture.md 的 File map 章节，且由 scripts/check_claude_md_freshness.py 对src/notebooklm/做新鲜度门禁；
  2. 逐条 RPC 载荷与每个生成的 protobuf 类型——变化快于教学价值，改用 docs/rpc-reference.md、docs/rpc-development.md 与 docs/android/README.md（Android 证据索引）；
  3. 逐命令/逐方法清单——保留在 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与deliver）；workflow、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 NotebookLM's features—including capabilities the web UI doesn't expose—via Python, CLI, and AI agents like Claude Code, Codex, and OpenClaw.项目地址: https://gitcode.com/GitHub_Trending/no/notebooklm-py