Novel Reader

Novel Reader - 智能长文本小说阅读器

使用 Python 安全、可靠地读取长文本小说，解决 LLM 上下文窗口有限的问题。完美支持 UTF-8 编码的中文小说。自动过滤无关内容，实时抽取详细的角色、道具、场景信息。

核心功能

• 多格式支持：如果输入文件是 PDF、DOC、DOCX 格式，先使用 doc-to-txt skill 转换为 TXT 纯文本格式，然后读取转换后的 TXT 文件
• 按字符位置读取：使用 Python 按字符位置精确读取，不会出现乱码
• 分段读取：每次读取最多 3000 字符，默认值为 3000 字符，避免超出工具输出限制。严禁跳读，必须连续逐段读取
• 灵活定位：可从任意位置开始读取
• 编码安全：原生支持 UTF-8 编码，正确处理中文字符
• 智能内容过滤：通过大模型自动识别并跳过小说中与正文无关的内容（上架感言、作者感谢、访谈、广告等）
• 实时资产抽取：每读取一段内容，立即识别并记录小说中的角色、道具、场景的详细信息
• 大纲记录：记录每段内容的摘要，形成完整大纲
• 进度追踪：记录当前阅读位置、已读字数等进度信息
• 上下文管理：充分利用 Agent 的上下文 compact 机制，在上下文快用完时自动压缩

重要要求

严禁跳读

• 必须连续逐段读取：每次读取 3000 字符后，下一次必须从当前结束位置继续读取（即 start = 上次的 start + 3000）
• 禁止跳读：绝对不允许跳过中间内容直接跳到后面的位置
• 绝对禁止 for 循环读取：严禁使用 for 循环批量读取文件（如 for i in $(seq ...)），因为 Agent 工具会对输出进行压缩，for 循环会导致内容被截断，当你看到 (some characters truncated) 表示内容已经被截断，你只能手动重新一段一段读取。
• 禁止一个命令多次调用 python 脚本：每个工具只能输出 3000 字，超出的内容会被截断，一次 tool call 最多只能调用一次 python 命令！
• 提升效率：因为要读取超长文本，你可以连续调用读取工具脚本（但不能用 for 循环），中间不思考也不说话。
• 更新循环：每读取 10 个小说片段（每次 3000 字符，共 30000 字符），就更新一次大纲、进度、资产文件，继续下一个循环。
• 禁止预设任务：禁止使用 TODO 列表，Task 列表相关工具！

使用方法

核心命令

python3 read_novel.py <小说文件路径> [--start <起始位置>]

参数说明

示例

获取小说信息：

python3 read_novel.py ./novel.txt --info

读取小说从头开始的 3000 个字符（使用默认参数）：

python3 read_novel.py ./novel.txt --start 0

读取小说从第 3000 个字符开始的 3000 个字符（仅指定 start）：

python3 read_novel.py ./novel.txt --start 3000

查看帮助：

python3 read_novel.py --help

工作流

完整工作流分为三个阶段：文件格式处理 → 初始化 → 循环读取 → 完成总结

前置步骤：文件格式处理

• 检查输入文件格式
• 如果是 PDF、DOC、DOCX 格式，先使用 doc-to-txt skill 转换为 TXT 纯文本格式
• 转换完成后，使用转换后的 TXT 文件进行后续操作

阶段一：初始化（仅需一次）

步骤 1：获取小说信息

python3 read_novel.py novel.txt --info

输出示例：

总字符数: 5512508
总行数: 158108
非空行数: 79053

步骤 2：检查读取进度

• 检查是否存在 读取进度.txt 文件
• 如果存在：读取当前位置，从该位置继续（断点续读）
• 如果不存在：从位置 0 开始全新读取

阶段二：循环读取（核心阶段）

每个循环读取 10 个片段（共 30000 字符），分为两个子阶段：

子阶段 A：批量读取（连续执行，中间不分析）

