# ebook-skill

把开源项目 [so-novel](https://github.com/freeok/so-novel)（通用网页小说抓取器）以 **git submodule** 形式引入，
并在它外面包一层**非交互 CLI**，让 agent / 脚本可以直接「搜索 → 选源 → 下载 → 拿到文件」，
不部署 Web 服务、不跑 TUI 交互菜单。

```
ebook-skill/
├─ vendor/so-novel/          # git submodule，上游引擎（Java 21 + Maven）
├─ tools/
│  ├─ src/skills/novel/ToolMain.java   # 封装层：search / download / toc / sources
│  ├─ build.ps1              # 构建引擎 jar + 编译封装层 + 生成运行时配置
│  ├─ lib.ps1                # 公共函数（定位 JDK21、路径、jar 工具）
│  ├─ config.ini.template    # 运行时配置模板
│  └─ runtime/               # 生成物（gitignore）：app.jar、rules/、config.ini、logs/
├─ bin/
│  ├─ novel.ps1              # 人读表格 + JSON 两种输出
│  └─ novel.cmd              # cmd.exe 入口（自动选 pwsh / powershell）
├─ books/                    # 下载落盘目录（gitignore）
├─ SKILL.md                  # 给 agent 的使用说明
└─ README.md
```

---

## 快速开始

```powershell
git submodule update --init --recursive     # 首次
pwsh tools\build.ps1                        # 首次构建（可自动下载 JDK 21）

pwsh bin\novel.ps1 sources                  # 看书源
pwsh bin\novel.ps1 search 诡秘之主           # 聚合搜索
pwsh bin\novel.ps1 toc   <详情页链接>        # 只解析目录，验证完整性
pwsh bin\novel.ps1 download <详情页链接> -Ext txt
```

依赖：JDK 21（没有则构建脚本从清华镜像下载便携版）、Maven（仅构建时需要）、Git。
下载成品在 `books/书名(作者).txt|epub|html|pdf`。

---

## 一、so-novel 是怎么下载小说的

上游不是「针对某个站点写死的爬虫」，而是**规则驱动 + 通用抓取引擎**：
每个书源是一段 JSON（`vendor/so-novel/bundle/rules/main.json` 等），引擎按规则抓页面。

### 1. 书源规则（Rule）

一条规则对应一个站点，字段分五段：

| 段 | 作用 | 关键字段 |
| --- | --- | --- |
| `url` / `name` / `disabled` / `needProxy` | 站点标识 | `url` 同时是「按详情页 URL 前缀路由到书源」的依据 |
| `search` | 搜索接口 | `url`(支持 `%s` 或 `@js:`)、`method`/`data`(GET/POST 表单)、`result`(结果条目选择器)、`bookName`/`author`/`latestChapter`…、`nextPage` |
| `book` | 详情页 | `bookName`/`author`/`intro`/`coverUrl`/`latestChapter`/`lastUpdateTime`/`status` |
| `toc` | 目录页 | `url`(目录可能不在详情页)、`list`(先取容器 HTML)、`item`(章节条目)、`desc`(倒序)、`nextPage`(分页) |
| `chapter` | 正文页 | `content`、`nextPage`(正文分页)、`nextPageInJs`、`nextChapterLink`(末页判定正则)、`filterTxt`/`filterTag`(广告清洗) |
| `crawl` | 站点级抓取参数 | `concurrency`、`min/maxInterval`、`maxAttempts` 等覆盖全局配置 |

选择器同时支持 **CSS** 与 **XPath**（以 `/`、`//`、`(` 开头判定为 XPath），
`元素选择器@href` / `@src` / `@content` 表示取属性；`meta[property="og:novel:book_name"]` 这类缺省值让「标准 meta」站点无需逐字段配置。

选择器后面还能挂 **DSL**：`选择器@js:代码` / `@java:代码` / 多段串联（`a@js:...;@js:...`）。
`HtmlExtractor` 先用选择器取原始文本，再交给 `StepEngine` 依次执行 JS（Javet V8 引擎池）或 Java 代码做二次加工
——这也是 `javet` 依赖和启动时预热 V8 的原因。

### 2. 搜索（SearchParser）

1. 用 `search.url` 拼搜索地址：普通 `%s` 字符串格式化，或 `@js:` 动态生成（签名、加密参数等）；
2. GET/POST（`data` 是 JSON，其中 `%s` 按顺序填参数），带随机 UA + Referer，可选 Cookie；
3. `result` 选出结果条目，逐条提取书名/作者/最新章节等，链接取 `@href` 的绝对地址；
4. 若有 `nextPage`，一次取全部翻页链接并发补齐（去重合并），再按 `search-limit` 截断；
5. 若结果条目为空但页面本身是详情页，则退化为「把搜索页当详情页」处理（部分源会直接跳转）；
6. 聚合搜索（`AggregatedSearchAction`）对**所有可搜索书源**并发跑一遍，最后 `SearchResultsHandler`
   用字符串相似度（`StrUtil.similar`）判断关键字更像书名还是作者，过滤低分（<0.25）、按相似度排序。
7. 遇 Cloudflare 挑战页（标题白名单判定）时可走外部 `cf-bypass` 服务取真实 HTML。

### 3. 详情 + 目录（BookParser / TocParser）

- 详情页解析书名、作者、简介、封面、最新章节、更新时间；规则没写的字段回退到 `og:novel:*` meta。
- 目录页并非总在详情页：`toc.url` 可用 `%s` 填详情页里的书籍 id（`book.url` 正则提取）。
- 目录分页有两种形态：`nextPage` 命中 `<option>` 下拉（一次性拿到所有分页 URL），或「下一页」按钮递归跟随。
- 多目录页用 5 个虚拟线程并发抓取，再按页序拼成章节列表；`desc` 表示站点是倒序，需要反转。

### 4. 正文抓取（ChapterParser / Crawler）

- **章节级并发**：Java 21 虚拟线程 + `VirtualThreadLimiter`，默认并发 `min(50, 章节数)`（配置 `concurrency` 可改，上限 100）。
- 每章请求前 `sleep` 一个随机间隔（默认 200–400ms，站点规则可覆盖），随机 UA + Referer。
- 正文页有分页时按 `nextPage` 循环拼接，用 `nextChapterLink` 正则 / 通用「_数字.html + 下一章文案」判定末页。
- 失败重试 `max-retries`（默认 3）次，重试间隔在 `retry-min/max-interval` 内随机并逐次递增；
  重试用尽则记录日志跳过该章（`enable-retry=0` 时直接中断）。
- 每章先落成独立文件（`0001_章节名.html` 等），避免长任务中途失败全丢。

### 5. 清洗与合成

`ChapterFilter`：去不可见字符/私用区字符、去 HTML 实体、按 `filterTxt` 正则和 `filterTag` 选择器删广告、
去正文开头重复的章节名、`1. 标题` 归一成 `第1章 标题`。
`ChapterFormatter`：把 `<br>` 等转成 `<p>` 段落。
之后按格式合成：

| 格式 | 处理器 | 产物 |
| --- | --- | --- |
| `txt` | `TxtMergeHandler` | 单文件，开头书名/作者/简介，正文全角缩进；可用 `txt-encoding` 指定 GBK 等 |
| `epub` | `EpubMergeHandler` | 带封面、metadata、分章的 epub |
| `html` | `HtmlTocHandler` | 带目录的单页 HTML |
| `pdf` | `PdfMergeHandler` | openhtmltopdf 生成 PDF |

中间章节目录默认在合成后删除（`preserve-chapter-cache=1` 可保留）。
输出命名：中间目录 `书名 (作者) TXT`，成品 `书名(作者).txt`，均在 `download-path` 下。

### 6. 反爬与网络层

随机 UA（`RandomUA`）、Referer、随机间隔、限流重试、可选 HTTP 代理（`[proxy]`）、
起点 Cookie（`[cookie] qidian`，用于拿最新/正版章节）、Cloudflare 时借助 `cf-bypass` 服务。
`Main` 在启动时创建并销毁一个 V8 runtime，绕开 Windows 上 Javet 首次创建 SIGSEGV 的问题。

---

## 二、这层封装做了什么（以及为什么需要）

上游三种形态都不适合当工具：

| 形态 | 问题 |
| --- | --- |
| TUI（默认） | 交互菜单，无法脚本化 |
| Web（`-Dmode=web`，端口 7765） | 需要常驻服务，与「不部署服务」冲突 |
| CLI（`-u <详情页>`） | **只能下已知 URL 的单本**，没有搜索；输出是彩色文本，无机器可读结果 |

所以 `tools/src/skills/novel/ToolMain.java` 直接复用上游库类，补上缺的部分：

- `search`：并发调用各书源 `SearchParser`，复用上游的相似度过滤/排序，输出 JSON；附带每个源的失败统计。
- `download`：与原 CLI 同一条路径（`SourceUtils.getRule(url)` 路由书源 → `BookParser` → `Crawler`），
  但支持 `--out` 指定目录、返回成品文件路径与大小。
- `toc`：只解析目录并给首尾章节，用来**先验证书源质量**（章节数、是否缺章）再决定下载。
- `sources`：列出激活书源（id、主页、是否支持搜索）。

工程细节：

- **stdout 只有一份 JSON**：库的彩色日志在进程内被重定向截留，`--log` 时以 `logTail` 返回最后 40 行，
  便于排查「源站 403 / Cloudflare / 目录为空」。
- **JSON 中非 ASCII 全部转成 `\uXXXX`**：Windows 控制台代码页（936）不会把中文搞成乱码，
  `ConvertFrom-Json` / Python `json.loads` 都会还原成正确文本。
- **配置即参数**：以 `-Dconfig.file` 指向生成的 `tools/runtime/config.ini`，书源规则走绝对路径，
  与当前工作目录无关；日志落 `tools/runtime/logs/`。
- **首次使用自动构建**：`bin/novel.ps1` 发现 `app.jar` 或 class 缺失会先调 `tools/build.ps1`。

---

## 三、命令参考

```powershell
# 搜索（-Limit 每个源最多取多少条，默认 30；-Source 只搜某个源；-Timeout 秒）
pwsh bin\novel.ps1 search 关键词 [-Limit 30] [-Source 8] [-Timeout 180] [-Log] [-Json]

# 下载（-Ext txt|epub|html|pdf，默认 txt；-Out 指定目录；URL 也可用 -Url）
pwsh bin\novel.ps1 download <详情页链接> [-Ext txt] [-Out D:\books] [-Log] [-Json]

# 只解析目录
pwsh bin\novel.ps1 toc <详情页链接> [-Json]

# 书源列表
pwsh bin\novel.ps1 sources [-Json]
```

`-Json` 输出契约（节选）：

```json
{
  "ok": true,
  "command": "search",
  "keyword": "诡秘之主",
  "count": 2,
  "results": [
    { "index": 1, "sourceId": 10, "sourceName": "笔趣阁52", "bookName": "诡秘之主",
      "author": "爱潜水的乌贼", "latestChapter": "新书已发", "lastUpdateTime": "09-26",
      "url": "https://www.52bqg.com/book_2279/" }
  ],
  "sources": { "total": 13, "returned": 20, "empty": 3, "failed": [] },
  "tookMs": 12000
}
```

```json
{ "ok": true, "command": "download", "bookName": "诡秘之主", "author": "爱潜水的乌贼",
  "sourceId": 10, "sourceName": "笔趣阁52", "ext": "txt",
  "file": "D:\\workbench\\ebook-skill\\books\\诡秘之主(爱潜水的乌贼).txt",
  "bytes": 1234567, "seconds": 42.1 }
```

失败时 `ok=false` 并带 `error`（附 `--log` 可看上游日志尾部）。

---

## 四、运行时配置（`tools/runtime/config.ini`）

构建时由 `tools/config.ini.template` 生成，仓库位置变化后删除该文件再跑一次 `tools\build.ps1` 即可重建。

| 配置 | 说明 |
| --- | --- |
| `[download] download-path` | 默认 `books/`，可用 `-Out` 单次覆盖 |
| `[download] extname` | 默认格式，命令行 `-Ext` 优先 |
| `[download] txt-encoding` | txt 编码，老设备可设 `GBK` |
| `[download] preserve-chapter-cache` | 1 = 保留中间章节文件 |
| `[source] active-rules` | 激活的规则文件（默认 `runtime/rules/main.json`，13 个源） |
| `[source] search-limit` | 每个源搜索结果上限 |
| `[source] search-filter` | 1 = 按相似度过滤低质量结果 |
| `[crawl] concurrency` | 章节并发，空 = 自动（≤50，上限 100） |
| `[crawl] min/max-interval` | 章节请求随机间隔（毫秒） |
| `[crawl] max-retries` | 单章重试次数 |
| `[proxy]` | 需要代理才能访问的书源：`enabled=1` + `host/port` |
| `[cookie] qidian` | 起点 `w_tsfp`，用于部分源的最新章节 |
| `[global] cf-bypass` | Cloudflare 绕过服务地址（如 `https://github.com/sarperavci/CloudflareBypassForScraping` 部署的实例） |

`runtime/rules/` 下的其他规则包（`cloudflare.json`、`proxy-required.json`、`rate-limit.json`、`no-search.json`）
默认**未激活**：需要时把 `active-rules` 指向对应文件（或把这些源合并进一个 json）。

---

## 五、维护

```powershell
# 更新上游代码（GitHub 直连不通时，本仓库已在 .git/config 配了 ghfast.top 镜像 insteadOf）
git -C vendor/so-novel fetch --tags
git -C vendor/so-novel checkout <tag>
git add vendor/so-novel && git commit -m "bump so-novel"

# 重建（引擎变更时必须；规则包更新可只刷规则）
pwsh tools\build.ps1 -Force -RefreshRules
```

已知坑：

- **Javet 原生库**：so-novel 依赖 JS 规则（`@js:`），需要平台对应的 `javet-v8-*` 原生库。
  它的 Maven profile 用 `x86_64` 匹配架构，而 Windows JDK 报 `amd64`，自动激活会失效，
  症状是「Javet library /libjavet-v8-windows-x86_64...dll is not found」、依赖 JS 规则的书源全部空结果。
  `tools/build.ps1` 已按平台显式传 `-P windows-x64|linux-x64|…`，重建后 `app.jar` 约 36 MB（含原生库）。
- **GitHub 被重置**：仓库本地配置了 `url."https://ghfast.top/https://github.com/".insteadOf`，
  删除用 `git config --unset url."https://ghfast.top/https://github.com/".insteadOf`。
- **JDK 21 必需**（虚拟线程 + 上游 class 版本 65）；`Find-Jdk21` 会依次找
  `EBOOK_NOVEL_JAVA_HOME` → `JAVA_HOME` → `tools/.jdk` → 常见安装路径（含 IntelliJ 自带 JBR）。
- **Maven** 只在构建时需要；Maven Central 走内网 nexus / 阿里云镜像均可。
- **规则失效**是最常见的失败原因（站点改版/关站）：`search` 出来为空、`toc` 章节数异常、
  下载 txt 只有简介——此时换一个书源，或更新子模块/规则。
- **目录质量比源数量重要**：`toc` 里首章不是第 1 章（分页缺失）或顺序反了（站点倒序但规则没标 `desc`），
  都会产出残书/反序书，直接换源。
- **别把并发调太高**：这些站点普遍限流，`concurrency` 40–60、间隔 200–400ms 是上游默认值，够用。

---

## 免责声明

本项目仅用于个人学习与技术研究，请遵守目标站点服务条款与著作权法规，不要用于商业分发。