书海捞针 howIdobetter/novel-pirate

novel-pirate

给 AI 智能体用的网络小说检索 / 抓取 / 整理技能：一个书名进，一个 EPUB 出。

不是「再写一个爬虫脚本」，而是把「哪儿有源、怎么判断这本是不是我要的那本、抓下来怎么排、正文怎么洗」这套实战知识，连同 5.9k 行可跑代码一起打包成技能。

- 适配：Claude Code / DeepSeek Harness / Codex 的 skills 目录（SKILL.md 是入口）
- 纯 Python：requests + beautifulsoup4 + lxml + Pillow，无浏览器依赖
- 正文清洗可外包给 codex 的 gpt-6-luna，主智能体上下文只收统计量

书名 ──► 检索(多引擎/多模板) ──► 打分+书名核对 ──► 目录(全本追踪) ──► 逐章抓取 │ EPUB3 + 封面 + TXT ◄── 清洗(正则/luna) ◄── 体检(audit) ◄┘

它解决什么

| 难处 | 这个仓库的做法 |
| 不知道去哪找 | references/sources.md：8 层来源清单 + 94 个域名活体核验表（哪活哪死、为什么死） |
| 搜到的不是这本书 | 目录页书名严格核对（《诡秘之主：失序之国》≠《诡秘之主》），同人/续作直接否掉 |
| 目录是乱的 | 倒序目录自动翻转、分类页链接剔除、书页只列最新章节时自动跟「全部章节目录」 |
| 正文抓不干净 | 容器打分 + 整页最长正文段兜底 + document.writeln(base64) 解码 + 41 条去广告规则 |
| 抓回来不知道好坏 | audit：字数分布、跨章重复段落、章内话题一致性（内容农场投毒就是这么发现的） |
| 全量正文烧 token | luna.py 把清洗外包给 codex exec -m gpt-6-luna，并发实测会死锁，已改为文件锁串行 |

快速开始

git clone https://github.com/howIdobetter/novel-pirate.git
cd novel-pirate
pip install -r requirements.txt

python3 scripts/nps.py doctor # 依赖 / codex / 字体 / 画像数
python3 scripts/selftest.py # 17 项离线自检，不联网

三种入口：

1) 一条命令：检索 → 选源 → 抓 20 章 → 出 EPUB
python3 scripts/nps.py pipeline "某本书" --out ~/books/某本书 --chapters 20 --format epub

2) 已有目录页 URL（宿主 web_search 搜到的最稳）
python3 scripts/nps.py pipeline "某本书" --from-url "https://example.com/book/123/" --full --format both

3) 手工三段式
python3 scripts/nps.py probe "<URL>" # 看 verdict / 选择器 / 反爬标记
python3 scripts/nps.py crawl "<URL>" --out ~/books/x --full --delay 1.2
python3 scripts/nps.py audit --dir ~/books/x
python3 scripts/nps.py build --dir ~/books/x --out ~/books/x/x --format both

作为技能安装（任一）：

cp -r novel-pirate ~/.claude/skills/ # Claude Code
cp -r novel-pirate ~/.dsh/skills/ # DeepSeek Harness
cp -r novel-pirate <project>/.dsh/skills/ # 项目级

命令表

| 命令 | 作用 |
| doctor | 环境自检：依赖、codex、中文字体、画像数量 |
| search | 多引擎 × 多 query 模板检索；SERP 缓存 12h；--urls 可直接吃外部链接 |
| probe | 单页探测：目录/章节判定、正文容器猜测、编码、反爬指纹 |
| crawl | 目录→逐章抓取，断点续跑，跨页拼接，区间补抓 |
| audit | 体检：字数分布 / 跨章重复 / 话题一致性 |
| clean | 只跑清洗（luna 优先，本地正则兜底） |
| build | TXT + EPUB3 + 封面，verify_epub 结构校验 |
| pipeline | 上面全串起来 |

实测数据（2026-10-23，本机跑出来的）

| 项 | 结果 |
| 站点画像 | 14 个，选择器全部来自真实页面 bs4 命中测试 |
| 域名核验 | 94 个：活 25 / 半活 8 / 死 22 / 本机不可达 8 / 被拦 8 |
| 整本抓取 | 书迷楼某书：书页只列 108 章 → 跟到「全部章节目录」1688 章 |
| 输出质量 | 20 章 47,564 字，中位 2209 字/章，EPUB3 校验通过（ok=true） |
| 清洗 | 1969 章真实语料上 clean(clean(x)) == clean(x) 全通过 |
| luna | 单次调用 9.9s / tokens used 6,881；2 路并发全部失败，已改串行（2 章 14s） |
| 自检 | selftest.py 17 项 ALL PASS；fetcher 单测 49 项 OK |

情报库：几条实测出来的硬结论

1. 搜索引擎会按 IP 拉黑。百度 /s?wd= 会回 200 + 1488B 空壳（最容易误判成「没结果」），360 会弹验证码（浏览器同样弹，实测同 IP），DDG html 端点常 202。所以技能的检索层是四级降级：SERP 缓存 → 换引擎 → 宿主 web_search → --urls/--from-url。
2. 有正文 ≠ 能用。bqg70.com 目录正常、正文 base64 也正常，但每章混入别的小说段落（主角换人、世界观断裂），跨章重复率抓不到——audit 的 topic_coherence 0.67 vs 正常源 0.75–0.83。结论：只当章节名基准。
3. https 挂 ≠ 站死。bqg70、xbiquge.biz 的 443 证书链坏了，http:// 是完整页面。fetcher 会自动 scheme 回退。
4. 域名一直在换。bqgui.cc → bqgicq.cc → /userverify → bqg759.xyz；ibiquge.cc → bpshu.cc。画像的 hosts 支持多域名。
5. 正版站拿全本性价比极低。起点首页直接 202 + 209B、字体加密；番茄正文在 __INITIAL_STATE__；它们的价值是校验目录，不是正文源。

目录结构

novel-pirate/
├── SKILL.md # agent 入口：决策树 / 命令 / 验收清单 / 故障速查 ├── scripts/ │ ├── nps.py # CLI 单入口（search/probe/crawl/audit/clean/build/pipeline） │ ├── fetcher.py # HTTP 层：编码探测、重试、每 host 限速、原子缓存、代理 │ ├── ebook.py # 清洗 + TXT + EPUB3 + 封面 + verify_epub │ ├── luna.py # codex gpt-6-luna 桥（分块清洗 / 结构抽取 / 元数据） │ ├── selftest.py # 离线自检 │ └── sites.yaml # 14 个实测站点画像 ├── references/ │ ├── sources.md # 8 层来源清单 + 94 域名核验表 + query 模板 │ ├── crawling.md # 反爬 / 分页 / 编码 / 校验手册 │ └── luna.md # token 预算与串行化实测 ├── templates/site_profile.yaml └── docs/ARCHITECTURE.md # 模块契约（加新站/改模块前先读）

加一个新站

python3 scripts/nps.py probe "https://新站/book/123/" # 拿 toc_selector_guess / content_selector_guess

照着 templates/site_profile.yaml 填，必须实测：toc.item 能选中 N 个节点、chapter.content 能出 1000+ 字，命中数量写进 notes。凭空写的选择器比没有更糟。

边界

- 只做「找源 + 抓取 + 整理」。仓库里不含任何小说正文，产物由使用者自己生成。
- 不做付费章节解密、账号操作、代充；起点/番茄的字体加密章节走换源。
- 默认克制：1.0–1.2s/请求、单 host 串行、4 并发只在跨 host 时有意义。
- 搜不到就报搜不到，不用模型续写冒充正文。

License

MIT，见 LICENSE。