全网网文爬虫与阅读管家

> 遇到问题？ 直接跳转 FAQ — 常见问题解答 | 报错速查表

概述

覆盖"发现→追更→下载→听书→清理"全链路的网文管理工具。当前搜索+追更+听书功能完整可用，下载/定时调度仍在完善中。

当前实际能做什么（诚实版）

| 你想要 | 能做到吗 | 怎么做 |

|--------|---------|--------|

| 在起点搜小说 | ✅ 没问题 | fuzzy-search -q "书名" |

| 知道某本书的URL，加入追更 | ✅ 没问题 | add-novel |

| 看我追了哪些书 | ✅ 没问题 | list |

| 把小说转成MP3听 | ✅ 大部分可以 | tts --book "书名"（国内可能需代理） |

| 下载整本小说到本地 | ⚠️ 部分可以 | 只能导出已爬取到的章节，不能自动抓全文 |

| 自动每天追更新章节 | 🔧 还不行 | 定时调度开发中，目前需手动执行 |

| 在番茄/晋江/飞卢搜书 | ⚠️ 需额外配置 | 需配合 web-access skill 用浏览器 |

工作原理（简单版）

搜索/URL → add-novel(记录书的元信息) → 数据库中有了书名/作者/URL
                                          ↓
                     TTS听书 ← 从起点实时获取章节文本 → download导出
                     (直接读取在线文本)              (从数据库导出已缓存的章节)

• add-novel 只是"记了个笔记"，不下载任何内容
• tts 听书时会实时从起点获取章节文本再转语音，所以只要 add-novel 成功就能用
• download 导出时读的是数据库里已缓存的章节，如果没缓存就导不出来

适用人群

• 追更多部连载小说的读者
• 喜欢睡前听书的用户
• 需要在手机/电脑/阅读器间同步阅读的用户
• 想整理自己小说书架的用户

对话式触发（自然语言示例）

对 AI 助手说以下任意一句即可触发：

| 你想做什么 | 直接说 |

|-----------|--------|

| 搜小说 | "帮我在起点搜一下修真小说"、"有没有类似凡人修仙传的书"、"搜一下系统流网文" |

| 追更 | "帮我追更剑来"、"下载某某小说的最新章节" |

| 听书 | "把凡人修仙传前10章转成MP3"、"睡前帮我把剑来转成有声书" |

| 整理 | "看看我收藏了哪些小说"、"清理一下已读完的小说缓存" |

| 统计 | "看一下我的阅读统计"、"我追了多少本书" |

能力总览

| 能力 | 说明 | 状态 | CLI命令 |

|------|------|------|---------|

| 模糊搜索 | 跨平台搜索（当前仅起点可用） | ✅ 起点可用 | fuzzy-search -q "修真 系统" |

| 添加追更 | 从小说URL添加到追踪列表 | ✅ 可用 | add-novel |

| 追更列表 | 查看/管理追更中的小说 | ✅ 可用 | list |

| 删除小说 | 从追更列表移除 | ✅ 可用 | remove --book 书名 |

| TTS听书 | edge-tts微软语音转MP3（国内可能需代理） | ✅ 可用 | tts --book 书名 --chapters 1-10 |

| 阅读统计 | 数据库查询，统计阅读进度 | ✅ 可用 | stats |

| EPUB/TXT导出 | 导出已有章节为电子书 | ⚠️ 仅导出已爬取章节 | download --book 书名 --format epub |

| 目录爬取 | 爬取书名/作者/简介/字数/状态 | 🔧 开发中 | crawl-catalog --full |

| 自动清理 | 已读/已听自动删除本地文件 | 🔧 开发中 | auto-delete --mode both |

| 每日调度 | 定时任务，每日自动追更 | 🔧 开发中 | schedule-daily --time 20:00 |

• ✅ 可用 — 功能完整，实际验证通过
• ⚠️ 受限 — 核心可用但有前置条件（如需先 add-novel，或搜索仅限起点）
• 🔧 开发中 — 框架已搭建，完整功能进行中

支持的平台

> 实测状态（2025-05）：8个平台中，当前仅起点中文网可直接搜索。番茄小说需CDP浏览器（配合 web-access skill），其余6个平台搜索接口已失效。通过 URL 添加追更（add-novel）的范围更广。

