从0开始把PDF教材喂给AI：一条交互式教程生成管线的实战指南

PS：其他教程已经正常更新，可以进入公众号点击查看其他发布的教程~（当然不是这个项目写的，周末摸鱼被Kernel Programming合RTR4搞的头大的时候突发奇想的项目）

你的硬盘里是不是也躺着几本”计划要读”的技术书？买了、下载了、甚至翻过目录了，但就是读不下去。不是内容不行——是你翻开那 700 页的 PDF，看到密密麻麻的学术体文字，脑子里自动跳出来成就：抱歉！今天不行！

笔者也是。手边那本 Real-Time Rendering 第四版（RTR4），图形学圣经，700 多页，写得很扎实，但说实话，每次翻到第三章就犯困。以及最近笔者正准备开发一个IMX系列的一站式教程仓库的时候（https://github.com/Awesome-Embedded-Learning-Studio/imx-forge） 每一次看技术手册，我都感觉自己的天要塌了。我们都知道，是要系统的学习知识，这些书都是必经之路。但是他们就像一个学识渊博但不善言辞的教授——你知道他讲的东西很重要，但他讲的每一个字都在催眠。

后来笔者想了一件事：既然我读不下去，那让 AI 帮我”速通”这本教材行不行？不是让它帮我总结要点——那种三段式摘要读完还是什么都不懂。而是让它把整本书重写成我愿意读下去的教程，带概念梳理、带练习题、带吐槽和踩坑预警，像一篇技术博客而不是一篇论文。15 分钟跑完一条管线，输出一个可以直接浏览的教程网站。

这个想法最后变成了一个叫 Grimoire 的开源项目（GitHub：https://github.com/charliechen114514/grimoire）定位很简单：技术书速通工具。把一本你买来吃灰的技术书丢进去，它帮你重写成一套带练习题、带概念梳理、风格你说了算的交互式教程网站。面试前要速通一本书？接手新项目要快速过一遍领域知识？买了一堆 Wolai 笔记想整理成系统教程？都是它该出场的场景。

整条管线从解析到生成到打包成网站全部自动化，中间还夹了一套质量审查机制来盯住 AI 的手。接下来笔者想把这个项目拆开来讲——不只是展示它能做什么，更想聊清楚它为什么必须被设计成这个样子。

先别急着丢给 ChatGPT

这件事最直觉的做法是：把每一章的内容粘贴到 ChatGPT，说”帮我重写成教程风格”。

笔者最开始也是这么干的。然后发现这条路走不通，原因不止一个。

第一道墙是 token 截断。一本正经的技术教材，一章动辄几万字，LLM 的 8K token 输出上限根本兜不住。你让 AI 重写一章内容，它写到一半就停了，后半截直接消失，连个”未完待续”都没给你留。

第二道墙更隐蔽——跨章的概念连续性。第一章提到”渲染管线”的时候给出了一种解释，到第四章再提的时候 AI 已经忘了自己之前怎么说的了，直接换了一套说法。术语不统一这件事在教程里是致命的，读者会在第四章突然怀疑自己是不是看的同一本书。

第三道墙是质量控制。AI 写出来的东西你总得检查吧？27 章的内容，你不可能一章一章手动审。但如果你不审，鬼知道它会在哪一章突然开始用论文腔写东西。

这三道墙拼在一起，指向一个核心认知：“教程生成”不是一个 Prompt 问题，而是一个工程问题。它实际上是五个子问题的组合——概念提取、教程正文生成、练习题创建、要点总结，外加一层质量审查和自动修复。每个子问题需要的上下文不同、策略不同、质量标准也不同。

所以我们需要的不是一个更大的 Prompt，而是一条结构化的管线。

拆解：一条教材变教程的管线长什么样

Grimoire 的管线分四个阶段，每个阶段干一件明确的事，像一条工厂流水线一样首尾衔接。

第一阶段是解析（Parse）。输入可以是 PDF 文件，也可以是网页 URL。PDF 走 PDFParser 提取文本和图片；网页走引擎系统——Wolai、静态 HTML、Playwright SPA 渲染三选一，也可以自动检测。解析的产物是一份 chapters_raw.json，把整本书按章节拆好，后续所有阶段都围着这份结构化数据转。

