legado.koplugin

Legado 书库接入 KOReader：pengcw/legado.koplugin 技术剖析

项目背景与痛点

中文网文读者的设备生态有一段长期断裂：内容在 Android 的「阅读」（Legado）里，阅读体验却在 Kindle、Kobo、PocketBook 这些墨水屏设备上——而 KOReader 恰恰是这些设备上体验最好的第三方阅读器。问题在于，KOReader 是纯本地阅读器，它不理解「书源」这套东西，更不会执行 ruleSearch、ruleToc、ruleContent 那一整套抓取规则。

pengcw/legado.koplugin 填的就是这条裂缝。它不是一个把网页抓下来存成 TXT 的粗糙脚本，而是试图把 Legado 的书源体系、书架语义和阅读进度，桥接到 KOReader 的 Lua 运行时里。对墨水屏用户而言，这意味着不必在手机和电纸书之间来回导文件，也不必为了追更去折腾 Calibre 转换链。

核心技术揭秘

理解这个项目的关键，是先看清 Legado 书源的复杂度。一条书源不是「一个 URL + 一个 CSS 选择器」，它是一套方言：@css:、@XPath:、@json:、@js: 前缀区分解析器，{{}} 做变量插值，<js> 块里允许写任意 JavaScript，还有 loginUrl、jsLib、header、webJs 等扩展字段。KOReader 端跑的是 Lua/LuaJIT，没有 V8，没有 jsoup，也没有 Android 的 OkHttp。这是本项目的真正技术难点，而不是「发个 HTTP 请求」。

从架构上看，插件走的是一条双轨路线：

第一条轨道是代理模式：插件把检索、目录、正文请求转发给局域网里跑着的 Legado 实例（其内置 HTTP 服务），由服务端完成规则执行，插件只负责结果消费。这让几乎所有书源都能用，代价是必须有一台常开的 Android 设备或服务端。第二条轨道是本地解析模式：插件在 Lua 侧实现规则方言的一个子集，把 @css、正则、简单 {{}} 翻译成 Lua 的字符串处理与模式匹配。这条路径离线可用，但对含 @js: 的书源必然降级。

往下是真正影响体验的部分：数据落地。KOReader 的 ReaderUI 面向的是本地文档，网络章节必须先经过正文清洗（剥标签、合并段落、处理 <br> 与全角空格）、再写入缓存或拼装成可被 DocumentRegistry 打开的文件。缓存分层在这里是刚需——目录层变动慢、正文层可增量追加、封面图需要单独落盘，否则每次翻页都重新请求会把墨水屏的刷新节奏彻底打乱。进度回写则是另一处细节：KOReader 有自己的 kosync 体系，插件需要把章节索引折算成 Legado 的 durChapterIndex / durChapterPos，两套坐标系的换算不准，就会出现「手机上在第 3 章、电纸书上跳回第 1 章」的经典事故。

功能亮点与差异

与常见的「RSS 抓取转 EPUB」方案相比，它的差异点有三个。

其一，保留书源语义而非网页语义。RSS 方案绑定具体站点，站点改版就废；书源方案绑定规则，规则社区维护，插件跟着规则走，生命周期长得多。

其二，书架与进度是一等公民。多数抓取工具只产出文件，读完即失联；本项目把「书架」抽象搬进 KOReader 菜单，检索、加书、追更、续读形成闭环，这是它区别于一次性转换脚本的核心。

其三，复用 Legado 既有生态。对已有 Legado 用户而言，书源、书架、阅读记录都是现成资产，插件是零迁移成本的前端延伸，而不是一个要重新配置的独立系统。

应用场景与落地建议

最适合的场景很明确：手里有 Kindle/Kobo，家里有一台常年开机的 Android 设备跑 Legado，希望在墨水屏上稳定追更。部署时注意几点：

• 网络与超时：墨水屏设备 WiFi 休眠策略激进，务必配置合理的重试与超时，并在章节拉取时保持网络唤醒，否则失败率会高得离谱。
• 规则兼容边界：上车前先看目标书源是否大量使用 @js: 与 loginUrl，这类源在本地模式下大概率不可用，应走代理模式。
• 缓存与存储：正文缓存要设上限并支持章节级清理，Kindle 的可用空间经不起整本缓存多个书源。
• 合规与频率：书源抓取本质上是对第三方站点的访问，请求频率、User-Agent、失败退避都要克制，这不是技术问题而是可持续性问题。

综合评价

优点：定位精准，切口极窄却极痛；架构上诚实地区分了「能代理就代理、能本地就本地」两条路径，没有为了纯粹性牺牲可用性；把书架、进度、缓存这些真正决定长期使用体验的东西都考虑进去了。

缺点：天花板清晰——Lua 侧永远无法完整复刻 JS 规则方言，兼容性只能靠子集加降级来维持；对 Legado 服务端的依赖使它并非「独立客户端」；书源生态的频繁变动会让解析层持续处于维护状态，这是所有规则型项目的宿命。

一句话总结：它不是通用方案，但对「Legado + 墨水屏」这个具体人群，它把原本需要五步手工操作的事情压缩成了一步，这就够了。