连续调用 10 次读取命令，每次读取 3000 字符：

• 第 1 次：--start <当前位置>
• 第 2 次：--start <当前位置+3000>
• ...
• 第 10 次：--start <当前位置+27000>

示例（从 0 开始的第一个循环）：

读取片段 1：--start 0
读取片段 2：--start 3000
...
读取片段 10：--start 27000

示例（从 60000 开始的第三个循环）：

读取片段 21：--start 60000
读取片段 22：--start 63000
...
读取片段 30：--start 87000

⚠️ 关键规则：10 次读取必须连续执行，中间不分析、不总结、不更新文件

子阶段 B：分析更新（读完 10 个片段后执行）

1. 分析这 10 个片段的内容 2. 更新 大纲.txt：添加这 10 个片段的章节摘要 3. 更新 读取进度.txt：记录当前位置（如 30000） 4. 创建或更新资产文件：提取新出现的角色、道具、场景

子阶段 C：判断是否继续

• 计算已读进度（已读字数/总字数）
• 如果未达到用户要求（如"读 5%"）：回到子阶段 A，继续下一批 10 个片段
• 如果已达到用户要求：进入阶段三

阶段三：完成总结

• 输出最终读取进度
• 总结已抽取的资产统计（角色数、道具数、场景数）

执行顺序示例

假设用户要求读取小说前 5%，小说文件是 novel.pdf：

前置步骤：文件格式处理

• 检查文件格式：.pdf
• 使用 doc-to-txt skill 将 novel.pdf 转换为 novel.txt
• 后续步骤使用 novel.txt 文件

步骤 1：初始化 1. 获取小说信息 → 总字数 5512508 2. 检查 读取进度.txt → 不存在，从位置 0 开始

步骤 2：循环读取

循环 1（片段 1-10，0-30000 字符）：

• 批量读取：连续执行 --start 0 到 --start 27000
• 分析更新：更新大纲、进度（30000）、资产
• 检查进度：30000/5512508 = 0.54%，未达到 5%，继续

循环 2（片段 11-20，30000-60000 字符）：

• 批量读取：连续执行 --start 30000 到 --start 57000
• 分析更新：更新大纲、进度（60000）、资产
• 检查进度：60000/5512508 = 1.09%，未达到 5%，继续

循环 3（片段 21-30，60000-90000 字符）：

• 批量读取：连续执行 --start 60000 到 --start 87000
• 分析更新：更新大纲、进度（90000）、资产
• 检查进度：90000/5512508 = 1.63%，未达到 5%，继续

... 继续循环 ...

循环 10（片段 91-100，270000-300000 字符）：

• 批量读取：连续执行 --start 270000 到 --start 297000
• 分析更新：更新大纲、进度（300000）、资产
• 检查进度：300000/5512508 = 5.44%，已达到 5%，停止

步骤 3：完成总结

• 输出最终进度：5.44%
• 统计资产：角色 X 个，道具 Y 个，场景 Z 个

关键规则

资产抽取

智能内容过滤

通过执行 Python 脚本读取小说内容后，让大模型读懂内容，自动识别并忽略与小说正文无关的内容，只保留小说的正文章节内容进行分析和资产抽取。不使用任何规则或正则表达式进行过滤，完全依赖大模型的理解能力。

实时资产抽取

每读取一段内容（不超过 3000 字符），立即从中识别并抽取新出现的资产（角色、道具、场景），并实时更新对应的文件。不要等到全部读完再更新。大模型会充分利用上下文 compact 机制，在快用完上下文时自动压缩。

抽取元素

从每段读取的内容中，识别并抽取以下三类资产，尽可能收集详细信息：

1. 角色 - 小说中出现的人物，包括：

• 基本信息：姓名、年龄、性别、身份、角色定位（主角/配角/反派/男二/女二等）
• 外貌特征：容貌、身高、体型、着装
• 性格特点：口头禅、习惯性动作、行为模式
• 背景关系：家庭、朋友、敌人、师承
• 能力修为：实力等级、特殊能力、武器装备
• 出场情节：首次出场、重要事件