第二阶段是批量生成（Batch Generate），这是管线的核心。每一章会经历四个 Agent 的接力：ConceptAgent 先跑，从原文中提取 10 到 25 个核心概念，同时维护一份跨章节的全局术语表。概念提取完之后，WritingAgent 和 ExerciseAgent 同时启动——一个写教程正文，一个出分级练习题，互不依赖所以并行跑。两者都完成后，TLDRAgent 收尾，把全章提炼成最多 5 个要点。多个章节之间也可以并行处理，用 --workers N 控制并发数，术语表通过快照策略保证并发安全。

第三阶段是质量审查（Review）。独立的 ReviewAgent 从风格一致性、难度曲线、概念密度三个维度给每章打分，低于 7 分的不及格章节会被送进 FixAgent 做最小化的定向修复，修完重新送审，循环迭代直到通过或达到最大重试轮次。

第四阶段是打包（Package），把所有生成的教程 Markdown 打包成一个可以直接部署的 MkDocs 静态网站。

这条管线的架构不是拍脑袋决定的。有几个地方的设计决策值得展开说，因为它们直接决定了输出质量。

先看 Phase 2 里 Agent 之间的依赖关系。ConceptAgent 必须先跑——它负责从原文中提取 10 到 25 个核心概念，还要区分哪些是本章新出现的、哪些是前面章节已经定义过的。这些概念信息会被后续的 WritingAgent 和 ExerciseAgent 消费，所以它是一个前置依赖。但概念提取完成之后，教程正文和练习题之间就没有依赖了——它们各自消费同一份概念列表，互不干扰，所以管线把它们做成并行的，用 asyncio.gather 同时跑。这一步直接把每章的耗时砍掉了大约 25% 到 30%。

跨章节的术语表（glossary）是一个更微妙的设计。当多个章节并行跑的时候（--workers 4 意味着最多 4 章同时处理），每章都能读到术语表，但它们不能同时往术语表里写新概念——否则就会出现竞争条件，A 章和 B 章可能对同一个术语给出不同的定义。Grimoire 的解法是快照策略：所有并行章节拿到的是同一份术语表快照，各自处理完之后，新概念在锁的保护下延迟合并回全局术语表。这意味着并行章节之间不会互相干扰，代价是后跑的章节可能看不到前面章节刚刚提取的新概念——但实践中这个代价很小，因为术语通常在多个章节里重复出现，不会只在一个章节里被首次定义。

Phase 3 的审查环节也是被故意独立出来的。如果生成和审查是同一个 Agent 自己干的，那相当于让学生给自己判卷——你永远不知道它会不会自我感觉良好。独立的 ReviewAgent 用一套完全不同的评分维度来审视输出，而 FixAgent 只做最小化的定向修改，不会把整章推翻重写。这个”审查与修复分离”的设计，是保证批量输出质量一致性的关键。

从零开始：5 分钟跑通你的第一个教程

环境搭建很快。笔者的开发环境是 WSL2 上的 Ubuntu，Python 3.12+，整个过程不超过三分钟。

先把项目 clone 下来，创建虚拟环境：

git clone https://github.com/charliechen114514/grimoire.git
cd grimoire
python -m venv .venv
source .venv/bin/activate
pip install -e .

这里 pip install -e . 会以开发模式安装所有核心依赖。如果你还需要 OCR 增强的 PDF 解析或者 Playwright 的 SPA 渲染，可以换成 pip install -e ".[all]"，一步到位。

接下来是 API 密钥。项目根目录有一个 .env.template 模板文件，复制成 .env 然后填入你的 Anthropic API Key 就行：

cp .env.template .env
# 编辑 .env，填入 ANTHROPIC_API_KEY=你的密钥

如果你用的是第三方代理（比如智谱、DeepSeek 的兼容接口），也可以在 .env 里设置 ANTHROPIC_BASE_URL 指向代理地址，Grimoire 会自动走代理。

