# 找书（Legado 书源）开发文档

彩读的「找书」功能兼容 [legado-E（阅读Sigma）](https://github.com/Luoyacheng/legado-E) 文本书源 JSON 格式，
在主进程用 TypeScript 复刻其核心解析链路，渲染进程提供**独立找书窗口**：书架、搜索、发现、详情、在线阅读、书源管理与整书下载。

> 用户入口：**更多 → 找书**（快捷键 `F7`），打开独立窗口（非主窗口内嵌面板）。  
> 亦可：桌面快捷方式、`--find-book` 启动；开发时用 `npm run dev:find`（`electron-vite dev -- --find-book`）。
> 实现参考：
> - [Legado_Max 帮助文档](https://github.com/youfengknight/Legado_Max/tree/main/app/src/main/assets/web/help/md)  
> - [Legado 书源规则说明](https://mgz0227.github.io/The-tutorial-of-Legado/Rule/source.html)  
> - [破冰的源教程](https://www.yuque.com/legado/yuan/pe61gy)  

---

## 1. 目录结构

```
src/
├── shared/bookSource/          # 主进程 / 渲染进程共享
│   ├── types.ts / ipc.ts / url.ts / paths.ts
│   ├── loginUi.ts / wordCountFormat.ts / legadoFlexStyle.ts
│   └── chapterReadingOrder.ts
├── shared/findBookWindowTitle.ts
├── main/findBookLaunch.ts      # --find-book、桌面快捷方式、初始 Tab
├── main/bookSource/
│   ├── registerBookSourceIpc.ts / searchService.ts / downloadService.ts
│   ├── checkSourceService.ts / integrationSmoke.ts
│   ├── store/bookSourceStore.ts
│   └── engine/                 # Legado 规则引擎（见 §3）
│       ├── webBook.ts / chapterCache.ts / getChapterContentWithCache.ts
│       ├── analyzeRule.ts / analyzeUrl.ts / jsExtensions.ts / …
│       ├── bookSourceJsTimeout.ts / legadoJsoupShim.ts / …
│       └── exploreKinds.ts / coverImage.ts / loginCheck.ts / …
└── renderer/src/
    ├── findBookMain.ts / FindBookWindow.vue / find-book.html
    ├── components/
    │   ├── AppCaptchaHost.vue / IconButton.vue
    │   ├── LoadingDotsBounce.vue / LoadingDotsRotate.vue  # 「加载中」动画
    │   ├── RefreshIcon.vue                               # 刷新图标（静止 / 旋转）
    │   └── HighlightedCodeTextarea.vue                   # 透明 textarea + 高亮叠层（编辑书源内联）
    └── bookSource/
        ├── components/
        │   ├── FindBookPanel.vue           # 壳：三 Tab + 叠层
        │   ├── FindBookshelfPanel.vue / FindDiscoverPanel.vue
        │   ├── BookDetailPanel.vue / FindBookReaderPanel.vue
        │   ├── FindBookReaderHeader.vue / BookSourcePanel.vue
        │   ├── FindBookListItem.vue            # 搜索/发现书籍行（VirtualList 固定行高）
        │   ├── findBookListLayout.ts           # 搜索/发现虚拟列表 rowStride
        │   ├── ReplaceRulePanel.vue            # 文本替换管理
        │   ├── EditBookSourcePanel.vue / ImportBookSourcePanel.vue
        │   ├── BookSourceFieldMonacoModal.vue  # 单字段全屏 Monaco（按需动态加载）
        │   ├── BookSourceLoginPanel.vue / CheckSourceConfigPanel.vue
        │   ├── DisclaimerPanel.vue
        │   └── FindBookSettings*.vue
        ├── editBookSourceFields.ts             # 编辑表单字段定义 / 行高上限
        ├── highlightBookSourceCode.ts          # 内联轻量正则高亮（对齐 CodeView）
        ├── formatBookSourceFieldText.ts        # 全屏字段语言推断 + js-beautify 格式化
        ├── monaco/
        │   ├── bookSourceRuntimeLib.ts         # 书源 JS 运行时 d.ts 文本（补全用）
        │   └── ensureBookSourceMonacoLibs.ts   # addExtraLib 幂等挂载
        ├── composables/
        │   ├── useBookSource.ts / useFindBookBookshelf.ts
        │   ├── useBookshelfUpdate.ts / useChapterCacheMarks.ts
        │   ├── useFindBookSettings.ts / useFindBookReaderSettings.ts
        │   └── useFindBook*Shortcuts.ts
        ├── findBookBookshelf.ts / bookshelfOpenReader.ts
        ├── services/clearBookChapterCache.ts / findBookDownloadActions.ts
        └── …
```

**持久化位置（userData）**

| 路径 / 键 | 说明 |
|------|------|
| `book-sources.db` | 书源 JSON、登录字段、source 级 cache |
| `localStorage: colortxt:replaceRules:findBook` | 找书文本替换规则 |
| `localStorage: colortxt:replaceRules:app` | 主窗口文本替换规则 |
| `book_source_cookies`（表） | 按域名 Cookie |
| `book-source/files/` | `importScript` / `cacheFile` 本地脚本 |
| `DownloadedBooks/` | 默认整书导出目录（找书设置可改） |
| `book_cache/` | 章节正文离线缓存（找书设置「缓存目录」可改） |
| `bookSourceAndroidId.txt` | `java.androidId()` 稳定值 |
| `localStorage: colortxt:findBookBookshelf` | 书架（进度、可选目录缓存） |
| 找书设置相关 localStorage | 与主应用「设置」分离（缓存/下载目录、阅读偏好、网络代理等） |

---

## 2. 架构与数据流

```
渲染进程 (FindBookWindow → FindBookPanel)
    │  window.colorTxt.bookSource*  (preload → IPC)
    ▼
registerBookSourceIpc.ts
    ├── bookSourceStore / searchService / downloadService
    └── engine/webBook.ts → AnalyzeUrl + AnalyzeRule + jsExtensions
```

### 2.1 UI 面板与叠层

```
FindBookPanel（standalone 时即为找书窗口内容）
├── Tab：书架 | 找书 | 发现
├── BookSourcePanel / FindBookSettingsPanel / DisclaimerPanel
├── BookDetailPanel      ← 叠层（书籍信息）
└── FindBookReaderPanel  ← 叠层（在线阅读）
```

**三 Tab 显隐**：书架 / 找书 / 发现均用 `v-show`（找书为 `.findBookSearchPane`），切换 Tab 时**保留**各自列表滚动位置。
找书隐藏时不跑 `tryAutoLoadMoreSearch`（避免 `display:none` 尺寸为 0 误触发加载）；切回找书再补一次。

**详情 ↔ 阅读器（`AppModal` + `modalStack.bringToFront`）**

| 操作 | 行为 |
|------|------|
| 首次从详情开阅读 | 打开阅读器；**不关**详情（压在下层） |
| 详情再次点章 /「开始阅读」且阅读器已在 | 阅读器抬到最前并切章，**同时关闭详情** |
| 阅读器顶栏「更多 → 书籍信息」 | 打开或抬升详情（阅读器可留在下层） |
| 换书（另一 `bookUrl`+`origin`） | 关闭阅读器并清空其 props，避免串书 |

两个「更多」：阅读器**顶栏**（书籍信息 / 编辑书源 / 清除缓存）vs **阅读工具栏**（窄屏版式与设置）。顶栏「刷新」「登录」已外置为图标按钮，勿与主应用「清除缓存」
（清 localStorage）混淆。

### 2.2 典型流程

**搜索** — `searchService` 多源并发 → `searchEvent` 流式推送。  
**发现** — `exploreKinds` → `webBook.exploreBook`（`ruleExplore`）。  
分类书籍列表支持顶栏「第 N 页」跳转指定页（对齐 Legado）；滚动仍可继续加载后续页。  
**详情 → 目录 → 正文**：

- 搜索/发现列表经 `searchBookToBook` 得到未完善 `Book`（`tocUrl` 为空）。  
- `getBookInfo` 写入真目录地址并完善同一份 `Book`。  
- `getChapterList` / `getChapterContentWithCache` 只收完整 `book`（读写 `book_cache`；
  正文可 `preferCache: false` 强制联网）。  
- 列表字段顺序对齐 Legado：`kind` 先于 `bookUrl`，以便 `{{book.kind}}`（如 `resourceId`）
  在拼详情链接时已是规则结果（含 `##` 去前缀）。  
- 目录/正文通过 `AnalyzeRule.setBook(book)` 使用。  
**整书下载** — 先缓存全部非分卷章，再导出 UTF-8 `.txt`（正文非空段首「　　」；标题不加）。  
**离线缓存** — 阅读器侧栏「离线缓存」走下载管道 `cacheOnly: true`，只写 `book_cache`、不导出 `.txt`。  
**书架开读** — 立即打开阅读器（可先展示书架侧详情 + 空目录，`tocLoading`），后台拉目录后再加载正文；有本地目录缓存可加速。

---

## 3. 核心模块原理

> **Legado 对照源码**  
> - `app/src/main/java/io/legado/app/model/analyzeRule/AnalyzeRule.kt`  
> - `app/src/main/java/io/legado/app/model/analyzeRule/AnalyzeUrl.kt`  
> - 子解析器：`AnalyzeByJSoup.kt` / `AnalyzeByJSonPath.kt` / `AnalyzeByRegex.kt`  
>
> **ColorTxt 实现**  
> - `engine/analyzeRule.ts` — 规则解释器  
> - `engine/analyzeUrl.ts` — URL 解析与请求  
> - `engine/legadoRuleSplit.ts` — `splitSourceRule`  
> - `engine/legadoDefaultRule.ts` — `##` 正则后缀、Cheerio 选择器  
> - `engine/legadoCompositeRule.ts` — `makeUpRule`、`parseLegadoUrlSuffixJson`

### 3.1 AnalyzeRule（规则解析）

**职责**：对**已有 HTML/JSON/对象**应用 Legado 规则链，输出字符串、URL 或元素列表。  
**不负责发请求**；网络由 `AnalyzeUrl` / `java.ajax` 完成。

#### 3.1.1 Legado 总流程

```mermaid
flowchart TD
  A["setContent 判定 JSON/HTML"] --> B["splitSourceRule 仅按 JS 切段"]
  B --> C["SourceRule 构造"]
  C --> C1["detectMode + splitPutRule"]
  C --> C2["解析 @get / 双花括号模板 为 ruleParam"]
  C --> C3["makeUpRule 无 result 预展开"]
  D["getString / getElements 链式循环"] --> E["putRule @put"]
  E --> F["makeUpRule 带当前 result"]
  F --> G{mode}
  G -->|Js| H[evalJS]
  G -->|Json| I[AnalyzeByJSonPath]
  G -->|XPath| J[AnalyzeByXPath]
  G -->|Default| K[AnalyzeByJSoup]
  G -->|Regex| L[AnalyzeByRegex]
  H --> M["replaceRegex ##后缀"]
  I --> M
  J --> M
  K --> M
  L --> M
  M --> N{"result 为空?"}
  N -->|是| O[链中断]
  N -->|否| D
```

**`splitSourceRule`（Legado）**：**只**在 `<js>…</js>` / `@js:` 处切段；
`&&` / `||` / `%%` **不会**在此层拆成多段。  
`@js:` 对齐 Legado `JS_PATTERN`（`@js:([\w\W]*)` 贪婪到规则末尾）；续行纯 JSONPath（`$.a`）可截断，
**勿**把 `$[i].select(...)` 等 JS 误判为 JSONPath。  
规则 JS 里 Jsoup `Element.select` 含根节点自身匹配（`li.select("li")`）；
`getElements` / Default 与 `@css:` 列表结果均为 Jsoup Element（可 `.attr` / `.select` / `.forEach`），
`java.getElement` 对齐 Legado 返回 **Elements**（可直接 `.text()` / `.attr()`，如部分书源发现
`java.getElement("@@tag.a.0").text()`）。
非仅 HTML 字符串；`JSON.stringify(Element)` 对齐 Rhino 输出 `outerHtml`（见 `toJSON`）。
`select()` 返回的 Elements 为**数组**（数字下标可枚举，`size`/`attr` 等不可枚举），以便
`for (i in els) { els[i].attr(...) }` 与 Rhino 一致。
若 `<js>` 返回 `JSON.stringify(Elements)`，下一跳选择器会先 `JSON.parse` 再拼 HTML，
避免 Cheerio 把 `\"` 当属性截断（如目录排序后的 `tag.a`）。
部分书源章名/章链 JS 仍按「Legado 把 JSON 当 HTML 解析」时的 `\&quot;` 形态写正则；
`bindJsHtmlValue` / `mangleLegadoObfuscatedAnchorHtml` 会把干净的 `<a class="g">` 还原成该形态，
并将 base64 型 `data-*` 重排到 mangled `class` 之后，以匹配 try 分支正则顺序。  
列表项为 Element 时，`isPlainRuleObject` / `{{@@…}}` kind 模板须走嵌套 `getString`，
不可误走 `readJsonField`（否则分类/状态标签会整段丢失）。  
非 JS 段整段交给 `AnalyzeByJSoup` 等，由 `RuleAnalyzer.splitRule("&&","||","%%")` 在**同一段、
同一 DOM/JSON 上下文**内处理。

**`SourceRule`（Legado 内嵌类）** 每段规则在构造时完成：

1. **模式**：
   - `@js:` → Js；`@Json:`/`$.` → Json；`@XPath:`/`//` → XPath；含
     `@get:`/`{{}}` 且无 `##` → Regex；否则 Default。  
   - `@put`/`@get` 展开后的 `https://…` / `data:` /
     `/book/x.html` 视为字面 URL（`isLegadoLiteralUrlRule`），勿再当 JsonPath。  
   - **仍含 `{{…}}`/`@get:` 时不可当字面量**（须先 `makeUpRule`，如 `$.bid`→`<js>…</js>`→
     `https://…?bookid={{result}}`）。  
   - **含 `&&`/`||`/`%%` 亦不可当字面量**（须分段：URL 前缀原样拼接 href，非法 CSS 勿抛）。  
   - `@js:` 后续行若以 `/pat/.test(...)` 等正则表达式开头，
     勿拆成 XPath（否则 isVip 只剩 `//` 注释 → `Unexpected end of input`）。  
   - 搜索 `@put:{id}` 须写入 `SearchBookItem.variable` 并随 `getBookInfo` 带入
     （否则 `tocUrl=list/@get:{id}` 丢 id，目录回退详情页把推荐书当章节）。  
   - **`AnalyzeRule.put` 对齐 Legado**：`chapter` → `book` → `ruleData` → **source**（有
     book/chapter 时**不**写入书源 cache）；否则详情 `@put:{bid:id}` 会污染全局 cache，
     书架直开正文 `java.get('bid')` 串到其它书。书架须持久化 `Book.variable`。  
   - 从 URL 回填 `bid` 时：勿覆盖**本书** `book.variable` / 规则链已有值；勿把书源
     cache 里其它书的 bid 当成「已有」；且须剥掉 `bid=bid=hash`
     （部分书源把 `Params="bid="+hash` 再拼进 `&bid=`，裸捕获会得到 `bid=hash`，正文「无此书」）。  
2. **`@put{…}`**：剥离到 `putMap`，链开始前 `putRule` 用 `getString(value)` 写入变量。  
3. **`makeUpRule(result)`**：展开 `@get:`、`{{…}}`（内嵌规则或 `evalJS`）；
   再按 `##` 拆出 `replaceRegex` / `replacement`；**`ruleStrS[0].trim()`** 后再替换
   （否则如部分书源 `{{…##·|\d.*}}##.*\s` 展开带尾空白时 `.*\s` 会整段清空，「完结」tag 丢失）；
   **四段** `rule##pat##repl###` 时 `replaceFirst=true`。
   替换正则对齐 Kotlin `Regex` 默认：**`.` 不匹配换行**（勿加 DOTALL，
   否则 `##(\s*.*【1】.*)?\s*标记` 类分页清理会把整篇正文吞掉）；
   跨行需求应由提取侧对齐 Jsoup（text/ownText 折叠空白、
   `@html` pretty-print 换行，见 §7.2）解决。  
4. **链式 `getString`**：每段 `makeUpRule(当前 result)` → 按 mode 解析 → `replaceRegex`；
   `result == null` 则 **continue**（不回退 `content`）。  
5. **`getElements`**：与 `getString` 不同，Legado **不在循环内**再次 `makeUpRule(result)`（仅构造期预展开）；
   `getElement` **会**在循环内 `makeUpRule(result)`。

**`evalJS` 绑定**（Legado `JsExtensions`）：

| 绑定 | 含义 |
|------|------|
| `java` | `AnalyzeRule` 自身（implements JsExtensions） |
| `result` | 链上当前值 |
| `src` | 原始 `content`（整段响应） |
| `source` / `book` / `chapter` | 书源与书籍上下文 |
| `baseUrl` / `nextChapterUrl` | URL 上下文 |
| `cookie` / `cache` | CookieStore / CacheManager |

**变量 `put` / `get` 优先级**（Legado）：`chapter` → `book` → `ruleData` → `source`。

#### 3.1.2 ColorTxt 映射

| Legado | ColorTxt | 说明 |
|--------|----------|------|
| `SourceRule` | `getOne` / `evalStringChainSegment` | 单段规则执行 |
| `splitSourceRule` | `legadoRuleSplit.splitSourceRule` | 仅按 JS 切段；`&&` 在段内处理 |
| `makeUpRule` | `expandAllTemplateExprs` + `applyPutPrefixRule` + `splitRuleRegexSuffix` | 模板展开与 `##` 后缀（见下） |
| `evalJS` | `evalRuleJs` → `evalJsAsync` | Node AsyncFunction，非 Rhino |
| `AnalyzeByJSoup` | `legadoDefaultRule` + cheerio | `&&`/`||`/`%%` 在段内处理 |
| `getStringList` NativeObject 分支 | `isJsonItemContent` + 字段直读 | JSON 列表项上 `{{$.id}}` 等 |

`makeUpRule` 补充：`{{@@…}}` / `{{$.…}}` / `{{result}}` 走嵌套 `getString`；其余 `{{}}` 内表达式走 JS；`##` 在 `legadoDefaultRule.ts`。  

**规则模式**（`detectMode`）：

| 前缀 / 特征 | 模式 | 说明 |
|-------------|------|------|
| `@css:` / `class.` / `tag.` | default | cheerio，对齐 Legado Default |
| `@json:` / `@Json:` / `$.` | json | jsonpath-plus |
| `@XPath:` / `@xpath:` / `//` | xpath | @xmldom/xmldom；见下 |
| `@js:` / `<js>` | js | `evalJsAsync` + `legadoAsyncJs` |
| `@webjs:` | webJs | ColorTxt 扩展；Legado 正文 webView 多在 URL 后缀 |
| `{{` | template | 纯模板；内嵌 `@`/`@@`/`$.`/`//` 为嵌套规则（对齐 Legado `isRule`），非 Rhino |
| 纯 `{{jsExpr}}` | js → expand 后直接返回 | `{{'书名'}}` 勿再 eval 展开结果 |
| `:` 开头（`allInOne`） | regex | `AnalyzeByRegex`；Java `(?s)`/`(?i)`/`(?m)`/`(?u)` 转 JS flags（勿直接 `new RegExp`，否则部分书源目录为空） |
| 其他 | default | `legadoDefaultRule` |

JSON 正文时：裸字段/`result.list[*]` 走 JsonPath；含 `@text`、`class.`/`tag.`/`^.`、或 **CSS 属性选择器**
`[attr=…]` 的仍走 default。不可用宽泛 `\[[^\]]+\]` 判断，否则 `[*]` 会被误判（如部分书源目录）。

XPath 补充：`text/html` 带 XHTML 默认 ns 时须 `xpathIgnoreXhtmlDefaultNs`；`getElements` 返回元素 HTML（非 textContent）。
未声明的 `xlink:href` 等会使 xmldom 抛 NamespaceError——解析前补 `xmlns:xlink`（或剥前缀）；
`//tag[@id=…]/*` 另用 cheerio 兜底。规则 JS 对 HTML 元素列表的 `String(result)` 须对齐 Java
Elements：`[html1, html2]`（部分书源 `slice(1,-1).split(/, (?=<li…)/)`）。
JsoupXpath 扩展（Legado）：末段 `/html()`（内部 HTML）、`/outerHtml()`、`/allText()`；标准 `xpath` 包无此语法，须在查询前剥离并本地提取。
结构破损页面（`</br>`、标签错配等）xmldom 解析会直接抛 fatalError——须先经 cheerio/parse5
纠错重排再解析，否则正文 `nextContentUrl` 等 XPath 静默取空、分页只加载第 1 页。  

**链式与组合**（务必区分两层）：

| 层级 | 分隔符 | Legado | ColorTxt |
|------|--------|--------|----------|
| **规则链** | 仅 `@js`/`<js>` 切段 | 前段输出作后段 `result` | 已对齐 |
| **段内组合** | `&&` / `||` / `%%` | JSoup/Regex 内部 `splitRule` | `splitLegadoCompoundRule` + `mergeLegadoDefaultCompound` |
| **字段备选** | `\|\|`（kind 等） | `splitLegadoCompoundRule` | `shouldSplitOrAlternatives` + `getOne` 内 `\|\|` |
| **正则后缀** | `##pat##repl` / `###` | `SourceRule.replaceFirst` | `splitRuleRegexSuffix` |

**常用 API**：`getString` / `getStringList` / `getElements` / `getUrl`；
`setContent` / `setBook` / `setChapter`；`put` / `get`（与 `source.put`、`@get:` 对齐）。

**已知与 Legado 的差异（修引擎时优先核对）**：

1. **`getElements` 空结果**：Legado `result ?: continue` 不回退；
   裸规则 `html`/`text`/`all` 在 **list** 模式须当 CSS/选择器（`select("html")`），不可走 `@html` 提取
   （否则 `chapterList:"html"` 单章源得到字符串列表、目录解析失败）。  
   章名 `{{book.name}}` / `{{title}}` / `{{chapter.title}}` 等须走 Legado 绑定变量展开，勿误当 JS 表达式求值（空标题→章节被跳过；正文 `replaceRegex` 中 `{{chapter.title}}` 未展开会变成 `.*.*` 清空正文）。  
   ColorTxt 链中空段直接中断（已去掉回退 `content`）。  
2. **JS 引擎**：Rhino 同步 + `shareScope` vs Node 异步 + `await java.ajax`；空返回、
   `result`/`src` 语义需按 Legado 测。  
   - **零宽/格式字符**：须在 prepare 前剥离（`\u200B` 等）；否则如部分书源
     `source.getSource​()` 在 V8 抛 `missing ) after argument list`。  
   - **`source.getSource()`**：对齐 Legado `BaseSource.getSource()` 返回书源自身；
     `eval(String(source.getSource().bookSourceComment))` 须能内联注释（与
     `source.bookSourceComment` 相同）。  
   - **`JavaImporter` + DES**：须提供 `DESKeySpec` / `SecretKeyFactory` /
     `Cipher.ENCRYPT_MODE` 与 `android.util.Base64.encodeToString`（部分书源
     `encryptByDES`）；`Cipher.getInstance("DES")` 按 `DES/ECB/PKCS5Padding` 处理。
     扁平 `Base64` 须同时保留 `java.util.Base64.getDecoder()`（部分 API 书源 AES 正文），
     勿用纯 android 桩覆盖。  
   - **`java.getElements` / `getStringList`**：须返回**真正的 Array**（`ensureLegadoListApi`），
     不可用非 Array 的 `legadoJsList` 对象；否则 `bookList` 中 `@js: …; return a` 后
     `getElements` 会把整表包成 1 条，发现列表为空（部分论坛书源发现分类）。
     `getElements` 对仍带 `toArray()` 的返回值须展开。  
   - **`ensureLegadoScriptReturn`**：跳过末尾纯注释行；`if (cond) a=…` 补 `return a`（勿 `return if`）。
     `prepareLegadoAsyncJs` / 同步 IIFE 须在 `})()` 前换行，避免 `return //注释; })()` 被行注释吃掉收尾
     （`Unexpected end of input`，如部分论坛书源发现 `bookList`）。  
   - **`evalRuleJs` 显式 `""`**：不可回退整页 `content`（否则无 `TextContent` 的 404 页经
     `formatKeepImg` 会把 `<style>` 正文化，如部分书源「页面不存在」后出现 `@media`）。
   - **`evalRuleJs` 显式 `@js`/`<js>` 且结果为 `undefined`**：仅当 JS 内 `setContent` 改写过正文时
     才回退 `content`；否则当空串。否则未补 `return` 的规则会把整页 HTML 当正文
     （部分论坛书源：读者出现 `DOCTYPE` / 论坛脚本源码）。
   - **`setContent` / `java.ajax`**：显式 `setContent` 须同步更新 `chainItemContext`；
     `java.ajax` **不得**永久改写 `AnalyzeRule.content`（对齐 Legado 只返回 body），仅在规则链内
     更新 `chainItemContext`，供同段 JS 内后续 `java.getString` 读到响应（部分书源正文 ★）；
     若 ajax 永久 `setContent`，详情 `lastChapter` 拉完目录后 `coverUrl`/`tocUrl` 会读错正文
     （部分书源：封面根路径 403、目录「tocHtml 缓存」空章）。  
   - **`list\nif(list==""){"提示"}` + 尾注释**：`ifElseChainIsTerminal` 须忽略尾注释以便分支补
     `return`；`ensureLegadoScriptReturn` 在块后补 `return list`（对齐 Rhino completion）。  
   - **`getUrlList` / `@js`**：若结果整段是 HTML（以 `<` 开头），视为无下一页，勿按行拆 URL
     （误回退整页时会把广告属性行拼成相对路径并去拉 404）。  
   - 沙箱须绑 `$`＝`result`（`{{$.book_id}}` 误进 JS 时勿 `ReferenceError`）。  
   - 含 `{{` 的 https URL 展开后须直接返回，勿再 `eval`。  
   - 链式上一段若为数组，须带 `toArray()`/`size()`/`get()`（`ensureLegadoListApi` / 脚本 prelude，
     且保持 `Array.isArray` 与 `.map`；**API 须 `enumerable:false`**，否则 `for (i in $)` /
     `$[i].select` 会扫到方法名）；prelude 不可把字符串/`StrResponse` 包成假 List。  
   - `await java.ajax` 若再跑 header `@js`/`loginCheckJs`，共享 jsLib 沙箱须进出恢复 `result`。  
   - `ensureLegadoScriptReturn` 须给末尾表达式补 `return`；末行仅为 `});` / `);`（分号后无语句）时不可提前退出，
     否则 `List.map(…);`、`JSON.stringify($$);` 会丢返回值。  
   - 末行 `}` / `};`（if/else 块结束）不可改成 `return }`，
     应保留块并在需要时补 `return result`（否则搜索 `bookUrl` `@js` 整批 SyntaxError）。  
   - `ensureLegadoIfElseBranchReturn` 只给**分支块顶层**表达式补 `return`，
     不可改写嵌套 `for`/`while` 体内（否则 `urlEncode` 首轮就 `return`，发现列表为空）；
     且仅处理**脚本末尾**的 if/else（`loginCheckJs` 在 if 后还有 `result` 时勿 `return java.log(...)`）。
     分支末行若为多语句（`json=…; url=…`），须对**最后一句**补 `return`，
     否则 tocUrl 返回 undefined → 目录回退详情页。
     勿在整段脚本末尾一律 `return url`（url 常仅在 if 内赋值 → `url is not defined`）。
     分支末行若为 `java.put`/`java.log` 等副作用，须先执行再 `return result`/`url`。  
   - 顶层 `try/catch` 亦须补分支 `return`（`ensureLegadoTryCatchBranchReturn`；
     否则 tocUrl 返回 undefined → 目录回退详情页）。
     补 `return` 时不可用 `/[;]/` / `\bclass\b` 粗判「多语句/关键字」——书源正则常含
     `&quot;`（以 `;` 结尾）与 `/class="…"/`，误判后 try 分支无法 return，只能靠
     catch 里 `result=match[1]` + 外层 `return result`，且 try 里 `match(...)[1]` 失败
     会被 `java.log(e)` 刷成 `Cannot read properties of null (reading '1')`。  
   - 共享作用域 `coerceLegadoResult` 须原样保留 `body()`/`url()` 的 StrResponse，不可当扁平 Map。  
   - 同理须原样保留 Jsoup `Element`（`outerHtml`/`attr`/`select`）；否则目录字段
     `@js:result.outerHtml()` 会变成 `outerHtml is not a function`（如部分站点 `isVip`）。  
   - 沙箱 `JSON.parse` 对**已是 object/array** 的值须原样返回（Jayway JSONArray `toString` 仍是合法 JSON，
     Node 会变成 `[object Object]`）；**数组**再经 `ensureLegadoListApi` 挂串行 `map(async…)`（Rhino
     同步 map 不会一次打出全部 `java.ajax`）。  
     字符串解析走 `parseLegadoLenientJson`：GSON 式单引号/无引号键、字符串内控制字符、
     以及页面内联 state 的 `undefined`/`NaN`/`Infinity`（否则 `Unexpected token 'u'`）；仍失败且形如 `{…}`/`[…]` 时按 JS 对象字面量求值。  
   - `.map` 回调因 `await java.ajax` 升为 async 后若仍得到 `Promise[]`，
     `evalJsAsync` 须串行 await（勿 `Promise.all` 加剧并行）。  
   - 未配置 `concurrentRate` 时 `fetchStrResponse` 仍默认限 **3** 路并发，避免其它并行路径打爆站点。  
2b. **简介 HtmlFormatter**：`indent1`/`indent2` 须把段首规范成**恰好一个** `　　`（折叠已有 `\u3000`），
    否则 `##^##$1<br>` 类规则会叠出双倍前导缩进；纯文本段首缩进仍保留为单个 `　　`。  
3. **JSON 列表项**：ColorTxt 对 `{{$.path}}` 有 `expandBraceJsonPathRule` 等扩展；
   勿与 Legado JsonPath 行为混为一谈。  
4. **禁止按书源名 / 站点名分支或点名**：差异应修在共享层，用 Legado 行为作准绳；注释与文档只用规则形态/字段名举例，勿写具体书源或网站名称。  
5. **`##` 与 `@js:` 顺序**：Legado 先 `splitSourceRule`（切出 `@js:`）再对各段做 `##`；
   `getString`/`getStringList` 含 `@js:`/`<js>` 时必须整段走规则链，
   禁止先 `splitRuleRegexSuffix`（否则会把 `@js:…` 吃进 replacement，简介出现字面量 `@js:`）。  
6. **`##pat##\n`**：替换值可以是换行；解析规则时不可 `trim()` 整段（会裁掉 `\n`），
   用 `trimLegadoRulePreservingRegexReplace`。
   `getString` 收尾的 `trimLegadoAsciiWhitespace` 也须**保留**结果首尾换行（榜单 `##…##\n$2:$1`），
   只去掉空格/制表等。简介规则如 `{{@id.intro@text## 　　##\n}}` 依赖此行为。  
7. **`{{$.path##regex}}`**：`expandLegadoTemplateJsonPathExpr` 必须先取路径再 `applyRuleRegex`（搜索
   `docId##.*_` 去前缀），不可只 `split("##")[0]` 丢掉替换。  
   - `getString` 遇字面 https URL 前仍须先展开 `{{`；AnalyzeUrl 的 `{{}}` 无列表 JSON 上下文时不可把残留
     `$..…` 当 JS eval（否则 `Unexpected token '.'`）。  
   - **纯模板**（如 `<p>{{$.data.Content[0].Content}}</p>`）
     须在 expand 前用 `isLegadoTemplateOnlyRule` 判定并直接返回；若先 expand 再进 `getStringChain`，
     JSON 页上 `detectMode` 会把 `<p>正文</p>` 当 JsonPath，正文变空。  
8. **JSON 下 `.field`**：`readJsonField` / `legadoJsonPathFromRule` 须把
   `.contentsize` 映射为 `$..contentsize`（勿按 `''.split('.')` 走空键）；否则 `##$##字` 在空值上只剩「字」。  
6. **`getElements` 中间段**：`id.list@dd@a` 等列表规则在 `list` 模式下中间选择器须保留全部匹配节点（勿
   `pickElements(0)`），否则目录只会解析到第一个 `dd`。  
7. **表格行片段**：`getElements` 序列化出的孤立 `<tr>`/`<td>` 经 Cheerio/HTML5 会剥掉单元格（与 Jsoup 不同）；
   解析前须用 `wrapOrphanTableFragments` / `loadCheerioHtml` 包一层 `<table>`，否则搜索
   `td.N@text`（如「247k」字数栏）会全空。  
   - `{{@@td.N@text##…}}` 须按 Legado `isRule` 走嵌套 `getString`（`expandAllTemplateExprs`），
     不可当 JS eval，否则 SyntaxError 后回退整段 HTML（表格 lastChapter 等）。  
7b. **Jsoup `Elements.text()`**：勿用 cheerio
    `.map().get().join()`（可能 join 到节点对象变成 `[object Object]`）；用 `.each` 收集字符串。
    `coerceLegadoRuleString` / `coerceLegadoMediaUrl` 遇带 `.text()` 的节点优先取文本。  
7b2. **Default 相对 CSS**：对齐 Jsoup `Element.select`，非整页查询时须包含 scope **自身**（`find` + `filter`）；
    仅 `find` 会导致 `.category-div@h3@…` 在条目根已是 `category-div` 时取空。  
7b3. **属性 `~=`**：书源语义为「包含」（同 `*=`），与 CSS 空格整词匹配不同；Cheerio 查询前改写
    `[attr~=val]`→`[attr*=val]`（兄弟组合器 `A ~ B` 不受影响）。如 `a[href~=catalog]` 可命中
    `…/rcatalog/…`（部分书源 tocUrl）。另：无引号且含空格/冒号等的属性值须自动加引号（Jsoup 宽松、
    Cheerio 会 `Attribute selector didn't terminate`），如部分书源 `div[style=text-indent: 2em;]@html`。  
7c. **规则 / 规则 JS 的 `$1`/`$2`**：链式上一段为**标量**数组（正则捕获组）时展开——含纯 `$2$3`、`$1@js:`，以及嵌入式
    `https://…/content/$1`（Legado `splitRegex`+`makeUpRule`；勿当字面 URL）。`data.books[*]` 等对象数组不可展开，否则会把
    `.replace(..., '（$1）')` 里的 `$1` 误替换成 `String(book)` →
    `（[object Object]）`（搜索 `latest` 日期等，展示层再清掉后只剩章节名）。  
7d. **HTML XPath**：xmldom `text/html` 会加 `xmlns=xhtml`，裸 `//ul/li` 结果为空；
    查询前改写为 `*[local-name()='…']`。目录 `chapterList` 为 XPath 时 `getElements` 须序列化元素 HTML，
    以便后续 `tag.a@text` / `tag.a@href`。  
8. **作者/书名净化**：对齐 Legado `BookHelp.formatBookAuthor` / `formatBookName`。  
8b. **详情 `canReName`**（对齐 Legado-E `BookInfo`）：`mCanReName = canReName && ruleBookInfo.canReName` 非空；
   未允许时保留搜索带入的书名/作者，仅在为空时用详情规则填充。封面规则空时回退 `og:image`。

### 3.2 AnalyzeUrl（URL 与网络）

**职责**：解析**带规则的书源 URL**（`searchUrl`、`tocUrl`、`@js:` 整段 URL 等），合并 headers/body，发起请求，
返回 `StrResponse`。

#### 3.2.1 Legado 总流程（`initUrl`）

```mermaid
flowchart TD
  A[构造: 书源默认 header + loginHeader] --> B[analyzeJs]
  B --> B1[按 JS_PATTERN 分段]
  B1 --> B2[非 JS 段 @result 替换]
  B1 --> B3[evalJS 段 → 新 result]
  B --> C[replaceKeyPageJs]
  C --> C1["双花括号模板内 RuleAnalyzer.innerRule + evalJS"]
  C --> C2["<1,2,3> 页码占位"]
  C --> D[analyzeUrl]
  D --> D1["paramPattern: ,\\s*(?=\\{) 切 URL 与 JSON"]
  D1 --> D2[GSON → UrlOption]
  D2 --> D3[method / headers / body / webView / js…]
  D3 --> D4[option.js 可改写 url]
  D --> E{GET?}
  E -->|是| F[analyzeQuery 编码 query]
  E -->|POST| G[analyzeFields 编码 form body]
  F --> H[getStrResponse / WebView]
  G --> H
```

**`UrlOption.headers`（Legado）**：JSON 里
`"headers": { "app-version": … }` 反序列化到 `headers` 字段；`getHeaderMap()` 返回该 `Map`，
再逐项写入 `headerMap`。  
**规范写法**是嵌套 `headers` 对象；扁平 `{app-version, sign, …}` 在 Gson 严格模式下
**不会**映射到 `UrlOption`（非标准 JSON 可能走宽松 GSON）。

**`analyzeJs` 与 `@result`**：URL 形如 `prefix@js:脚本@resultsuffix` 时，脚本返回值替换 `@result`，
再与 suffix 拼接。

#### 3.2.2 ColorTxt 映射

| 步骤 | Legado | ColorTxt |
|------|--------|----------|
| 默认头 | `source.getHeaderMap` | `buildSourceRequestHeaders` + `resolveSourceRequestHeaders` |
| `analyzeJs` | `JS_PATTERN` + `evalJS` | `analyzeJs()` + `evalJsAsync`；整段 `@js:` URL 特判 |
| 模板 / 页码 | 整串 `replaceKeyPageJs` **后再**切 UrlOption；**不改写** `ruleUrl`（仍可含 `,{}`） | 同：模板后再 `splitUrlFetchOptions`；`ruleUrl` 保留 UrlOption，`url`/`urlPartForFetch` 才是请求路径 |
| URL 后缀 JSON | `UrlOption` + GSON | `parseLegadoUrlSuffixJson`（宽松 JSON / stringify body） |
| GET query | `analyzeQuery` + `encodedQuery` / `queryEncoder`（保留字面量 `+`） | 同：已编码 query 原样；否则整段 `encodeLegadoQueryString`（勿把 `+` 编成 `%2B`）；gorgon 签名头保留原 query |
| POST body | `analyzeFields`（非 JSON/XML） | 同 |
| 请求 | OkHttp（忽略证书）+ 可选 WebView | `fetchStrResponse` → Chromium `session.fetch`（忽略坏证书）；仅 UrlOption/`java.webView` 显式开 webView |
| 变量 | `ruleData.variableMap` | `ruleVariables`（search `@js` 与 bookList 共享） |
| 单结果详情 | `BookList.getInfoItem`：`bookUrl=getAbsoluteURL(url, ruleUrl)`（可含 POST）；`infoHtml=body` | 同；`getBookInfo` 优先用 `infoHtml`；`tocUrl==bookUrl` 时写 `tocHtml`，目录免二次 GET；正文 `nextContentUrl` 遇下一章 URL 即停 |

模板 / UrlOption 注意：

- **禁止**先拆 `,{}` 再模板展开（否则 ``{{java.connect(`…,{…}`)}}`` 会在模板内被截断）。  
- **`getUrl` 保留跨行 UrlOption**；请求前剥离须用 `,\s*(?=\{)`。  
- 普通 GET/POST 均走 Chromium `session.fetch`（浏览器 TLS 指纹）；仅书源显式 `"webView":true` / `java.webView` 才开隐藏窗。  
- object body 须 `JSON.stringify`，勿 `String(obj)`→`[object Object]`。  
- webView 加载遇 `ERR_TIMED_OUT`（-7）时不立刻失败，仍等 `did-finish-load` 或总超时（部分站超时事件后仍出正文）。  

**URL 形态示例**：

```
https://example.com/search?q={{key}}
https://example.com/api,{"method":"POST","body":"k={{key}}","charset":"gbk"}
https://example.com/page,{"headers":{"sign":"…"},"method":"POST"}
https://example.com/page,{"webView":true,"webJs":"document.body.innerHTML"}
data:text/html;charset=utf-8,<html>...</html>
```

**带签名 header 的 API 书源典型链路**（无书源特例，仅说明引擎协作）：

1. `searchUrl` 的 `@js`：`java.put("headers", JSON.stringify({headers}))`
   → 写入 `ruleVariables`。  
2. `ruleSearch.bookUrl` / `ruleBookInfo.tocUrl`：`{{…}}` +
   `+ "," + java.get("headers")` → `AnalyzeUrl` 解析后缀 JSON → `headerMap` 带 sign。  
3. `ruleBookInfo.init`：对齐 Legado，先以**原始响应字符串**作 `result` 执行
   （部分书源 jsLib 的 `isHtmlString`/`isJsonString` 依赖字符串；预解析成对象会
   `str.startsWith is not a function`）；`@js` 返回 **对象** → `setContent(对象)`，
   后续 `@json:`/`$.` 规则作用在该对象上（禁止 `String(init)`）。  
4. `ruleToc.chapterList`：对 init 后的 JSON 走 `getElements` / JsonPath。

**处理顺序**（`ensureUrlReady`，对齐 Legado `initUrl`）：

1. 合并书源 / 登录 headers  
2. `analyzeJs`（内联 `@js` / `<js>`，`@result`）  
3. `replaceKeyPageJs`（`{{key}}` / `{{page}}` / 内嵌 JS / `<页码列表>`）  
4. `analyzeUrl`（`,{"method":…}` → options，绝对 URL，GET/POST 域编码）  
5. `fetchStrResponse`（并发率、proxy、Cookie）  
6. 可选 `webJs` / 调用方传入的 `ruleContent.webJs`

**并发与代理**

- `concurrentRateLimiter.ts`：书源 `concurrentRate`（如 `1500` 或 `20/60000`）；
  未配置时默认每源最多 **3** 路进行中请求（防 async map / 其它并行路径打爆站点）。  
- `httpProxy.ts`：从 header 的 `proxy` 字段提取，支持 http/socks4/socks5；找书设置「代理」
  提供全局默认（书源 header / URL `proxy` 优先）。

### 3.3 webBook（业务编排）

文件：`engine/webBook.ts`

| 函数 | 规则字段 | 要点 |
|------|----------|------|
| `searchBook` | `searchUrl`, `ruleSearch` | loginCheck；列表字段顺序对齐 Legado（kind 先于 bookUrl） |
| `exploreBook` | `ruleExplore` | 与搜索共用列表解析；仅跑 `loginCheckJs`（**不**跑无脚本时的登录页启发式，对齐 Legado）；**不用** `bookUrlPattern` 判详情（仅搜索用） |
| `getBookInfo` | `ruleBookInfo` | loginCheckJs；kind / 封面；`tocUrl`（`isUrl=true`）；`stripNumericIdPrefix` |
| `getChapterList` | `ruleToc` | loginCheckJs；完整 `Book`；`preUpdateJs`；路径折叠；反转 / `formatJs` / 去重 |
| `getChapterContent` | `ruleContent` | loginCheckJs；完整 `Book`；多页 / `subContent` / `title` / `replaceRegex`；规则 JS/解密失败向上抛并返回「获取正文失败」；非分卷正文为空抛「内容为空」 |

`getChapterList` 补充：

- `setBook(toEngineBook(book))`；`preUpdateJs` 对齐 Legado（`java.refreshTocUrl` /
  `java.reGetBook` 可刷新 tocUrl）。  
- http(s) 路径折叠 `//`（如 `{{baseUrl}}/catalog/` + 尾斜杠详情址）。  
- `nextTocUrl` 的 `@js` 返回 URL 数组时原样拉取。  
- `isVolume` 规则为空时，仍识别 JS 目录项上的 `isVolume` 字段；合成 url（标题+序号）的分卷章不跑正文规则。  

`getChapterContent` 补充：防御性修补 ads-read 空/错误 `BookID`；AES 空密文对齐 Hutool 抛错（勿静默空串）。  

#### 3.3.1 封面代理与 HEIF/HEIC 转换

文件：`engine/coverImage.ts`  
依赖：`heic-convert`（`package.json`）；类型声明 `src/main/types/heic-convert.d.ts`。

搜索 / 详情 / 书架等拿到的原始 `coverUrl` 往往是站方直链（含防盗链、Cookie、URL 后缀 headers）。主进程统一走封面代理后再给渲染进程显示：

- **搜索 / 发现列表**：解析时**不**预拉封面，只保留 HTTP 源链；
  列表侧 `useBookshelfCoverUrls` 仅对 VirtualList **可见窗**（含 overscan）
  异步 `bookSourceResolveCoverDisplay`，并限制并发（默认 4）；瞬时失败冷却后可对可见项再试，
  避免多源大结果一次打满 IPC/网络导致封面永久占位。
- **书架列表**：无虚拟窗时仍解析当前列表全部项，同样走并发上限。
- **详情页**：`getBookInfo` 会拉取并代理封面；`img@src.0` 等结果下标须正确解析，
  且详情规则为空时应回退列表源链再代理（勿把未代理的 HTTP 直链交给渲染进程）。

| 步骤 | 说明 |
|------|------|
| URL 规范化 | `coverDecodeJs`（若有）→ 绝对 URL；解析 URL 后缀 JSON 中的 headers |
| 拉取 | 合并书源 / 登录头 + Cookie Jar + 默认 UA |
| MIME 识别 | 优先 `Content-Type`；`octet-stream` 时用魔数嗅探（含 HEIC `ftyp`） |
| **HEIF/HEIC 转换** | 多数无法直接解码；`heic-convert`→JPEG（0.92）；失败再试 `nativeImage`；仍失败则跳过 |

封面 MIME / HEIC 补充：魔数含 `ftyp` + `heic`/`heix`/`mif1` → `image/heic`；Windows 上 `nativeImage` 通常仍失败。  
| 本地协议 | 成功后经 `registerRemoteCoverBytes` 挂到 `colortxt-local:`，UI 只加载该代理地址 |

要点：

- 书架可持久化 **HTTP 源 URL**（`coverSourceUrl`），需要时再拉一遍并转换；展示用 URL 仍是 `colortxt-local:`。
- 日志常见条目：`HEIC 转 JPEG 失败: …`、`封面 HEIC 无法解码，已跳过`。
- 正文插图规则（`imageDecode` 等）**不走**此路径；当前仅**书籍封面**做 HEIF 转码。
- 默认规则末段支持 `@src.0` / `@href.0`（先取全部匹配再按下标截取，与 `img.0@src` 同效）。

### 3.4 JavaScript 运行时

书源中的 `jsLib`、`@js:`、`<js>`、`loginUrl` 等均在主进程用 Node **`AsyncFunction`** 执行（非 Rhino JVM）。

| 模块 | 作用 |
|------|------|
| `rhinoRuntime.ts` | `evalJs` / `evalJsAsync`；注入 java/source/book/chapter/result… |
| `legadoAsyncJs.ts` | 自动 `await` 注入与 `async` 提升（见下） |
| `sharedJsScope.ts` | `jsLib` 共享作用域；同域执行 `header`/`@js`/`loginCheckJs`（避免原生 `Map`） |
| `legadoJavaShims.ts` | `Packages.*` / `JavaImporter`；`UUID.randomUUID()`、`android.os.Build` 等可字符串化桩；未实现路径深代理带 `@@toPrimitive`（避免 `String(Packages…)` 抛错） |
| `legadoJsoupShim.ts` | `org.jsoup.Jsoup.parse` / **`Jsoup.connect(url).get()`**（异步拉页→Document，规则侧自动 `await`；勿 spawnSync 以免搜索卡 UI）；Elements `.text`/`.attr`/`.select` |

`legadoAsyncJs.ts` 要点：

- 自动 `await java.ajax` / `java.post` / HTTP 形态 `java.get` / `java.webView` /
  `java.getStrResponse`（loginCheckJs）等。  
- 将含 `await` 的函数提升为 `async`，并对 jsLib / **loginCheckJs 中经 `java.put` 导出的**
  异步方法名（如 `util.login`）在规则脚本里注入 `await`。  
- `await fn()()` / `await fn()[i]`：须包成 `(await fn())()`，否则对 Promise 再调用会报
  `is not a function`（发现页 `handlerFactory()()` 一类）。  
- 回调形参调用补 `await`（如 `cacheGetAndSet(key, supplyFunc)` 内 `supplyFunc()`），
  避免把 Promise 当结果写入缓存。  
- `arr.forEach(async …)` 改写为串行 `__legadoForEachSerial`（对齐 Rhino 同步阻塞）。  
- 括号匹配跳过注释/正则（避免大 jsLib 提升死循环）。  
- Rhino 箭头参数、`return` 补全：单行多语句如 `java.put(...);result` 只对末句加 `return`；
  不误改 `continue`/`break`；末行带尾部分号的多语句（如 `sign=md5(); r=…; url+r;`）须先去掉
  行尾分号再认最后一句，否则会 `return sign=md5();` 提前结束。  
- 正则字面量 `\ ({n,m}`（`\` + 空格 + `({n,m}`）改写为 `( {n,m}`，避免 V8 `Nothing to repeat`
  （部分正文剥标签规则在 Rhino 可跑）。  
- `function f(key){ let key = … }`：Rhino 允许形参与 `let`/`const` 同名；V8 会 SyntaxError 导致整段
  `jsLib` 加载失败（如 `check_token` 未进入共享作用域）。预处理将冲突形参改名。  
- jsLib 函数 bind 到共享沙箱，使 `const { java, source } = this` 在 async 严格模式下仍可用。  
- 尾部 `(()=>{…})();` IIFE 须 `return (()=>…)()`，勿 `return })();` 触发 ASI。
  脚本为「顶层函数声明 + 尾部 IIFE」时（部分书源 bookList `(() => { return handlerFactory()() })()`），
  向上回溯 IIFE 起始行（前一非空行须以 `;`/`}` 结束且整段通过语法探测）整体补 `return`，
  否则脚本返回 undefined、IIFE promise 脱管（分类「暂无书籍」+ UnhandledRejection）。  
- **顶层 `try/catch` 分支末尾表达式亦补 `return`**，否则 tocUrl 类脚本返回 undefined。
- 脚本已声明 `let/const/var result` 时，List API 前置只读 `globalThis.result`（勿 `typeof result`，会踩 TDZ）。

**超时**（`bookSourceJsTimeout.ts`）：同步 CPU 超时 30s（`vm` timeout，防死循环卡主进程）与
异步墙钟超时 180s（`raceWithJsTimeout` + deadline，覆盖 bookList 内几十次串行 `java.ajax`
补拉详情的场景）分离；Legado/Rhino 无整段 JS 超时，只有单请求超时（我们单请求 20s）。
环境变量 `BOOK_SOURCE_JS_TIMEOUT_MS` / `BOOK_SOURCE_JS_WALL_TIMEOUT_MS` 可覆写；
搜索另有 searchService 单源 30s 兜底。

**脚本内可用绑定**（与 Legado 对齐，名称一致）：

- `java`、`source`、`book`、`chapter`、`result`、`baseUrl`、`key`、`page`
- `book.variable` / `chapter.variable` 对齐 Legado 为**字符串**字段（可 `book.variable=""` 再 `+=` 累加正文）；
  不可做成普通 Map 对象，否则 `+=` 会得到 `[object Object]`（如部分书源）
- `cookie.*`、`cache.*`
- 正文规则额外注入：`nextChapterUrl`（`setNextChapterUrl` 后）

### 3.5 jsExtensions（java.* 实现）

文件：`engine/jsExtensions.ts`

已实现的主要接口（节选）：

| API | 说明 |
|-----|------|
| `java.ajax(url)` | GET/POST + URL 后缀 JSON，返回 body 字符串 |
| `java.ajaxAll(urls)` | 并发请求，返回 `StrResponse[]`（`.body()`） |
| `java.get(url, header?)` | HTTP `get`（`.body()` 等）；兼 `java.get("key")` 读变量 |
| `java.webView` / `webViewGetOverrideUrl` | 隐藏窗；等待 / 挑战页轮询；SSL 放行；退出强制销毁 |

`java.webView` 补充：

- `did-finish-load` 后再等 `1000 + webViewDelayTime` ms。  
- 遇 JS 挑战页（如 `fffffffffffffffffff` / 短 `probe.js`）继续轮询至正文。  
- `did-fail-load` 须区分 `isMainFrame`：子框架（广告/统计 iframe）失败不可判整页失败，
  否则取登录态的 webView 调用永远拿不到正文，已登录仍反复弹登录框
  （Android WebView 子资源失败同样不中断页面）。
  终端 `electron: Failed to load URL: …` 若来自子框架即此类被墙日志，属噪音。  
- 加载前先清 session 该域残留、再把 CookieJar 注入 session（**域级 Cookie**，
  `domain: eTLD+1`）：host-only 注入既不匹配子域，也可能遮蔽同名 `.domain`
  登录 Cookie；勿用 `extraHeaders` 发 Cookie（只影响首个请求，页面 AJAX 仍走
  session，见 §3.7 Cookie 一致性）。  
- 末窗关闭 / `before-quit` 时强制销毁，避免进程挂起。  
| `java.createSymmetricCrypto` / `aesDecodeToString` / `desEncodeToBase64String` / `tripleDESEncodeBase64Str` 等 | AES/DES/3DES 加解密（3DES 快捷 API 为 `mode`+`padding` 五参，非整段 transformation） |
| `java.startBrowserAwait` | 打开验证浏览器窗口 |
| `java.getUserAgent` / `java.getWebViewUA` | 请求 UA vs WebView/Chromium UA（须区分；部分书源用相等性检测「源阅」） |
| `java.getVerificationCode` | 图片验证码（渲染进程弹窗） |
| `java.toast` / `java.longToast` | IPC → `AppToastHost` → `appToast`（`kind: none`，无图标；`\n` 换行；多行按行数拉长展示）；日志记 `[toast]` |
| `java.refreshBookUrl()` | 返回详情最终 URL（`redirectUrl`/`res.url`）供 `tocUrl`；原 `bookUrl` 带 UrlOption 时不覆盖，以免丢掉搜索 POST |
| `java.readBookConfig` / `getReadBookConfig` 等 | **洛雅橙分叉**桩（官方 Legado 无）；返回 `"{}"` / `{}`，仅满足 `typeof` 存在性检测 |
| `java.importScript` / `cacheFile` / `readTxtFile` | 脚本导入 |
| `source.get` / `source.put` | 书源变量缓存 `v_{url}_{key}` |
| `source.putConcurrent` | 运行时修改并发率 |
| `source.getLoginInfoMap` | 对齐 Legado-E：**永不返回 null**，无登录信息返回空 Map（部分书源正文规则直接 `map.xx = …` 赋属性，返回 null 会抛 `Cannot set properties of null`）；Legado-E 无信息且有 `loginUi` 时还会以非 button 行的 default 值播种，此处未实现 |
| `source.putLoginInfo` / `removeLoginInfo` | 整串 JSON 覆盖保存 / 清空 `book_source_login`；返回布尔（解析失败返 false，对齐 Legado） |

完整 StrResponse 形态见 `legadoStrResponse.ts`（`body()`、`url()`、`code()`、`headers()`、
`header(name)` 等）。

### 3.6 登录与验证

| 机制 | 文件 | 行为 |
|------|------|------|
| `loginUrl` / `loginUi` | `loginCheck.ts` | 执行登录 JS 或打开浏览器；搜索启发式见 `awaitLoginForSearchPage`（发现不用） |
| `loginCheckJs` | `loginCheck.ts` | 请求后检测；自动 await；搜索/发现/详情等均会跑 |
| 浏览器验证 | `sourceVerification.ts` | 可见 BrowserWindow + 内容 BrowserView；证书异常放行（对齐 Legado SSL proceed）；底栏「更多」系统菜单（复制 URL / DevTools）；Cookie 回写 |
| 图片验证码 | `sourceVerification.ts` + `AppCaptchaHost.vue` | IPC `captchaRequest` / `captchaReply` |
| 登录信息 | `bookSourceStore` | `book_source_login` 表 + `loginHeader` |

### 3.7 存储

`bookSourceStore.ts`（SQLite `better-sqlite3`）：

- **book_sources**：完整书源 JSON + enabled + last_update_time  
- **book_source_login**：`getLoginInfoMap` 字段  
- **book_source_cache**：`cache.get/put`、`source.get/put`  
- **book_source_cookies**：全局 Cookie Jar（`enabledCookieJar` 时带上）。
  键为**可注册域（eTLD+1，tldts）**而非完整主机名，子域共享（对齐 Legado
  `NetworkUtils.getSubDomain`）——登录常在 `accounts.example.com` 写 `Domain=.example.com`
  会话 Cookie、业务请求在 `www.example.com`，按主机名归档会取不到登录态，
  已登录仍反复弹登录框（会话 Cookie 如 `PHPSESSID` 类）；载入时须以
  `Domain=<eTLD+1>` 写回 jar（host-only 不匹配子域），持久化用 `serializeSync`
  枚举（`getCookiesSync(裸域)` 会漏子域 host-only Cookie）

Cookie 一致性（jar 为唯一权威，对齐 Legado「CookieStore + 全局 CookieManager」模型）：

- `ses.fetch` 默认 credentials 会用分区 session 的 Cookie **整体替换**显式
  `Cookie` 头（实测 Electron 35）——分区里积累的游客 Cookie 会把登录请求降级成
  游客（接口返 400）。书源 HTTP 须 `credentials:'omit'`：显式头原样发出，
  响应 `Set-Cookie` 仍可读（回写 jar），且不污染 session。
- 后台 webView 加载前**清掉 session 里该域残留再种入 jar**。曾用
  `extraHeaders` 发 Cookie：只作用于首个请求，页面内 AJAX 走 session（空）→
  站点发回游客会话 → `persistWebViewCookies` 把游客 Cookie 覆盖回 jar，
  登录态被静默摧毁。
- 登录窗确认 / webView 结束回写 jar 后须 `cookies.flushStore()`：Chromium
  Cookie 异步落盘（~30s），dev 重启 / 崩溃会丢刚登录的会话。
- 登录态 PHPSESSID 形如 `{userId}_{hash}`，纯 32 hex 为游客——排查「带了
  Cookie 仍 400/未登录」时先看 jar 里该值的形态。

---

## 4. 数据结构

### 4.1 书源 JSON（BookSourceRecord）

类型定义：`src/shared/bookSource/types.ts`

仅 **`bookSourceType === 0`（文本）** 会被导入与启用；其他类型在 `normalizeBookSource` 时过滤。

**顶层常用字段**

| 字段 | 说明 |
|------|------|
| `bookSourceUrl` | 唯一键，书源标识 |
| `bookSourceName` | 显示名 |
| `searchUrl` | 搜索地址，含 `{{key}}` `{{page}}` |
| `exploreUrl` | 发现分类（URL、`@js:`，或 JSON 数组；`url` 内可含多行 `@js:`，按 GSON 宽松解析） |
| `header` | 静态或 `@js:` 动态 JSON 请求头 |
| `loginUrl` / `loginUi` / `loginCheckJs` | 登录 |
| `jsLib` | 全局 JS 函数库 |
| `concurrentRate` | 并发率限制 |
| `enabledCookieJar` | 启用 Cookie |
| `ruleSearch` / `ruleExplore` / `ruleBookInfo` / `ruleToc` / `ruleContent` | 各阶段规则 |

**ruleSearch / ruleExplore（列表）**

`bookList`, `name`, `author`, `coverUrl`, `bookUrl`, `intro`, `kind`, `wordCount`,
`lastChapter` …

**ruleBookInfo（详情）**

`init`, `name`, `author`, `tocUrl`（可为 `java.refreshBookUrl()`）, `coverUrl`, `intro`,
`kind`, …

**ruleToc（目录）**

| 字段 | 说明 |
|------|------|
| `preUpdateJs` | 拉目录前执行；可调 `java.refreshTocUrl()`（重拉详情写 tocUrl）、`java.reGetBook()`（精确搜索后再拉详情） |
| `chapterList` | 列表规则；`-`：页面已是倒序（新→旧），不再反转；无 `-`：反转一次使数组「最新在前」（UI 正序再翻回旧→新） |
| `chapterName` / `chapterUrl` | 支持裸 `text` / `href` |
| `formatJs` | 目录完成后格式化标题（`index`/`title`/`chapter`/`gInt`） |
| `nextTocUrl` | 目录翻页 |
| `isVolume` / `isVip` / `isPay` | 分卷 / VIP / 付费标记；`isVolume` 规则可空——JS 列表项自带 `isVolume:true` 时仍识别 |

**ruleContent（正文）**

| 字段 | 说明 |
|------|------|
| `content` | 正文 HTML/文本规则 |
| `title` | 正文页章节名（优先于 `chapterName`） |
| `nextContentUrl` | 正文分页；去重后 1 个 URL 串行、多个并发。对齐 Legado：若下一页 URL 等于 `nextChapterUrl`（或目录中其它章）则停止。页头/页脚重复下一页链须先去重，否则会误走并发并把下一章拼进本章 |
| `webJs` | WebView 执行 JS（请求后或 ruleContent 级） |
| `sourceRegex` | 响应体正则裁剪 |
| `subContent` | 副正文，拼接到正文后 |
| `replaceRegex` | `##` 行替换或整条规则替换 |

### 4.2 运行时对象

```typescript
// 搜索 / 发现列表（展示 DTO）
SearchBookItem { id, name, author, bookUrl, origin, originName, coverUrl?, kind?, ... }

// 权威对象（对齐 Legado Book；列表经 searchBookToBook，详情完善同一份）
Book {
  name, author, intro, coverUrl, kind, tocUrl, bookUrl,
  coverSourceUrl?, wordCount?, lastChapter?, updateTime?,
  origin?, originName?, variable?,
  infoHtml?, infoUrl?, tocHtml?
}

// 目录项
BookChapter { title, url, isVolume, isVip, isPay? }

// IPC：目录 / 正文只收 book
BookSourceGetChapterListPayload = { bookSourceUrl, book: Book }
BookSourceGetChapterContentPayload = { bookSourceUrl, book: Book, chapterUrl, ... }
```

辅助：`src/shared/bookSource/bookModel.ts` — `searchBookToBook`（`tocUrl` 空，待详情补全）
/ `stripNumericIdPrefix` / `toEngineBook` / `coerceBook`（引擎入参）。
书架：`BookshelfBook = Book & 进度字段`；无 `tocUrl` 则先 `getBookInfo`，有目录缓存则直开。

---

## 5. IPC 接口

定义：`src/shared/bookSource/ipc.ts`  
注册：`src/main/bookSource/registerBookSourceIpc.ts`  
渲染封装：`src/renderer/src/bookSource/composables/useBookSource.ts`

| 通道 | 用途 |
|------|------|
| `bookSource:list/get/save/delete/toggle/reorder` | 书源 CRUD |
| `bookSource:importPreview/importCommit` | 导入预览与提交 |
| `bookSource:fetchUrl/readFile` | 网络/本地 JSON 导入 |
| `bookSource:search` + `searchEvent` | 搜索（可取消） |
| `bookSource:download` + `downloadEvent` | 整书下载或仅离线缓存（`cacheOnly`，可取消） |
| `bookSource:exploreKinds/exploreBooks` | 发现 |
| `bookSource:getBookInfo/getChapterList` | 详情与目录 |
| `bookSource:getChapterContent` | 章节正文（默认优先 book_cache；`preferCache: false` 强制联网并回写） |
| `bookSource:chapterCacheStatus` | 查询已缓存章节 URL |
| `bookSource:saveChapterCache` | 写入/覆盖单章离线正文缓存 |
| `bookSource:clearChapterCache` | 按书清除离线章节缓存 |
| `bookSource:clearAllChapterCache` | 清除缓存目录下全部章节离线缓存 |
| `bookSource:checkSource` 等 | 校验书源 |
| `bookSource:login/browserLogin/getLoginInfo/...` | 登录 |
| `bookSource:captchaRequest/Reply/Dismiss` | 验证码 |

搜索 / 下载为**异步事件流**：先返回 `searchId` / `downloadId`，再通过 `webContents.send` 推送进度与结果。

---

## 6. 使用说明（功能面）

### 6.1 窗口与入口

- **更多 → 找书** / `F7`：打开（或聚焦）找书独立窗口。
- 顶栏「主界面」回到主窗口；可创建桌面快捷方式；命令行 `--find-book[=bookshelf|search|discover]`。
- 找书窗口自带设置 / 主题 / 书源管理 / 免责声明。
- 找书设置标签：「下载」「阅读」「编辑」「代理」（网络代理，见 §6.11）。
- 仅找书窗口启动时也会按主设置里的快捷键绑定调用 `setGlobalShortcut`（「隐藏/显示阅读器」等系统级热键），不依赖主窗口挂载。

### 6.2 书源管理

- **导入**：本地 `.json`、网络 URL、或剪贴板 JSON（Legado 导出格式，数组或单对象）；后两者与本地导入相同，走导入预览再提交。
- **新建**：无有效 `customOrder` 时插入书源列表顶部（与「置顶」相同：`customOrder = min - 1`）；导入若自带序号则保留。
- **编辑**：分标签表单（基本 / 搜索 / 发现 / 详情 / 目录 / 正文…）；阅读器顶栏「编辑书源」默认打开「正文」。  
  - 「更多」含 **登录**（有 `loginUrl` 时）、**搜索**（先保存草稿再限定该书源搜索，并关闭叠层）、清除 Cookie、**复制源 / 粘贴源**、
    设置源变量。  
  - 粘贴源仅填表单，须点确定才保存（对齐 Legado）。  
  - 有未保存改动时关闭面板会确认（`AppModal` `beforeClose` + `appConfirm`）。  
  - **内联高亮**（对齐 legado-E `CodeView`，**非**每字段 Monaco）：规则 / JS / JSON 候选字段用
    `HighlightedCodeTextarea`（透明 textarea + 叠层）；纯元数据（书源名/URL/分组/注释等）仍用
    `AutoResizeTextarea`。正则着色见 `highlightBookSourceCode.ts`（超长 ≥8192 跳过着色；短文本即时、
    长文本防抖 500ms）；Enter 自动缩进对齐 CodeView；约 10 行后滚动
    （`EDIT_BOOK_SOURCE_TEXTAREA_MAX_HEIGHT_PX`）。主题色 `--bs-hl-*`（`style.css`）。  
  - **全屏单字段 Monaco**（标签右侧「源码」图标，仅高亮候选字段）：`BookSourceFieldMonacoModal`
    动态 `import("monaco-editor")`，确认写回表单；返回放弃、有改动则确认；无页脚，顶栏返回 / 确定。
    右键：剪切 / 复制 / 粘贴 / **格式化**（`js-beautify`，对齐 legado-E；整段 JS 或抽出
    `<js>` / `@js:` / `@webjs:`）；查找替换用 Monaco 内置。语言推断
    （`bookSourceFieldMonacoLanguage`）：`loginUi`/`header`→`json`；`bookUrlPattern`/
    `sourceRegex`/`replaceRegex`→`plaintext`；**其余→`javascript`（着色）**——关闭 JS/TS
    诊断，避免规则 DSL（`{{ }}` / `$..` / `##`）红波浪线误报。
    **JS 字段**另挂内置运行时 API 智能提示（`ensureBookSourceMonacoLibs` +
    `bookSourceRuntimeLib.ts`：`java` / `source` / `book` / `cache` / `cookie` / `result` 等），
    并开启 hover / 参数提示；不含完整 `Packages.*` / Jsoup。  
- **启用 / 排序 / 分组 / 登录 / 校验**：默认仅启用文本源参与搜索；**特指某一书源搜索**（`sourceUrls`）时不要求该源已启用；
  校验走 `checkSourceService`。
- 列表底栏勾选计数为 **当前筛选结果中已勾选数 / 当前显示数**（被过滤掉的不计入）；批量删除/导出/启停等亦仅作用于当前显示中的勾选项。
- 「过滤书源」文本框仅匹配 **书源名**（`bookSourceName`，不含分组等）。

### 6.3 找书（搜索）

- 多源并发；可选精准搜索、限定单一书源（限定后即使该书源未启用也会搜索）。
- 搜索历史本地保存；点结果进**书籍信息**。
- 空状态：  
  - 未搜索且无启用搜索源：`(; '⌒' )`「没有可用搜索源哦」  
  - 未搜索且有源：`(•◡•)و`「想找什么书呀」  
  - 有源搜完无结果：「没有找到相关内容哦」  
  - **特指书源**视为「有搜索源」（文案与有启用源一致）  
  - 无启用搜索源且未特指时不发起搜索、不显示进度栏。  

### 6.4 发现

- 需配置 `exploreUrl` 且 `enabledExplore !== false`；按书源切换分类与列表。  
- 展开书源行：右侧 **搜索**（限定该书源找书）、**更多**（编辑书源 / 置顶到书源列表 / 禁用发现）；未展开时仅 hover / 聚焦时显示。
- 无可发现书源 / 筛选无匹配时居中空状态提示（`(; '⌒' )` +「没有内容哦」）。

### 6.5 书架

- 数据键：`colortxt:findBookBookshelf`（含加入时间、最后阅读、更新时间、可选 `chapters`/`tocUrl` 缓存）。
- 点封面/标题可直接开读：先开阅读器（`tocLoading`），后台解析目录后再进正文；**不**再叠全屏书架过渡层。
- 行「更多」可进书籍信息、**书源搜索**（限定该书 `origin` 书源，切到找书并聚焦搜索框）、更新、移除等。
- 工具栏：筛选、排序、全部更新、书架管理、更新日志。
- 空书架：`(•◡•)و`「书架还空着，先去搜索书籍或从发现里添加吧」（样式与找书/发现空状态一致）。

### 6.6 书籍信息（详情）

- 封面、简介、目录（正/倒序）、加书架、开始/继续阅读、一键下载。
- 目录项：最后阅读标记、已缓存勾标；下载中章用 `LoadingDotsRotate`。
- 顶栏操作（有内容时）：**日志**（有日志/错误才显示）→ **刷新** → **编辑书源** → **登录**（书源配置了 `loginUrl`）→ **更多**。
  - 「刷新」：重新拉详情 + 目录；仅**点击刷新**时 `RefreshIcon` 旋转，初次进入加载不转。
  - 「更多」：复制书籍/目录 URL、设置源变量、**清除缓存**（warning）。
- 加载文案用「加载中」+ `LoadingDotsBounce`（不用省略号）。

### 6.7 在线阅读器

- 复用主应用阅读能力：字体/行距/主题/语音/全屏/定时滚屏等（找书阅读设置）。
- 底栏（`FindBookReaderFooter`）：左侧可挂番茄时钟（与主界面同款，设置在找书「阅读」页；关闭阅读器时自动停止）；右侧展示 `阅读进度：{章进度%}（{正序章号}/{总章数}，{当前行}/{总行}）` 与 `当前章节字数`（去空白后 `formatCharCount`）；章进度按阅读正序下标相对总章数计算（与主界面按全文行/滚动进度不同）。全屏时与章节导航一并收入底栏浮层（贴底感应显隐，同主界面）。
- **侧栏开关** `showSidebar` 写入 `colortxt.findBook.settings`（可从主界面种子复制）；打开阅读器时若正文章节仅 1 章则**临时**收起侧栏（不改持久化），用户手动切换后仍会持久化。
- **目录附加信息** `showChapterTag`（`BookChapter.tag` / `ruleToc.updateTime`）默认关闭；详情页「目录」与阅读器侧栏「章节」旁可切换，写入同一找书设置。
- 阅读工具栏：支持「编辑模式」与「保存」（写入当前章 `book_cache` 缓存文件；无「智能排版」）。内存中始终保留原文；**编辑模式直接编辑原文**（不跑文本替换/转换）
  ；阅读态经展示管线再渲染。
- 设置「编辑」：仅「显示行号」「启用小地图」（均默认关闭）。
- 侧栏目录同步缓存勾标；切到已缓存章可直接读本地，不写联网 UI；未缓存章显示「加载中」与侧栏旋转点。
- 侧栏标题「章节」旁：**重新获取目录**（只更新 TOC，不重拉正文）。
  - 对比最新章：无变化 toast「无变更」（info）；有变化 toast「目录已更新，最新章节：xxx」（success）。
- 侧栏右侧：**离线缓存**（`cacheOnly` 下载，进度条 + 停止）、正/倒序。
- 顶栏操作：**日志**（可选）→ **刷新**（强制重拉**当前章**正文，`preferCache: false`）→ **编辑书源**（默认定位正文）
  → **登录**（可选）→ **更多**（书籍信息 / 清除本书缓存）。
  - 顶栏刷新图标仅在用户点击后旋转（`refreshingChapter`），普通切章不转。
- `RefreshIcon` / `LoadingDots*` 为可复用组件：图标只管静止/旋转，禁用由外层按钮处理。

### 6.8 缓存与下载（易混点）

| 概念 | 位置 | 作用 |
|------|------|------|
| **章节缓存目录** | 找书设置 → 下载 →「缓存」区块 | `book_cache/`，阅读与整书/离线缓存共用 |
| **清除全部缓存** | 同上「清除缓存」 | `clearAllChapterCache`，清空缓存根目录 |
| **下载（导出）目录** | 找书设置 → 下载 → 下载目录 | 导出的 `.txt` |
| **清除本书缓存** | 详情/阅读器「更多」 | 只删该书 `book_cache` 子目录 |
| **离线缓存（阅读器）** | 侧栏缓存按钮 | 只写章节缓存，不导出 `.txt`（`cacheOnly`） |
| **编辑保存（阅读器）** | 工具栏「编辑模式 → 保存」 | 覆盖当前章 `.nb` 缓存文件 |
| 主应用「清除缓存」 | 主设置 | **不是**书源章节缓存 |

整书「下载」交互仍是一键导出：内部先补全缓存再自动导出。导出完成后可按设置加入主窗口文件列表等（`findBookDownloadActions`）。
取消下载/离线缓存时 UI 立刻退出忙碌态（世代号打断）。

### 6.9 登录与验证码

- 书源 `loginUrl` / `loginUi`；**搜索**无 `loginCheckJs` 时遇登录页可弹浏览器或验证码（发现分类不跑此启发式，对齐 Legado）。
- 浏览器登录窗：证书异常放行（对齐 Legado）；底栏「更多」为纵向三点图标，点击弹出系统菜单（复制 URL / 开发者工具）。
- 验证码 UI：`AppCaptchaHost`（找书窗口与主窗口均可挂载）。
- VIP 购买：阅读器在「登录」左侧显示「购买」（需 `loginUrl`，且当前章 `isVip && !isPay`）；确认后执行
  `ruleContent.payAction`（对齐 Legado `ReadBookActivity.payAction`）。

### 6.10 文本替换（全局 ReplaceRule）

对齐 Legado「替换净化」；与书源 `ruleContent.replaceRegex` **相互独立**。语义上与「转换」（简繁/全半角）同类，**仅阅读展示管线**套用：

| 层级 | 作用时机 | 持久化 |
|------|----------|--------|
| 书源 `replaceRegex` | 联网解析正文时 | 写入章节缓存 |
| 全局文本替换 | **仅阅读展示**（在「转换」之前） | 渲染进程 localStorage（找书 / 主窗分键）；**不**写入缓存；**整书导出不套用** |

阅读展示顺序：`文本替换 → 转换（简繁/全半角）→ 压缩空行 / 首行缩进`。

- 入口：主窗口 / 找书阅读器工具栏「文本替换」（`ReplaceRulePanel`）。  
  - **分键 localStorage**：找书 `colortxt:replaceRules:findBook`、主窗口
    `colortxt:replaceRules:app`。  
  - 兼容导入 Legado `replaceRule.json`（本地 / 网络 / 剪贴板）。  
- 「替换为」在**使用正则**时支持 `@js:`：对齐 Legado `RegexExtensions.replace`。  
  - 每次匹配执行脚本，绑定 `result` = 本次匹配文本，返回值作替换结果。  
  - 非正则仍为字面量替换。  
  - 渲染进程 CSP 含 `'unsafe-eval'` 以允许 `new Function`（仅执行用户自备规则）。  
- 纯函数：`@shared/bookSource/replaceRuleApply.ts`。  
  - 找书：`FindBookReaderPanel.renderChapterText`。  
  - 主窗口：`useTxtStreamPipeline`（格式化之后、「转换」之前）。  
- 找书规则编辑支持 **替换范围 / 排除范围**（可选，书名或书源 URL；对齐 Legado `scope` / `excludeScope`；主窗口编辑面板不展示这两项）；
  找书阅读按当前书的 `name` / `origin` 过滤启用规则。
- 找书管理面板规则列表展示 **替换范围** 列（空显示「全部」）；主窗口列表不展示该列。
- 管理面板：增删改/启停/导入先落本地草稿，点「保存」才 `commitReplaceRulesLocal` 写入对应键并派发本窗口变更事件；「关闭」不保存则丢弃未提交修改。
- **编辑模式**：工具栏按钮为「格式化：文本替换」；面板主按钮为「应用」= **保存规则** + 对当前编辑缓冲区套用已启用的正文替换规则（与「格式化：压缩空行 / 转换」
  同类，写回 Monaco）。
- IPC `getChapterContentWithCache` **只返回原文**（与缓存一致）；规则启停变更时重跑展示管线，不重拉章。
- **无总开关**：是否套用只看规则列表里是否有已启用项；主窗口 / 找书各自读对应 localStorage 键。
- **不预置**规则（对齐官方 Legado）；需要时自行新建或导入。

### 6.11 网络代理

- 入口：找书窗口「更多 → 设置 → 代理」。
- 支持 HTTP / SOCKS5 / SOCKS4；可选用户名密码；格式对齐 Legado `scheme://host:port[@user@pass]`。
- 持久化在 `colortxt.findBook.settings` 的 `proxy` 字段；确定后经 IPC 同步到主进程
  `httpProxy.setDefaultBookSourceProxy`。
- 生效范围：书源 `fetchStrResponse`（默认 undici，失败回退 Chromium `session.fetch`）与封面拉取；
  书源 header 或请求 opts 中的 `proxy` **优先于**全局设置。
  发请求前去掉 hop-by-hop 的 `Keep-Alive`（如部分书源 `Keep-Alive:""` 会触发 undici
  `invalid keep-alive header`）；**保留**其它空值头（部分 API 书源 `AUTHORIZATION=` 参与 sign）。
  `ERR_BLOCKED_BY_CLIENT` 时回退另一网络栈。
- 设置页「测试」：用当前草稿代理配置探测指定 URL（默认 Google；建议列表含 Google / GitHub）；未启用代理时直连探测。
- 显式 webView 隐藏窗等路径暂不走该全局代理（CookieJar 仍可共享）。
- 部分站点按 IP 拦截（如返回极短 `[STOP_IP]` / 403）：需在找书设置启用代理后才能搜到。

---

## 7. 规则能力与兼容范围

彩读目标是**高兼容 Legado 文本源**，但并非 100% 复刻 Android 端。实现与缺口对照如下。

### 7.1 已实现（核心）

- Default / CSS / XPath / JSONPath / 正则 / `@js` / `@webjs`
- URL 后缀 JSON：`method`、`body`、`headers`、`charset`、`webView`、`webJs`/`js`、
  `webViewDelayTime`、`bodyJs`、`proxy`。  
  - `body: '{"k":1}'` 等单引号写法经 `normalizeLegadoLooseJson` 解析。  
  - JSON body 默认 `Content-Type: application/json`。  
  - **须完整落盘到 fetch options**，否则 `{"webView":true}` 会退回普通 HTTP 只拿到 loading 壳。  
- `&&` / `||` / `%%`；`##` 正则替换（含首替-only 后缀）
- `@get:` / `source.put` / 书源变量；`jsLib` 共享作用域
- `java.ajax` / `ajaxAll` / `get`(connect) / WebView / 对称解密
- `loginCheckJs`、`startBrowserAwait`、Cookie、并发率
- 目录 `formatJs`、正文 `title`/`subContent`、多页 toc/content
- 封面：`colortxt-local:` 代理缓存；**HEIF/HEIC → JPEG**（`heic-convert`，见 §3.3.1）

### 7.2 部分实现或未实现

| 能力 | 状态 |
|------|------|
| `java.post` / `head` / `connect` 独立方法 | `post`/`connect` 已 await；`head` 仍待对齐 |
| `ajaxTestAll` | 未实现 |
| 正文 `imageDecode` / `imageStyle` / 富文本 HTML 净化 | 下载为纯文本，图片规则未完整处理 |
| 全局文本替换（ReplaceRule） | 已实现：管理 / 导入 / 阅读展示套用（导出 `.txt` 不套用）；正则「替换为」支持 `@js:`（`result` 绑定）；正则超时打断仍未对齐 |
| 正文 `@textNodes` | 已对齐：仅直接 Text 子节点 + `\n` 拼接 |
| `@text` 空白 | 对齐 JSoup `Element.text()`：块级/`br` 边界插空格，再把 code≤0x20 空白压成单空格（Cheerio 原样拼接会让榜单等 `##\S+\s+…` 失效） |
| `@html` / `@all` | 对齐 JSoup `Elements.outerHtml()`（含选中节点自身标签，`jsoupPrettyHtml.ts` 复刻 Jsoup 1.16.2 pretty-print：`<br>`/块级换行缩进、文本空白折叠）。**`@html` 会去掉 script/style**；**`@all` 保留**（正文规则常靠 body 内 `__INITIAL_STATE__`）。`script`/`style` 内容按 DataNode 原样写出。行边界决定 `##` 正则（不跨行）吃掉什么——分页导航须独占一行，否则同行正文末句被误删；勿用 innerHTML，否则简介首行常少换行 |
| `payAction`、VIP 章节购买 | 已实现：阅读器顶栏「购买」→ 执行 `ruleContent.payAction`（返回绝对 URL 开 WebView；真值则删章缓存并刷新目录/正文） |
| 正文懒加载 `nextPageLazyLoad` | 未实现（一次拉完多页） |
| 音频/视频书源 | 仅文本源 `type=0` |
| Cronet / DNS 强制 `dnsIp` | 未实现 |
| `@put:` 内联规则 | 部分支持，复杂写法可能对不齐 |

**排错建议**：以 Legado_Max 源码 + 帮助 md 为准；社区教程（喵公子、破冰）作规则语义与样例补充；用具体
`.json` 书源 + 主进程 `logs` 数组调试。

---

## 8. 开发说明

### 8.1 修改引擎后

主进程代码变更需**完全重启** `npm run dev`（非热更新）。

### 8.2 日志

各阶段向 `logs: string[]` 追加人类可读信息；错误经 `bookSourceErrorLog` 格式化。UI 在详情/搜索调试面板展示。

### 8.3 扩展 java API

1. 在 `jsExtensions.ts` 的 `javaBindings` 增加方法。  
2. 若需异步，确保 `legadoAsyncJs` 能注入 `await`（或方法返回 Promise）。  
3. 网络类优先复用 `fetchStrResponse` / `AnalyzeUrl`，以自动获得 Cookie、并发率、proxy。

### 8.4 扩展规则类型

1. `legadoRuleSplit.ts`：新前缀分段。  
2. `analyzeRule.ts`：`detectMode` + `getOne` 分支。  
3. 补充集成用例（`integrationSmoke.ts` 或真实书源 JSON）。

### 8.5 冒烟测试

```bash
npm run dev
# 或 npm run dev:find（仅找书窗口；详见 [开发构建.md](./开发构建.md)）
# 主进程 integrationSmoke（若已配置入口）或手动 F7 搜索测试书源
```

---

## 9. 模块依赖关系（简图）

```mermaid
flowchart TB
  UI[FindBookPanel + panels]
  IPC[registerBookSourceIpc]
  WB[webBook]
  AU[AnalyzeUrl]
  AR[AnalyzeRule]
  JS[jsExtensions + rhinoRuntime]
  ST[bookSourceStore]
  NET[fetchStrResponse]
  WV[backstageWebView]
  VER[sourceVerification]

  UI --> IPC
  IPC --> WB
  IPC --> ST
  WB --> AU
  WB --> AR
  AU --> NET
  AU --> WV
  AU --> JS
  AR --> JS
  AR --> WV
  NET --> ST
  JS --> VER
  WB --> VER
```

---

## 10. 相关文件索引

| 关注点 | 入口文件 |
|--------|----------|
| 类型与 JSON | `shared/bookSource/types.ts` |
| IPC 契约 | `shared/bookSource/ipc.ts` |
| 找书窗口启动 | `main/findBookLaunch.ts`、`FindBookWindow.vue` |
| 面板壳 / 叠层 | `FindBookPanel.vue`、`utils/modalStack.ts` |
| 书架 | `findBookBookshelf.ts`、`FindBookshelfPanel.vue`、`bookshelfOpenReader.ts` |
| 详情 / 阅读器 | `BookDetailPanel.vue`、`FindBookReaderPanel.vue` |
| 编辑书源 / 内联高亮 | `EditBookSourcePanel.vue`、`editBookSourceFields.ts`、`highlightBookSourceCode.ts`、`HighlightedCodeTextarea.vue` |
| 单字段全屏 Monaco | `BookSourceFieldMonacoModal.vue`、`formatBookSourceFieldText.ts`（`js-beautify`）、`monaco/bookSourceRuntimeLib.ts`（API 补全） |
| 章节缓存勾标 | `composables/useChapterCacheMarks.ts` |
| 清除缓存 UI | `services/clearBookChapterCache.ts`（单书 / 全部） |
| 找书设置 | `useFindBookSettings.ts`、`FindBookSettings*.vue` |
| 搜索 / 下载 | `searchService.ts`、`downloadService.ts`（含 `cacheOnly`） |
| 章节缓存 | `chapterCache.ts`、`getChapterContentWithCache.ts`（`preferCache`） |
| 封面 / HEIF | `coverImage.ts`（`heic-convert` → JPEG → `colortxt-local:`） |
| 加载 / 刷新图标 | `LoadingDotsBounce.vue`、`LoadingDotsRotate.vue`、`RefreshIcon.vue` |
| 单源 / 规则 / 网络 | `webBook.ts`、`analyzeRule.ts`、`analyzeUrl.ts` |
| IPC 封装 | `composables/useBookSource.ts` |

---

*文档随代码演进更新；若与 Legado 官方行为冲突，以 [legado-E（阅读Sigma）](https://github.com/Luoyacheng/legado-E) 仓库当前实现为准。*