| 平台 | 域名 | 搜索 | 追更(URL添加) | 反爬等级 |

|------|------|------|-------------|---------|

| 起点中文网 | m.qidian.com | ✅ 可用 | ✅ 可用 | ⭐⭐ |

| 番茄小说 | fanqienovel.com | ⚠️ 需CDP浏览器 | ⚠️ 需CDP | ⭐⭐⭐⭐ |

| 纵横中文网 | www.zongheng.com | ❌ 接口404 | 部分可访问 | ⭐⭐ |

| 晋江文学城 | www.jjwxc.net | ❌ 页面改版 | 部分可访问 | ⭐⭐ |

| 飞卢小说 | b.faloo.com | ❌ 接口404 | 需Cookie | ⭐⭐⭐ |

| SF轻小说 | book.sfacg.com | ❌ 域名失效 | 未知 | ⭐⭐ |

| 刺猬猫 | www.ciweimao.com | ❌ 接口404 | 需Cookie | ⭐⭐⭐ |

| QQ阅读 | book.qq.com | ❌ 接口404 | 部分可访问 | ⭐⭐ |

什么是CDP浏览器？为什么需要它？

番茄小说等平台的内容由 JavaScript 动态加载，普通爬虫拿不到数据，必须用真实浏览器访问。"CDP 浏览器"就是这个用途。你只需要求 AI 助手「搭配 web-access skill 帮我在番茄小说搜索《xxx》」，无需自己安装任何东西。

快速开始

安装依赖

最少依赖（搜索+追更+统计）：

pip install requests beautifulsoup4 lxml

按需追加：

pip install edge-tts    # 听书功能
pip install ebooklib    # EPUB导出

一键全装：

pip install requests beautifulsoup4 lxml ebooklib edge-tts

检查哪些功能可用：

from importlib import util as _u
checks = {
    "核心(requests)": _u.find_spec("requests"),
    "搜索(bs4+lxml)": _u.find_spec("bs4"),
    "TTS(edge-tts)": _u.find_spec("edge_tts"),
    "EPUB(ebooklib)": _u.find_spec("ebooklib"),
}
for name, ok in checks.items():
    print(f"  {'✅' if ok else '❌'} {name}")

基本使用

# 1. 模糊搜索发现小说
python scripts/novel_scraper.py fuzzy-search -q "凡人修仙传"

# 2. 添加目标小说到追踪列表
python scripts/novel_scraper.py add-novel "https://www.qidian.com/info/1010215264"

# 3. TTS 转音频（睡前听书）
python scripts/novel_scraper.py tts --book "剑来" --chapters 1-10

# 4. 查看阅读统计
python scripts/novel_scraper.py stats

完整使用流程示例

> 从零开始，走一遍"搜书→追更→听书"的完整流程。

场景：我想找本修仙小说来听

第1步：搜索小说

python scripts/novel_scraper.py fuzzy-search -q "修仙 系统"

输出：

搜索结果（起点中文网）:
  ⭐⭐⭐⭐⭐ 凡人修仙传 (忘语) - 经典修仙
  ⭐⭐⭐⭐   修仙归来在都市 (XX) - 都市修仙
  ⭐⭐⭐     系统逼我做皇帝 (XX) - 系统流

第2步：把想看的书加入追更

# 先去起点网站复制该书的URL，然后：
python scripts/novel_scraper.py add-novel "https://www.qidian.com/info/1010841692/"

输出：

✅ 已添加: 凡人修仙传 (忘语)
   平台: 起点中文网 | 总章节: 2446章

第3步：确认添加成功

python scripts/novel_scraper.py list

输出：

追更列表 (1本):
  凡人修仙传 - 忘语 - 起点 - 2446章

第4步：转成MP3听书

python scripts/novel_scraper.py tts --book "凡人修仙传" --chapters 1-10

输出：

正在生成音频: 凡人修仙传 第1-10章
  ✅ 第1章 已生成 (2.3MB)
  ✅ 第2章 已生成 (1.8MB)
  ...
音频保存在: ~/Novels/凡人修仙传/audio/

第5步：睡前听

在手机/播放器中打开 ~/Novels/凡人修仙传/audio/ 目录，按顺序播放即可。