好了，所有准备工作到这里就结束了。下面这一行命令会把整个管线从头跑到尾——解析、生成、审查（含自动修复）、打包成网站：

python -m cli all books/your-textbook.pdf --slug MYBOOK

如果是 Wolai 上的教程网页，把 PDF 路径换成 URL 就行，管线会自动检测域名并选择对应的解析引擎：

python -m cli all "https://www.wolai.com/xxxxx" --slug RTR4 --workers 4

这里的 --workers 4 开启 4 章并行处理。实测 RTR4 这本 27 章的教材，用 4 个 worker 跑完全部章节只花了大约 15 分钟——包含概念提取、教程正文生成、练习题创建和要点总结。

管线跑完之后，输出在 output/MYBOOK/ 目录下。进到这个目录，用 MkDocs 起一个本地服务器就能预览成品了：

cd output/MYBOOK && mkdocs serve
# 打开 http://127.0.0.1:8000 预览

到这里你的第一个 AI 生成的教程网站就跑起来了。

灵魂所在：让 AI 用你的风格写教程

如果说管线架构是骨架，那写作风格系统就是 Grimoire 的灵魂。

一般的 AI 写作工具给你一个文本框，你输入”用技术博客风格重写”，AI 就按它理解的那个风格给你输出。问题是，AI 理解的”技术博客风格”和你理解的不是同一个东西——它可能给你整出一堆”好了，接下来让我们看看”这种一眼就能识别的模板过渡句，或者用学术论文腔把原本有趣的机制讲得比原文还无聊。

Grimoire 不走这条路。它用一份 600 多行的纯 Markdown 配置文件（config/writing_style.md）来精确控制生成风格的每一个维度——从人格定位、语气规则、叙事节奏到过渡句模板，全部可配。

举一个具体的例子。这份风格文件定义了三种叙事节奏模式，针对不同类型的内容自动切换。第一种叫”SICP 紧绷模式”，用在章节引子和核心概念首次亮相的场景——句子短，留白多，一句话只讲一件事，讲完就停，强迫读者停下来思考。第二种叫”侯捷紧密模式”，用在机制拆解和代码逐段讲解——每句话都有信息量，没有废话，读者像在跑步机上连续走，节奏紧凑但不留悬念。第三种叫”费曼流动模式”，用在类比引入和踩坑故事——思路外放，像在跟朋友聊天，允许绕路和重复。

这套节奏机制解决的是 AI 生成文本最常见的病征——”起伏太平”。每个段落读起来密度一样、节奏一样，像心电图上画了一条直线。而一个好的技术教程，段落之间需要有张力的起伏：建立期待 → 推进展开 → 反直觉的转折点 → 释放和喘息。Grimoire 的风格配置里甚至有一节专门讲”段落张力曲线”的设计，要求每个超过 400 字的大段内建一条完整的张力弧线。

还有一个笔者特别满意的机制——类比回收规则。风格文件强制要求每个类比必须出现三次：第一次建立映射，第二次在讲完真实机制后揭示类比开始失效的边界，第三次在小节末尾用同一个类比检验读者的理解。这解决的是技术写作里最常见的”类比用完就丢”问题——读者看完类比觉得懂了，但一回到真实机制就又懵了，因为类比和现实之间的距离从来没被说清楚。

最终效果长什么样？这里是 RTR4 第二章的生成片段：

实时渲染这件事，本质上是一个残酷的数学游戏。

这听起来有点夸张，但让我们把这个画面拆解开来：你的显示器每秒钟需要刷新几十次（通常是 60 次甚至更多），每一次刷新，计算机都必须在不到 16.7 毫秒的时间里，完成从「这里有辆车」到「屏幕上这辆车该有的颜色和光影」的全部计算。

这不仅仅是算得快的问题。这是一场关于「感知」的战斗。

这不是原文的语气——原文是标准的英文学术教材体。Grimoire 把它重写成了一个带着叙事张力的开场，而风格文件同时控制了这种重写不会跑偏——它不会在第四章突然开始用”本节将介绍”这种官方文档腔。

