本地化AI阅读助手：零成本构建长文本记忆索引与防剧透剧情回顾

1. 项目概述：一个为长文本阅读者设计的本地化AI回忆助手

作为一个深度阅读爱好者，我经常被一个问题困扰：读一本动辄几十万字的网络小说或长篇巨著，中间因为工作、生活打断几天，再捡起来时，前面的人物关系、关键伏笔、剧情脉络已经变得模糊不清。直接翻回去重读？时间成本太高。问AI助手？要么得把整本书喂给它，消耗天价的token费用；要么它只能基于公开信息胡编乱造，因为它根本没“读”过你手上这本特定的书。

这正是book-recall这个项目诞生的背景。它不是一个简单的文本解析工具，而是一个精心设计的“阅读伴侣”工作流。其核心思想非常巧妙：将高成本的AI推理与低成本的本地计算进行解耦。整个流程中，最繁重的文本解析、实体（人物、地点）识别、章节摘要生成全部在本地完成，无需调用任何大模型API，实现“零AI成本”的预处理。只有当用户需要回忆时，系统才会将预处理好的、高度压缩的“记忆索引”一次性提交给AI，请求其生成一份连贯、准确且绝对无剧透的剧情回顾。

简单来说，它帮你把一本厚厚的书，提炼成一份仅占原体积约19%的“精华笔记”，并且这份笔记的结构化程度极高，包含了人物出场脉络、地点变迁和章节概要。当你读到第50章有点懵时，不是把前49章原文扔给AI，而是把这本“精华笔记”的前49章部分交给它，让它帮你写一份“前情提要”。这种设计，将一次回忆的AI调用成本从可能的上百万token和数十次API调用，压缩到了区区一次调用和几千token，效率提升是数量级的。接下来，我将拆解这个项目从设计思路到具体实现的每一个环节，分享其中涉及的技术选型、实操细节以及我趟过的一些坑。

2. 核心设计思路与架构拆解

2.1 成本与效率的权衡：为何选择“本地索引+单次AI调用”架构

在构思一个AI阅读辅助工具时，我们面临几个核心矛盾：准确性、成本、实时性和防剧透。最 naive 的方案是把用户当前进度之前的所有文本直接拼接，扔给大模型。这对于短篇文章可行，但对于长篇作品，动辄几十万字的上下文长度会直接击穿绝大多数模型的上下文窗口，即使能处理，其token费用也高得惊人（按主流API价格，百万token可能高达数十元人民币）。

另一种方案是预先用AI为每一章生成摘要，回忆时汇总这些摘要。这虽然降低了单次请求的上下文长度，但需要为每一章都调用一次AI，对于一本上千章的网络小说，前期成本同样无法承受，且失去了灵活性。

book-recall选择了一条更工程化的路径：用规则与启发式方法在本地完成“粗加工”。本地处理的优势是零边际成本，可以尽情使用计算密集型的NLP基础操作（如分词、词性标注、命名实体识别）。虽然精度可能不及大模型，但对于“提取高频人名、地名”、“生成简短内容梗概”这类任务，经过精心设计的规则集足以达到可用水平。本地处理产出的是一份结构化、轻量级的“索引”。最终，仅将这份索引（而非原文）提交给AI进行“精加工”，生成人类友好的叙述性回顾。这个架构完美平衡了成本（仅1次AI调用）、效果（基于真实内容的准确回忆）和上下文长度限制。

2.2 核心工作流四步分解

项目的流程图清晰地展示了四个阶段：

1. 解析：将 EPUB、PDF、TXT 等格式的原始书籍文件，解析为纯文本，并按照章节进行分割。输出是一个结构化的JSON文件，包含书籍元数据和按章节组织的原文。
2. 索引：这是本地计算的核心。对每一章文本，运行一系列启发式算法，提取关键信息，生成该章的“索引卡片”，包含：
   • 人物列表：出现在本章的角色。
   • 地点列表：本章涉及的地点。
   • 章节摘要：一段由规则生成的、非常简短的概要（例如，通过提取首句、尾句或高频词句组合而成）。
