Readest 阅读器功能修复知识库解读:PDF 渲染、文本选择、词典、工具栏与 RSVP 的工程速查
Readest 阅读器功能修复知识库解读:PDF 渲染、文本选择、词典、工具栏与 RSVP 的工程速查
本文是对 Readest 开源电子书阅读器仓库内 apps/readest-app/.claude/memory/reader-feature-fixes.md 这份"阅读器功能修复"聚合索引的深度解读。该索引汇总了 PDF 查看器、文本选择、即时词典、工具栏定制、RSVP 速读、小组件与杂项 UI 等领域一批已解决/已稳定的工程记忆,每条记忆对应具体的 GitHub issue 编号、合并 PR 与关键技术结论。读完本文,你可以快速定位阅读器各功能模块的已知问题、根因与修复方案,并借助仓库源码理解这些结论背后的实现细节。
这份文档是什么:一张"已解决修复"的导航图
reader-feature-fixes.md 本身是一个 聚合索引(aggregator index):它不重复存储修复细节,而是每行一条、以 issue 编号 + 记忆文件名 的形式指向 apps/readest-app/.claude/memory/ 目录下的独立记忆文件,打开链接文件才能看到完整细节。其 description 元数据明确说明了覆盖范围:
Aggregator index for resolved/stable reader-feature memories (PDF viewer, selection, dict, toolbar, RSVP, widgets, misc UI)
索引从 MEMORY.md 迁移而来,目的是保持索引文件短小。因此在阅读本仓库时,正确的用法是:先看这份索引找到条目,再打开对应记忆文件获取根因与修复细节,最后回到源码/测试验证。本文即按此路径,将索引中的条目按主题整理成可检索的速查手册。
PDF 查看器:滚动性能、捏合缩放与固定版式
PDF 是阅读器中最复杂的渲染场景之一,索引中 PDF 相关条目最多,且大量修复发生在 packages/foliate-js/(以子模块方式维护的渲染内核)。
滚动模式渲染延迟(#4795)
Android 上 PDF 滚动模式出现空白页。根因通过真机 CDP(Chrome DevTools Protocol)实测得出:单页渲染(canvas 栅格 + 文本层 + 注解层)约 415ms(未缓存)/ 65ms(已缓存),而滚动模式的 IntersectionObserver 只有 rootMargin: '50% 0px'(约半页提前量),且加载无并发上限、无视口优先级,导致快速滚动时渲染永远追不上。修复在 fixed-layout.js:
- 观察器加宽到
rootMargin: '200% 0px'(约 2 个视口提前量),观察器只负责标记page.visible; - 新增纯函数
planScrollModePages({pages, currentIndex, maxLoaded, maxConcurrent, loadingCount}),优先加载离当前页最近的可视/空闲页,并以#scrollMaxLoaded = 12(画布内存上限)、#scrollMaxConcurrent = 3约束并发,驱逐最远的非可视已加载页且永不驱逐可视页; - 单页加载失败置为
error态而非idle,避免失败页被无限重试; - pdf.js 的
MAX_CACHED_PAGES从 8 提升到 16。
调度器有独立单元测试 fixed-layout-scroll-scheduler.test.ts 保护。索引还总结了滚动 PDF 的缓存最佳实践:两层有界缓存(活动画布上限=硬内存天花板,解码页缓存稍大)、距离/视口感知的 LRU、及时释放位图(canvas.width=0),以及低端设备上最有效的杠杆——限制有效 DPR(画布内存与 DPR 平方成正比)。
滚动 PDF 实时捏合缩放(#4817)
滚动模式下的捏合缩放修复同样全部位于 foliate-js(readest 侧仅子模块 bump + 一个单元测试)。核心架构结论非常关键:跨页捏合与原生文本选择互斥——每个页面是独立 iframe,Android 会在手指落到第二个 iframe 时对第一个 iframe 发送 touchcancel,跨页手势只能由宿主接管全部触摸,但这要求 iframe pointer-events: none,会杀死原生选择。用户最终选择了原生选择、放弃跨页捏合。同页捏合在滚动模式会整体缩放 .scroll-container,pinchEnd 时以中心页 getBoundingClientRect 为锚点重渲染回滚,且页间距必须随缩放联动(margin: calc(var(--scroll-page-gap,4px) * var(--scroll-zoom,1))),否则预览与提交会出现位移。
跨页选择、复制与菜单行为
- PDF 跨页选择(#5809,已合并 #5831):Chrome 与 Xiaomi 真机验证通过,iOS 未覆盖——修复记录明确标注了验证边界。
- PDF 复制拼接换行(#5814,已合并 #5828):复制时跨行文本会拼接,未缩进的最后一行仍会被合并。
- 滑动平移误触发菜单(#5142):PDF 滑动平移会误开/误关菜单栏,修复要点记录在 pdf-swipe-pan-toggles-menu-5142.md。
- 固定版式书籍横向滚动(#4995,foliate#65 + readest#5485 均已合并):新增
scroll-direction属性(vertical|horizontal),与flow="scrolled"正交;direction: rtl必须挂在宿主滚动元素而非.scroll-container上,否则滚动锚点恢复会"瞬移";横向模式下的滚轮平移由computeScrollWheelDelta处理,且 CDP 合成手势无法测试该路径(无滚动轴时根本不派发 wheel 事件),只能靠真实硬件或 vitest 浏览器测试。 - 侧栏拖拽改 PDF 尺寸(#5043,已合并 #5198):拖拽侧栏后 PDF 尺寸不更新,修复为 FXL iframe 中
PE:auto会击败 body 的PE-none,改用 shield overlay 方案。
PDF/CBZ 对比度调节(View 菜单)
为固定版式/图像文档(PDF/CBZ/FXL-EPUB)在 View 菜单新增 Contrast 步进器,细节见 pdf-cbz-contrast-view-menu.md:
contrast: number存入BookStyle(默认 100,范围 50–300,步长 10);- 过滤样式在 style.ts 的
applyFixedlayoutStyles()中应用于img, canvas规则,CSSfilter是单一属性,第二条filter:会覆盖第一条,因此必须把invert(100%)与contrast(${c}%)拼进同一条声明(两者可交换,顺序无关);浅色模式下对比度同样生效; - 通过
saveViewSettings(envConfig, bookKey, 'contrast', value, /*skipGlobal*/ true, ...)只写当前文档,不进全局。
另有 pdf-scroll-lag-preload-4795.md 记录了 CDP 调试发布包的要点:WebView 远程调试被 devtools Cargo feature 门控,需 pnpm dev-android(release + --features devtools)构建安装;CDP webSocketDebuggerUrl 返回无端口的 ws://localhost/devtools/...,需改写为 ws://127.0.0.1:9222<path>。
文本选择与点击交互:跨页、键盘与 Instant Highlight
选择相关
- 跨页选择自动翻页(#4741):详见 cross-page-selection-autoturn-4741.md。
- 键盘调整选区(#4728):详见 keyboard-selection-adjust-4728.md。
- iOS 选择工具栏闪烁(延迟到 touchend 再显示):详见 ios-selection-toolbar-flash-defer.md。
点击/双击
- 双击选词(iframe 内):iframe-double-click-word-select.md。
- 双击拖动误翻页(#4524):dblclick-drag-pageturn-4524.md。
- 点击图片/表格打开(#4600):tap-to-open-image-table-4600.md。
- 长按缩放(#5069)已被移除;Samsung 保存到相册(#5109)未确认——索引如实标注了这些"未落地/存疑"状态。
Instant Highlight(即时高亮)
- 吞掉点按/滑动翻页(#4795 配套):Android 用户开启即时高亮快捷动作后,点按正文无法翻页。根因是
useTextSelector.handlePointerDown对每个指针按下都preventDefault()并立即开始高亮,压制了驱动翻页的原生 click。修复在 useTextSelector.ts:触摸/笔输入引入 300ms 静止保持门限(INSTANT_HOLD_MS = 300)与 10px 移动容忍(INSTANT_HOLD_MOVE_PX = 10)——点按先释放、滑动先移动,都走原生翻页;只有静止保持才触发高亮。鼠标路径不变(点击与按压拖拽本身无歧义)。 - 孤儿高亮(#4773):instant-highlight-delete-orphan-4773.md。
- 取消注释时的空高亮泄漏(#4791):empty-highlight-leak-on-annotate-cancel-4791.md。
Instant Highlight 的 iOS 侧有一个值得复用的经验:WebKit 的文本选择识别器无法从 JS 层面击败——user-select: none 在 iOS 上会让 caretRangeFromPoint 返回 null(破坏选择/高亮 API),selectstart 的 preventDefault 是死路(iOS 长按选择根本不触发 selectstart)。最终方案是原生门控 TextSelectionSuppressor.swift(swizzle WKContentView 的选择手势 gate),驱动链路为 set_text_selection_suppressed(Rust)→ bridge.ts 的 setTextSelectionSuppressed。
注解与 Overlayer
- 全局注解翻页延迟(#4575):global-annotation-pageturn-perf-4575.md。
- Overlayer splitRange 文本节点(用于 TTS/注解高亮框):overlayer-splitrange-textnodes.md。
- Android 图片 callout 冻结:
.no-context-menu必须加在 ANCESTOR 上,见 android-image-callout-freeze.md。
词典、Word Lens 与语言排版
词典弹出框
- 弹出框字号(#4443):dict-popup-font-size-4443.md。
- 词形还原/lemmatization(#4574):dict-lemmatization-4574.md。
- 弹出框朗读按钮(#4876):dict-popup-tts-speak-4876.md。
- iOS 即时词典双弹窗:用"每次手势只锁一次"的 latch 解决,见 ios-instant-dict-double-popup.md。
- 单字词典门控(#5213,已合并 #5529):8 字符 CJK 上限,见 quick-action-dictionary-single-word-5213.md。
- 弹出框 chrome 字体族(#5496):
.popup-container对 e-ink 是承重墙,见 popup-chrome-family-5496.md。
Word Lens(行内注释)
Kindle 风格的 Word Lens 是阅读器的一大特色,完整设计见 wordlens-feature.md:
- CEFR 词频滑块:A1–C2 六档映射到词频排名截断值,定义在 difficulty.ts:英文用
FREQUENCY = [1000, 2000, 4000, 8000, 14000, 24000],中文按 HSK 级别×3000 类比;isDifficult(rank, cutoff)判定"该词是否难到需要注释"。 - CFI 安全的 DOM 注入(核心技术):注释以
<ruby class="wl-gloss" cfi-skip>word<rt cfi-inert>gloss</rt></ruby>注入活动 iframe 文档。foliate 的epubcfi.js会把cfi-skip包装器的子节点上提、移除cfi-inert子树,使 CFI 与纯文本逐字节一致——高亮、书签、进度不受影响,KOSync 同样安全(xcfi.ts遵循相同属性)。 - 与 TTS/搜索/注解隔离:TTS 拒绝过滤器已含
tags:<a href="https://link.gitcode.com/i/cc7b82dc93c9cfa455043e4ddf7cdd71" target="_blank">'rt'];globalAnnotations的 findTextRanges 拒绝rt/rp;[wordHighlight.ts 增加isInertText跳过逻辑并导出rangeTextExcludingInert(否则 Edge TTS 词边界偏移会漂移);搜索 SearchBar.tsx 对rt之外补充了attributes:['cfi-inert']。 - R2 运行时分发:数据包不随安装包分发,源在
apps/readest-app/data/wordlens/(含manifest.json,记录 pair/source/target/file/bytes/sha256/entries),由scripts/sync-wordlens-r2.mjs(pnpm wordlens:sync,envWORDLENS_R2_BUCKET)上传到cdn.readest.comR2;运行时 glossPacks.ts 负责 fetchManifest→resolvePack→ensurePack(sha256 校验、单飞、?v=<sha8>缓存破坏)→loadGlossIndex。 - 构建数据:
node scripts/build-wordlens-data.mjs en-zh <ecdict.csv> [topN](ECDICT,难度取 COCAfrq排名)与zh-en <cedict.txt> <hsk.json> [topN](CC-CEDICT + HSK)。注意陷阱:kaikki 的<code>-extract.jsonl.gz是单语词典(同语言释义),英语注释在kaikki.org/dictionary/<Language>/...jsonl(0.9–3GB)中。
RTL、波斯语与西里尔文本
- RSVP 的 RTL 词显示(#4630):RSVP 的 ORP 焦点字母布局按字符索引把词切成
wordBefore/orpChar/wordAfter三段并排布在 LTR span 中,这会破坏阿拉伯语字母连写(علم 显示成 ل م ع)并颠倒视觉顺序。修复为:新增 isRTLText(RTL_PATTERN = /[\u0590-\u08FF\uFB1D-\uFDFF\uFE70-\uFEFF]/,覆盖希伯来/阿拉伯/叙利亚/塔纳/NKo 等),检测到 RTL 就复用 CJK 的整词渲染分支并加dir='rtl'。通用教训:任何复杂连写/bidi 文字都不能按字符索引拆 span。 - 波斯语 RLM 半空格(#5216/#5651):rlm-bidi-mark-shaping-5216.md(真因是字体回退 shaping,非 sanitizer)与 persian-rlm-halfspace-zwnj-5651.md(U+0600–06FF 含数字,数字间交换会翻转视觉顺序)。
- 俄语悬挂前置词 NBSP(#4769):russian-hanging-prepositions-nbsp-4769.md。
- TTS 日语 ruby 读音(#5539,已合并 #5546 + foliate-js#67):TTS 应朗读
<rt>注音而非让引擎猜汉字读音。交换必须在节点过滤器层完成(绝不能改写文本,否则高亮 CFI 漂移),判据是<rt>是否为纯假名(isKanaReading) 而非书语言;配套两个 foliate 补丁:fragmentToSSML要过滤文本节点(组 ruby 的 base 是<ruby>的裸文本子节点)、Overlayer.#splitRange不再收集rt/rp/rtc/[cfi-inert]的矩形(furigana 永不参与高亮)。
工具栏定制、注解中心与设置同步
Customize Toolbar 全局化(#4760)
"Customize Toolbar"(注解栏,源自 #4014,v0.11.12 发布)的修改只对当前书生效、不全局生效。根因在 serializer.ts:serializeConfig 用 globalViewSettings<a href="https://link.gitcode.com/i/5a2e5bff7e7c3f1e5f05bd24c1122823" target="_blank">key] !== value 的引用比较决定哪些 per-book 设置需要持久化为覆盖项,而函数先 JSON.parse(JSON.stringify(config)) 深拷贝,导致任何数组/对象值(如 annotationToolbarItems,潜伏的还有 paragraphMode、proofreadRules、ttsHighlightOptions、noteExportConfig)都是新引用 ≠ 全局 → 每次保存都写成 per-book 覆盖项,重新打开后旧覆盖项遮蔽全局修改。修复最小且通用:新增 isSameViewSettingValue(a,b) = a===b || JSON.stringify(a)===JSON.stringify(b),仅用于 viewSettings 的 reduce(searchConfig 保留 !==,因为它含函数/大 results)。测试见 [serializer.test.ts。已知限制:旧版(有 bug 的 v0.11.12)已写入的、内容与当前全局不同的覆盖项不会被追溯清除。
注解中心(Annotations Hub,#5398/#3870,已合并 #5448)
侧栏 Annotations 标签页成为 per-book 注解中心。关键决策:filterBooknotes(notes, {kind, query, excludedColors?, excludedStyles?}) 与 collectAnnotationFacets 由 hub、Notebook 搜索栏、过滤器导出组共享;工具栏改为"图标行 + 过滤下拉"(search/funnel/3-dot);过滤面板必须合并 Dropdown 注入的 menuClassName(no-triangle mt-1),否则旧三角缺口会渲染;最近滚动抑制效果与 lastScrolledCfiRef 交互,清空过滤时若不清该引用会把列表"搁浅"。详见 annotations-hub-5398-3870.md。
其他工具栏/UI 条目
- e-ink 黑条(#4839):customize-toolbar-eink-black-bar-4839.md。
- 复制链接注解工具(#5452,已合并 #5464):opt-in 集合 =
ALL_减去DEFAULT_,见 annotation-toolbar-copylink-5452.md。 - 注解数汇总(#5576)与高亮样式预览色(#5578):annotations-toolbar-count-summary-5576.md、highlight-style-buttons-preview-colors.md(解析
customColors[c] || c)。 - 进度条点按开关(#5293,已合并 #5466):tap-toggle-progress-bar-5293.md。
- header notch 负边距(#5303,已合并 #5447):z-10 仅在"抬起"时开启,否则会盖住桌面工具栏,见 header-notch-negative-margin-5303.md。
- 标题栏拖拽需要 headerRef(#5584):拖拽是 JS 实现,每个 header 必须传
headerRef并排除其输入框,见 titlebar-drag-needs-headerref-5584.md。 - 窗口标题显示书名(#5547):window-title-book-name-a11y-5547.md。
RSVP 速读、自动滚动与光标
RSVP
- RTL 整词渲染(#4630):见上文"RTL 与语言排版"。
- 控制栏重叠回退(REVERT):rsvp-control-bar-overlap-revert.md。
- 字体设置(#4519):rsvp-font-settings-4519.md。
- 横屏安全区(#5548):是"物理 pl/pr 例外"的唯一一处,见 rsvp-landscape-safe-area-insets-5548.md。
- 精细 WPM 输入(#5820,已合并 #5825):rsvp-fine-wpm-entry-5820.md。
自动滚动
- 中键自动滚动(#4951,已合并 #4955):桌面 Tauri 滚动模式中键自动滚动,无设置开关、默认开启。核心是 autoscroller.ts 的纯
Autoscroller类(RAF 循环、12px 死区、10 px/s 每 px 线性速度、上限 4000、整像素发射 + 小数进位、held→sticky/drag 状态机),滚动走renderer.containerPosition += delta原生滚动路径(section 预加载照常工作)。iframe 事件处理器在父 realm 维护 armed 注册表,让handleMousedown对中键 preventDefault(压制 WebView2 原生自动滚动,避免双重驱动)。 - 提词器 Auto Scroll(#4998,已合并 #4999):仅滚动模式的提词器式自动滚动,View 菜单切换(Shift+A)。
PacedScroller与中键Autoscroller同文件:恒定速度、整像素 + 小数进位、PACED_SCROLL_MAX_FRAME_MS帧间隔钳制(后台标签恢复);速度autoScrollSpeed存BookLayout(默认 100 = 20 px/s 基础,25–500 步长 25);会话态镜像到 readerStoreviewState.autoScrollEnabled,会话不持久化、速度持久化。停顿检测:containerPosition连续 ≥800ms 不变 →view.next()跳节或显示 "End of book" toast。 - 速度滑动调节(#5206)与恢复续滚(#5631,已合并 #5710):auto-scroll-speed-swipe-5206.md(镜像左缘亮度手势,仅会话内启用)、autoscroll-resume-on-reopen-5631.md(per-book
autoScrollRunning)。
光标与滚动条
- 自动隐藏光标(#5178,已合并 #5404):foliate-js 本就带完整的
CursorAutohider(在 view.js,门控autohide-cursor属性,挂在 view 元素而非 renderer 上,每次 mousemove 惰性重查),readest 只是接线:FoliateViewer 初始化时view.toggleAttribute('autohide-cursor', !isMobile && setting);autohideCursor从ReadSettings移到顶层SystemSettings(按设备而非同步字段,不在SETTINGS_WHITELIST)。注意:默认值为true,桌面用户更新后即生效(PR 中已提请维护者决策)。 - 选择过程中光标被隐藏(foliate-js#68 + #5557):cursor-autohide-blanked-during-selection.md。
- 底部页脚药丸变黑(#5342,已合并 #5347):药丸背景与
mix-blend-difference不能共存,见 footer-pill-vs-blend-5342.md。 - Home/End 跳转(#5660,已合并 #5673):
goToFraction(0|1)单次调用 +inited守卫;页脚 "66 / 68" 是对的,见 home-end-book-jump-5660.md。 - 页脚页码跳变(#3392,已合并 #5524):page-number-jump-3392.md。
阅读器内搜索
- 搜索模式(#4560,Calibre 对标):在 foliate-js search.js 内新增
regex与nearby-words模式(regexSearch/nearbyWordsSearch/mode分发),per-wordcfis+ 注解去重在 view.js;BookSearchConfig.mode/nearbyWords+BookSearchMatch.cfis+SearchExcerpt.segments进 types/book.ts,schema v2→v3 在 serializer.ts(ensureSearchMode从旧布尔matchWholeWords推导,nearbyWords默认 10 词)。侧栏模式选择器 + 灰色修饰符 + "within N words" 步进器 +searchError态 + 分段摘录。原计划的 Turso 缓存引擎与searchBookagent 工具被 /autoplan 评审砍掉、分期进行。 - 500 条上限(#5724,已合并 #5728):书内搜索在 500 条匹配处静默停止,因为 #5389 把阅读器搜索接到了
searchLibraryBooks(其 per-book 上限MAX_BOOK_SEARCH_RESULTS = 500是为防止一本书淹没全库扫描)。修复:LibrarySearchOptions.maxResultsPerBook默认 500(库扫描用),SearchBar.tsx 传Infinity。所有 matcher 本就以Infinity为无限制默认,无需改动。代价提示:侧栏结果列表无虚拟化,常用词在长书中会物化全部 DOM 匹配。
版式、小组件与平台杂项
段落模式(Paragraph Mode)
- 开关/续读(#4717):paragraph-mode-toggle-resume-4717.md。
- 误触退出(#4474):paragraph-mode-accidental-exit-4474.md。
- 样式对齐 TTS mini player(#5275,已合并 #5338):底栏复用播放器卡片(
not-eink:bg-base-300 eink-bordered rounded-2xl shadow-lg);遮罩必须完全不透明(bg-base-100),否则 8% 透明会让正文透出重影;hoveredBookKey === bookKey会整条隐藏 ParagraphBar(QA 时悬停一次就再也看不见)。 - 显示设置(#5246,已合并 #5403):字体挂在 frame 上或 66ch 宽度不会随比例缩放,见 paragraph-mode-display-settings-5246.md。
:has()白名单陷阱(#5555)与翻译 CFI 稳定性(#5555):paragraph-layout-has-allowlist-trap.md(判据是line-height: normal)、translation-cfi-stability.md(风险是源节点被清空)。
Webtoon 模式与 D-pad
- Webtoon Mode(#3647):图像书(CBZ/漫画/PDF/固定版式 EPUB)的无缝滚动:滚动流 + 0 页间距 + 适配宽度。关键架构事实:foliate-js 固定版式滚动渲染器天然按宽度适配(
#renderScrollMode按hostWidth/vpWidth * scaleFactor缩放、忽略zoom属性),唯一破坏适配宽度的是scale-factor ≠ 100,所以 Webtoon 模式强制zoomLevel=100;4px 页间距原本硬编码在.scroll-page { margin: 4px 0 },改为--scroll-page-gapCSS 变量(默认 4px),toggle 时捕获/恢复滚动锚点防跳变。 - D-pad 导航(Android TV/蓝牙遥控器 + 桌面方向键):dpad-navigation.md。自研
useSpatialNavigation(阅读器工具栏版 + 书库网格版,同名不同目录),弃用第三方库(init 时序问题 + 与useShortcuts冲突)。关键坑:Android WebView 内置空间导航会截获方向键,需给非交互浮层元素加tabIndex={-1};可见性检测不能用offsetParent(fixed 容器内恒为 null),改用 focus-probe(btn.focus()后检查document.activeElement);方向键必须在容器层stopPropagation,否则冒泡到 window 被useShortcuts当成翻页。
小组件与平台
- 移动端阅读小组件(#1602):mobile-reading-widgets.md。
- iOS App Group 破坏(CarPlay provisioning):ios-appstore-appgroup-carplay-provisioning.md(stale skip-worktree pbxproj)。
- 小组件封面亮边线:ios-widget-cover-bright-edge-line.md。
- e-ink 刷新翻页器(#4687):eink-screen-refresh-pageturner-4687.md。
- 生物识别应用锁(#4645):biometric-app-lock-4645.md。
- 参考页/页码标签(#4542):reference-pages-672-4542.md。
- 环境光 Ambient Mode(#5394):ambient-mode-light-sensor-5394.md(
emitOrQueue仅一次性;themeStore 与getThemeCode默认值必须一致)。 - 注解共享 + 工具栏(#4014):annotation-share-toolbar-4014.md。
- 书详情页页码(#5516,已合并 #5523):实时计数在
bookData.config,见 book-details-page-count-5516.md。 - Android 自动填充登录(#5499,已合并 #5505):提交时用 FormData,见 android-signin-autofill-formdata-5499.md。
- 下拉书签手势(#1359,已合并 #5493):pull-down-bookmark-gesture-1359.md。
- 书签下拉在固定版式(#5142/#5757):门控为
hasVerticalPanning,Xiaomi 通过 CDP 合成触摸验证,见 bookmark-pull-fixed-layout-5142.md。
OPDS/WebDAV 与封面
- OPDS 组轮播(#4750):opds-groups-carousel-4750.md。
- WebDAV 浏览排序+搜索(#4724):webdav-browse-sort-search-4724.md。
- OPDS feed 封面+元数据(#5270,#5471+#5477 均已合并):逐字段 feed 优先合并,见 opds-feed-cover-5270.md。
- 服务端更新后 OPDS 封面过期(#5492,已合并 #5495):缓存键加入
<updated>,见 opds-cover-updated-cache-5492.md。 - Discord 封面回退(#5352,已合并 #5382):content-addressed 临时键 + 负缓存区分 missing vs transient,见 discord-cover-fallback-5352.md。
- 封面原地变更陈旧(memo):cover-stale-inplace-mutation-memo.md。
工程方法与实践:这份索引教给我们的调试范式
通读索引及其背后的记忆文件,可以提炼出 Readest 团队稳定的工程方法论,这些对任何复杂跨端阅读器项目都有借鉴价值:
- 真机 CDP 验证是默认纪律:大量修复标注 "CDP-verified on Xiaomi 13 (fuxi)"、"Xiaomi verified",且明确区分"合成触摸可测/不可测"(CDP 合成触摸不触发 WebView 长按选择手势;CDP 无法测试横向滚轮平移)。索引中还有专门的 feedback-always-verify-on-xiaomi.md。
- 内存文件即"设计决策 + 坑"的记录体:每条记忆都包含 root cause、final design、gotcha、验证方式,且互相链接(
[[related-memory]]),形成可导航的知识图。 - 子模块 PR 流程:foliate-js 是子模块,搜索/滚动/选择等内核改动必须先在子模块提交 PR(
git push git@github.com:readest/foliate-js.git HEAD:refs/heads/<branch>+gh pr create --repo readest/foliate-js),readest 侧只 bump 指针;squash 合并后要重瞄指针。 - "宁可修根因,不搞特例":如 #4760 拒绝
GLOBAL_ONLY_VIEW_SETTINGS特例清单,最终落在通用的值比较修复;#5724 拒绝在 matcher 层加新 cap,提示"要虚拟化列表而不是重新引入上限"。 - 测试锚定行为:调度器(fixed-layout-scroll-scheduler.test.ts)、序列化器(serializer.test.ts)、RTL 检测(jsdom 断言整词 span +
dir)、自动滚动(注入 raf/now 的 autoscroller.test.ts)、光标自动隐藏契约测试(autohide-cursor.test.ts)等,都用单测锁定修复语义。
结语
reader-feature-fixes.md 是 Readest 阅读器工程知识的高度浓缩入口:它以一行一条的形式,把 PDF 渲染性能、跨页选择、即时词典、工具栏全局化、RSVP 的 RTL 处理、自动滚动、注解中心等数十个已解决问题的结论与记忆文件对应起来。对于想要深入理解或二次开发 Readest 阅读器的工程师,建议按"索引 → 记忆文件 → 源码/测试"的路径逐条追读;文中引用的 fixed-layout.js 滚动调度器、serializer.ts 值比较、rsvp/utils.ts 的 RTL 检测与 SearchBar.tsx 的 maxResultsPerBook: Infinity 等实现,都可以作为理解这些修复如何落地的第一手证据。