commit
9c5fef1a4d
412 files changed
+94582
No files matched your search
@@ -0,0 +1,555 @@
|
||||
"""
|
||||
Append "两项核心改进" markdown content to the main docx document.
|
||||
"""
|
||||
import sys, os, re
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
|
||||
from docx import Document
|
||||
from docx.shared import Pt, Inches, RGBColor
|
||||
from docx.oxml.ns import qn
|
||||
|
||||
DOCX_PATH = "docs/Sakura_Downloader_完整项目文档.docx"
|
||||
MD_PATH = "docs/三项核心改进-分页规则_搜索健康分_书架保存解耦.md"
|
||||
|
||||
doc = Document(DOCX_PATH)
|
||||
|
||||
# ---- helpers ----
|
||||
from docx.oxml import OxmlElement
|
||||
|
||||
def page_break():
|
||||
p = doc.add_paragraph()
|
||||
run = p.add_run()
|
||||
br = OxmlElement('w:br')
|
||||
br.set(qn('w:type'), 'page')
|
||||
run._element.append(br)
|
||||
|
||||
def heading(text, level=1):
|
||||
return doc.add_heading(text, level=level)
|
||||
|
||||
def para(text):
|
||||
return doc.add_paragraph(text)
|
||||
|
||||
def bold_para(text):
|
||||
p = doc.add_paragraph()
|
||||
run = p.add_run(text)
|
||||
run.bold = True
|
||||
return p
|
||||
|
||||
def code_block(code_text):
|
||||
for line in code_text.split('\n'):
|
||||
p = doc.add_paragraph()
|
||||
p.paragraph_format.space_before = Pt(0)
|
||||
p.paragraph_format.space_after = Pt(0)
|
||||
p.paragraph_format.left_indent = Inches(0.3)
|
||||
run = p.add_run(line if line else ' ')
|
||||
run.font.name = 'Consolas'
|
||||
run.font.size = Pt(8.5)
|
||||
run.font.color.rgb = RGBColor(0x33, 0x33, 0x33)
|
||||
try:
|
||||
run._element.rPr.rFonts.set(qn('w:eastAsia'), 'Consolas')
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
def make_table(headers, rows):
|
||||
table = doc.add_table(rows=1, cols=len(headers), style='Table Grid')
|
||||
hdr_cells = table.rows[0].cells
|
||||
for i, h in enumerate(headers):
|
||||
hdr_cells[i].text = h
|
||||
for p in hdr_cells[i].paragraphs:
|
||||
for run in p.runs:
|
||||
run.bold = True
|
||||
for row_data in rows:
|
||||
row = table.add_row()
|
||||
for i, txt in enumerate(row_data):
|
||||
row.cells[i].text = str(txt)
|
||||
return table
|
||||
|
||||
# ============================================================
|
||||
# APPEND NEW APPENDIX
|
||||
# ============================================================
|
||||
|
||||
page_break()
|
||||
heading('附录 B — 两项核心改进:TOC 分页规则 · 搜索健康分', level=1)
|
||||
para('')
|
||||
para('日期:2026-06-22(v2,整合 Claude / ChatGPT / Gemini 三方 review)')
|
||||
para('范围:仅移动端 Dart 侧(sakura_mobile/lib/src/core/)')
|
||||
para('原则:不改 Python 插件,不改 UI 层,只动 core 层。')
|
||||
para('')
|
||||
|
||||
# ── Part 0 ──
|
||||
heading('〇、前置声明:图片解析问题是独立维度', level=2)
|
||||
para('ChatGPT 指出一个关键事实——当前用户最痛的是"搜得到、看不了",而不是"搜得慢"。图片解析失败的根因是 @js 规则执行器缺失(newImgs、eval(result.match(...)) 等 JS 表达式无法执行),这套方案没有直接解决它。')
|
||||
para('真正解决"看不了"需要:LegadoRuleExecutor V2 + QuickJS,见《Legado规则引擎重构方案》。')
|
||||
para('本文档解决的是另外两个独立的、也必须解决的痛点:')
|
||||
para(' • 目录只拿到前 50 章 → 改进 1')
|
||||
para(' • 搜索等 20 秒才出结果 → 改进 2')
|
||||
para(' • 打开章节图片为空 → 需要 JS 引擎(本文档范围外)')
|
||||
para('实施时不冲突,可以并行推进。但 TOC 分页规则中有 <js> / @js: 语法,如果涉及 java.get() / java.put() / java.ajax(),需要等 JS 引擎到位后才能完整支持。详见 §1.7。')
|
||||
para('')
|
||||
|
||||
# ── Part 1 ──
|
||||
heading('一、改进 1:TOC 章节目录分页规则完整支持', level=2)
|
||||
|
||||
heading('1.1 问题', level=3)
|
||||
para('fetchToc() 只拉第一页目录。很多书源第一页只给 50~100 章,剩余的靠分页目录规则指向下一页。不支持分页规则 → 用户看到的目录永远不全。')
|
||||
|
||||
heading('1.2 兼容的字段名(解析时一次性确定)', level=3)
|
||||
para('书源 JSON 中,下一页 URL 的字段名可能是以下任意一种。在 fromJson 阶段遍历一次并存入 _resolvedTocNextPageRule,避免每次访问 getter 都遍历。')
|
||||
|
||||
code_block("""static const List<String> _tocNextPageCandidates = [
|
||||
'tocNextPageRule', // Legado 标准名
|
||||
'nextTocUrl', // 常见别名
|
||||
'nextUrl', // 通用别名
|
||||
'nextPage', // 页码式
|
||||
'tocNextPage', // 变体
|
||||
];
|
||||
|
||||
String? _resolvedTocNextPageRule;
|
||||
|
||||
String? get tocNextPageRule => _resolvedTocNextPageRule;
|
||||
|
||||
// 在 fromJson 中调用一次:
|
||||
void _resolveTocNextPageRule(Map<String, dynamic> json) {
|
||||
for (final name in _tocNextPageCandidates) {
|
||||
final v = json[name];
|
||||
if (v is String && v.trim().isNotEmpty) {
|
||||
_resolvedTocNextPageRule = v.trim();
|
||||
return;
|
||||
}
|
||||
}
|
||||
_resolvedTocNextPageRule = null;
|
||||
}""")
|
||||
|
||||
heading('1.3 分页规则语法全集', level=3)
|
||||
make_table(
|
||||
['规则类型', '语法示例', '说明'],
|
||||
[
|
||||
['JS 表达式(简单)', '<js>nextUrl</js>', '简单 JS 可直接 eval'],
|
||||
['JS 表达式(复杂)', '<js>java.get("baseUrl")</js>', '需要 JS 引擎(见 §1.7)'],
|
||||
['JS 缩写', '@js:nextUrl', '同上'],
|
||||
['模板拼接', 'https://host/list?page={{page}}', '{{page}} 从 1 自增'],
|
||||
['偏移模板', '{{page+1}} / {{page-1}}', '页号偏移'],
|
||||
['CSS 选择器', 'text.下一页@href', '从当前页 HTML 提取'],
|
||||
['class 选择器', 'class.next@href', '同上'],
|
||||
['id 选择器', 'id.pagenext@href', '同上'],
|
||||
['XPath', '//a[contains(text(),\'下一页\')]/@href', 'XPath 提取'],
|
||||
['字符串切片', '!0:-1', '对当前 URL 切片'],
|
||||
['offset 翻页', 'offset=50', '按 offset 递增'],
|
||||
['纯文本 URL', 'https://...', '直接跳转'],
|
||||
['相对路径', '/list/2.html', '基于当前 URL 拼接'],
|
||||
]
|
||||
)
|
||||
para('')
|
||||
|
||||
heading('1.4 实现 — TocPaginationResolver', level=3)
|
||||
|
||||
code_block("""class TocPaginationResolver {
|
||||
final LegadoRuleExecutor _ruleExecutor;
|
||||
final HttpClient _client;
|
||||
|
||||
TocPaginationResolver(this._ruleExecutor, this._client);
|
||||
|
||||
/// 拉取全部分页章节,合并去重。
|
||||
/// 返回 Stream 以便 UI 逐页展示进度。
|
||||
Stream<List<ChapterInfo>> fetchAllChapters({
|
||||
required String firstPageUrl,
|
||||
required String? tocNextPageRule,
|
||||
required String tocRule,
|
||||
required Map<String, String>? headers,
|
||||
int maxPages = 20,
|
||||
}) async* {
|
||||
final all = <ChapterInfo>[];
|
||||
final seenPageUrls = <String>{};
|
||||
final seenChapterUrls = <String>{};
|
||||
|
||||
String? url = firstPageUrl;
|
||||
int page = 0;
|
||||
|
||||
while (url != null && page < maxPages) {
|
||||
if (!seenPageUrls.add(url)) break;
|
||||
|
||||
final html = await _client.get(url, headers: headers);
|
||||
final batch = _ruleExecutor.selectList(html, url, rule: tocRule);
|
||||
|
||||
int added = 0;
|
||||
for (final ch in batch) {
|
||||
if (seenChapterUrls.add(ch.url)) {
|
||||
all.add(ch);
|
||||
added++;
|
||||
}
|
||||
}
|
||||
|
||||
if (batch.isNotEmpty) yield List.of(batch);
|
||||
if (added == 0) break;
|
||||
|
||||
url = _resolveNextPage(
|
||||
currentUrl: url,
|
||||
currentHtml: html,
|
||||
rule: tocNextPageRule,
|
||||
pageIndex: page,
|
||||
);
|
||||
page++;
|
||||
}
|
||||
}
|
||||
|
||||
String? _resolveNextPage({
|
||||
required String currentUrl,
|
||||
required String currentHtml,
|
||||
required String? rule,
|
||||
required int pageIndex,
|
||||
}) {
|
||||
if (rule == null || rule.trim().isEmpty) return null;
|
||||
final r = rule.trim();
|
||||
|
||||
// 1) JS: <js>...</js> 或 @js:...
|
||||
if (r.startsWith('<js>') || r.startsWith('@js:')) {
|
||||
final code = r
|
||||
.replaceFirst(RegExp(r'^<js>'), '')
|
||||
.replaceFirst(RegExp(r'</js>$'), '')
|
||||
.replaceFirst(RegExp(r'^@js:'), '');
|
||||
return _ruleExecutor.evalJs(code, context: {
|
||||
'result': currentHtml,
|
||||
'baseUrl': currentUrl,
|
||||
'page': pageIndex,
|
||||
});
|
||||
}
|
||||
|
||||
// 2) 切片
|
||||
if (r.startsWith('!')) return _applySlice(currentUrl, r.substring(1));
|
||||
|
||||
// 3) CSS 选择器 / XPath
|
||||
if (_isSelector(r)) return _ruleExecutor.select(currentHtml, currentUrl, rule: r);
|
||||
|
||||
// 4) 模板 {{page}} / {{page+1}} / {{page-1}}
|
||||
if (r.contains('{{page')) return _renderPageTemplate(r, pageIndex);
|
||||
|
||||
// 5) offset / start 参数
|
||||
if (RegExp(r'[?&](offset|start)=').hasMatch(r)) return _renderOffsetTemplate(r, pageIndex);
|
||||
|
||||
// 6) 绝对 URL
|
||||
if (r.startsWith('http://') || r.startsWith('https://')) return _renderPageTemplate(r, pageIndex);
|
||||
|
||||
// 7) 相对路径
|
||||
return Uri.parse(currentUrl).resolve(r).toString();
|
||||
}
|
||||
|
||||
bool _isSelector(String s) =>
|
||||
s.startsWith('text.') || s.startsWith('class.') ||
|
||||
s.startsWith('id.') || s.startsWith('@') || s.startsWith('//');
|
||||
|
||||
// 模板渲染(Dart 语法修正:用 .toString() 而非字符串插值)
|
||||
String _renderPageTemplate(String tpl, int page) {
|
||||
return tpl
|
||||
.replaceAll('{{page+1}}', (page + 1).toString())
|
||||
.replaceAll('{{page-1}}', (page - 1).toString())
|
||||
.replaceAll('{{page}}', page.toString());
|
||||
}
|
||||
|
||||
// offset 修正:initial + initial * page,而非 initial * page
|
||||
String _renderOffsetTemplate(String tpl, int page) {
|
||||
return tpl
|
||||
.replaceAllMapped(RegExp(r'offset=(\\d+)'), (m) {
|
||||
final initial = int.parse(m.group(1)!);
|
||||
return 'offset=${initial + initial * page}';
|
||||
})
|
||||
.replaceAllMapped(RegExp(r'start=(\\d+)'), (m) {
|
||||
final initial = int.parse(m.group(1)!);
|
||||
return 'start=${initial + initial * page}';
|
||||
});
|
||||
}
|
||||
|
||||
String? _applySlice(String url, String expr) {
|
||||
final parts = expr.split(':');
|
||||
if (parts.length != 2) return null;
|
||||
final a = int.tryParse(parts[0]) ?? 0;
|
||||
final b = int.tryParse(parts[1]);
|
||||
final start = a < 0 ? url.length + a : a;
|
||||
if (b != null) {
|
||||
final end = b < 0 ? url.length + b : b;
|
||||
return url.substring(start, end);
|
||||
}
|
||||
return url.substring(start);
|
||||
}
|
||||
}""")
|
||||
|
||||
para('')
|
||||
heading('1.5 集成到 LegadoEngine.fetchToc', level=3)
|
||||
|
||||
code_block("""Future<List<ChapterInfo>> fetchToc(BookSource source, String tocUrl) async {
|
||||
final rule = source.tocRule;
|
||||
if (rule == null || rule.isEmpty) return [];
|
||||
|
||||
final resolver = TocPaginationResolver(_ruleExecutor, _client);
|
||||
final all = <ChapterInfo>[];
|
||||
await for (final batch in resolver.fetchAllChapters(
|
||||
firstPageUrl: tocUrl,
|
||||
tocNextPageRule: source.tocNextPageRule,
|
||||
tocRule: rule,
|
||||
headers: _buildHeaders(source),
|
||||
maxPages: 20,
|
||||
)) {
|
||||
all.addAll(batch);
|
||||
}
|
||||
return all;
|
||||
}""")
|
||||
|
||||
para('')
|
||||
heading('1.6 死循环防护(三层)', level=3)
|
||||
para(' 1. maxPages = 20 — 单书最多翻 20 页目录')
|
||||
para(' 2. seenPageUrls — 同一 URL 不重复请求')
|
||||
para(' 3. added == 0 终止 — 当前页无新增章节则停止,防止环状分页')
|
||||
|
||||
heading('1.7 JS 规则的兼容边界', level=3)
|
||||
para('TOC 分页规则中有 <js> / @js: 语法,分为两档:')
|
||||
|
||||
make_table(
|
||||
['复杂度', '示例', '当前能否跑'],
|
||||
[
|
||||
['简单 JS', 'nextUrl', '✅ 正则/字符串拼接能跑'],
|
||||
['中等 JS', 'JSON.parse(result).nextPage', '✅ 如有 JSON 解析'],
|
||||
['复杂 JS', 'java.get("baseUrl")', '❌ 需要 LegadoJsRuntime'],
|
||||
['复杂 JS', 'java.ajax(url)', '❌ 需要完整 QuickJS'],
|
||||
]
|
||||
)
|
||||
|
||||
para('简单 JS 分页规则(约占 60%)可立即支持;复杂 JS 需要等 JS 引擎到位后补上。届时只需在 _resolveNextPage 的 JS 分支里替换 eval 实现即可,代码结构不需要改。')
|
||||
para('')
|
||||
|
||||
# ── Part 2 ──
|
||||
heading('二、改进 2:搜索源健康分 + 短超时 + 滑动窗口并发', level=2)
|
||||
|
||||
heading('2.1 问题', level=3)
|
||||
para('当前 search() 对所有启用源并发请求,每个源 timeout 20~30 秒。10 个源一批,坏源多时整批拖到 20+ 秒。两个根因:')
|
||||
para(' 1. 坏源不降权 — 每次都等它超时')
|
||||
para(' 2. Future.wait 批量阻塞 — 一个慢源卡住整批')
|
||||
|
||||
heading('2.2 源健康分模型(SourceHealth)', level=3)
|
||||
para('核心特性:')
|
||||
para(' • 成功率 60% + 平均延迟 25% + 新鲜度 15%,满分 100')
|
||||
para(' • 连续失败 ≥5 → 熔断,但每 1 小时自动释放一次探测机会(熔断恢复)')
|
||||
para(' • 分数在 getter 中动态计算衰减(超过 7 天无活动折半),不依赖 save 时机')
|
||||
para(' • 衰减不修改原始数据,只在读取时乘以系数')
|
||||
|
||||
code_block("""class SourceHealth {
|
||||
final String sourceId;
|
||||
int successCount = 0, failCount = 0, timeoutCount = 0;
|
||||
int totalLatencyMs = 0, _consecutiveFails = 0;
|
||||
DateTime? lastSuccessAt, lastFailAt;
|
||||
|
||||
// 熔断 + 自动恢复:连续失败 >=5 且距上次失败 <1h -> 禁用
|
||||
bool get isUsable {
|
||||
if (_consecutiveFails >= 5) {
|
||||
if (lastFailAt != null &&
|
||||
DateTime.now().difference(lastFailAt!).inHours >= 1) return true;
|
||||
return false;
|
||||
}
|
||||
if (failCount >= 5 && successCount == 0) return false;
|
||||
return true;
|
||||
}
|
||||
|
||||
// 健康分 0~100(动态衰减,不依赖 save 时机)
|
||||
double get score {
|
||||
final latest = lastSuccessAt ?? lastFailAt;
|
||||
final decay = latest != null &&
|
||||
DateTime.now().difference(latest).inDays >= 7 ? 0.5 : 1.0;
|
||||
final total = successCount + failCount + timeoutCount;
|
||||
if (total == 0) return 50.0 * decay;
|
||||
double s = 60.0 * (successCount / total.toDouble());
|
||||
if (successCount > 0 && totalLatencyMs > 0) {
|
||||
final avg = totalLatencyMs / successCount;
|
||||
if (avg < 500) s += 25.0;
|
||||
else if (avg < 2000) s += 25.0 * (1.0 - (avg - 500) / 1500);
|
||||
}
|
||||
if (lastSuccessAt != null) {
|
||||
final h = DateTime.now().difference(lastSuccessAt!).inHours;
|
||||
if (h < 1) s += 15.0;
|
||||
else if (h < 24) s += 15.0 * (1.0 - h / 24);
|
||||
}
|
||||
return (s * decay).clamp(0.0, 100.0);
|
||||
}
|
||||
|
||||
void recordSuccess(int latencyMs) { successCount++; totalLatencyMs += latencyMs; lastSuccessAt = DateTime.now(); _consecutiveFails = 0; }
|
||||
void recordFailure() { failCount++; lastFailAt = DateTime.now(); _consecutiveFails++; }
|
||||
void recordTimeout() { timeoutCount++; lastFailAt = DateTime.now(); _consecutiveFails++; }
|
||||
}""")
|
||||
|
||||
para('')
|
||||
heading('2.3 健康分持久化(防抖 + 延迟写盘)', level=3)
|
||||
para('SourceHealthStore 关键设计:')
|
||||
para(' • recordSuccess/recordFailure/recordTimeout 只改内存 Map,不触发 IO')
|
||||
para(' • save() 启动 2 秒 Timer,同一轮搜索的多次调用被合并(防抖)')
|
||||
para(' • flush() 立即写盘(仅在 app 退出时调用,取消 Timer 后直接写)')
|
||||
para(' • 衰减计算在 SourceHealth.score getter 中动态完成,save 时不修改原始数据')
|
||||
|
||||
heading('2.4 分阶段搜索调度器(滑动窗口 + 取消机制)', level=3)
|
||||
para('核心改进:')
|
||||
para(' • 滑动窗口 _pool 替代 Future.wait — 最大并发 6,谁先完成谁先返回,快源不阻塞')
|
||||
para(' • _searchToken 版本号 — 用户连续搜索 A→B→C 时旧结果自动丢弃')
|
||||
para(' • 慢源结果走同一个 Stream yield(不引入 EventBus),保持数据流单一源')
|
||||
para(' • 整轮搜索结束后统一调用一次 health.save()')
|
||||
|
||||
code_block("""class SearchScheduler {
|
||||
static const fastTimeout = Duration(seconds: 5);
|
||||
static const slowTimeout = Duration(seconds: 8);
|
||||
static const maxConcurrent = 6;
|
||||
int _searchToken = 0; // 取消旧搜索用
|
||||
|
||||
Stream<SearchPhase> search(String keyword, List<BookSource> allSources) async* {
|
||||
final token = ++_searchToken;
|
||||
|
||||
final usable = allSources.where((s) => _health.isUsable(s.id)).toList()
|
||||
..sort((a, b) => _health.score(b.id).compareTo(_health.score(a.id)));
|
||||
|
||||
if (usable.isEmpty) { yield SearchPhase(name: 'error', message: '没有可用的搜索源'); return; }
|
||||
|
||||
// 分三档
|
||||
final fast = usable.where((s) => _health.score(s.id) >= 70).toList();
|
||||
final normal = usable.where((s) { final sc = _health.score(s.id); return sc >= 40 && sc < 70; }).toList();
|
||||
final slow = usable.where((s) => _health.score(s.id) < 40).toList();
|
||||
|
||||
final results = <SearchItem>[], doneIds = <String>{}, seen = <String>{};
|
||||
|
||||
// 阶段 1:快速源(5s 超时,滑动窗口)
|
||||
await for (final r in _pool(fast, keyword, timeout: fastTimeout, token: token))
|
||||
{ doneIds.add(r.sourceId); _merge(results, r.items, seen); }
|
||||
yield SearchPhase(name: 'partial', items: List.of(results), doneCount: doneIds.length, totalCount: usable.length);
|
||||
|
||||
// 阶段 2:普通源(8s 超时)
|
||||
await for (final r in _pool(normal, keyword, timeout: slowTimeout, token: token))
|
||||
{ doneIds.add(r.sourceId); _merge(results, r.items, seen); }
|
||||
yield SearchPhase(name: 'partial', items: List.of(results), doneCount: doneIds.length, totalCount: usable.length);
|
||||
|
||||
// 阶段 3:慢源后台继续,走同一个 Stream
|
||||
if (slow.isNotEmpty) {
|
||||
yield SearchPhase(name: 'pending_slow', items: List.of(results), doneCount: doneIds.length, totalCount: usable.length,
|
||||
message: '${slow.length} 个慢源正在后台搜索...');
|
||||
await for (final r in _pool(slow, keyword, timeout: slowTimeout, token: token)) {
|
||||
if (token != _searchToken) return; // 用户发起新搜索,丢弃旧结果
|
||||
doneIds.add(r.sourceId); _merge(results, r.items, seen);
|
||||
yield SearchPhase(name: 'slow_append', items: List.of(results), doneCount: doneIds.length, totalCount: usable.length);
|
||||
}
|
||||
}
|
||||
|
||||
yield SearchPhase(name: 'complete', items: List.of(results), doneCount: doneIds.length, totalCount: usable.length);
|
||||
unawaited(_health.save()); // 整轮搜索结束统一写盘
|
||||
}
|
||||
|
||||
// 滑动窗口并发(替代 Future.wait)
|
||||
Stream<_SourceResult> _pool(List<BookSource> sources, String keyword, {required Duration timeout, required int token}) async* {
|
||||
final pending = sources.toList();
|
||||
final running = <Future<_SourceResult?>>{};
|
||||
while (pending.isNotEmpty || running.isNotEmpty) {
|
||||
while (running.length < maxConcurrent && pending.isNotEmpty)
|
||||
running.add(_searchOne(pending.removeAt(0), keyword, timeout, token: token));
|
||||
if (running.isEmpty) break;
|
||||
final done = await Future.any(running.map((f) => f.then((v) => (f, v))));
|
||||
running.remove(done.$1);
|
||||
if (done.$2 != null) yield done.$2!;
|
||||
}
|
||||
}
|
||||
|
||||
Future<_SourceResult?> _searchOne(BookSource source, String keyword, Duration timeout, {required int token}) async {
|
||||
if (token != _searchToken) return null;
|
||||
final sw = Stopwatch()..start();
|
||||
try {
|
||||
final items = await _engine.search(source, keyword).timeout(timeout);
|
||||
if (token != _searchToken) return null;
|
||||
sw.stop();
|
||||
_health.recordSuccess(source.id, sw.elapsedMilliseconds);
|
||||
return _SourceResult(source.id, items);
|
||||
} on TimeoutException {
|
||||
_health.recordTimeout(source.id);
|
||||
return null;
|
||||
} catch (_) {
|
||||
_health.recordFailure(source.id);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
class _SourceResult { final String sourceId; final List<SearchItem> items; _SourceResult(this.sourceId, this.items); }
|
||||
|
||||
class SearchPhase {
|
||||
final String name; // searching | partial | pending_slow | slow_append | complete | error
|
||||
final List<SearchItem> items;
|
||||
final int doneCount, totalCount;
|
||||
final String? message;
|
||||
SearchPhase({required this.name, this.items = const [], this.doneCount = 0, this.totalCount = 0, this.message});
|
||||
}""")
|
||||
|
||||
para('')
|
||||
heading('2.5 UI 增量渲染时序', level=3)
|
||||
para('t=0s → 显示"正在搜索 N 个源..."')
|
||||
para('t=0~5s → 快速源逐个完成 → 滑动窗口下结果立刻追加到列表')
|
||||
para('t=5~8s → 普通源逐个完成 → 继续追加')
|
||||
para('t=8s → "慢源正在后台搜索..." → 用户已看到前两档结果')
|
||||
para('t=8~15s → 慢源逐个完成 → 静默追加到列表末尾')
|
||||
para('t=15s → "搜索完成"')
|
||||
|
||||
heading('2.6 取消机制', level=3)
|
||||
para('用户连续搜 A→B→C 时:_searchToken 递增版本号。_searchOne 开头检查 token != _searchToken 则 return null;阶段 3 yield 前检查则 return 丢弃旧搜索的后台任务。旧搜索的未完成请求仍会走完网络超时,但结果不会污染新搜索的 UI。')
|
||||
para('')
|
||||
|
||||
# ── Part 3 ──
|
||||
heading('三、两改进的协作关系', level=2)
|
||||
para('用户搜索一本书 → SearchScheduler(按健康分排序、滑动窗口、增量推 UI)→ 用户点击结果 → fetchBookInfo → fetchToc(TocPaginationResolver 拉全章节,支持分页)→ 用户阅读某章 → fetchChapterContent(需要 JS 引擎,本文档范围外)。')
|
||||
para('改进 1 保证"搜到书后章节不断尾",改进 2 保证"搜索本身不卡"。')
|
||||
para('')
|
||||
|
||||
# ── Part 4 ──
|
||||
heading('四、实施顺序', level=2)
|
||||
para('第 1 步:SourceHealth + SourceHealthStore(纯数据层,不影响现有流程,可与图片解析的 JS 引擎并行推进,先跑几天积累健康数据)')
|
||||
para('第 2 步:SearchScheduler 滑动窗口 + 短超时 + Stream(替换现有 search() 并发逻辑,UI 适配 Stream<SearchPhase>)')
|
||||
para('第 3 步:TocPaginationResolver(简单 JS/CSS/模板分页立即生效约 60% 源;复杂 JS 分页需要等 JS 引擎,代码结构无需改动)')
|
||||
para('第 4 步:联调 + 回归')
|
||||
para('')
|
||||
para('与图片解析的关系:第 1~2 步与 LegadoRuleExecutor V2 + QuickJS 可并行推进、互不冲突。')
|
||||
para('')
|
||||
|
||||
# ── Part 5 ──
|
||||
heading('五、风险控制', level=2)
|
||||
|
||||
make_table(
|
||||
['风险', '应对'],
|
||||
[
|
||||
['TOC 分页死循环', 'maxPages=20 + seenPageUrls 去重 + added==0 终止'],
|
||||
['复杂 JS 分页规则暂时跑不通', '简单规则(~60%)立即支持;复杂规则骨架预留,换 JS 引擎即可'],
|
||||
['健康分误杀快源(网站临时维护)', '连续失败 ≥5 才熔断 + 每 1h 自动释放探测机会 + 手动可重置'],
|
||||
['搜索时 SharedPreferences 频繁 I/O', '内存改、整轮结束统一写盘 + 2s 防抖'],
|
||||
['滑动窗口仍有慢源卡槽位', '超时兜底(5s/8s),超时后释放槽位'],
|
||||
['连续快速搜索旧结果污染 UI', '_searchToken 版本号,旧结果自动丢弃'],
|
||||
['新源全部 50 分', '第一轮搜索后就有真实分,冷启动无影响'],
|
||||
['Future.wait 批阻塞', '已替换为滑动窗口 _pool,先完成先返回'],
|
||||
]
|
||||
)
|
||||
|
||||
para('')
|
||||
para('')
|
||||
|
||||
# ── Part 6 ──
|
||||
heading('六、Review 整合清单', level=2)
|
||||
para('以下为三方 review 指出的问题和本方案的对应处理:')
|
||||
|
||||
make_table(
|
||||
['Reviewer', '指出的问题', 'v2 的处理'],
|
||||
[
|
||||
['Claude', 'offset 计算 initial * page 有误', '改为 initial + initial * page'],
|
||||
['Claude', '阶段 3 后台任务无取消机制', '加入 _searchToken 版本号取消'],
|
||||
['Claude', '衰减在 save() 里做不可靠', '衰减改为 score getter 动态计算'],
|
||||
['Claude', '字段名每次访问都遍历', '改为 fromJson 时一次性解析到字段'],
|
||||
['Claude', '第 3 步依赖 Legado 重构前置', '明确标注依赖,与 JS 引擎可并行'],
|
||||
['ChatGPT', '图片解析才是 P0,优先级需修正', '§0 前置声明 + §4 与图片解析并行'],
|
||||
['ChatGPT', '<js> 规则含 java.xxx 无法执行', '§1.7 明确兼容边界,骨架预留'],
|
||||
['Gemini', 'Future.wait 批阻塞快源', '改为滑动窗口 _pool'],
|
||||
['Gemini', '熔断无自动恢复', 'isUsable 加 1h 自动释放探测'],
|
||||
['Gemini', 'save() 高频 I/O', '防抖 2s + 整轮结束统一写'],
|
||||
['Gemini', '慢源用 EventBus 引入第二数据源', '慢源走同一个 Stream yield'],
|
||||
['Gemini', '\'${page + 1}\' 字符串字面量错误', '改为 (page + 1).toString()'],
|
||||
]
|
||||
)
|
||||
|
||||
# ---- Save ----
|
||||
doc.save(DOCX_PATH)
|
||||
print('Done! Document updated successfully.')
|
||||
print(f'Total paragraphs now: {len(doc.paragraphs)}')
|
||||
print(f'Total tables now: {len(doc.tables)}')
|
||||
Reference in new issue
Block a user