Files
SakuraHub/docs/Legado规则引擎重构-分阶段实施方案.md
2026-11-16 20:45:22 +08:00

739 lines
26 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 藏在 `<script>` 的 JS 变量里(如 `var newImgs = ["url1","url2"]`),暴力扫描 `<img>` 标签找不到任何东西。
### 3.2 修改位置
`legado_engine.dart` 中的 `fetchChapterContent()` 和 `_extractImageUrls()`。
### 3.3 逻辑
```
extractImagesWithFallback(String rawHtml, String baseUrl):
1. 先用 RuleParser 走 contentRule → 语法错误或结果为空 → 进入兜底
2. 兜底 1:扫描 HTML img 标签
RegExp: <img[^>]+(?:src|data-src|data-original|data-srcset)=["']([^"']+)["']
同时提取 srcset 中的备选 URL
3. 兜底 2:扫描常见 JS 变量
按优先级依次尝试:
newImgs = [...]
imageList = [...]
chapterImages = [...]
page_url = ...
pics = [...]
imgData = [...]
chapterData.images = [...]
km5_img_url = ...
result.imageList = ...
提取方式:
RegExp: var\s+变量名\s*=\s*(\[[^\]]*\])
RegExp: var\s+变量名\s*=\s*['"]([^'"]+)['"]
如果是 JSON 数组 → jsonDecode
如果是逗号分隔 → split(',').map(trim)
4. 兜底 3:扫描 data:image 内嵌图片
5. 全部 URL resolve 为绝对路径
```
### 3.4 改动量
- `_extractImageUrls()` 新增 ~40 行
- 不影响现有 `RuleParser` 任何逻辑
- 无需新依赖
### 3.5 预期效果
截图 3 「这一章还没有找到漫画页面」在包子漫画 5 上直接消除(即使 `contentRule` 语法不被支持,script 变量扫描也能抓到 `newImgs`)。
---
## 四、第 2 步:RuleParser 支持 @tag/@text/@html/@src 链式语法
> 这是最核心的一步。包子漫画 5、6漫画、WebToon 等主流漫画源全部依赖这种语法。
### 4.1 Legado 链式规则语法规范
Legado 规则的本质是**管道链式操作**,每一步的输出是下一步的输入。语法格式:
```
基础选择器@操作.子选择器@属性
```
**链式管道符**:
| 符号 | 含义 | 示例 |
|------|------|------|
| `@tag.xxx` | 在当前结果内找第一个 `<xxx>` 子元素 | `@tag.img` → 找 img 标签 |
| `@text` | 提取当前元素的 innerText | `.title@text` |
| `@html` | 提取当前元素的 innerHtml | `.content@html` |
| `@src` | 提取 src 属性值 | `img@src` |
| `@href` | 提取 href 属性值 | `a@href` |
| `@class` | 提取 class 属性值 | `div@class` |
| `@alt` / `@title` | 提取 alt / title 属性 | `img@alt` |
| `@data-xxx` | 提取 data-xxx 属性值 | `img@data-original` |
| `@css:.xxx` | 用 CSS 选择器在当前结果内再次选择 | `div.content@css:.chapter@text` |
**管道执行顺序**:
```
原始 HTML
→ CSS 选择器(第一段)→ 得到匹配元素集合
→ @tag.img → 在每个元素内找第一个 img
→ @src → 提取 src 属性值
→ 返回字符串列表
```
### 4.2 实现方式:在 RuleParser 内部新增链式分支
`select()` 和 `selectList()` 方法检测规则中是否包含 `@tag` / `@text` / `@html` / `@src` 等链式操作符。如果有,走新分支 `_selectChain()`。
```dart
List<String> _selectChain(String fragment, String rule) {
// 1. 解析 rule 为执行步列表
final steps = _parseChainSteps(rule);
// 2. 从 fragment 开始,逐步执行
var current = <String>[fragment];
for (final step in steps) {
current = _executeChainStep(current, step);
if (current.isEmpty) return const [];
}
return current;
}
List<_ChainStep> _parseChainSteps(String rule) {
// 规则示例: ".book-list li@tag.a@href"
// 拆分为: [('.book-list li', css), ('a', tag), ('href', attr)]
//
// 关键:@ 是管道分隔符,不是属性选择器的一部分
// "@tag.xxx" 是一个整体 token
// "@src" "@href" "@text" "@html" 是属性提取 token
// "@css:.xxx" 是嵌套 CSS token
}
List<String> _executeChainStep(List<String> fragments, _ChainStep step) {
switch (step.type) {
case _StepType.css:
return _cssSelect(fragments, step.value); // 降级到现有 CSS 路径
case _StepType.tag:
return _tagSelect(fragments, step.value); // fragments 中每个元素内找第一个 <tag>
case _StepType.attr:
return _attrExtract(fragments, step.value); // 提取属性值
case _StepType.text:
return _textExtract(fragments); // 提取 innerText
case _StepType.html:
return _htmlExtract(fragments); // 提取 innerHtml
case _StepType.nestedCss:
return _nestedCssSelect(fragments, step.value); // @css: 语法
}
}
```
### 4.3 链式步骤解析规则
```
规则字符串:
"div.image-area@tag.img@src"
解析产物:
[
{ type: css, value: "div.image-area" }, // @ 之前的部分 → CSS 选择器
{ type: tag, value: "img" }, // @tag.img → 找 img 子标签
{ type: attr, value: "src" }, // @src → 提取 src 属性
]
规则字符串:
"h1.title@text||h1.book-name@text"
解析产物(备选规则):
[
[ {css:"h1.title"}, {text} ], // 方案 A
[ {css:"h1.book-name"}, {text} ], // 方案 B → 先执行 A,A 为空则执行 B
]
规则字符串:
".chapter-content@html##去除广告正则##"
解析产物(带替换):
[
{ type: css, value: ".chapter-content" },
{ type: html, value: null },
{ type: regexReplace, value: "去除广告正则" },
]
```
### 4.4 改动量
- `legado_rule_parser.dart` 新增 `_selectChain()` 方法 ~120 行
- `_parseChainSteps()` ~40 行
- 辅助方法 `_tagSelect()` / `_attrExtract()` / `_textExtract()` / `_htmlExtract()` ~80 行
- `select()` 和 `selectList()` 入口处新增链式检测分支 ~10 行
- 总计 ~250 行
- **零新依赖**(tagSelect / attrExtract 用现有 html parser 或 RegExp 实现)
### 4.5 预期效果
包子漫画 5 的 `contentRule: "div.comic-content@tag.img@src"` 能正确执行:
1. CSS `div.comic-content` → 拿到内容区 DOM
2. `@tag.img` → 在内容区找所有 img 标签
3. `@src` → 提取每个 img 的 src
4. 返回图片 URL 列表
---
## 五、第 3 步:支持 ## 替换、|| 备选、&& 拼接
### 5.1 语法定义
| 符号 | 含义 | 示例 |
|------|------|------|
| `\|\|` | 备选规则:第一个成功就返回,否则尝试下一个 | `.title@text\|\|h1@text` |
| `&&` | 串联拼接:两个结果用空格或换行拼接 | `.title@text&&.author@text` |
| `##` | 正则替换/净化:对当前结果执行正则替换 | `@text##\s+\|\|##g` |
| `###` | 正则删除:删除匹配的部分 | `@html###<script[^>]*>.*?</script>###` |
### 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": "<js>\nvar result = [];\nvar imgs = JSON.parse...\nnewImgs.map(...)\nresult.join('\\n')</js>"
```
或者写在 `ruleContent.content` 里用 `@js:` 前缀。
当前引擎对 `@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<String> _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<String, String> _context`。
```dart
class LegadoRuleExecutor {
final Map<String, String> _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 或 <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 / <js>
final bool hasPutGet; // 规则中包含 @put / @get
final List<String> warnings; // 警告信息列表
}
```
### 9.3 检测逻辑(导入时运行)
```dart
SourceCompatInfo analyzeSource(LegadoSource source) {
final warnings = <String>[];
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('<js>')) 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>` / `@js:` | ★★★ | 漫画图片解密 | 第5/8步 |
| `@put` / `@get` | ★★ | 跨步骤传递 ID | 第6步 |
| `@css:` | ★★★ | 嵌套 CSS 选择 | 第2步 |
| `@data-xxx` | ★★ | data-original 等 | 第2步 |
| `,{method,body}` | ★★ | POST 搜索 | 请求层(现有) |