如果你不喜欢默认的 SICP 叙事风，项目里还提供了第二套模板（writing_style2.template.md），是更接近工程师博客实战风的风格——更强调手把手推进、踩坑预警和”上号！”式的段落标题。复制过来覆盖默认配置就行，一行命令搞定。

不止 PDF：插件式引擎怎么吃掉一整个网站

Grimoire 最早只能吃 PDF，但笔者后来发现很多好的技术教程不是写在 PDF 里的——它们在 Wolai、Notion、各种静态网站上。于是 Web 解析引擎系统被设计成了插件式架构。

核心是一个叫 BaseWebEngine 的抽象基类，每个引擎只需要实现一个 parse() 方法——输入 URL，输出标准化的章节数据。引擎的选择逻辑也很直觉：如果命令行里显式指定了引擎名（--engine wolai），就用指定的；如果没有指定，就根据 URL 域名自动匹配（比如 wolai.com 自动走 Wolai 引擎）；如果域名也没匹配上，就回退到静态 HTML 引擎用 httpx + BeautifulSoup 抓取。

内置的三个引擎各有各的绝活。Wolai 引擎是最快的——它不走浏览器渲染，而是直接调 Wolai 的公开 API 拿页面结构，27 章的内容大概 7 秒钟就全部解析完毕。Static 引擎适用于传统的服务端渲染网站，用 httpx 抓页面再用 BeautifulSoup 提取正文。Playwright 引擎最重但最通用，它启动一个无头 Chromium 浏览器来渲染 SPA 页面——React/Vue 那种内容全靠 JS 动态加载的网站，不用浏览器根本拿不到完整内容。

说实话，Playwright 引擎在开发过程中坑了笔者半天。标准的 asyncio.sleep() 和 Playwright 自带的 page.wait_for_timeout() 在某些 SPA 网站上会把主线程卡死——页面在那里等着，你的代码也在那里等着，两边互相等，最后一起超时。解决方案是绕开 Python 侧的 sleep，改用 page.evaluate() 注入一个浏览器内的 Promise + setTimeout 组合，让等待动作跑在浏览器的事件循环里而不是 Python 的事件循环里。这个坑真的很隐蔽，笔者在这里血压拉满。

如果你需要解析的网站不在内置引擎的覆盖范围内，自己写一个引擎也不难。20 行 Python 代码就够——继承 BaseWebEngine，设置 NAME 和 DOMAINS，实现 parse() 方法，把文件丢到 src/parsers/engines/ 目录下，引擎就会被自动发现和注册，不需要手动配置任何东西。或者你也可以用 --engine /path/to/my_engine.py 直接指定一个外部文件。

27 章并行跑：断点续跑与并发加速

RTR4 有 27 章，如果串行处理——一章一章排着队跑——整个生成过程会非常漫长。Grimoire 提供了 --workers N 参数来开启章节级并行处理。

并行的核心挑战不是”怎么同时做多件事”，而是”怎么同时做多件事且不出错”。术语表的并发竞争问题前面讲过了——快照策略配合延迟合并解决的。另一个需要处理的是全局 API 并发控制。4 个 worker 意味着最多 4 章同时处理，每章内部 WritingAgent 和 ExerciseAgent 又是并行的，所以实际的并发 API 请求数可能是 worker 数的两倍。Grimoire 用一个全局信号量（MAX_CONCURRENT_CHAPTERS * 2）来限制并发请求数的上限，配合指数退避做双重保护，避免被 API 限流直接打回来。

还有一个在工程上很重要的机制——断点续跑。每一章完成后，进度会被原子性地写入 progress.json。这意味着你随时可以 Ctrl+C 中断处理——去吃饭、合上电脑、甚至断网——下次重新运行同一个命令时，管线会自动跳过所有已经完成的章节，从断点继续。对于一本几十章的大书来说，这个机制基本是必须的，因为你不可能保证一次性跑完几个小时的管线而不被打断。

审查 Agent：谁来看住 AI 的手