常见组合操作

| 我想... | 命令组合 |

|---------|---------|

| 搜书+加入+听书 | fuzzy-search → add-novel → tts |

| 看我追了什么+听了多少 | list + stats |

| 不想追了，删掉 | remove --book "书名" |

| 导出成TXT放到阅读器 | download --book "书名" --format txt |

详细功能

1. 模糊搜索（全网发现）

> ⚠️ 当前搜索受平台限制：8个平台中7个搜索接口已失效（见上方平台状态表）。推荐直接用 add-novel 添加已知小说，或配合 web-access skill 搜索番茄小说。

基础用法见"快速开始"，以下是高级参数：

# 多关键词搜索（空格分隔）
python scripts/novel_scraper.py fuzzy-search -q "修真 穿越 系统"

# JSON格式输出（方便程序处理）
python scripts/novel_scraper.py fuzzy-search -q "凡人" --format json

# 精简输出（只显示书名+作者）
python scripts/novel_scraper.py fuzzy-search -q "重生" --format simple

评分机制：书名匹配 50% + 简介匹配 40% + 作者匹配 10%，按相关度（1-5星）降序排列，跨平台重复结果自动去重。

容错机制：单个平台请求失败不影响其他平台，底部会汇总跳过原因及操作建议。

2. 目录管理

首次全量爬取所有目标小说信息 → 输出 catalog.xlsx，后续仅增量更新。

> 当前仅起点中文网、纵横中文网的详情页解析可用。crawl-log 表用于记录爬取历史。

3. 批量下载（EPUB/TXT）

> 重要：download 命令不是自动抓取全书，而是把数据库中已有的章节导出为文件。你需要先通过其他方式把章节内容存入数据库。

# 导出为EPUB（推荐，手机/平板/阅读器通用）
python scripts/novel_scraper.py download --book "凡人修仙传" --format epub

# 导出为TXT（纯文本，任何设备可读）
python scripts/novel_scraper.py download --book "凡人修仙传" --format txt

输出目录：~/Novels/<书名>/

预期输出：

导出 EPUB: 凡人修仙传
  找到 5 条章节记录
  ✅ 已生成: ~/Novels/凡人修仙传/凡人修仙传.epub (2.1MB)

如果看到"找到 0 条章节记录"，说明数据库中还没有该书的章节内容。add-novel 只记录书的元信息（书名/作者/URL），不下载章节。

4. TTS语音转音频

使用微软 edge-tts 引擎（AI神经语音，中文最自然的免费方案）。

# 可用中文语音
edge-tts --list-voices | grep zh-CN
# zh-CN-XiaoxiaoNeural  女声（推荐）
# zh-CN-YunxiNeural     男声
# zh-CN-XiaoyiNeural    女声 情感丰富

# 转换指定章节
python scripts/novel_scraper.py tts --book "剑来" --chapters 1-10

# 合并为单个文件（连续播放）
python scripts/novel_scraper.py tts --book "剑来" --chapters 1-10 --merge

> 国内网络注意：edge-tts 依赖微软云服务 speech.microsoft.com，国内连接可能不稳定。

>

> 解决方案（按推荐顺序）：

> 1. 设置代理：set HTTPS_PROXY=http://127.0.0.1:7890（Windows）或 export HTTPS_PROXY=...（Mac/Linux）

> 2. 换用本地 TTS（无需联网）：pip install pyttsx3 — 用系统自带语音引擎，质量一般但离线可用

> 3. 手动生成：用浏览器打开 Azure TTS 在线演示 手动粘贴文本生成音频

5. 阅读统计

python scripts/novel_scraper.py stats

预期输出：

阅读统计:
  追更小说: 3 本
  已读章节: 42 章
  已听章节: 15 章
  生成音频: 23 个 (45.2MB)

6. 代码集成（Python 调用）

如果你需要在自己的脚本中调用本 skill 的功能：

import subprocess, json

def run_cmd(args):
    """调用 novel_scraper CLI，返回 stdout"""
    result = subprocess.run(
        ["python", "scripts/novel_scraper.py"] + args,
        capture_output=True, text=True, cwd="D:/claude 开发/skill of me/web-novel-scraper"
    )
    if result.returncode != 0:
        raise RuntimeError(result.stderr.strip())
    return result.stdout

