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 列表相关工具！ ## 使用方法 ### 核心命令 ```bash python3 read_novel.py <小说文件路径> [--start <起始位置>] ``` ### 参数说明 | 参数 | 说明 | 示例 | |------|------|------| | `<小说文件路径>` | 小说文件的路径（必填），支持 TXT、PDF、DOC、DOCX 格式。如果是 PDF/DOC/DOCX 格式，先使用 doc-to-txt skill 转换为 TXT | `test-files/novel.txt` 或 `test-files/novel.pdf` | | `--info` | 获取小说信息（总字符数、总行数、非空行数） | `--info` | | `--start` | 起始位置（字符索引，从 0 开始，默认：0，可选） | `--start 10000` | ### 示例 获取小说信息： ```bash python3 read_novel.py ./novel.txt --info ``` 读取小说从头开始的 3000 个字符（使用默认参数）： ```bash python3 read_novel.py ./novel.txt --start 0 ``` 读取小说从第 3000 个字符开始的 3000 个字符（仅指定 start）： ```bash python3 read_novel.py ./novel.txt --start 3000 ``` 查看帮助： ```bash python3 read_novel.py --help ``` ### 工作流 **完整工作流分为三个阶段：文件格式处理 → 初始化 → 循环读取 → 完成总结** #### 前置步骤：文件格式处理 - 检查输入文件格式 - 如果是 PDF、DOC、DOCX 格式，先使用 doc-to-txt skill 转换为 TXT 纯文本格式 - 转换完成后，使用转换后的 TXT 文件进行后续操作 #### 阶段一：初始化（仅需一次） **步骤 1：获取小说信息** ```bash 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 个 #### 关键规则 | 规则 | 说明 | |------|------| | **严禁边读边分析** | 每读完一个片段就分析更新是错误的做法 | | **必须批量读取** | 10 个片段全部读完后再统一分析更新 | | **支持断点续读** | 通过读取进度.txt 实现中断后继续 | | **进度计算** | 每次循环读取 30000 字符（10 × 3000）| ## 资产抽取 ### 智能内容过滤 通过执行 Python 脚本读取小说内容后，让大模型读懂内容，自动识别并忽略与小说正文无关的内容，只保留小说的正文章节内容进行分析和资产抽取。不使用任何规则或正则表达式进行过滤，完全依赖大模型的理解能力。 ### 实时资产抽取 每读取一段内容（不超过 3000 字符），立即从中识别并抽取新出现的资产（角色、道具、场景），并实时更新对应的文件。不要等到全部读完再更新。大模型会充分利用上下文 compact 机制，在快用完上下文时自动压缩。 ### 抽取元素 从每段读取的内容中，识别并抽取以下三类资产，尽可能收集详细信息： 1. **角色** - 小说中出现的人物，包括： - 基本信息：姓名、年龄、性别、身份、角色定位（主角/配角/反派/男二/女二等） - 外貌特征：容貌、身高、体型、着装 - **音色特征**：根据角色性格和身份推断音色特点（如"低厚温润中年男声""清冽有力少女音""沙哑低沉老年女声"），下游用于 Seedance 音色锚定 - 性格特点：口头禅、习惯性动作、行为模式 - 背景关系：家庭、朋友、敌人、师承 - 能力修为：实力等级、特殊能力、武器装备 - 出场情节：首次出场、重要事件 - **妆造变化**：如果角色在不同场景/剧情阶段更换了服装、发型、妆容或配饰，必须记录每种不同的妆造，包括：出现的场号/集数、具体的外观变化描述（服装款式/颜色、发型变化、妆容变化、新增或移除的配饰）。每种妆造都需要在下游单独生成参考图和音色参考视频 2. **道具** - 小说中出现的物品、法宝、武器等，包括： - 基本信息：名称、类型、来源 - **外观特征（视觉细节）**：形状、颜色、材质、大小、**独特标记/纹样/装饰**。描述必须足够详细，能据此生成一张道具参考图（如："黑色塑料外壳U盘，小巧扁平约5cm长，正面印有银色条纹，USB-A金属接口"而非"一个U盘"） - 功能特性：特殊能力、使用方法、效果 - 历史背景：来历、前任主人、重要事件 - 相关角色：拥有者、使用者、争夺者 3. **场景** - 小说中出现的地点、环境、场所等，包括： - 基本信息：名称、类型、地理位置 - **环境特征（视觉细节）**：地形、气候、建筑风格、氛围、**关键物品的空间布局**。描述必须足够详细，能据此生成一张场景参考图和一段360度旋转视频（如："现代高端医院VIP病房，单人间，左侧靠墙放置白色电动病床，床头挂心电监护仪，右侧有木质床头柜和落地窗，门在正对面"而非"医院病房"） - 功能用途：居住、修炼、交易、战斗 - 相关势力：所属势力、管理者、常驻人物 - 重要事件：发生过的关键情节 ### 目录结构 在小说文件所在目录下创建以下结构： ``` 小说名或项目名/ ├── 大纲.txt ├── 读取进度.txt ├── 角色/ │ ├── <角色名1>.txt │ ├── <角色名2>.txt │ └── ... ├── 道具/ │ ├── <道具名1>.txt │ ├── <道具名2>.txt │ └── ... └── 场景/ ├── <场景名1>.txt ├── <场景名2>.txt └── ... ``` ### 文件内容格式 #### 大纲.txt ``` 1. <第一段内容的摘要> 2. <第二段内容的摘要> ... ``` **说明**： - 按小说内容的逻辑分段添加摘要，不按固定字数分段 - 大模型根据内容自然决定何时添加新的摘要条目 - 每条摘要用序号标识，按阅读顺序排列 - 只记录小说正文内容的摘要，跳过无关内容 - 跳过小说中与正文无关的内容，如上架感言、作者感谢、访谈、广告等 #### 读取进度.txt ``` 当前位置: <字符索引> 已读字数: <数字> 总字数: <数字> 进度: <百分比>% ``` #### 角色文件（角色/<角色名>.txt） 每个角色文件包含该角色的详细描述，参考格式如下： ``` <角色名称> 【基本信息】 姓名： 年龄： 性别： 身份： 角色定位： 【外貌特征】 容貌： 身高： 体型： 着装： 【音色特征】 音色描述：（如"低厚温润中年男声""清冽有力少女音"，用于下游 Seedance 音色锚定） 【性格特点】 性格： 口头禅： 习惯性动作： 行为模式： 【背景关系】 家庭： 朋友： 敌人： 师承： 【能力修为】 实力等级： 特殊能力： 武器装备： 【出场情节】 首次出场： 【妆造变化】（如有） - 妆造1（默认）：[出现集数/场号] [服装/发型/妆容/配饰描述] - 妆造2（[造型名称]）：[出现集数/场号] [服装/发型/妆容/配饰变化描述] - ... （每种妆造需在下游单独生成面部特写+全身像+音色参考视频） ``` #### 道具文件（道具/<道具名>.txt） 每个道具文件包含该道具的详细描述，参考格式如下： ``` <道具名称> 【基本信息】 名称： 类型： 来源： 【外观特征（视觉细节，需足够详细以生成参考图）】 形状： 颜色： 材质： 大小： 独特标记/纹样/装饰： 整体外观描述（一句话，可直接作为图像生成 prompt 输入）： 【功能特性】 特殊能力： 使用方法： 效果： 【历史背景】 来历： 重要事件： 【相关角色】 拥有者： 使用者： 争夺者： ``` #### 场景文件（场景/<场景名>.txt） 每个场景文件包含该场景的详细描述，参考格式如下： ``` <场景名称> 【基本信息】 名称： 类型： 地理位置： 【环境特征（视觉细节，需足够详细以生成参考图和360度视频）】 地形： 气候： 建筑风格： 氛围： 关键物品空间布局：（如"左侧靠墙放置病床，床头挂监护仪，右侧有床头柜和落地窗，门在正对面"） 整体环境描述（一句话，可直接作为图像生成 prompt 输入）： 【功能用途】 居住： 修炼： 交易： 战斗： 【相关势力】 所属势力： 管理者： 常驻人物： 【重要事件】 发生过的关键情节： ``` ### 抽取规则 1. **去重**：如果资产文件已存在，只需追加新的信息，不要重复创建 2. **准确性**：确保抽取的资产名称准确，避免错别字 3. **完整性**：尽可能记录资产的所有相关信息，使用上述详细格式 4. **自然语言**：使用自然语言描述，让大模型理解抽取需求 5. **内容过滤**：在抽取资产前，先过滤掉无关内容，只从正文中抽取 6. **实时更新**：每读取一段内容（不超过 3000 字符），立即识别并抽取新出现的资产，不要等全部读完再更新 7. **不使用规则/正则**：完全通过执行 Python 脚本获取内容，让大模型自己理解和分析，不使用任何规则或正则表达式进行匹配 8. **重要性筛选**：只记录重要的资产，不重要的角色、场景、道具可以忽略跳过。判断标准包括： - **角色**：对剧情有推动作用的主要角色、关键配角、重要反派等；路人、龙套、一次性出现的次要角色可忽略 - **道具**：对剧情有关键作用的法宝、武器、重要物品；普通物品、一次性道具可忽略 - **场景**：故事发生的主要地点、重要场所；临时场景、一笔带过的地点可忽略 ## 技巧提示 1. **获取文件总字符数**： ```bash 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 - ✅ **语法简单**：一个模式搞定所有场景