AI 生成的教程质量不稳定是常态，不是例外。同一套风格配置，第一章可能写得行云流水，到了第五章突然开始堆砌列表、用”本文将介绍”这种论文腔。如果没有审查机制，你需要一章一章手动检查，那自动化管线的意义就打了对折。

Grimoire 的审查系统由两个 Agent 配合完成。ReviewAgent 从三个维度给每章打分：风格一致性（style）、难度曲线（difficulty）和概念密度（density），每个维度 1 到 10 分，三项都 >= 7 才算通过。它不只是给个分数——还会给出具体的问题定位，指出哪一段出了什么问题、严重程度如何、建议怎么改。

比如 RTR4 第一章的实际审查报告里，ReviewAgent 发现了这样一个问题：练习题的参考答案部分用了”1.xxx 2.xxx”的编号列表体，出现了”根据图形渲染管线的定义……”这种教科书腔调。它给出的修复建议是把解析改写成连贯的叙述体——”如果你把整个流程看作数据在管道里流动，那么裁剪肯定是第一道关卡……”这种风格。

审查不通过的章节会被送给 FixAgent，它做的事不是推翻重写，而是最小化的定向修改——只动有问题的段落，保留其余部分。修改完后重新送审，如果通过了就放行，没通过就再修一轮。默认最多修两轮（可通过 --max-retries 调整）。

这个”最小化修复”的设计是故意的。如果你让 FixAgent 推翻重写，它可能在修好原有问题的同时引入新的问题——相当于用一个新的未知数替换一个已知的问题。定向修改把变动范围控制在最小，每一轮修复的可预测性更高。

在 all 命令里，审查加自动修复是默认开启的。如果你只想要审查报告不想自动改东西，加一个 --no-fix 就行。

大章节的暴力拆解：Verbose 模式与自适应分节

标准模式下，Grimoire 对每章做一次压缩重写，输出大约是原文 20% 的篇幅。这个比例对于大多数”想要快速掌握要点”的场景已经够了，但如果你想要的是一份基本保留所有技术细节的忠实改写——比如你想用它替代原文来做学习参考——20% 显然不够。

这就是 Verbose 模式存在的理由。开启后（--verbose-mode），管线会用 PDF 的 TOC 层级结构来自适应分节：先按 L2 标题切分，如果某一节超过 30K 字符就展开到 L3 甚至 L4 子标题。切完之后，每一节独立调用 LLM 进行忠实改写，输出 token 上限也提到了 16K。最终结果是一章被拆成多个文件（ch05_1.md、ch05_2.md、ch05_3.md……），外加一个索引页把它们串起来。

内容保留率从 20% 跳到大约 75%，API 成本也相应地涨了 3 到 5 倍。这是预料之中的权衡——你想保留更多细节，就得花更多的 API 调用。

值得注意的是，即使不开启 Verbose 模式，管线也会自动检测大章节并做分节处理。对于从 Wolai 等网页来源获取的章节，如果原文里包含 Markdown 标题（比如 ### 12.1 图像处理），管线会按标题切分后逐节处理，防止单次 LLM 调用的输出 token 不够导致内容截断。这个机制对 PDF 来源同样安全——pymupdf 提取的 TOC 通常已经包含多级条目，会优先使用 TOC 数据来分节。

说点现实的：API 成本和耗时

笔者知道大家最关心的一个问题是：这玩意烧多少钱？

以 RTR4 为例，27 章，标准模式，使用 sonnet 模型，--workers 4 并行处理。从 progress.json 记录的时间戳来看，整个生成阶段从 08:44:16 到 08:59:13，大约 15 分钟。API 成本方面，标准模式下每章大约一次 WritingAgent 调用加一次 ExerciseAgent 调用（并行）加一次 TLDRAgent 调用，总计大约 3-4 次 LLM 调用。27 章加起来大概 80-100 次调用。

Verbose 模式的成本会涨到 3-5 倍，因为每章被拆成多节，每节独立调用。如果你用的是 opus 模型追求最高质量，价格还会再上一个台阶。