3. 提示词构建：当用户请求回忆（例如，读到第30章），系统会执行一个关键操作：严格过滤。它只加载第1章至第29章的索引卡片，第30章及之后的内容完全不可见。然后，将这些卡片的有效信息，压缩、组织成一个格式工整的提示词（Prompt）。这个提示词会明确指令AI：“你是一名讲故事助手，请根据以下按时间顺序排列的章节索引，为我生成一份到此为止的剧情回顾，严禁推测或提及后续内容。”
4. AI回忆：将构建好的提示词发送给大模型（如 GPT-3.5/4, Claude 等），得到一份流畅、连贯、无剧透的剧情总结。

这个流程的妙处在于，索引的大小远小于原文。原文可能500万字，索引可能只有不到100万字，且因为高度结构化，信息密度极高，最终构建提示词时还可以进行二次压缩（例如，只选取重要章节的摘要），使得送入AI的上下文可能只有几千token，却承载了全书前段的精华。

2.3 防剧透机制的严格性设计

“防剧透”是这个工具的灵魂，不仅仅是一个功能点，而是贯穿整个数据处理流程的设计原则。其实现是多层次的：

• 数据访问层面：在build_index和recall阶段，程序逻辑上就根本没有读取后续章节文件的可能。回忆脚本的输入参数是--chapter N，内部在处理时，会严格将数据数组切片到N-1。
• 提示词指令层面：发送给AI的提示词中，会包含强有力的指令，例如：“以下信息严格截止到第N章之前，你绝对不知道第N章及之后的内容。你的回顾必须基于且仅基于所提供信息，禁止任何形式的 extrapolation（外推）或 speculation（猜测）。”
• 输出校验层面（可选但推荐）：对于关键任务，可以在收到AI回复后，用简单的规则进行一次后检查，例如扫描回复中是否出现了后续章节才出现的关键人物名或地名（这些信息在索引中已被提前提取），如果出现，则可以触发警告或要求AI重写。

这种机制确保了工具的可信度。用户知道，无论怎么问，得到的回答都不会“说漏嘴”，这建立了核心的用户信任。

3. 关键技术细节与本地处理实现

3.1 多格式解析与智能章节分割

书籍来源格式多样，可靠解析是第一步。

• EPUB解析：使用ebooklib和BeautifulSoup。EPUB本质是一个ZIP包，包含HTML文件、样式表和元数据。解析流程是：解压 -> 读取content.opf获取骨架 -> 按顺序提取HTML文件 -> 用BeautifulSoup清理标签、样式、脚本 -> 获取纯文本。章节分割通常可以依据EPUB自带的目录（NCX或Nav），但有些制作粗糙的EPUB可能需要回退到基于标题标签（如<h1>,<h2>）的启发式分割。
• PDF解析：这是一个更大的挑战。我们使用poppler工具集的pdftotext命令行工具（通过subprocess调用）或pdfminer.six、PyMuPDF这类库。PDF解析的难点在于布局复杂（双栏、页眉页脚、图表）、文字编码问题以及完全没有原生的章节概念。这里的“智能章节分割”通常需要结合多种信号：大幅度的页面空白、特定样式的标题文本（如字体变大加粗）、以及类似“第X章”这样的模式匹配。在实践中，我通常采用正则表达式匹配章节标题模式作为首要分割依据，辅以段落格式变化作为次要依据，效果相对稳定。
• TXT解析：最简单也最棘手。简单在于文本可直接读取，棘手在于章节格式千奇百怪。我们的策略是定义一组强大的正则表达式，来匹配常见的中英文章节标题模式，例如：r'第[一二三四五六七八九十零百千\d]+章'，r'Chapter\s+\d+',r'[Ss]ection\s+\d+'， 以及识别连续的换行符后跟特定格式的文字等。

