# 在线搜索与阅读 — 源码架构总结 > 总结日期:2026-06-21 > 源码范围:`sakura_mobile/lib/src/core/` + `sakura_mobile/lib/src/pages/` > 说明:本文档梳理在线搜索→详情→目录→阅读全流程的现有源码结构,不做方案设计。 --- ## 目录 1. [文件清单与职责](#一文件清单与职责) 2. [核心类关系图](#二核心类关系图) 3. [Provider 依赖注入](#三provider-依赖注入) 4. [数据模型详解](#四数据模型详解) 5. [搜索引擎 LegadoEngine](#五搜索引擎-legadoengine) 6. [规则解析器 RuleParser](#六规则解析器-ruleparser) 7. [书源管理 SourceManager](#七书源管理-sourcemanager) 8. [统一搜索 UnifiedSearch](#八统一搜索-unifiedsearch) 9. [页面层源码](#九页面层源码) 10. [缓存与阅读记录](#十缓存与阅读记录) 11. [完整调用链路](#十一完整调用链路) --- ## 一、文件清单与职责 ### Core 层(核心引擎 + 数据模型) | 文件 | 行数 | 核心职责 | |------|------|---------| | `legado_models.dart` | 515 | 所有数据模型:`LegadoSource`、`OnlineBookInfo`、`OnlineChapter`、`OnlineChapterContent`、`OnlineReadingRecord`、`UnifiedSearchResult`、`SourceRepo` | | `legado_engine.dart` | 956 | 在线内容引擎:HTTP 请求、搜索、BookInfo 解析、TOC 解析、章节内容解析、编码处理、错误归一化 | | `legado_rule_parser.dart` | 262 | HTML/JSON/Regex 规则解析器:CSS 选择器、JSONPath、Regex 三种解析方式 | | `source_manager.dart` | 368 | 书源生命周期管理:导入、启用/禁用、订阅更新、健康检查、SharedPreferences 持久化 | | `unified_search.dart` | 173 | 统一搜索编排:合并云库搜索 + 在线书源搜索,返回 `SearchSection` 列表 | | `online_cache.dart` | 25 | 会话级内存缓存:BookInfo、TOC、ChapterContent 三级缓存 | | `online_reading_history.dart` | 57 | 阅读记录持久化:SharedPreferences 存储最近 50 条记录 | | `providers.dart` | 32 | Riverpod 依赖注入:5 个全局 Provider | | `api_client.dart` | — | 云端 API 客户端(搜索用 `gallery()` / `novels()`) | | `session.dart` | — | 会话管理(登录态) | ### Pages 层(UI 页面) | 文件 | 行数 | 核心职责 | |------|------|---------| | `explore_page.dart` | 503 | 在线搜索页:输入框、漫画/小说切换、结果列表展示、点击跳转 | | `online_book_detail_page.dart` | 338 | 在线书籍详情页(合并 BookInfo + TOC UI):封面、书名、作者、简介、章节列表、正序/倒序、继续阅读 | | `online_manga_reader_page.dart` | 208 | 在线漫画阅读器:PageView 图片浏览、上一章/下一章/目录导航、预加载、阅读记录 | | `online_novel_reader_page.dart` | 195 | 在线小说阅读器:文本展示、字体缩放、上一章/下一章/目录导航、预加载、阅读记录 | --- ## 二、核心类关系图 ``` ┌──────────────────────────────────────────────────────────────┐ │ providers.dart │ │ ┌─────────────┐ ┌──────────────┐ ┌───────────────────┐ │ │ │ Session │ │SourceManager │ │ LegadoEngine │ │ │ │ Controller │ │ (书源管理) │ │ (在线内容引擎) │ │ │ └──────┬───────┘ └──────┬───────┘ └────────┬──────────┘ │ │ │ │ │ │ │ ┌──────▼───────┐ │ │ │ │ │SakuraApiClient│ │ │ │ │ │ (云端API) │ │ │ │ │ └──────┬───────┘ │ │ │ │ │ │ │ │ │ ┌──────▼─────────────────▼────────────────────▼──────────┐ │ │ │ UnifiedSearch │ │ │ │ (编排:cloudFuture + onlineFuture → SearchSection) │ │ │ └────────────────────────┬──────────────────────────────┘ │ └───────────────────────────┼────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ ▼ ▼ ▼ ExplorePage OnlineBookDetailPage OnlineXxxReaderPage (搜索UI) (详情+目录UI) (阅读UI) ``` ### LegadoEngine 内部结构 ``` LegadoEngine ├── Dio _http ← HTTP 客户端(15s 连接超时,20s 接收超时) ├── OnlineContentCache cache ← 会话级缓存 │ ├── 搜索 ─────────────────────────── │ ├── search() ← 单源搜索(构建请求 → 获取响应 → 解析结果) │ ├── searchAll() ← 多源并发搜索(每批 10 个,Future.wait) │ ├── _buildSearchRequest() ← 构建搜索 URL + 编码关键词 │ ├── _applySearchTemplate() ← 替换 {{key}} / {{page}} 占位符 │ └── _fallbackSearchResults() ← 回退:扫描 标签 │ ├── 详情 ─────────────────────────── │ ├── fetchBookInfo() ← 解析书籍详情页 → OnlineBookInfo │ ├── 目录 ─────────────────────────── │ ├── fetchToc() ← 解析章节目录(带缓存) │ ├── _fetchPaginatedToc() ← 分页目录加载(最多 20 页) │ └── _fallbackChapters() ← 回退:章节识别器扫描 │ ├── 内容 ─────────────────────────── │ ├── fetchChapterContent() ← 解析章节内容 → OnlineChapterContent │ ├── fetchPlainText() ← 旧 API:从 URL 提取纯文本(无规则) │ ├── fetchImageUrls() ← 旧 API:从 URL 提取图片(无规则) │ └── _extractImageUrls() ← 图片提取(含 data-src/data-original) │ ├── 编解码 ───────────────────────── │ ├── _encodeKeyword() ← URL 关键词编码(GBK/UTF-8/平台通道) │ ├── _decodeBody() ← 响应体解码(GBK/UTF-8/Latin1) │ └── _charsetFromContentType() ← 从 Content-Type 提取 charset │ ├── HTTP ─────────────────────────── │ ├── _fetchBody() ← 统一 HTTP 请求(GET/POST,字节响应 + 状态码检查) │ ├── _debugDioException() ← Dio 异常日志 │ └── _debugHttpResponse() ← HTTP 错误日志 │ ├── 工具 ─────────────────────────── │ ├── _resolveUrl() ← 相对 URL → 绝对 URL │ ├── resolveResourceUrl() ← 公开版 URL 解析 │ ├── _htmlToText() ← HTML → 纯文本 │ ├── _plainTextFromJson() ← JSON → 提取文本字段 │ ├── _imageUrlsFromJson() ← JSON → 提取图片 URL │ ├── _safeSelect() / _safeSelectList() ← 规则解析安全包装 │ ├── _shortError() ← 错误消息归一化(中文映射表) │ └── parseSources() ← JSON 文本 → List │ └── 数据类 ───────────────────────── └── _LegadoRequest { method, url, body } ``` --- ## 三、Provider 依赖注入 **文件**:`sakura_mobile/lib/src/core/providers.dart` ```dart // 1. 会话管理(登录态)— StateNotifier final sessionProvider = StateNotifierProvider(...); // 2. 云端 API 客户端 — 依赖 sessionProvider final apiClientProvider = Provider((ref) { ref.watch(sessionProvider); return ref.read(sessionProvider.notifier).client(); }); // 3. 书源管理器 — ChangeNotifier(UI 可监听 busy/message 状态) final sourceManagerProvider = ChangeNotifierProvider((ref) { final manager = SourceManager(); manager.initializeIfFirstRun(); // 首次运行提示导入书源 return manager; }); // 4. 在线引擎 — 单例 final legadoEngineProvider = Provider((ref) => LegadoEngine()); // 5. 统一搜索 — 组合 apiClient + sourceManager + engine final unifiedSearchProvider = Provider((ref) { return UnifiedSearch( api: ref.watch(apiClientProvider), sourceManager: ref.watch(sourceManagerProvider), engine: ref.watch(legadoEngineProvider), ); }); ``` **Provider 消费方式**(在各页面中): ```dart // 获取一次值(不监听变化) final engine = ref.read(legadoEngineProvider); // 监听变化(UI 自动刷新) final manager = ref.watch(sourceManagerProvider); ``` --- ## 四、数据模型详解 ### 4.1 LegadoSource(书源规则) **文件**:`legado_models.dart:21-306` 完整的 Legado 书源模型,包含四个规则模块。 **构造函数参数(共 29 个字段)**: ```dart class LegadoSource { // === 基础字段 === final String id; // 派生自 name+url 的 hash final String name; // bookSourceName final String url; // bookSourceUrl final int type; // 0=小说, 2=漫画 final bool enabled; // === HTTP 配置 === final String? userAgent; final Map headers; // 含 Cookie final String? charset; // gbk / utf-8 final String? urlEncoding; // 关键词 URL 编码字符集 final String? ruleKind; // css / json / regex // === Search 规则(ruleSearch)=== final String? searchUrl; // 搜索 URL 模板,含 {{key}} {{page}} final String? searchListRule; // 结果条目列表选择器 final String? searchNameRule; // 书名选择器 final String? searchAuthorRule; // 作者选择器 final String? searchCoverRule; // 封面选择器 final String? searchDetailRule; // 详情链接选择器 → detailUrl final String? searchMethod; // GET / POST final String? searchBody; // POST body 模板 // === BookInfo 规则(ruleBookInfo)=== final String? bookInfoUrl; // 详情页 URL 模板 final String? bookInfoNameRule; final String? bookInfoAuthorRule; final String? bookInfoCoverRule; final String? bookInfoIntroRule; final String? bookInfoTocRule; // ⭐ 目录页 URL 选择器 // === TOC 规则(ruleToc)=== final String? tocUrl; // 目录页 URL 模板(支持 {{page}}) final String? tocListRule; // 章节条目列表选择器 final String? tocNameRule; // 章节名称选择器 final String? tocUrlRule; // 章节链接选择器 final String? tocNextPageRule; // 下一页目录选择器 // === Content 规则(ruleContent)=== final String? contentRule; // 正文内容选择器 final String? contentNextRule; // 下一章链接选择器 final String? contentPrevRule; // 上一章链接选择器 } ``` **类型判断**: - `isNovel` → `type == 0` - `isManga` → `type == 2` **fromJson 解析逻辑**(`legado_models.dart:130-261`): 1. 从 `json['ruleSearch']` 提取搜索规则(13 种 key 备选) 2. 从 `json['ruleBookInfo']` 提取详情规则(4 种 key 备选) 3. 从 `json['ruleToc']` 提取目录规则(5 种 key 备选) 4. 从 `json['ruleContent']` 提取内容规则(3 种 key 备选) 5. 从 `json['header']` / `json['headers']` 提取请求头(支持 Map / JSON 字符串 / 冒号分隔行三种格式) 6. 从 `json['cookie']` 合并 Cookie 到 headers **copyWith 方法**(`legado_models.dart:93-128`): - 唯一可变参数:`enabled` - 所有规则字段原样传递(不可变对象) **toJson 方法**(`legado_models.dart:263-305`): - 输出完整的 Legado 兼容 JSON - 包含 `ruleSearch` / `ruleBookInfo` / `ruleToc` / `ruleContent` 四个顶层 key - 空值不输出(`if (xxx != null)` 条件添加) **字段名对照表**(输出 JSON key → Legado 标准名): | 内部字段 | JSON key | |---------|----------| | `name` | `bookSourceName` | | `url` | `bookSourceUrl` | | `type` | `bookSourceType` | | `searchListRule` | `ruleSearch.bookList` | | `bookInfoTocRule` | `ruleBookInfo.tocUrl` | | `tocListRule` | `ruleToc.chapterList` | | `contentRule` | `ruleContent.content` | --- ### 4.2 OnlineBookInfo(运行时书籍详情) ```dart class OnlineBookInfo { final String title; // 书名(来自 bookInfoNameRule 解析或搜索结果的 initialTitle) final String? author; final String? coverUrl; final String? intro; // 简介 final String tocUrl; // 目录页 URL ⭐ final String sourceName; // 来源书源名称 } ``` **来源**:`LegadoEngine.fetchBookInfo()` 解析 `detailUrl` 指向的页面。 --- ### 4.3 OnlineChapter(运行时章节条目) ```dart class OnlineChapter { final String title; // 章节标题 final String url; // 章节内容 URL final int index; // 序号(从 1 开始) } ``` **来源**:`LegadoEngine.fetchToc()` 解析目录页。 --- ### 4.4 OnlineChapterContent(运行时章节内容) ```dart class OnlineChapterContent { final String title; // 章节标题 final String? textContent; // 小说正文(纯文本) final List imageUrls; // 漫画图片 URL 列表 final String? nextChapterUrl; // 下一章 URL(contentNextRule 解析结果) final String? prevChapterUrl; // 上一章 URL } ``` **来源**:`LegadoEngine.fetchChapterContent()` 解析章节页。 --- ### 4.5 OnlineReadingRecord(阅读记录) ```dart class OnlineReadingRecord { final String sourceId; // 书源 ID final String sourceName; // 书源名称 final String bookTitle; // 书名 final String detailUrl; // 书籍详情页 URL final String chapterUrl; // 当前阅读的章节 URL final String chapterTitle; // 当前阅读的章节标题 final int chapterIndex; // 章节序号(0-based) final int totalChapters; // 总章节数 final DateTime lastReadTime; // 最后阅读时间 } ``` **存储**:`OnlineReadingHistory` → SharedPreferences JSON 数组,最多 50 条。 --- ### 4.6 UnifiedSearchResult(搜索结果条目) ```dart class UnifiedSearchResult { final String sourceId; // 书源 ID final String sourceName; // 书源名称 final String title; // 书名 final String? author; final String? coverUrl; final String? detailUrl; // 书籍详情页 URL(非章节 URL) final String? errorMessage; // 非空表示搜索失败 bool get isError => errorMessage?.trim().isNotEmpty == true; } ``` **两种构造方式**: - 正常结果:`UnifiedSearchResult(sourceId:, sourceName:, title:, ...)` - 错误结果:`UnifiedSearchResult.error(sourceId:, sourceName:, errorMessage:)` → title 固定为"搜索失败" --- ### 4.7 SearchItem / SearchSection(搜索页 UI 数据) ```dart class SearchItem { final String title; final String sourceName; final String? author; final String? coverUrl; final String? detailUrl; final Artwork? artwork; // 云库漫画 final Novel? novel; // 云库小说 final UnifiedSearchResult? online; // 在线源结果 final String? errorMessage; bool get isCloud => artwork != null || novel != null; bool get isError => errorMessage?.trim().isNotEmpty == true; } class SearchSection { final String id; // 'cloud' | 'online' final String title; // '我的云库' | '在线源' final List items; } ``` --- ## 五、搜索引擎 LegadoEngine **文件**:`legado_engine.dart`(956 行) ### 5.1 初始化 ```dart class LegadoEngine { LegadoEngine({Dio? http}) : _http = http ?? Dio(BaseOptions( connectTimeout: Duration(seconds: 15), receiveTimeout: perSourceTimeout, // 20s headers: { 'User-Agent': 'Mozilla/5.0 ... Chrome/120 ...', 'Accept': 'text/html,...', 'Accept-Language': 'zh-CN,zh;q=0.9', }, )); static const maxConcurrency = 10; // 单批并发数 static const perSourceTimeout = Duration(seconds: 20); final OnlineContentCache cache = OnlineContentCache(); // 会话缓存实例 } ``` ### 5.2 搜索方法 #### search() — 单源搜索 ``` 输入: LegadoSource, keyword, page ↓ 1. 检查 searchUrl / searchListRule 非空 2. _buildSearchRequest(source, searchUrl, keyword, page) → _encodeKeyword(source, keyword) // GBK/UTF-8 百分号编码 → _applySearchTemplate(template, encodedKeyword, page) // 替换 {{key}} {{keyword}} {key} {keyword} // searchKey %s {{page}} {page} → resolveResourceUrl(source.url, rawUrl) // 相对→绝对 → 返回 _LegadoRequest(method, url, body) 3. _fetchBody(source, url) // HTTP GET/POST 4. RuleParser(body) 解析 5. _safeSelectList(parser, searchListRule) → 提取结果条目片段 6. 每个片段提取: title/author/coverUrl/detailUrl 7. 过滤空 title 8. 如果规则解析无结果 → _fallbackSearchResults() ``` #### searchAll() — 多源并发搜索 ``` 输入: List, keyword ↓ 循环: start=0; start < sources.length; start += 10 每批最多 10 个源,Future.wait 并发 每个源: search(source, keyword) .timeout(20s) .catchError() → UnifiedSearchResult.error() 结果追加到 results 列表 ``` **关键**:`searchAll` 不做跨源去重。同一本书出现在 5 个书源中 → 5 条结果。 **错误处理**: - 超时 → 返回带 `errorMessage` 的错误结果,不影响其他源 - 其他异常 → 同上 #### _fallbackSearchResults() — 搜索回退 当 `searchListRule` 解析不到结果时触发: 1. 扫描 HTML 中所有 `` 标签 2. 标题必须包含搜索关键词(完全匹配) 3. 过滤 `#` 和 `javascript:` 链接 4. 最多返回 30 条 #### _applySearchTemplate() — 占位符替换 支持的占位符(按替换优先级): ```dart {{key}} → encodedKeyword {{page}} → pageText {{keyword}} → encodedKeyword {page} → pageText {{searchKey}} → encodedKeyword → pageText {key} → encodedKeyword {keyword} → encodedKeyword {searchKey} → encodedKeyword → encodedKeyword → encodedKeyword → encodedKeyword searchKey → encodedKeyword // 无包裹的字符串直接替换 %s → encodedKeyword // printf 风格(仅替换第一个) ``` ### 5.3 详情方法 #### fetchBookInfo() — 解析书籍详情 ``` 输入: LegadoSource, detailUrl, {initialTitle, initialAuthor, initialCoverUrl} ↓ 1. 查缓存: cache.getBookInfo(source.id, absoluteUrl) 2. _fetchBody(source, absoluteUrl) 3. RuleParser(body) → 逐一提取: → bookInfoNameRule → parsedTitle → bookInfoAuthorRule → parsedAuthor → bookInfoCoverRule → parsedCover → bookInfoIntroRule → parsedIntro → bookInfoTocRule → parsedToc 4. 确定 tocUrl: - 优先: parsedToc - 其次: source.tocUrl - 兜底: absoluteUrl (即 detailUrl 本身) 5. title 兜底: initialTitle → '未命名作品' 6. 写入 bookInfoCache 7. 返回 OnlineBookInfo ``` ### 5.4 目录方法 #### fetchToc() — 解析章节目录 ``` 输入: LegadoSource, tocUrl ↓ 1. 查缓存: cache.getToc(source.id, absoluteUrl) 2. 未命中 → _fetchPaginatedToc(source, absoluteUrl) 3. 写入 tocCache 4. 返回 List ``` #### _fetchPaginatedToc() — 分页目录加载 ``` 输入: LegadoSource, template (含 {{page}} 的 URL) ↓ 初始化: chapters=[], seenUrls={}, seenPages={}, nextUrl=template, page=1 循环条件: page <= 20 && nextUrl != null 1. 替换 {{page}} / {page} → requestedUrl 2. seenPages 去重 → break 3. _fetchBody → body 4. RuleParser(body) → tocListRule → fragments 5. 遍历 fragments: → tocNameRule → title → tocUrlRule → url → seenUrls 去重 → chapters.add(OnlineChapter(title, url, index)) 6. 如果 fragments 为空: → _fallbackChapters(body) // 章节识别器回退 7. 如果本页新增 0 条 → break 8. 检查 tocNextPageRule → 有则更新 nextUrl 否则如果 template 含 {{page}} → 继续 page++ 否则 → nextUrl = null(停止) 返回 chapters ``` #### _fallbackChapters() — 章节识别器回退 当 `tocListRule` 不可用时触发: 1. 正则匹配 `` 标签 2. 标题必须匹配章节特征正则: ```dart r'(第\s*[0-9一二三四五六七八九十百千万零〇两]+\s*[章节卷回话]|chapter\s*\d+|episode\s*\d+)' ``` 3. 按出现顺序排列 **与搜索回退的区别**:搜索回退要求标题包含搜索关键词,目录回退要求标题匹配章节正则。后者更精准,避免把导航链接当章节。 ### 5.5 内容方法 #### fetchChapterContent() — 解析章节内容 ``` 输入: LegadoSource, OnlineChapter ↓ 1. 查缓存: cache.getChapter(source.id, absoluteUrl) 2. _fetchBody → body 3. RuleParser(body) → contentRule → content(主内容) 4. 如果是漫画: → contentRule 提取 fragments 列表 → 合并 fragments 为 contentBody 5. 如果是小说: → contentBody = content.isEmpty ? body : content 6. 提取导航: → contentNextRule → nextChapterUrl → contentPrevRule → prevChapterUrl 7. 构建 OnlineChapterContent: - 小说: textContent = _plainTextFromJson(contentBody) || _htmlToText(contentBody) - 漫画: imageUrls = _extractImageUrls(contentBody, absoluteUrl) - nextChapterUrl / prevChapterUrl 8. 写入 chapterCache 9. 返回 OnlineChapterContent ``` #### fetchPlainText() — 旧 API(无规则) ``` 输入: LegadoSource, url ↓ _fetchBody → body _json 文本提取优先 → _plainTextFromJson(body) 回退 HTML → _htmlToText(body) ``` #### fetchImageUrls() — 旧 API(无规则) ``` 输入: LegadoSource, url ↓ 如果 url 本身是图片 → 直接返回 [url] 否则 _fetchBody → body HTML img 扫描: JSON 图片扫描: _imageUrlsFromJson(body) 合并去重 ``` 两者都是旧 API,不依赖 `contentRule`,直接从 HTML/JSON 中暴力提取。 ### 5.6 HTTP 层 #### _fetchBody() — 统一 HTTP 请求 ``` 输入: LegadoSource, url, {method, data} ↓ 1. 校验 URL(非空、有 scheme) 2. 构建 headers: - Referer: source.url - ...source.headers(含 Cookie) - User-Agent: source.userAgent ?? 默认 UA 3. 发起请求: - GET: _http.get>(url, options: ResponseType.bytes, followRedirects: true, validateStatus: _ => true) - POST: _http.post>(url, data: data, ...) 4. 捕获 DioException → _debugDioException() 打日志 → rethrow 5. 检查 statusCode: - 404 → throw 'Source search endpoint is missing or expired.' - 403/444 → throw 'Source refused access...' - 其他 >= 400 → throw 'HTTP $code from $host.' 6. 解码响应体: _decodeBody(bytes, declaredCharset: source.charset, contentType: headers['content-type']) ``` **关键设计**: - `ResponseType.bytes` — 始终以字节数组接收,避免 Dio 自动用错误编码解码 - `validateStatus: (_) => true` — 不抛 DioException,自己检查状态码 - `followRedirects: true` — 自动跟随重定向 ### 5.7 编解码层 #### _encodeKeyword() — URL 关键词编码 ``` 输入: LegadoSource, keyword ↓ 确定编码: source.urlEncoding ?? source.charset ?? 'utf-8' ↓ utf-8 → Uri.encodeQueryComponent(keyword) gbk/gb2312/gb18030 → gbk.encode(keyword) → 手动百分号编码 其他编码 → _encodingChannel.invokeMethod('encodeQuery') → 平台原生编码 MissingPluginException → throw ``` #### _decodeBody() — 响应体解码 ``` 输入: List bytes, declaredCharset, contentType ↓ 确定 charset: declaredCharset ?? _charsetFromContentType(contentType) ↓ latin1/iso-8859-1/windows-1252 → latin1.decode(bytes) gbk/gb2312/gb18030 → gbk.decode(bytes) // FormatException → latin1 兜底 其他/未指定 → utf8.decode(bytes) // FormatException → latin1 兜底 ``` #### _charsetFromContentType() — 提取 charset ```dart // 从 "text/html; charset=gbk" 中提取 "gbk" RegExp(r'charset=([^;]+)') ``` ### 5.8 错误处理 #### _shortError() — 错误消息归一化 完整的错误消息映射链(按优先级): ``` 1. DioException 类型匹配: connectionTimeout/receiveTimeout/sendTimeout → '连接 {host} 超时,请稍后重试。' connectionError → '无法连接 {host},请检查网络或更换书源。' badResponse + 404 → '书源搜索接口已失效(404)。' badResponse + 403/444 → '{host} 拒绝了访问,可能需要 Cookie 配置。' badResponse + 其他 → '{host} 返回了异常状态(HTTP {code})。' 2. FormatException: 含 utf/encoding → '响应编码异常,请检查书源的 charset 配置。' 其他 → '书源规则期望 JSON 格式,但站点返回了其他内容。' 3. 原始字符串归一化: '[unknown]: null' / 'null' → '目标站点返回了空响应...' '[unknown]: none' / 含 'unknown:none' → '连接异常,书源可能已失效。' 含 'connection refused' → '目标站点拒绝了连接。' 含 'connection timed out' → '连接超时,请稍后重试。' 含 'no address associated' → '无法解析目标站点域名,请检查网络。' 4. 兜底: message > 120 字符 → 截断 空字符串 → '未知错误' ``` --- ## 六、规则解析器 RuleParser **文件**:`legado_rule_parser.dart`(262 行) ### 6.1 支持的三种解析类型 通过 `_resolveKind()` 自动识别: ``` 规则前缀: "json:" 或 "$." → json 模式 "regex:" → regex 模式 其他 → css 模式(默认) ``` ### 6.2 CSS 模式 #### selectList() — 多元素选择 ``` 1. 清理选择器(去掉 @attr 后缀) 2. html_parser.parse(body) → document 3. document.querySelectorAll(cleanSelector) 4. 每个元素 → outerHtml 5. 如果 querySelectorAll 抛异常(畸形选择器)→ 降级到 _legacyCssFragments() ``` #### select() — 单元素选择 ``` 1. 检查 @attr 后缀(如 "img@src" → 提取 src 属性值) 2. html_parser.parse(fragment) → document 3. document.querySelector(cleanSelector) 4. 有 @attr → element.attributes[attr] 5. 无 @attr → element.text 6. 如果 querySelector 抛异常 → 降级到 _legacyCssText() ``` #### _legacyCssFragments() — 正则降级 ``` 提取选择器开头的 tag 名 → 正则匹配 ... → 返回 outerHtml ``` #### _legacyCssText() — 正则降级 ``` 提取 tag 名 → 正则匹配 → @attr 提取属性值 / 默认提取 innerText ``` ### 6.3 JSON 模式(JSONPath) **支持的语法**: ``` $.data → 取 data 字段 $.data.chapters → 取 data.chapters 字段 $.data.chapters[*] → 取 chapters 数组全部元素 $.data.items[0] → 取 items 数组第 1 个元素 $.data.list[2].name → 取 list[2].name ["complex-key"] → 支持引号包裹的 key(自动转为 .key) ``` **JsonPath 解析流程**(`_jsonPath()`): ``` 1. 去掉前缀: json: 或 $. 2. 按 . 分割 path 3. 逐段遍历: - segment 以 [*] 结尾 → 取数组全量 - segment 含 [n] → 取数组第 n 个元素 - 普通 key → _child(node, key) 4. _child() 递归: - key 为空 → 返回 node - node is Map → node[key] - node is List → node.map(item => _child(item, key)) ``` **JSON Body 预处理**(`_jsonBody()`): ``` 1. 去掉 UTF-8 BOM(0xFEFF) 2. 检测 JSONP 格式: callback({...}) → 正则提取括号内 JSON 3. jsonDecode ``` ### 6.4 Regex 模式 **selectList() — Regex 全量匹配**: ``` 去掉 "regex:" 前缀 RegExp(rule, dotAll: true).allMatches(body) → 有捕获组: match.group(1) → 无捕获组: match.group(0) 过滤空值 ``` **select() — Regex 首次匹配**: ``` 去掉 "regex:" 前缀 RegExp(rule, dotAll: true).firstMatch(fragment) → match.group(1) ?? match.group(0) ``` ### 6.5 规则多值支持 `_ruleAlternatives()` — 支持 `||` 分隔的多个规则备选: ```dart // "div.title || h1.title || .book-name" → 三个规则依次尝试 // 第一个有结果的规则立即返回 ``` --- ## 七、书源管理 SourceManager **文件**:`source_manager.dart`(368 行) ### 7.1 生命周期 ``` 构造 → load() → initializeIfFirstRun() ↓ SharedPreferences 读取已保存书源 ↓ _loaded = true → notifyListeners() ↓ startAutoUpdateTimer() // 每 6 小时检查订阅更新 ``` ### 7.2 书源导入 #### importFromRepo(SourceRepo) — 从仓库导入 ``` 1. 如果是订阅源 → _addSubscription(url) 2. HTTP GET repo.url 3. importFromJsonText(response.body) ``` #### importFromUrl(String) — 从自定义 URL 导入 ``` HTTP GET url → importFromJsonText(response.body) ``` #### importFromJsonText(String) — 解析 JSON 并入库 ``` 1. _engine.parseSources(body) → List 2. 遍历 imported: - _sources.indexWhere(id 匹配) → 更新现有源 - 否则 → 追加新源 3. _save() → SharedPreferences 4. notifyListeners() ``` #### parseSources() — JSON → 书源列表 ``` 1. 检测 HTML(body 以 get sources; // 已启用书源 List get enabledSources; // 已启用的小说源(type == 0) List get enabledNovelSources; // 已启用的漫画源(type == 2) List get enabledMangaSources; // 按 ID 查找 LegadoSource? sourceById(String sourceId); ``` ### 7.4 书源状态管理 ```dart // 启用/禁用某个书源 setEnabled(sourceId, enabled) → _save() → notifyListeners() // 健康检查(HTTP GET 搜索 URL,最多检查 10 个源) checkEnabledSources() → Future.wait(targets.map(_checkSource)) → List ``` ### 7.5 持久化 ```dart // 存储 key _sourcesKey = 'legado_sources_v1' _initializedKey = 'source_manager_initialized_v1' _subscriptionsKey = 'legado_subscription_urls_v1' _lastSubscriptionUpdateKey = 'legado_last_subscription_update_v1' // 书源存储格式 jsonEncode(_sources.map(source.toJson()).toList()) // 即完整的 Legado 兼容 JSON 数组,含 ruleSearch/ruleBookInfo/ruleToc/ruleContent ``` --- ## 八、统一搜索 UnifiedSearch **文件**:`unified_search.dart`(173 行) ### 8.1 搜索编排 ```dart Future> search({query, mode}) { // 1. 并行发起两个搜索 cloudFuture = mode==manga ? _searchCloudManga(query) : _searchCloudNovels(query) onlineFuture = engine.searchAll(sources, query) .then(items => items.map(SearchItem.online)) // 2. 等待两个 Future 都完成(Future.wait) results = await Future.wait([cloudFuture, onlineFuture]) // 3. 组装 SearchSection return [ if (results[0].isNotEmpty) SearchSection(id: 'cloud', title: '我的云库', items: results[0]), if (results[1].isNotEmpty) SearchSection(id: 'online', title: '在线源', items: results[1]), ] } ``` ### 8.2 云库搜索 ```dart _searchCloudManga(query) → api.gallery(search: query, contentType: 'manga') → rows.map(Artwork.fromJson).map(SearchItem.cloudArtwork) _searchCloudNovels(query) → api.novels(search: query) → rows.map(Novel.fromJson).map(SearchItem.cloudNovel) ``` ### 8.3 SearchItem 工厂方法 ```dart SearchItem.cloudArtwork(artwork) → title, sourcePlatform, author, coverUrl, artwork SearchItem.cloudNovel(novel) → title, sourcePlatform, author, coverPath, novel SearchItem.online(result) → title, sourceName, author, coverUrl, detailUrl, online, errorMessage SearchItem.error(sourceName, msg)→ title='搜索失败', sourceName, errorMessage ``` --- ## 九、页面层源码 ### 9.1 ExplorePage — 在线搜索页 **文件**:`explore_page.dart`(503 行) **状态管理**: ```dart final search = TextEditingController(); // 搜索输入框 late UnifiedSearchMode mode; // manga / novel Future>? future; // 搜索结果 Future final savingOnline = {}; // 正在保存的 item key 集合 ``` **搜索触发**: ```dart _submit() { query = search.text.trim(); if (query.isEmpty) return; setState(() { future = ref.read(unifiedSearchProvider).search(query: query, mode: mode); }); } ``` **模式切换**(漫画 ↔ 小说): ```dart SegmentedButton → onSelectionChanged → mode = newMode; future = null; ``` **搜索状态展示**(FutureBuilder 四种状态): ``` future == null → 空状态(搜索引导文案) ConnectionState.waiting → CircularProgressIndicator snapshot.hasError → 错误状态(cloud_off 图标 + 文案) sections.isEmpty → 无结果状态(search_off 图标 + 文案) 有结果 → Column: section 标题 + SearchResultTile 列表 ``` **搜索结果点击 — _openItem()**: ``` item.artwork != null → ArtworkDetailPage(artwork) // 云库漫画:本地详情页 item.novel != null → NovelReaderPage(novel) // 云库小说:本地阅读器 item.isError → SnackBar(errorMessage) // 错误提示 online != null → source = sourceManager.sourceById(online.sourceId) → source == null → SnackBar('书源已不可用') → OnlineBookDetailPage( // 🆕 在线结果 → 详情页 source, initialTitle, initialAuthor, initialCoverUrl, detailUrl, onSave ) ``` **保存到书架 — _saveOnlineItem()**: ``` 1. fetchBookInfo(source, detailUrl) → info 2. fetchToc(source, info.tocUrl) → chapters 3. fetchChapterContent(source, chapters.first) → content 4. 漫画: api.importOnlineManga(...) → 跳转到 ArtworkDetailPage 5. 小说: api.importOnlineNovel(...) → 跳转到 NovelReaderPage 6. 异常: SnackBar('保存失败:$error') ``` **UI 组件**: - `_SourceSummary` — 已启用书源数量卡片 - `_SearchResultTile` — 搜索结果条目(封面缩略图 + 标题 + 作者/来源 + 保存按钮) - subtitle 三要素:`作者(未知作者兜底) - 来源名称 - 云库/在线` - 错误条目:粉色背景 + warning 图标 + errorMessage - `_ResultThumb` — 封面缩略图(CachedNetworkImage,160×220,有 fallback 图标) - `_ExploreEmptyState` — 空状态占位 --- ### 9.2 OnlineBookDetailPage — 在线书籍详情页 **文件**:`online_book_detail_page.dart`(338 行) **接收参数**: ```dart source: LegadoSource // 书源 detailUrl: String // 书籍详情页 URL initialTitle: String // 搜索结果中的书名(兜底) initialAuthor: String? // 搜索结果中的作者(兜底) initialCoverUrl: String? // 搜索结果中的封面(兜底) onSave: Future Function()? // 保存回调 ``` **状态管理**: ```dart OnlineBookInfo? info; // BookInfo 解析结果 List chapters; // 章节列表 Object? infoError; // BookInfo 加载错误 Object? tocError; // TOC 加载错误 bool loadingInfo = true; // BookInfo 加载中 bool loadingToc = true; // TOC 加载中 bool descending = false; // 章节排序(正序/倒序) bool saving = false; // 保存中 OnlineReadingRecord? readingRecord; // 阅读记录 ``` **加载流程 — _load()**: ``` 1. detailUrl 为空 → 显示错误 2. engine.fetchBookInfo(source, detailUrl, ...) → info 3. setState: loadingInfo=false, loadingToc=true 4. _loadToc(info.tocUrl) 5. OnlineReadingHistory.find(sourceId, detailUrl) → readingRecord 6. 异常 → setState: infoError=error, loadingInfo=false, loadingToc=false ``` **分段加载 — _loadToc(url)**: ``` 1. setState: tocError=null, loadingToc=true 2. engine.fetchToc(source, url) → chapters 3. setState: loadingToc=false 4. 异常 → setState: tocError=error, loadingToc=false ``` **关键设计**:BookInfo 和 TOC 是两次独立的 HTTP 请求(因为 detailUrl ≠ tocUrl),但 UI 合并在同一页面。BookInfo 先渲染,TOC 区域独立 loading。 **章节点击 — _openChapter(index)**: ``` source.isManga → OnlineMangaReaderPage(source, title, chapters, currentChapterIndex: index, detailUrl) → push → 回来后重新查阅读记录 → 刷新已读标记 source.isNovel → OnlineNovelReaderPage(同上) ``` **页面结构**: ``` AppBar: '书籍详情' ↓ 上半部分(BookInfo 渲染): Row: 封面 (CachedNetworkImage, 104×142) Column: 书名(headlineSmall) + 作者 + 来源(灰色) + 章节数(粉色) 简介 ExpansionTile(可展开/收起) 操作按钮: FilledButton: '从第一章开始阅读' / '继续阅读'(根据 readingRecord) OutlinedButton: '保存到书架'(条件显示) 下半部分(TOC 渲染): Row: '章节目录(共 N 章)' + 正序/倒序切换按钮 三种状态: loading → CircularProgressIndicator error → _ErrorState(重试按钮) chapters.isEmpty → 空状态文案 有数据 → ListView of ListTile: - leading: menu_book 图标 - title: 章节名称 - trailing: 已读 ✓ 或 chevron_right - onTap: _openChapter(chapter.index - 1) ``` --- ### 9.3 OnlineMangaReaderPage — 在线漫画阅读器 **文件**:`online_manga_reader_page.dart`(208 行) **接收参数**: ```dart source: LegadoSource title: String // 书名 chapters: List // 完整章节列表 currentChapterIndex: int // 当前章节序号(0-based) detailUrl: String // 书籍详情 URL(用于阅读记录) ``` **状态管理**: ```dart late int chapterIndex = widget.currentChapterIndex; late Future contentFuture = _load(); final pageController = PageController(); int pageIndex = 0; // 当前漫画页(PageView 内) ``` **加载流程 — _load()**: ``` 1. engine.fetchChapterContent(source, chapter) → content 2. OnlineReadingHistory.save(OnlineReadingRecord(...)) 3. 预加载下一章: next = chapterIndex + 1 if next < chapters.length: engine.fetchChapterContent(source, chapters[next]) .catchError(...) // 预加载失败静默忽略 4. return content ``` **章节切换 — _move(delta)**: ``` target = chapterIndex + delta if target < 0 || target >= chapters.length → return setState: chapterIndex = target pageIndex = 0 contentFuture = _load() pageController.jumpToPage(0) ``` **页面结构**: ``` AppBar: '章节标题(3/336)' ↓ FutureBuilder: error → _MangaState('这个章节暂时没有加载成功。', retry) loading → CircularProgressIndicator data.imageUrls.isEmpty → _MangaState('这一章还没有找到漫画页面...', retry) data.imageUrls: Stack: PageView.builder: InteractiveViewer → Image.network(pages[index], headers: source.headers) Positioned(右下角): '3/18' 页数指示器 bottomNavigationBar: [← 上一章] [📋 目录(pop)] [下一章 →] - 上一章: chapterIndex > 0 可用 - 下一章: chapterIndex < chapters.length - 1 可用 ``` --- ### 9.4 OnlineNovelReaderPage — 在线小说阅读器 **文件**:`online_novel_reader_page.dart`(195 行) **接收参数**: ```dart source: LegadoSource title: String // 书名 chapters: List // 完整章节列表 currentChapterIndex: int // 当前章节序号(0-based) detailUrl: String // 书籍详情 URL(用于阅读记录) ``` **状态管理**: ```dart late int chapterIndex = widget.currentChapterIndex; late Future contentFuture = _load(); double fontSize = 18; // 可调字号(14-26) ``` **加载流程 — _load()**:与漫画阅读器完全相同的逻辑。 **页面结构**: ``` AppBar: '章节标题(3/336)' actions: [缩小字体] [放大字体] body → FutureBuilder: error → _ReaderState('章节加载失败', retry) loading → CircularProgressIndicator data.textContent 为空 → _ReaderState('这一章还是空白', retry) data.textContent: ListView: Text(章节标题, titleLarge) Text(正文, fontSize: fontSize, height: 1.75) bottomNavigationBar: 与漫画阅读器完全相同的三按钮导航 ``` --- ## 十、缓存与阅读记录 ### 10.1 OnlineContentCache — 会话级内存缓存 **文件**:`online_cache.dart`(25 行) ```dart class OnlineContentCache { final _bookInfo = {}; // key: sourceId|url final _toc = >{}; // key: sourceId|tocUrl final _chapters = {}; // key: sourceId|chapterUrl // 缓存 key 规则 String _key(String sourceId, String url) => '$sourceId|$url'; // BookInfo getBookInfo(sourceId, url) → _bookInfo[key] putBookInfo(sourceId, url, value) → _bookInfo[key] = value // TOC(返回不可变列表) getToc(sourceId, url) → _toc[key] putToc(sourceId, url, value) → _toc[key] = List.unmodifiable(value) // Chapter getChapter(sourceId, url) → _chapters[key] putChapter(sourceId, url, value) → _chapters[key] = value } ``` **缓存生命周期**:当次 APP 会话(进程存活期间)。APP 杀死后缓存消失。 **缓存消费者**: - `fetchBookInfo()` → 查/写 `_bookInfo` - `fetchToc()` → 查/写 `_toc` - `fetchChapterContent()` → 查/写 `_chapters` ### 10.2 OnlineReadingHistory — 阅读记录持久化 **文件**:`online_reading_history.dart`(57 行) **存储方式**:SharedPreferences,key = `online_reading_history_v1` **数据格式**:JSON 数组,每个元素是 `OnlineReadingRecord.toJson()` ```dart static Future save(OnlineReadingRecord record) { 1. 读取现有记录 → all() 2. 删除同一本书的旧记录(按 sourceId + detailUrl 去重) 3. 新记录插入到数组头部(最近阅读排在前面) 4. 超过 50 条 → 截断尾部 5. 写回 SharedPreferences } static Future find(sourceId, detailUrl) { 遍历 all() → 匹配 sourceId + detailUrl → 返回第一条 } static Future> all() { 从 SharedPreferences 读取 → jsonDecode → List.map(OnlineReadingRecord.fromJson) } ``` **调用的地方**: - 进入章节时:`OnlineReadingHistory.save()`(在 `_load()` 中) - 进入详情页时:`OnlineReadingHistory.find()`(显示"继续阅读"还是"从第一章开始") - 从阅读器返回时:`OnlineReadingHistory.find()`(刷新章节已读标记) --- ## 十一、完整调用链路 ### 11.1 搜索链路 ``` 用户输入 "海贼王" → 按回车 ↓ ExplorePage._submit() ↓ UnifiedSearch.search(query: "海贼王", mode: manga) ↓ 并行 ├─ _searchCloudManga("海贼王") │ → SakuraApiClient.gallery(search: "海贼王", contentType: 'manga') │ → HTTP GET /api/v1/gallery?search=海贼王&content_type=manga │ → List → SearchItem.cloudArtwork() │ └─ LegadoEngine.searchAll(enabledMangaSources, "海贼王") ↓ 分批(每批 10 个) ├─ search(源1, "海贼王") │ ├─ _encodeKeyword(源1, "海贼王") → GBK/UTF-8 编码 │ ├─ _applySearchTemplate(源1.searchUrl, encoded, page=1) │ │ → "https://example.com/search?keyword=%E6%B5%B7%E8%B4%BC%E7%8E%8B" │ ├─ _fetchBody(源1, url) → HTTP GET → 字节数组 → _decodeBody → HTML 字符串 │ ├─ RuleParser(html).selectList(源1.searchListRule) │ │ → fragments = ["
...", "
..."] │ └─ 遍历 fragments: │ ├─ select(fragment, searchNameRule) → "海贼王" │ ├─ select(fragment, searchAuthorRule) → "尾田荣一郎" │ ├─ select(fragment, searchDetailRule) → "/book/123" │ └─ UnifiedSearchResult(title:"海贼王", detailUrl:"https://.../book/123") │ ├─ search(源2, "海贼王") → 同上... └─ ... ↓ Future.wait → List: [SearchSection(id:'cloud', items: [...]), SearchSection(id:'online', items: [UnifiedSearchResult...])] ↓ ExplorePage FutureBuilder → 渲染结果列表 ``` ### 11.2 详情链路 ``` 用户点击搜索结果中的 "海贼王" ↓ ExplorePage._openItem(item) ↓ item.online.detailUrl = "https://example.com/book/123" Navigator.push(OnlineBookDetailPage( source: 源1, detailUrl: "https://example.com/book/123", initialTitle: "海贼王", initialAuthor: "尾田荣一郎", )) ↓ OnlineBookDetailPage._load() ↓ LegadoEngine.fetchBookInfo(源1, "https://example.com/book/123") ├─ cache.getBookInfo(源1.id, url) → 未命中 ├─ _fetchBody(源1, url) → HTML 字符串 ├─ RuleParser(html) → 提取: │ ├─ bookInfoNameRule → "海贼王" │ ├─ bookInfoAuthorRule → "尾田荣一郎" │ ├─ bookInfoCoverRule → "https://example.com/img/cover.jpg" │ ├─ bookInfoIntroRule → "拥有财富、名声、权力..." │ └─ bookInfoTocRule → "/book/123/catalog" ├─ tocUrl = "https://example.com/book/123/catalog" ├─ cache.putBookInfo(...) └─ return OnlineBookInfo(title:"海贼王", tocUrl:"https://.../catalog", ...) ↓ setState → loadingInfo=false, info=OnlineBookInfo, loadingToc=true ↓ 上半部分立即渲染(封面+书名+作者+简介+按钮) ↓ _loadToc("https://example.com/book/123/catalog") ↓ LegadoEngine.fetchToc(源1, "https://example.com/book/123/catalog") ├─ cache.getToc(源1.id, url) → 未命中 ├─ _fetchPaginatedToc(源1, url) │ ├─ page=1: _fetchBody → HTML │ │ RuleParser → tocListRule → fragments │ │ 每 fragment: tocNameRule="第1话" + tocUrlRule="/book/123/ch1" │ │ → chapters.add(OnlineChapter("第1话", "https://.../ch1", index:1)) │ │ ... │ ├─ tocNextPageRule → 有 → nextUrl = "?page=2" │ ├─ page=2: 同上... │ └─ tocNextPageRule → 空 → 停止 ├─ cache.putToc(...) → List(共 1130 条) └─ return chapters ↓ setState → loadingToc=false, chapters=[1130条] ↓ 下半部分渲染章节列表 ↓ OnlineReadingHistory.find(源1.id, detailUrl) → readingRecord 或 null ``` ### 11.3 阅读链路 ``` 用户在详情页点击 "第1话" ↓ OnlineBookDetailPage._openChapter(0) // index 从 0 开始 ↓ Navigator.push(OnlineMangaReaderPage( source: 源1, title: "海贼王", chapters: [1130条], currentChapterIndex: 0, detailUrl: "https://example.com/book/123", )) ↓ OnlineMangaReaderPage._load() ↓ chapter = chapters[0] → {title:"第1话", url:"https://.../ch1"} ↓ LegadoEngine.fetchChapterContent(源1, chapter) ├─ cache.getChapter(源1.id, url) → 未命中 ├─ _fetchBody(源1, url) → HTML ├─ RuleParser(html) → contentRule → "#chapter-content" 的 innerHtml ├─ _extractImageUrls(contentBody, absoluteUrl) │ ├─ RegExp: / data-src / data-original │ └─ JSON 图片扫描 ├─ contentNextRule → "/book/123/ch2" → nextChapterUrl ├─ contentPrevRule → 空 → prevChapterUrl=null ├─ cache.putChapter(...) └─ return OnlineChapterContent( title: "第1话", imageUrls: ["https://.../img01.jpg", "https://.../img02.jpg", ...], nextChapterUrl: "https://.../ch2", ) ↓ OnlineReadingHistory.save(OnlineReadingRecord( sourceId, sourceName, bookTitle, detailUrl, chapterUrl, chapterTitle, chapterIndex:0, totalChapters:1130, lastReadTime: now, )) ↓ 预加载下一章: engine.fetchChapterContent(源1, chapters[1]) .catchError(...) // 后台静默,失败不影响当前阅读 ↓ 渲染 PageView: Image.network("https://.../img01.jpg") ← 第1页 Image.network("https://.../img02.jpg") ← 第2页 ... 用户点击 "下一章" ↓ _move(1) → chapterIndex = 1 ↓ setState → contentFuture = _load() ↓ engine.fetchChapterContent(源1, chapters[1]) ├─ cache 命中!(已预加载) → 秒切 └─ _load() 内部再次 save 阅读记录 + 预加载第3章 ``` --- ## 附录:关键设计要点总结 ### 数据流方向 ``` LegadoSource (静态规则,SharedPreferences 持久化) ↓ LegadoEngine (规则驱动解析,HTTP + 缓存) ↓ OnlineBookInfo / OnlineChapter / OnlineChapterContent (运行时数据,内存缓存) ↓ UI Pages (ExplorePage / OnlineBookDetailPage / ReaderPages) ``` ### 编码处理链 ``` 搜索关键词: _encodeKeyword(source, keyword) → gbk.encode / Uri.encodeQueryComponent / 平台通道 响应体: _fetchBody → ResponseType.bytes → _decodeBody(bytes, source.charset, content-type charset) → gbk.decode / utf8.decode / latin1.decode ``` ### 缓存策略 ``` BookInfo → 进入详情页时缓存,同一书源 + 同一 detailUrl 只请求一次 TOC → 进入详情页时缓存,同一书源 + 同一 tocUrl 只请求一次 Chapter → 阅读时缓存当前章 + 预加载下一章 阅读记录 → SharedPreferences 持久化,跨会话保留 ``` ### 回退策略优先级 ``` 规则解析优先: 1. 用书源声明的 rule 解析(CSS/JSON/Regex) 2. 规则为空或无结果 → 回退 - 搜索: _fallbackSearchResults (全 扫描 + 关键词过滤) - 目录: _fallbackChapters (章节正则过滤的 扫描) - 内容: _htmlToText / _extractImageUrls (从 HTML 暴力提取) ```