2. 道具 - 小说中出现的物品、法宝、武器等，包括：

• 基本信息：名称、类型、来源
• 外观特征：形状、颜色、材质、大小
• 功能特性：特殊能力、使用方法、效果
• 历史背景：来历、前任主人、重要事件
• 相关角色：拥有者、使用者、争夺者

3. 场景 - 小说中出现的地点、环境、场所等，包括：

• 基本信息：名称、类型、地理位置
• 环境特征：地形、气候、建筑风格、氛围
• 功能用途：居住、修炼、交易、战斗
• 相关势力：所属势力、管理者、常驻人物
• 重要事件：发生过的关键情节

目录结构

在小说文件所在目录下创建以下结构：

小说名或项目名/
├── 大纲.txt
├── 读取进度.txt
├── 角色/
│   ├── <角色名1>.txt
│   ├── <角色名2>.txt
│   └── ...
├── 道具/
│   ├── <道具名1>.txt
│   ├── <道具名2>.txt
│   └── ...
└── 场景/
    ├── <场景名1>.txt
    ├── <场景名2>.txt
    └── ...

文件内容格式

大纲.txt

1. <第一段内容的摘要>

2. <第二段内容的摘要>

...

说明：

• 按小说内容的逻辑分段添加摘要，不按固定字数分段
• 大模型根据内容自然决定何时添加新的摘要条目
• 每条摘要用序号标识，按阅读顺序排列
• 只记录小说正文内容的摘要，跳过无关内容
• 跳过小说中与正文无关的内容，如上架感言、作者感谢、访谈、广告等

读取进度.txt

当前位置: <字符索引>
已读字数: <数字>
总字数: <数字>
进度: <百分比>%

角色文件（角色/<角色名>.txt）

每个角色文件包含该角色的详细描述，参考格式如下：

<角色名称>

【基本信息】
姓名：
年龄：
性别：
身份：
角色定位：

【外貌特征】
容貌：
身高：
体型：
着装：

【性格特点】
性格：
口头禅：
习惯性动作：
行为模式：

【背景关系】
家庭：
朋友：
敌人：
师承：

【能力修为】
实力等级：
特殊能力：
武器装备：

【出场情节】
首次出场：

道具文件（道具/<道具名>.txt）

每个道具文件包含该道具的详细描述，参考格式如下：

<道具名称>

【基本信息】
名称：
类型：
来源：

【外观特征】
形状：
颜色：
材质：
大小：

【功能特性】
特殊能力：
使用方法：
效果：

【历史背景】
来历：
重要事件：

【相关角色】
拥有者：
使用者：
争夺者：

场景文件（场景/<场景名>.txt）

每个场景文件包含该场景的详细描述，参考格式如下：

<场景名称>

【基本信息】
名称：
类型：
地理位置：

【环境特征】
地形：
气候：
建筑风格：
氛围：

【功能用途】
居住：
修炼：
交易：
战斗：

【相关势力】
所属势力：
管理者：
常驻人物：

【重要事件】
发生过的关键情节：

抽取规则

1. 去重：如果资产文件已存在，只需追加新的信息，不要重复创建 2. 准确性：确保抽取的资产名称准确，避免错别字 3. 完整性：尽可能记录资产的所有相关信息，使用上述详细格式 4. 自然语言：使用自然语言描述，让大模型理解抽取需求 5. 内容过滤：在抽取资产前，先过滤掉无关内容，只从正文中抽取 6. 实时更新：每读取一段内容（不超过 3000 字符），立即识别并抽取新出现的资产，不要等全部读完再更新 7. 不使用规则/正则：完全通过执行 Python 脚本获取内容，让大模型自己理解和分析，不使用任何规则或正则表达式进行匹配 8. 重要性筛选：只记录重要的资产，不重要的角色、场景、道具可以忽略跳过。判断标准包括：