实操心得：永远不要相信来源数据的规范性。在解析模块中，必须加入大量的日志输出和中间结果保存功能。例如，将解析出的疑似章节标题和位置打印出来，人工复核一下。可以编写一个简单的预览脚本，将分割结果用章节号标注后输出到文件，快速验证分割准确性。这是调试过程中最耗时但最重要的一步。

3.2 中英文双语实体提取的启发式规则

这是本地索引构建中最具挑战性的部分，完全依赖规则和启发式方法，不依赖训练好的NER模型（为了轻量和可移植性）。

中文人物名提取：

1. 姓氏库匹配：建立一个常见的中文姓氏库（赵钱孙李...）。扫描文本，标记所有出现在姓氏库中的单字。
2. 上下文窗口：对于每个标记的姓氏，检查其后面紧跟的1到2个字符（中文名通常1-2字）。如果这些字符属于常见的人名用字范围（可以维护一个常用名用字库，或简单判断是否为Unicode中文字符），则将其组合为一个候选全名。
3. 昵称/别称关联：处理像“萧炎哥哥”、“熏儿”这样的称呼。通过规则匹配“XX哥哥/姐姐/师弟”等模式，提取“萧炎”作为人名。对于“熏儿”这类可能本身就是名字的，也纳入人名库。
4. 指代消歧（基础版）：建立人物出现频率表。当后续章节出现“他”、“她”、“那位黑袍人”时，很难准确关联。一个简单的启发式规则是：优先指向本章或最近几章内出现频率最高的同性别人物。这并不完美，但能解决一部分问题。

英文人物名提取：

1. 首字母大写序列：英文人名通常由多个首字母大写的单词组成（如“Harry Potter”）。通过正则表达式r'[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+'可以捕获大部分。
2. 对话归因：在英文小说中，对话后常跟“said CharacterName”或“CharacterName said”。匹配r'\"[^\"]+\"[^.\"]*said\s+([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)'这类模式，是极其精准的人物名来源。
3. 所有格与称谓：识别“'s”结构（如“Harry's wand”）和“Mr./Mrs./Ms./Dr.”等称谓后接的大写名词。

地点提取：

• 中文：匹配常见的地名后缀，如“村”、“镇”、“城”、“市”、“国”、“山”、“河”、“楼”、“殿”、“广场”等，并检查其前面的修饰词（通常为2-4个中文字符）。
• 英文：依赖介词上下文。例如，出现在“in the *”, “at the *”, “to *”, “from *” 这些介词短语中的首字母大写名词短语，很可能是地点。同时，“City of *”, “Kingdom of *” 也是强信号。

注意事项：规则式提取必然会有误报（把不是实体的词提取出来）和漏报（没提取出某些实体）。我们的目标不是100%准确，而是高召回率，尽可能抓取所有可能的实体。因为后续是AI来消化这些信息，AI对人类语言有很强的理解能力，即使索引里混入了一些噪声（如误将“春天”作为地点），AI在生成回顾时也能大概率忽略或合理处理。相反，如果漏掉了关键人物，回忆的完整性就会受损。所以，规则可以设计得“宽松”一些。

3.3 章节摘要的生成策略

本地生成的摘要不能太复杂，目标是“提示词”，而非“优美文章”。常用方法有：

1. 首尾句组合：抽取章节的第一句和最后一句。这通常能抓住章节的起承转合。
2. 高频词句提取：去除停用词后，计算词频，找出包含高频关键词的句子。
3. 文本分块与中心句：将章节文本按段落或固定长度分块，对每一块用简单的TextRank算法或只是选取最长/最短的句子来代表该块，然后组合。 在book-recall的实现中，为了极致轻量，可能采用了非常简洁的方法，比如选取章节开头的若干个字符（如前200字）作为“概要”。虽然粗糙，但在后续AI整合时，这些信息碎片足以作为触发详细记忆的线索。

3.4 索引的存储与结构设计

本地处理的结果需要被高效存储和读取。JSON是一个理想的选择，因为它人类可读、语言无关、且易于序列化。

