SPEC-014 · 整页 Markdown 存储与上传契约¶
给谁看:接手云端后端的开发。 为什么写:v0.10.138 起客户端把抓到的网页整页转成 Markdown 存在本地, 并给每行留了
pending标记 —— 但上传通道一根线都没接。 Tony 2026-09-01 拍板:「云端后边让开发做后端,文档要留好」。 本文写清楚存了什么、为什么这么存、以及后端要提供什么才能把它接上。
一、客户端现状(v0.10.138 已落地)¶
三版分工¶
| 版本 | 做了什么 | 能否回滚 |
|---|---|---|
| v0.10.135 | DB 初始化失败可见化 + 15 s 超时兜底(ISSUE-0111) | ✅ |
| v0.10.136 | offscreen + turndown 转换层,结果只写 sysLog | ✅ |
| v0.10.137 | offscreen 并发误杀修复(ISSUE-0113) | ✅ |
| v0.10.138 | PageMarkdown 表 + version 5→6 + 淘汰 + 级联删 | 🔴 不可逆 |
为什么是 Markdown 而不是纯文本或原始 HTML¶
Tony 原话:「我希望是 Markdown 因为这个后续 AI 更易读」。 落地时又明确否掉了精简版:「不要精简转化 要完整页面!」—— 理由成立:按「联系方式够用」裁掉的部分,恰恰是下游 AI 判断商家类型 / 规模 / 主营的依据。
转换在 offscreen document 里跑,因为 turndown 需要 DOMParser,
而 MV3 Service Worker 里没有。这是硬约束,不是性能取舍。
二、表结构(PageMarkdown)¶
| 列 | 类型 | enableSearch | 说明 |
|---|---|---|---|
urlHash |
String | primaryKey | sha256(url)。同页重抓 upsert 覆盖,不堆历史版本 |
googleId |
String | true | 🔴 级联删除唯一可行的外键 |
domain |
String | true | 仅人工检索用,不参与删除判据 |
normalizedUrl |
String | false | |
md |
String | false | 整页 Markdown 明文 |
bytes / htmlBytes |
Number | false | |
visibleTextLen |
Number | false | frontmatter 后的非空白字符数,用来事后捞空壳页 |
scrapedAt |
Number | true | 淘汰按它走 where |
pending |
Number(0/1) | true | 上传队列标记,默认 1 |
🔴 enableSearch 在 jsstore 里缺省是 true(worker 源码 :211),
每个 false 都必须显式写 —— 不写就是给整页正文建索引。
为什么外键必须是 googleId¶
domain一对多,会误删同域名的其它商家;getIdsByQuery返回的是MapTaskData的自增 id,与googleId连类型都不同, 拿它匹配会命中 0 行且不报错 —— 删了个寂寞还看不出来。
客户端为此把 googleId 从 engine-manager 一路传到写库口
(processWebsiteScrape / runWebsiteScrapePipeline / scheduleMarkdownConversion 都加了可选参数)。
拿不到 googleId 就不入库,宁可少存一页,也不写一行永远删不掉的孤儿。
三、🔴 两条铁律(后端接线时也要知道)¶
1. 本表任何查询禁止带 order¶
jsstore 的 Select 构造器一见 orderQuery 就 setLimitAndSkipEvaluationAtEnd_()
(worker :2989-2995)⇒ limit 只在末尾 slice、游标先扫全表。
真 jsstore 4.9.0 + fake-indexeddb 实测(25 KB/行):
| 行数 | {order, limit:50} |
{where:{scrapedAt:'<'}, limit:50} |
count() |
|---|---|---|---|
| 2,000 | 97 ms | 4 ms | 0 ms |
| 20,000 | 621 ms / heap 1,274 MB | 2 ms | 1 ms |
而 jsstore 在 MV3 SW 里跑在主线程(IS_WORKER 判据 worker :1213 在 SW 下为 false),
那 621 ms 就是采集调度器被占住的 621 ms。
2. 将来撤掉 Markdown 只能「停止写入 + 保留表定义」¶
从 tables 数组里删掉这张表 = 该 store 被 deleteObjectStore 静默删掉(worker :642)。
不报错、不提示。
四、上限与淘汰¶
- 上限按行数:
MAX_MD_ROWS = 30_000(× 25.7 KB ≈ 771 MB 明文) - 超限后淘汰到 90% 水位,按
scrapedAt从老到新 - 用实时
count()而非影子计数器:计数器要存storage.local, 而 SW 30 s 空闲即杀 +deepScrapeConcurrency最高 10 的读改写竞态会让它单向漂移; 一旦漂高,库里没满也会每插一条淘汰一条,且「永不全表 sum」恰恰堵死自愈路径。count()只要 1 ms,直接查真值。 - 没有
order就拿不到「第 N 老那行」的时间戳,改用二分探 cutoff(24 轮 ≈ 24 ms) - 🔴 淘汰写 sysLog(warn 级),用户的数据被删掉了不能只有 console
wxt.config.ts 已加 unlimitedStorage。
🔴 它只解配额上限,不解 best-effort 逐出 —— 浏览器在磁盘吃紧时仍可能整库回收,
别拿它当持久性保证。
五、级联删除(四个入口全接)¶
| 入口 | 文件 | 做法 |
|---|---|---|
deleteByQuery(有 where) |
search-data.ts |
先 collectGoogleIdsFor → 删主表 → 级联 |
deleteByQuery(空 where) |
search-data.ts |
clearData 主表 → clearPageMarkdown |
deleteNoEmail 的 dropIds |
search-data.ts |
同上,先收后删 |
| 删任务时删数据 | task-manager.ts |
allRows 是全字段查询,googleId 直接在手 |
clearSearchData |
search-data.ts |
主表清空 → 附属表清空 |
🔴 顺序不能反:collectGoogleIdsFor 一旦挪到 removeByQuery 之后,
它查的就是已被删掉的行 → 返回空数组 → 级联一行不删 → 留下永远删不掉的孤儿。
而这个失效完全静默:主表删除照样成功、无异常、无日志,只有磁盘在涨。
tests/page-markdown-cascade-order.test.ts 用源码顺序断言把它钉死了。
级联失败不抛:主表删除是用户的核心诉求且已成功,不能因附属表没删干净就报失败;
失败写 sysLog,残留会在下次 clearSearchData 时清掉。
六、⚠️ 后端要提供什么(本版未接,通道待建)¶
客户端当前只留接口面:
// src/utils/page-markdown-store.ts
takePendingMarkdownBatch(limit = 20): Promise<PageMarkdownRow[]> // where:{pending:1}
🔴 绝不能走 cloud-data-sync.tsx¶
它的 payload 过 exNullData(parse-data.ts:174)—— 遍历全部 key、零白名单。
接上去整页正文会直接出网,且没有任何字段级控制。
Markdown 上传必须走独立的、显式字段白名单的通道。
后端需要提供¶
- 一个独立端点(不复用
SPEC-011通道B 的商家同步端点),接收{ urlHash, normalizedUrl, domain, md, bytes, scrapedAt }—— 不含googleId(那是本地自增域的业务主键,出网没有意义且是额外的可关联信息)。 - 幂等语义:以
urlHash为幂等键。客户端会重抓同一页并 upsert 覆盖本地行, 上传可能重复发同一个urlHash,服务端必须能安全覆盖或忽略。 - 明确的成功回执,客户端据此把
pending置 0。 没有回执就不能置 0 —— 否则一次网络抖动就是永久丢页。 - 体积上限与拒收语义:单页明文可达数百 KB。服务端要给出上限, 并在超限时返回可区分的错误码(客户端据此把该行标记为「不再重试」而不是无限重发)。
未定,需要 Tony 拍板的¶
- 整页正文出网的合规边界(抓的是公开网页,但整页存储 + 上传与只存联系方式性质不同)
- 保留期与服务端侧的淘汰策略
- 是否需要按域名/客户维度隔离
七、证据边界¶
- 本地存储、淘汰、级联删的逻辑全部有单测(
page-markdown-store.test.ts14 条 +page-markdown-cascade-order.test.ts8 条),并做过变异自测(五路 + 三路全部咬住)。 - 🔴 但没有在真实 Chrome MV3 里跑过完整链路 —— 单测用内存数组 mock 掉了
jsstore helper,测的是本项目写的逻辑,不是 jsstore 的真实行为。
jsstore 的行为结论(order 扫全表、
enableSearch缺省 true、删表即deleteObjectStore) 来自逐行读 worker 源码 + 基线里记录的 fake-indexeddb 实测,本版未复跑。 - 30,000 行 × 25.7 KB 的容量估算是算术推算,没有真的灌满过。