笔者的实用建议是这样的：先用 --model haiku 快速跑一遍看看整体效果和风格是否符合预期——haiku 的成本大约只有 sonnet 的十分之一，速度快很多。确认风格满意之后，再用 sonnet 正式生成。opus 可以留着给审查环节用（python -m cli review MYBOOK --fix -m opus），让最强的模型来负责质量把关，但不需要让它跑全部的生成任务。

另外，Grimoire 支持通过 ANTHROPIC_BASE_URL 接入第三方代理，所以如果你用的是智谱、DeepSeek 等提供 Anthropic 兼容接口的服务，直接配置 base URL 和对应的模型映射就行，不需要改任何代码。

魔改指南：插件、Prompt、模型全可换

Grimoire 的设计思路是”分层定制”——你可以不动一行代码就调整大部分行为，也可以深入到 Python 层做任意扩展。

最简单的定制是换写作风格。编辑 config/writing_style.md，这是一个纯 Markdown 文件，你写的每一条规则都会被 Agent 当作风格指令来遵循。文件写得越详细，生成的教程风格就越一致。项目自带两套模板，一套是默认的 SICP 叙事风，一套是工程师博客实战风，复制过来改一改就能用。

再深一层是调整 Agent 的 Prompt。所有 Agent 的系统提示词和用户提示词都在 prompts/system/ 和 prompts/user/ 目录下，全部是纯 Markdown 文件——不涉及任何 Python 代码。这意味着你不需要理解项目的代码结构就能调整 Agent 的行为。想让练习题出得更难？改 prompts/user/exercise_user.md。想让 TLDR 更精炼？改 prompts/user/tldr_user.md。

最深的一层是代码扩展。Web 解析引擎前面已经展示过了——继承 BaseWebEngine，20 行代码搞定一个新引擎。如果你想做更激进的事情，比如添加一个新的 Agent 类型或者修改编排逻辑，项目结构很清晰：每个 Agent 一个文件，编排逻辑在 orchestrator.py，批处理在 batch.py，都有充分的注释。

Prompt 与代码分离是整个定制系统里最重要的设计决策。它意味着一个不懂 Python 的人——比如一位专注于教学法的内容创作者——也可以通过编辑 Markdown 文件来精确控制 AI 的输出风格，而不需要碰任何代码。

还没完——接下来想做什么

Grimoire 目前还有一些局限，笔者不打算藏着掖着。PDF 解析依赖正则匹配 Chapter N 格式的章节标题，如果你的 PDF 没有这种格式（比如中文教材用”第 N 章”），需要改一下正则。所有的 Prompt 和风格配置目前是中文的，英文支持需要翻译 Prompt 文件。Playwright 引擎需要安装 Chromium 的系统依赖。

项目在 GitHub 上开源，MIT 协议，欢迎提交 Issue 和 PR。如果你有好的写作风格配置或者新的 Web 引擎实现，笔者非常乐意把它们集成进项目。

回到开头那个 700 页的 PDF

还记得开头说的那本”改天再看”的 RTR4 吗？笔者现在已经能用大约 15 分钟把它从一本 700 页的学术教材变成一个 27 章的交互式教程网站——每章带着概念梳理、练习题和要点总结，写法是那种笔者自己愿意读下去的叙事风格，不是催眠的学术腔。教程正文生成之后还有一轮自动质量审查兜底，不达标的章节会被自动修复。

Grimoire 不是又一个”让 AI 帮你写东西”的工具——市面上做这件事的已经太多了。它要解决的是一个更具体的问题：你手边有一本技术上没问题但就是读不下去的书，你需要一种方式让它变成你能学进去的东西。用多 Agent 管线分工协作保证内容质量、用独立的审查机制控制风格一致性、用可配置的风格系统让你说了算、用断点续跑和并行加速保证工程实用性。这些设计决策没有一个是为了炫技——每一个都是为了让那句”改天再看”少出现一次。

面试前要速通一本领域教材？新项目上手需要快速过一遍知识体系？买来吃灰的技术书终于想读了？试试 Grimoire。

GitHub：https://github.com/charliechen114514/grimoire — Star、Issue、PR 都欢迎。