# 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 搜索 | 请求层(现有) |