# 搜索小说
output = run_cmd(["fuzzy-search", "-q", "修真", "--format", "json"])
results = json.loads(output)
for book in results[:3]:
    print(f"{book.get('title')} - {book.get('author')}")

# 添加追更
run_cmd(["add-novel", "https://www.qidian.com/info/1010215264"])

# TTS 转音频
run_cmd(["tts", "--book", "剑来", "--chapters", "1-5"])

# 查看追更列表
print(run_cmd(["list"]))

数据库结构

SQLite data/novels.db：

| 表名 | 用途 | 关键字段 |

|------|------|---------|

| novels | 小说主表 | title, author, platform, status, total_chapters |

| chapters | 章节表 | novel_id, title, chapter_num, is_read, is_listened |

| settings | 配置项 | key, value |

> 数据库文件：data/novels.db

FAQ — 常见问题解答

出了问题？按这个顺序排查

功能不正常
  │
  ├─ 看到报错信息？
  │    ├─ 是 → 在下方"报错速查表"中查找对应行
  │    └─ 否（空白/无输出）→ 检查命令拼写，运行不带参数看帮助
  │
  ├─ 依赖问题？
  │    ├─ ModuleNotFoundError → 运行依赖诊断脚本（见"快速开始"）
  │    └─ 装了还是报错 → 确认 Python 环境一致（python vs python3）
  │
  ├─ 网络问题？
  │    ├─ TTS失败 → 设代理或换 pyttsx3
  │    ├─ 搜索0结果 → 只用起点搜索，或用 web-access
  │    └─ 连接超时 → 检查网络，关VPN，稍后重试
  │
  └─ 功能不存在？
       ├─ 标记"🔧 开发中" → 该功能暂不可用，等待后续版本
       └─ 标记"⚠️ 受限" → 看上方平台状态表确认前置条件

搜索相关

Q: 为什么搜索返回 0 条结果？

A: 三层原因：

1. 平台自身问题（最常见）：晋江/飞卢/纵横等6个平台搜索接口已失效；番茄小说需要CDP浏览器；仅起点中文网可直接搜索。
2. 网络问题：国内访问部分平台 DNS 不稳定，可尝试切换网络。
3. 关键词问题：用更通用的词，减少关键词数量。

解决方案：搭配 web-access skill 用浏览器搜索，或直接用 add-novel 添加。

Q: 什么是 CDP 浏览器？我需要安装什么吗？

A: 就是"用程序控制真实浏览器访问网页"。番茄小说等平台数据靠 JavaScript 动态加载，普通爬虫拿不到。你不需要额外安装，本 skill 会配合 web-access skill 自动处理。安装 web-access skill 即可。

TTS 听书相关

Q: 为什么 TTS 生成失败？

A: edge-tts 依赖微软云服务 speech.microsoft.com。排查步骤：

1. 确认依赖已装：pip install edge-tts
2. 国内网络：可能需要代理，设置 HTTPS_PROXY=http://127.0.0.1:7890
3. 如果不想用代理：换用离线方案 pip install pyttsx3（质量一般但不联网）

Q: TTS 报错 "ConnectionError" 或长时间无响应？

A: 国内直连微软云不稳定。设代理或换 pyttsx3。

Q: TTS 报错全是英文看不懂？

A: 常见英文报错翻译：

• No such file or directory → 文件路径不对，检查书名和路径
• Connection refused → 网络不通，检查代理或网络
• Timeout → 连接超时，微软云响应慢，稍后重试

Q: TTS 生成的MP3音质怎么样？

A: edge-tts 是微软 AI 神经语音，中文自然度很好（推荐 zh-CN-XiaoxiaoNeural 女声）。pyttsx3 离线方案音质偏机械，但不依赖网络。

下载/导出相关（功能限制说明）

Q: 下载说完成了但只下了几章？

A: 这是当前版本的已知限制。"下载"命令只能导出已经爬取到本地数据库中的章节，不能自动抓取全书。流程是：

1. add-novel 添加小说（此时只记录元信息，不下载章节）
2. 章节内容需要通过其他方式获取后存入数据库
3. download 导出数据库中已有的章节