book_data.json文件可能的结构如下：

{ "metadata": { "title": "斗破苍穹", "author": "天蚕土豆", "total_chapters": 1645, "language": "zh" }, "chapters": [ { "chapter_id": 1, "title": "第一章 陨落的天才", "raw_text": "这里是第一章的完整文本...", "index": { "characters": ["萧炎", "萧薰儿", "纳兰嫣然"], "locations": ["乌坦城", "萧家"], "summary": "天才少年萧炎斗气消失，沦为家族废柴，遭遇未婚妻纳兰嫣然登门退婚。" } }, // ... 其他章节 ] }

而book_index.json则是book_data.json的轻量化版本，可能只包含chapters[*].index部分，或者进一步压缩摘要，从而将体积减小到原文的19%左右。

4. 完整实操流程与配置详解

4.1 环境准备与依赖安装

首先，需要一个Python环境（3.10或以上）。建议使用虚拟环境来管理依赖。

# 创建并激活虚拟环境（可选但推荐） python3 -m venv venv_bookrecall source venv_bookrecall/bin/activate # Linux/macOS # venv_bookrecall\Scripts\activate # Windows # 安装核心Python依赖 pip install ebooklib beautifulsoup4 lxml # EPUB解析 # PDF解析库选择其一，pdfminer.six 更纯Python，PyMuPDF性能更好 pip install pdfminer.six # 或者 pip install PyMuPDF # 安装系统级依赖（用于PDF解析的poppler） # macOS (使用Homebrew) brew install poppler # Ubuntu/Debian sudo apt-get update sudo apt-get install poppler-utils # Windows: 可以从 poppler-for-windows 等网站下载二进制包，并将bin目录加入PATH。

4.2 第一步：解析书籍 (parse_book.py)

这个脚本负责将原始书籍文件“拆解”成结构化的章节数据。

python scripts/parse_book.py /path/to/你的小说.epub \ --output ./books/斗破苍穹/ \ --title "斗破苍穹" \ --author "天蚕土豆"

参数解析：

• 输入文件：EPUB, PDF, TXT 格式的书籍路径。
• --output：指定一个目录来存放输出结果。脚本会在这个目录下创建book_data.json。
• --title/--author：手动指定书籍元数据。如果文件内嵌了元数据，脚本会优先使用内嵌的，这些参数用于覆盖或补充。

内部过程与调试：脚本运行时会打印日志，显示如“发现XX个章节”、“正在解析第X章...”等信息。如果章节分割结果不理想，你需要查看脚本中关于章节分割的正则表达式或逻辑，并可能需要针对你的书籍格式进行调整。一个实用的调试方法是，修改脚本，让它将分割后的每个章节标题和开头几行文本输出到一个临时文件，方便你人工检查分割点是否正确。

4.3 第二步：构建本地索引 (build_index.py)

解析完成后，我们对book_data.json中的每一章文本运行实体提取和摘要生成算法。

python scripts/build_index.py ./books/斗破苍穹/book_data.json

这个脚本会：

1. 读取book_data.json。
2. 遍历每一个章节的raw_text。
3. 应用之前提到的中英文启发式规则，提取characters和locations。
4. 生成该章节的简单summary。
5. 将更新后的索引信息写回book_data.json（或单独保存到book_index.json）。

实操心得：首次运行时，务必检查索引生成的质量。可以写一个简单的预览脚本，随机抽查几个章节，打印出提取到的人物、地点和摘要，看看是否符合预期。例如，检查是否漏掉了重要角色，或者摘要是否完全不知所云。根据检查结果，你可能需要微调提取规则中的参数，比如中文人名识别的最小/最大长度，英文对话归因的正则表达式等。

4.4 第三步：请求AI回忆 (recall.py)

这是享受成果的时刻。假设你已经读到了第300章。

# 使用默认的OpenAI API (GPT模型) export OPENAI_API_KEY='你的-api-key' python scripts/recall.py ./books/斗破苍穹/book_data.json --chapter 300 # 如果你想使用Claude或其它模型，脚本可能支持 --api_type 和 --model 参数 python scripts/recall.py ./books/斗破苍穹/book_data.json --chapter 300 --api_type claude --model claude-3-haiku-20240307

脚本内部工作流：

1. 加载与过滤：读取book_data.json，严格只加载第1至第299章的index数据。
2. 提示词工程：这是核心步骤。脚本会将这299章的索引数据，组织成一个给AI的“任务说明书”。一个精心设计的提示词模板如下：

   你是一位专业的文学总结助手。请根据用户提供的、按时间顺序排列的章节索引信息，为他生成一份截至特定章节之前的、连贯且生动的剧情回顾。 索引信息如下： [章节1标题]: 人物：[A, B]， 地点：[X]， 概要：... [章节2标题]: 人物：[A, C]， 地点：[X, Y]， 概要：... ... (第3章到第298章) ... [章节299标题]: 人物：[A, D, E]， 地点：[Y, Z]， 概要：... 重要指令： 1. 你的回顾必须严格且仅基于以上索引信息。 2. 索引信息截止到第299章，你绝对不知道第300章及之后的任何内容。 3. 回顾需涵盖主要情节线、关键人物关系变化和重要事件。 4. 行文需流畅自然，像在讲述一个故事。 5. 严禁任何形式的推测、剧透或提及索引中未出现的信息。 现在，请生成截至第299章的剧情回顾：

3. 调用与输出：将组装好的提示词通过对应的API发送给大模型，接收并打印出模型生成的回顾文本。

5. 常见问题、排查技巧与高级用法

5.1 问题排查清单

5.2 性能优化与扩展思路

• 索引压缩策略：当书籍章节过多时，即使索引也会很大。可以在构建提示词时进行动态压缩。例如，只选择满足以下条件的章节索引加入提示词：1) 该章节出现了新人物；2) 该章节摘要中包含“战斗”、“突破”、“发现”等关键事件词；3) 每隔N章选取一章作为“里程碑”。这样可以大幅缩短提示词。
• 支持更多模型：项目默认可能只支持OpenAI API。你可以很容易地扩展recall.py，加入对 Anthropic Claude、Google Gemini 或开源模型（通过Ollama、LM Studio本地部署）的支持。关键在于抽象出一个统一的“AI Provider”接口。
• 图形化界面（GUI）：为普通用户开发一个简单的桌面应用，提供文件拖拽解析、进度条选择、回忆结果显示等功能，可以极大提升易用性。可以用PyQt或Tkinter实现。
• 增量更新索引：如果你读了一部分书，生成了索引，后来书更新了（比如网络小说连载了新章节）。理想情况下，应该能只对新章节进行解析和索引，然后合并到原有索引中，避免全量重处理。

5.3 安全与隐私考量

这是一个本地优先的工具，这是其最大的隐私优势。你的原始书籍文件、解析后的文本、生成的索引，都只存在于你的电脑上。只有在主动执行recall.py时，高度压缩和加工后的提示词才会被发送到你所选择的AI服务商（如OpenAI）的服务器。这意味着，AI服务商无法通过这段提示词还原出你的原始书籍内容，极大保护了阅读隐私。当然，选择可信的API服务商并了解其数据使用政策仍然是必要的。

从我个人的使用体验来看，book-recall这类工具真正解决了一个高频痛点。它将重度的AI计算从每次回忆请求中剥离，通过一次性的本地预处理，将成本分摊到近乎为零。虽然本地规则提取的精度有上限，但在“回忆剧情”这个场景下，配合大模型强大的上下文理解与整合能力，最终效果令人满意。它让我能够更从容地享受长篇作品的乐趣，不再害怕中断，也不再为遗忘而烦恼。如果你也是一个阅读爱好者，并且具备一些Python脚本能力，我强烈建议你尝试搭建并使用它，它很可能会改变你的阅读习惯。