企业官网建设流程全解析

zlibrary-to-notebooklm 是一个开源的自动化桥梁工具：一条命令即可把 Z-Library 上的书籍自动下载下来，并上传到 Google NotebookLM，让你立刻用 AI 与整本书对话。它的核心架构非常干净——Python 做编排、Playwright 负责浏览器自动化、NotebookLM CLI 负责上传，三层各司其职。本文将从新手视角带你拆解这条完整链路，看懂每个模块在源码中是如何协作的。

先搞懂全链路：一本书是怎么"上车"的 📚

整条流水线可以概括为8 个阶段（完整 13 步流程图见 docs/WORKFLOW.md）：

Z-Library 书籍链接 ↓ 1. 加载已保存的登录会话（~/.zlibrary/storage_state.json） ↓ 2. Playwright 启动 Chromium，访问书籍页面 ↓ 3. 智能选择格式：PDF 优先，EPUB 备选 ↓ 4. 文件下载到 ~/Downloads ↓ 5. 格式处理：PDF 直接用 / EPUB 转 Markdown ↓ 6. 词数检查：超过 35 万词自动按章节分块 ↓ 7. NotebookLM CLI 创建笔记本并逐个上传 ↓ 8. 返回笔记本 ID ✅

对应到源码，三个脚本正好对应三个"工位"：

想快速上手安装，可参考 INSTALL.md；技能定义则写在 SKILL.md 和 skill.yaml 中，方便作为 Claude Skill 被 AI 助手直接调用。

模块一：login.py 的"一次登录，永久使用"魔法 🔑

登录脚本只有 90 来行，却包含三个关键设计（见 scripts/login.py）：

1. 持久化浏览器上下文：用launch_persistent_context把整个浏览器数据目录固定到~/.zlibrary/browser_profile/，cookies、缓存全部落地保存，下次启动直接"带着记忆"打开网站。
2. 反自动化检测：启动参数里带了--disable-blink-features=AutomationControlled，抹掉浏览器被 Playwright 驱动的指纹，降低被风控拦截的概率。
3. 半自动 + 安全存储：浏览器自动打开 Z-Library，登录动作由人完成（避开验证码等难题），回终端按 ENTER 后，会话写入storage_state.json，并设置600权限（仅本人可读写）、目录700权限。

这套"人肉登录 + 机器复用"的模式，是浏览器自动化项目里最稳妥的登录方案。

模块二：upload.py 全链路编排，架构核心 🧠

scripts/upload.py 是全项目的中枢，核心是ZLibraryAutoUploader类，主流程在 scripts/upload.py 的main()中，只有三步调用：

downloaded_file, file_format = await uploader.download_from_zlibrary(url) final_file = uploader.convert_to_txt(downloaded_file, file_format) result = uploader.upload_to_notebooklm(final_file)

2.1 智能格式选择：如何找到下载按钮？

download_from_zlibrary 方法处理了网站新旧两套 UI 的兼容，优先级为PDF > EPUB > 其他（PDF 保留排版，AI 分析效果最好）：

• 新版界面：先找"三点菜单"按钮，点开后再找PDF/EPUB选项；
• 旧版界面：找data-convert_to="pdf"转换按钮，点击后轮询最多 60 秒，等页面出现"转换完成"提示；
• 兜底策略：如果都失败，就扫全页所有a[href*="/dl/"]下载链接，从 URL 里判断格式。

下载环节还注册了page.on('download', handle_download)事件监听，由 Playwright 统一接管下载并保存到~/Downloads；万一事件没捕获到，还有"扫描下载目录里 2 分钟内最新文件"的备用兜底。这种多层容错是自动化脚本对抗网站改版的关键。

2.2 为什么用 JavaScript 点击而不是直接 click？

源码里点击链接用的是download_link.evaluate('el => el.click()')——直接执行 JS 点击，可以绕过元素被遮挡、不可见等 Playwright 常规点击限制，是浏览器自动化里常用的小技巧。

模块三：convert_epub.py 把 EPUB 翻译成 AI 友好的 Markdown 📝

NotebookLM 对纯文本的检索效果最好，所以下载到 EPUB 时，scripts/convert_epub.py 会接手转换：