> 完整的"自动抓取全书章节→导出"功能正在开发中。目前如果你想导出，需要确保章节内容已存在于数据库。

Q: EPUB 生成失败？

A: 两个可能：

1. ebooklib 未安装 → pip install ebooklib
2. 章节内容为空 → 当前版本章节下载功能开发中，需先获取章节内容再生成

Q: 导出的TXT/EPUB文件在哪？

A: 输出目录是 ~/Novels/<书名>/。如果找不到，检查当前用户目录下是否有 Novels 文件夹。

Q: 自动追更/定时更新能用吗？

A: 定时调度（schedule-daily）功能仍在开发中。当前需手动执行命令追更。想追更新章节，需要重新运行搜索或手动检查。

追更管理相关

Q: 怎么确认小说已经成功添加到追更？

A: 运行 python scripts/novel_scraper.py list，如果列表里出现了你要的书就说明添加成功了。

Q: add-novel 报错怎么办？

A: 常见原因：

• URL 格式不对 → 确认是从浏览器地址栏复制的完整链接
• 该平台不支持 → 参考上方"支持的平台"表，只有部分平台的URL可以添加
• 网络超时 → 检查网络后重试

Q: 我追了10本书，怎么批量管理？

A: 目前只能逐本操作：

• list 查看全部
• remove --book "书名" 逐本删除
• stats 查看整体统计

批量管理功能在后续版本规划中。

平台/环境相关

Q: 为什么很多平台显示"不可用"？

A: 网文平台频繁更新反爬机制。搜索接口下线（404）、反爬增强（验证码）、页面改版（解析失效）都属于爬虫工具的正常情况。当前最可靠方案是搭配 web-access skill 通过浏览器操作。

Q: 提示 'No module named X'？

A: 运行 pip install requests beautifulsoup4 lxml ebooklib edge-tts 安装全部依赖。

Q: Windows 上提示 "python3 不是命令"？

A: Windows 用 python 而非 python3，把命令中的 python3 替换为 python。

Q: 运行没有任何输出/直接退出了？

A: 可能原因：

1. 命令写错了 → 检查拼写，运行不带参数的命令看帮助信息
2. Python环境问题 → 确认 python --version 能正常输出
3. 脚本路径不对 → 确认在正确的目录下运行

报错速查表

| 报错信息 | 原因 | 解决 |

|---------|------|------|

| ModuleNotFoundError: requests | 核心依赖未装 | pip install requests beautifulsoup4 lxml |

| ModuleNotFoundError: edge-tts | TTS依赖未装 | pip install edge-tts |

| ModuleNotFoundError: ebooklib | EPUB依赖未装 | pip install ebooklib |

| ConnectionError / Timeout | 网络不通 | 检查网络，TTS需代理 |

| FileNotFoundError | 文件/书名路径错 | 检查书名是否正确 |

| python3: command not found | Windows无python3命令 | 用 python 替代 |

| 搜索返回0条结果 | 平台接口失效 | 用起点搜索或web-access |

| No such book in database | 小说未添加到追更 | 先执行 add-novel |

| 运行无任何输出 | 命令写错/环境问题 | 检查命令拼写和Python环境 |

| TTS生成但没声音 | MP3路径找不到 | 检查 ~/Novels/<书名>/audio/ |

容错机制说明

了解工具在出问题时的行为，避免困惑：

| 场景 | 工具行为 | 你需要做的 |

|------|---------|-----------|

| 搜索时某个平台挂了 | 自动跳过，继续搜其他平台 | 底部会显示跳过的平台和原因 |

| TTS连不上微软云 | 报错并停止 | 设代理或换 pyttsx3 |

| add-novel URL不支持 | 提示平台不支持 | 换支持的平台URL |

| download时没章节数据 | 导出空文件或报错 | 先确认章节内容已存在 |

注意事项

| 项目 | 说明 |

|------|------|

| 版权 | 仅爬取免费/试读章节，VIP章节需平台授权 |

| 反爬 | 建议搭配 web-access skill 的CDP浏览器使用，尤其在搜索番茄小说等 JS 渲染平台时 |

| 磁盘 | 长篇小说音频可达数百MB，注意空间 |

| TTS耗时 | 1小时文本约20-30分钟生成 |

| 频率 | 建议每日1次，避免被封IP |