• 角色：对剧情有推动作用的主要角色、关键配角、重要反派等；路人、龙套、一次性出现的次要角色可忽略
• 道具：对剧情有关键作用的法宝、武器、重要物品；普通物品、一次性道具可忽略
• 场景：故事发生的主要地点、重要场所；临时场景、一笔带过的地点可忽略

技巧提示

1. 获取文件总字符数：

python3 -c "
with open('test-files/novel.txt', 'r', encoding='utf-8', errors='replace') as f:
    print(len(f.read()))
"

2. 读取分段：每次读取最多 3000 字符，默认值为 3000 字符，避免超出工具输出限制

3. 上下文管理：大模型通常有 128k 上下文窗口，Agent 会在快用完上下文时自动压缩，请合理利用

为什么用 Python？

• ✅ 编码安全：原生支持 UTF-8，不会出现乱码
• ✅ 按字符读取：不是按字节，正确处理中文字符（每个中文字符算 1 个）
• ✅ 跨平台：Windows/Mac/Linux 都一样
• ✅ 系统预装：几乎所有现代系统都预装了 Python 3
• ✅ 语法简单：一个模式搞定所有场景

Novel Reader - 智能长文本小说阅读器

智能读取和分析长文本小说，解决 LLM 上下文窗口有限的问题。

功能特性

• 📖 分段读取：每次读取固定字数或按章节分段，避免超出上下文窗口限制
• 📝 智能摘要：每读完一章生成一句话摘要，维护整体大纲和前情提要
• 📊 进度追踪：记录阅读百分比、已读字数、总字数
• 🎯 资产管理：自动识别并记录新出现的角色、道具、场景，更新资产信息

安装

无需特殊依赖，只需要 Python 3.6+。

chmod +x scripts/novel_reader.py

使用方法

基本用法

python scripts/novel_reader.py /path/to/novel.txt

命令行参数

• --chunk-size - 每次读取的字数（默认：5000）
• --chapter-detector - 章节检测模式（regex 或 heuristic，默认：regex）
• --force-restart - 强制重新开始阅读，忽略已保存的进度

示例

1. 开始阅读一本小说：

python scripts/novel_reader.py /Users/bytedance/books/my_novel.txt

2. 自定义每次读取的字数：

python scripts/novel_reader.py /Users/bytedance/books/my_novel.txt --chunk-size 8000

3. 强制重新开始：

python scripts/novel_reader.py /Users/bytedance/books/my_novel.txt --force-restart

数据文件

脚本会在小说目录下自动创建以下文件：

• {小说名}_outline.md - 整体大纲，包含每章摘要
• {小说名}_progress.json - 阅读进展，包含前情提要和进度统计
• {小说名}_assets.json - 资产信息，包含角色、道具、场景

工作原理

1. 从上次中断的位置继续阅读 2. 读取固定字数或检测到下一章标题时停止 3. 生成当前章节的一句话摘要 4. 提取并记录新出现的角色、道具、场景 5. 更新阅读进度、大纲和资产信息 6. 显示当前阅读状态和内容预览

章节检测

支持两种章节检测模式：

• regex：使用正则表达式匹配常见的章节标题格式（中文和英文）
• heuristic：启发式检测（待实现）

支持的章节标题格式

中文格式

• 第一章、第二回、第三卷、第四部、第五篇
• 第6集、第7幕、第8话、第9节
• 第一百二十章、第三千零五十回
• 第1章：标题、第2回 - 标题
• 【第一章】标题、[第二章] 标题
• 第3章（支持前导空格）

英文格式

• Chapter 1、CHAPTER 2、Chapter Three
• Ep. 3、Episode 4、EPISODE 5
• Part 6、PART 7、Act 8、ACT 9
• Scene 10、SCENE 11

数字格式

• 1. 标题、2) 标题、3、标题

许可证

MIT