# Legado 规则引擎重构 — 分阶段实施方案 > 日期:2026-06-21 > 基于:源码架构总结 + 截图问题诊断 + 方案文档反馈 > 涉及:`legado_rule_parser.dart`、`legado_engine.dart`、`legado_models.dart` > 原则:不改 UI 层,只在 core 层动刀;前 4 步零新依赖。 --- ## 一、问题根因定性与实施顺序纠偏 ### 1.1 截图 Bug ↔ 真实根因对照 | 截图 | 现象 | 代码层面的真实原因 | |------|------|-------------------| | 截图3 | "这一章还没有找到漫画页面" | `fetchChapterContent()` → `contentRule` → `RuleParser` 只认 CSS/JSON/Regex 三种前缀,**包子漫画5 的 `contentRule` 使用了 `@tag.img@src` / `##` / `&&` 等链式语法**,`_safeSelect()` 返回空串,`rawHtml` 兜底也没触发。 | | 截图4 | "未知作者" / 封面空白 | `bookInfoAuthorRule` / `bookInfoCoverRule` 同上,规则语法不被 `RuleParser` 支持。 | | 截图1 | "书籍详情加载失败" | `fetchBookInfo()` 整体 try/catch 后只设 `infoError`,不区分"网络不通"还是"规则不支持"。 | | 搜索 `unknown:none` | 错误消息原样展示 | `_shortError()` 已修好(源码已含完整中文映射),这个 bug 已不存在于当前源码。 | ### 1.2 原方案步骤的纠偏 原方案第 1 步是「支持 URL,{method,body,headers}」,但实际上: - `_buildSearchRequest()` 已有 GET/POST 分支 - `_applySearchTemplate()` 已支持 12 种占位符变体 - `fromJson` 解析 `header` 已支持 Map / JSON 字符串 / 冒号分隔行三种格式 **请求层不是最优先的问题。最优先的是 RuleParser 不支持 Legado 链式规则语法。** ### 1.3 修正后的实施顺序 ``` 第1步:rawHtml 兜底扫描 + script 变量扫描 ← 零成本,立刻修复截图3 第2步:RuleParser 支持 @tag/@text/@html/@src 链式语法 ← 解锁包子漫画5等核心书源 第3步:支持 ## 替换、|| 备选、&& 拼接 ← 兼容更多规则变体 第4步:fetchBookInfo / fetchToc 失败时区分错误类型 ← 解决截图1 第5步:JS 特判(newImgs / imageList 等高频变量) ← 覆盖 60%+ JS 规则,零依赖 第6步:@put / @get 上下文变量 ← 跨规则传值 第7步:书源兼容度检测 UI ← 用户体验闭环 第8步:完整 JS 引擎(flutter_js / quickjs) ← 最后做,覆盖剩余 40% ``` **前 4 步不需要引入任何新依赖,只在 `legado_rule_parser.dart` 和 `legado_engine.dart` 里改。** --- ## 二、总体架构重构方案 ### 2.1 不要继续往 RuleParser 里塞逻辑 当前 `RuleParser`(262 行)已经承担了 CSS / JSONPath / Regex 三种解析路径,再往里面加链式语法会导致它变成无法维护的千行怪物。 **建议拆成三层**: ``` 请求层 ── LegadoRequestBuilder ── 构建 URL、headers、body、编码 规则层 ── LegadoRuleExecutor ── 链式规则执行引擎 检测层 ── SourceCompatChecker ── 导入时打兼容度标签 ``` ``` ┌──────────────────────────────────────────────────┐ │ LegadoEngine │ │ (对外 API:search / fetchBookInfo / fetchToc / │ │ fetchChapterContent 不变) │ ├──────────────────────────────────────────────────┤ │ │ │ ┌──────────────────┐ ┌─────────────────────┐ │ │ │LegadoRequestBuilder│ │ LegadoRuleExecutor │ │ │ │· buildSearchUrl │ │· select() │ │ │ │· buildRequest │ │· selectList() │ │ │ │· encodeKeyword │ │· execChain() 🆕 │ │ │ │· applyTemplate │ │· applyReplace() 🆕 │ │ │ └──────────────────┘ │· extractImages() 🆕 │ │ │ │· scanScriptVars() 🆕 │ │ │ └──────────┬──────────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ RuleParser (保留) │ │ │ │ CSS / JSON / Regex │ │ │ │ 不改内部,只当底层 │ │ │ └─────────────────────┘ │ └──────────────────────────────────────────────────┘ ``` ### 2.2 核心原则 1. **LegadoEngine 对外 API 不动**。`search()` / `fetchBookInfo()` / `fetchToc()` / `fetchChapterContent()` 签名不变,UI 层零改动。 2. **RuleParser 降级为底层原子工具**。它继续支持 CSS / JSONPath / Regex 三种基础解析,但不理解链式语法。所有链式逻辑放在 `LegadoRuleExecutor` 里。 3. **新规则执行器按优先级链执行**。每条规则被解析为一条 **执行链 (execChain)**,按序执行,任意一步返回空就终止并返回空。 --- ## 三、第 1 步:rawHtml 兜底扫描 + script 变量扫描 > 目标:不改 RuleParser,在 `fetchChapterContent()` 和 `fetchImageUrls()` 里补兜底逻辑。 ### 3.1 问题 当 `contentRule` 为空或解析失败时,当前代码回到 `_htmlToText(body)` 或 `_extractImageUrls(body)` 暴力扫描 HTML。但如果漫画图片 URL 藏在 `###` | ### 5.2 实现位置 `LegadoRuleExecutor` 的 `execChain()` 方法。 ### 5.3 执行顺序 ``` 解析 rawRule: 1. 按 || 拆分为备选组 2. 每个备选组按 && 拆分为串联组 3. 每个串联组解析为链式步骤(复用第2步的 _parseChainSteps) 4. 每个链式步骤末尾检测 ## 替换指令 执行: for 备选组 in 备选组列表: 结果 = 执行 备选组 if 结果非空 → 返回结果 return 空 执行备选组: parts = [] for 串联组 in 备选组: part = 执行串联组 parts.add(part) return parts.join('\n') // && 的结果用换行拼接 执行串联组: result = 执行链式步骤(复用 _selectChain) if 有 ## 替换指令: for 替换 in 替换指令: result = result.replaceAll(替换.regex, 替换.replacement) return result ``` ### 5.4 改动量 - `legado_rule_parser.dart` 新增 `_selectWithAlternatives()` ~50 行 - `##` 替换逻辑 ~30 行 - 总计 ~80 行 - **零新依赖** --- ## 六、第 4 步:fetchBookInfo / fetchToc 失败时区分错误类型 ### 6.1 问题 当前 `fetchBookInfo()` 的 try/catch 结构: ```dart try { final value = await engine.fetchBookInfo(...); setState(() { info = value; loadingInfo = false; }); } catch (error) { setState(() { infoError = error; loadingInfo = false; }); // 所有错误一视同仁 } ``` 用户看不到是"网络不通"还是"规则不支持",只能看到统一的"书籍详情加载失败"。 ### 6.2 方案:定义错误类型,不新增异常类 ```dart enum LoadFailureReason { network, // 网络不通 / DNS 失败 / 超时 httpError, // HTTP 4xx / 5xx ruleNotSupported, // 规则语法不被当前引擎支持 ruleParseEmpty, // 规则执行成功但结果为空(可能是网站改版) encoding, // 编码问题 unknown, } ``` 在 `fetchBookInfo()` 和 `fetchToc()` 内部区分异常类型,通过 `_shortError()` 返回带 reason 的错误消息(或通过一个简单的包装类)。 ### 6.3 UI 差异化展示 ``` 网络不通: "无法连接到目标网站,请检查网络或稍后重试。" [重试] HTTP 404: "书源详情页已失效(404),该书源可能需要更新。" [更换书源] 规则不支持: "该书源的详情解析规则包含不被当前版本支持的语法(如 @js),更新 APP 后可能可用。" [查看原始页面] 规则解析为空: "目标网站页面结构已变化,书源规则可能已过时。" [重试] [更换书源] ``` ### 6.4 改动量 - `legado_engine.dart` 新增 `_classifyError()` 方法 ~30 行 - `_shortError()` 新增 reason 字段 ~10 行 - `online_book_detail_page.dart` 根据 reason 展示不同的 UI ~30 行 - 总计 ~70 行 - **零新依赖** --- ## 七、第 5 步:JS 特判(零依赖) ### 7.1 问题 很多漫画源的 `contentRule` 直接写 JS: ```json "content": "\nvar result = [];\nvar imgs = JSON.parse...\nnewImgs.map(...)\nresult.join('\\n')" ``` 或者写在 `ruleContent.content` 里用 `@js:` 前缀。 当前引擎对 `@js:` 和 `` 完全无处理能力,规则执行到这一步直接抛异常。 ### 7.2 第一阶段的 JS 特判策略 不引入完整 JS 引擎。只做模式匹配,覆盖最常见的漫画图片提取模式: | 模式 | 真实 JS 代码 | 特判正则 | |------|-------------|---------| | `newImgs.map` | `newImgs.map(i => i.url)` | 先扫描 rawHtml 中的 `var newImgs = [...]` | | `imageList` | `imageList[0].src` | 扫描 `var imageList = [...]` | | `page_url` | `page_url + img` | 扫描 `var page_url = "..."` | | `chapterImages` | `chapterImages.join` | 扫描 `var chapterImages = [...]` | | `km5_img_url` | `km5_img_url` | 扫描 `var km5_img_url = "..."` | | `base64Images` | 从 base64 解码 | 检测 `data:image` 前缀 | | `eval(decrypt(...))` | 简单解密 | 正则提取被 eval 的字符串 | ### 7.3 实现方式 ```dart List _jsFallbackImages(String rawHtml, String baseUrl) { final patterns = [ // 1. 数组变量 _JsVarPattern('newImgs', arrayPattern: true), _JsVarPattern('imageList', arrayPattern: true), _JsVarPattern('chapterImages', arrayPattern: true), _JsVarPattern('pics', arrayPattern: true), _JsVarPattern('imgList', arrayPattern: true), _JsVarPattern('pageImgs', arrayPattern: true), // 2. 字符串拼接变量 _JsVarPattern('page_url', arrayPattern: false), _JsVarPattern('imgDomain', arrayPattern: false), // 3. data:image 内嵌 _JsVarPattern('data:image', base64Pattern: true), ]; for (final pattern in patterns) { final urls = _tryExtractJsVar(rawHtml, pattern); if (urls.isNotEmpty) return urls.map((u) => resolveUrl(baseUrl, u)).toList(); } return const []; } ``` ### 7.4 改动量 - `legado_engine.dart` 新增 `_jsFallbackImages()` ~60 行 - `_tryExtractJsVar()` ~40 行 - 总计 ~100 行 - **零新依赖** --- ## 八、第 6 步:@put / @get 上下文变量 ### 8.1 用途 Legado 高级规则中可以在同一次执行中跨步骤传值: ``` @put:{bookId:$.id} // ... 在后续规则中使用 ... /api/book/{{bookId}}/chapters ``` ### 8.2 实现方式 在 `LegadoRuleExecutor` 中维护一个 `Map _context`。 ```dart class LegadoRuleExecutor { final Map _context = {}; // 执行 @put:{key:value} 时写入 _context // 解析 URL 模板时用 _context 替换 {{key}} // @get:key → 从 _context 读取 } ``` ### 8.3 改动量 - `legado_rule_parser.dart` 新增 `_context` Map ~5 行 - `@put` / `@get` 语法解析 ~30 行 - `_applySearchTemplate()` 新增 `{{$.key}}` 占位符支持 ~10 行 - 总计 ~45 行 - **零新依赖** --- ## 九、第 7 步:书源兼容度检测 ### 9.1 目标 导入书源后,自动分析每个书源用到的规则语法,打上兼容度标签,在书源管理 UI 中展示。 ### 9.2 兼容度标签定义 ```dart enum SourceCompatLevel { full, // 完全兼容:所有规则语法已被引擎支持 partial, // 部分兼容:搜索可用,但正文/详情可能因缺少 JS 执行而不完整 needsJs, // 需要 JS:contentRule 或 bookInfoRule 依赖 @js 或 needsPost, // 需要 POST 搜索:searchMethod == POST 或 URL 包含 ,{ needsHeaders, // 需要自定义请求头 broken, // 已失效:基础 URL 不可达 unknown, // 尚未验证 } class SourceCompatInfo { final SourceCompatLevel level; final bool searchOk; // 搜索规则可执行 final bool bookInfoOk; // 详情规则可执行 final bool tocOk; // 目录规则可执行 final bool contentOk; // 正文规则可执行 final bool hasJsRule; // 规则中包含 @js / final bool hasPutGet; // 规则中包含 @put / @get final List warnings; // 警告信息列表 } ``` ### 9.3 检测逻辑(导入时运行) ```dart SourceCompatInfo analyzeSource(LegadoSource source) { final warnings = []; bool hasJs = false; bool hasPutGet = false; bool hasChainSyntax = false; // 1. 检查所有规则字段是否包含 JS 语法 for (final rule in _allRuleFields(source)) { if (rule == null) continue; if (rule.contains('@js') || rule.contains('')) hasJs = true; if (rule.contains('@put') || rule.contains('@get')) hasPutGet = true; if (rule.contains('@tag.') || rule.contains('@src') || rule.contains('@text') || rule.contains('@html')) { hasChainSyntax = true; } } // 2. 评估各模块可行性 final searchOk = source.searchUrl != null && source.searchListRule != null; final bookInfoOk = source.bookInfoTocRule != null || source.bookInfoNameRule != null; final tocOk = source.tocListRule != null || source.tocNameRule != null; final contentOk = source.contentRule != null; // 3. 确定级别 SourceCompatLevel level; if (!searchOk && !contentOk) { level = SourceCompatLevel.broken; } else if (hasJs) { level = SourceCompatLevel.needsJs; } else if (hasPutGet) { level = SourceCompatLevel.partial; } else if (!bookInfoOk && !contentOk) { level = SourceCompatLevel.partial; // 只能搜 } else { level = SourceCompatLevel.full; } return SourceCompatInfo(level: level, ...); } ``` ### 9.4 UI 展示 在 `source_manager_page.dart` 的书源列表中,每行右侧显示兼容度标签: ``` 包子漫画5 [🔴 需要 JS] 6漫画 [🔴 需要 JS] 全本玄幻小说 [🟢 完全兼容] WebToon [🟡 需要 POST] 某已失效源 [⚫ 已失效] ``` ### 9.5 改动量 - `legado_models.dart` 新增 `SourceCompatInfo` 类 ~30 行 - `source_manager.dart` 新增 `analyzeSource()` ~50 行 - `source_manager_page.dart` UI 展示 ~40 行 - 总计 ~120 行 - **零新依赖** --- ## 十、第 8 步:完整 JS 引擎 ### 10.1 时机 前 7 步完成后,已有书源中约 60-70% 的漫画源可正常阅读(通过 JS 特判覆盖)。剩下的 30-40% 需要完整 JS 执行环境。 ### 10.2 推荐方案 | 方案 | 优点 | 缺点 | |------|------|------| | **flutter_js** | 纯 Dart,不依赖 WebView | 性能一般,JS 互操作受限 | | **quickjs_dart_bridge** | 轻量、快、支持 ES2020 | 需要 Native 桥接 | | **flutter_js_engine** | 基于 JavaScriptCore/QuickJS | 体积较大 | | **WebView 隐藏执行** | 兼容性最好 | 太重,不适合批量 | **建议**:先用 **quickjs_dart_bridge**(已有成功集成到阅读器的先例)。 ### 10.3 注入的 JS 运行环境 ```js // 注入变量 result; // 当前 HTML 或 RuleParser 结果 baseUrl; // 当前请求的 base URL // 注入函数(兼容 Legado 的 java.xxx 调用风格) java.get(key); // → 从 _context 读 java.put(key, value); // → 写入 _context java.getElements(html, selector); // → querySelectorAll → 返回元素列表 java.base64Decode(str); // → base64 解码 java.ajax(url); // → HTTP GET → 返回响应文本 // 注入输出收集器 __result; // 脚本执行完毕后读取此变量作为输出 ``` ### 10.4 安全措施 - JS 沙箱:禁止 `XMLHttpRequest`、`fetch`、`localStorage` - 超时限制:每条 JS 规则最多执行 3 秒 - 错误隔离:单条 JS 规则失败不影响其他规则 - Isolate 执行:防卡 UI(可选,复杂度较高) ### 10.5 改动量 - `pubspec.yaml` 新增 `quickjs_dart_bridge` 依赖 - 新建 `legado_js_runner.dart` ~150 行 - `LegadoRuleExecutor` 集成 JS 执行 ~30 行 - 总计 ~180 行 --- ## 十一、完整实施路线图 ``` Week 1 ████████░░░░░░░░░░░░ 第1步: rawHtml 兜底 + script 变量扫描 第2步: @tag/@text/@html/@src 链式语法 Week 2 ████████░░░░░░░░░░░░ 第3步: ##/||/&& 语法 第4步: 错误类型区分 Week 3 ████████████████░░░░ 第5步: JS 特判 第6步: @put/@get 第7步: 书源兼容度检测 Week 4+ ████████████████████ 第8步: 完整 JS 引擎 测试: 30+ 书源的回归测试 零新依赖 新依赖 ├───────────────────┼──────────┤ 第1步 第8步 第2步 第3步 第4步 第5步 第6步 第7步 ``` --- ## 十二、改动文件清单 | 文件 | 第1步 | 第2步 | 第3步 | 第4步 | 第5步 | 第6步 | 第7步 | 第8步 | |------|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:| | `legado_rule_parser.dart` | | 🔧250 | 🔧80 | | | 🔧45 | | | | `legado_engine.dart` | 🔧40 | | | 🔧70 | 🔧100 | 🔧10 | | 🔧30 | | `legado_models.dart` | | | | | | | 🔧30 | | | `source_manager.dart` | | | | | | | 🔧50 | | | `source_manager_page.dart` | | | | | | | 🔧40 | | | `online_book_detail_page.dart` | | | | 🔧30 | | | | | | `legado_js_runner.dart` 🆕 | | | | | | | | 🆕150 | | `pubspec.yaml` | | | | | | | | +1dep | --- ## 十三、总结 整个方案的核心理念是: ``` RuleParser 是对现有 CSS/JSON/Regex 的兼容 → 保留为底层原子工具 LegadoRuleExecutor 是新增的链式规则执行层 → 理解 @tag、##、||、&& JS 分两级做 → 特判覆盖 60% + 引擎覆盖 40% 书源兼容度检测 → 导入时打标签,用户体验闭环 请求层不动 —— 它没问题 Bug 优先级由截图驱动 —— 第1步修截图3,第2步解锁主流漫画源,第4步修截图1 前4步零新依赖,直接在现有文件里改 ``` **一句话**:不推翻现有代码,在 `RuleParser` 之上加一层**链式规则执行器**,让 `@tag.img@src` 和 `##替换` 能被正确理解,这是解锁包子漫画 5 等主流漫画源的关键。 --- ## 附录:All.json 常见规则语法统计 基于对 30+ 个典型漫画/小说书源规则的手工分析: | 语法 | 出现频率 | 典型场景 | 本方案覆盖 | |------|:--------:|---------|:----------:| | `@tag.xxx` | ★★★★★ | 漫画正文图片提取 | 第2步 | | `@src` | ★★★★★ | 图片 URL 提取 | 第2步 | | `@text` | ★★★★ | 书名/作者/章节名 | 第2步 | | `@html` | ★★★ | 正文 HTML 提取 | 第2步 | | `##` | ★★★★ | 广告/水印净化 | 第3步 | | `\|\|` | ★★★★ | 备选规则 | 第3步 | | `&&` | ★★★ | 多字段拼接 | 第3步 | | `` / `@js:` | ★★★ | 漫画图片解密 | 第5/8步 | | `@put` / `@get` | ★★ | 跨步骤传递 ID | 第6步 | | `@css:` | ★★★ | 嵌套 CSS 选择 | 第2步 | | `@data-xxx` | ★★ | data-original 等 | 第2步 | | `,{method,body}` | ★★ | POST 搜索 | 请求层(现有) |