• 用ebooklib打开 EPUB，遍历所有文档项（get_type() == 9），提取书名、作者等元数据；
• 用BeautifulSoup逐节点递归处理 HTML：h1~h6转 Markdown 标题、b/strong转加粗、ul/ol转列表、a转链接（核心函数 html_to_markdown）；
• 自动丢弃script、nav、svg等噪声标签，并过滤掉内容不足 100 字符的空章节。

依赖清单见 requirements.txt：playwright、ebooklib、beautifulsoup4、lxml 四个核心库。

模块四：35 万词智能分块，绕开 NotebookLM CLI 的限制 📦

NotebookLM 官方单来源上限是 50 万词，但 CLI 上传大文件时容易超时，所以项目选了一个实测安全值：35 万词。

split_markdown_file 的分块算法相当讲究：

1. 先按#/##/###章节标题切分，保证每一块从章节边界开始，内容完整不截腰；
2. 单个章节本身超过 35 万词的，再按段落二次切分；
3. 词数统计做了中英文兼容——中文字符逐字计数，英文按单词计数（count_words）；
4. 输出为书名_part1.md、书名_part2.md……逐块上传到同一个笔记本。

例如 270 万词的大书会被切成 8 块，每块约 34 万词，全部上传后 AI 提问时依然当作一本书回答。

模块五：NotebookLM CLI 上传与 JSON 解析 🚀

上传阶段（upload_to_notebooklm）通过subprocess调用三条 CLI 命令完成收尾：

notebooklm create '书名' --json # 创建笔记本，解析出 notebook ID notebooklm use <notebook_id> # 切换上下文 notebooklm source add '文件路径' --json # 上传来源（分块则循环执行）

几个工程细节值得学习：

• --json+ 解析 ID：从输出里提取notebook.id和source.id，失败时直接返回结构化错误信息，方便上层（或 AI Skill）做重试；
• 书名清洗：自动去掉文件名里的[...]、(...)杂质并截断到 50 字符，保证笔记本标题干净；
• 分块容错：某一块上传失败只跳过该块并继续，最后汇总"成功 x/y 个分块"，不会全盘失败。

配置与安全：所有状态都在 ~/.zlibrary/ 🔒

项目不落任何凭据到仓库里，所有运行状态集中在家目录（结构说明见 README.zh-CN.md）：

~/.zlibrary/ ├── storage_state.json # 登录会话（cookies），权限 600 ├── browser_profile/ # 浏览器持久化数据，权限 700 └── config.json # 账号配置备份

会话过期是最高频问题，处理方式就是删掉storage_state.json重新跑一遍 scripts/login.py，更多问题可查 docs/TROUBLESHOOTING.md。

新手阅读路线：如何一步步看懂这个项目 🗺️

建议按"由外到内"的顺序阅读源码，约 1 小时可通读全部核心代码：

1. README.zh-CN.md—— 5 分钟了解功能与使用方式；
2. docs/WORKFLOW.md—— 对着 13 步流程图理解全链路；
3. scripts/login.py—— 最短的脚本，理解会话保存机制；
4. scripts/upload.py—— 重点精读三个方法：download_from_zlibrary→convert_to_txt→upload_to_notebooklm；
5. scripts/convert_epub.py—— 学习递归式 HTML→Markdown 转换写法；
6. docs/TROUBLESHOOTING.md—— 反推作者踩过的坑。

总结：这套架构的三大可借鉴点 ✨

zlibrary-to-notebooklm 代码量不大，但把"浏览器自动化 + 文件格式处理 + 第三方 CLI 集成"三件事串得干净利落：

• 职责单一：三个脚本各管一段，main()三行串起全流程，读起来没有心理负担；
• 处处容错：新旧 UI 双兼容、下载事件双兜底、分块上传失败不中断，自动化脚本的稳定性全靠这些细节；
• 尊重限制：用 35 万词分块正面解决 CLI 超时问题，而不是硬扛官方限制。

如果你想在自己的项目里做类似的"网站自动化 → 格式转换 → AI 知识库"链路，这个仓库的源码结构就是很好的起步模板。

⚠️免责声明：本项目仅供学习研究与技术演示用途，请仅用于你拥有合法访问权限的资源，并支持正版阅读。