跳转至

整页 Markdown 管线

契约细节(表结构、后端接口、容量估算)在 SPEC-014-page-markdown-storage-and-upload。 本文只讲架构长什么样和三条一碰就出事的约束。

数据流

flowchart TD
    A[engine-manager<br/>task.googleId] --> B[processWebsiteScrape]
    B --> C[fetch 路径<br/>website-scrape-pipeline]
    B --> D[tab fallback 路径<br/>scrapeWithTab]
    C --> E[scheduleMarkdownConversion<br/>fire-and-forget]
    D --> E
    E --> F[offscreen document<br/>turndown]
    F --> G[persistMarkdown]
    G --> H[(PageMarkdown 表)]

两条抓取路径都要接:只接 fetch 的话,反爬 / JS 渲染页一条都不入库, 而那正是最需要渲染后 HTML 的一类。

全程 fire-and-forget:转换和入库永不阻塞抓取主流程,也永不喂回 extractContactFromHtml(那条路径吃的是原始 html)。

为什么要 offscreen

turndown 需要 DOMParser,MV3 Service Worker 里没有。硬约束,不是性能取舍。 产物层面已核:含 turndown 实现的只有 chunks/offscreen-*.js, background.js 里只有 createDocument 的 justification 文案。

🔴 三条硬约束

1. offscreen 文档是全局单例,关它会连坐

deepScrapeConcurrency 最高 10。关文档的条件必须是两条 AND: 只有 timeout 才关(port-disconnected 说明文档已经没了,再关是帮倒忙)+ 只有自己是最后一个在飞的才关。判断到置标志之间不许有 await。 详见 0113-offscreen-close-concurrent-kill。

2. PageMarkdown 的任何查询禁止带 order

jsstore 一见 orderQuery 就把 limit 推到末尾 slice、游标先扫全表。 20,000 行实测 621 ms / heap 1.27 GB(对比 where 2 ms、count() 1 ms), 而且 jsstore 在 MV3 SW 里跑在主线程。 淘汰因此改用二分探 cutoff(没有 order 就拿不到「第 N 老那行」的时间戳)。

3. 级联删的顺序不能反

collectGoogleIdsFor 必须在 removeByQuery 之前 —— 挪到后面就是查已删的行, 返回空数组,级联一行不删,留下永远删不掉的孤儿。 这个失效完全静默:主表删除照样成功、无异常、无日志,只有磁盘在涨。 tests/page-markdown-cascade-order.test.ts 用源码顺序断言钉死。

为什么不用影子计数器

按行数限量本可以维护一个 storage.local 计数器省掉 count()。不行: SW 30 s 空闲即杀 + 并发读改写竞态会让它单向漂移;一旦漂高, 库里没满也会每插一条淘汰一条,而「永不全表 sum」恰恰堵死了唯一的自愈路径。 count() 只要 1 ms,直接查真值。

撤掉它的正确方式

只能停止写入 + 保留表定义。 从 tables 数组里删掉这张表 = 该 store 被 deleteObjectStore 静默删掉。