miuread-koreader

MiuRead

6.5.0-beta.23 · 最近阅读排版优化与图标修正

5.9.0 开始把“本机/云端冲突需要用户判断”改为无感云端镜像：打开书籍时自动按同步因果和更新时间选择最新阅读状态，在定位完成前短暂保护翻页；精确 chapter_uid + co 仍是最终验收依据。账号书架默认使用微信云端顺序，已读完状态与当前位置分离解析，自动云端跳转可以短时撤回。

本仓库同时维护正式版与内测版：

• main：正式版
• beta：内测版
• 正式 OTA：stable-channel/update.json
• 内测 OTA：beta-channel/update-beta.json

Versions

• 正式版：以 GitHub Releases 中最新的非 Pre-release 为准。
• 内测版：以 GitHub Releases 中最新的 Pre-release 为准。

完整版本记录见 CHANGELOG.md。

当前 beta 开发基线：6.5.0-beta.23（基于 6.5.0-beta.19 完整源码）。保留原有 Schema 136、账号/下载/评论/多设备进度机制。

6.2.0-beta.3 阅读时间修复与评论界面调整

• 修复上一个版本的真实 Kindle 故障：阅读时间 Worker 不再遗漏开书时取得的 Web 位置快照；严格校验会话时间、账户所绑定书籍及章节目录，使用完整 /web/book/read 时间协议，不额外调用错误的 Legacy Web GET。
• 时间上报仍为首次约15秒、后续约60秒，失败时不补传历史时间；后台服务协议升级到 v32。关书时最新 Kindle 原生精确进度与阅读时间继续分开写入。
• 评论获取入口、范围编辑器和分页章节选择改用完整不透明背景的原生阅读器弹窗；批量下载进度界面也使用完整白底，减少正文穿透、遗留局部覆盖和墨水屏刷新异常。
• 保留 beta.2 评论下载、暂停继续、断点缓存与完整双 EPUB 机制；当前已完成离线测试，在线记账与真实 Kindle 显示仍待验证。

6.2.0-beta.2 阅读时间与评论获取更新

• 阅读时间首次约 15 秒、之后约每 60 秒由独立 Worker 上报。第一次需要取得可信 Web 位置；同一阅读会话后续使用该位置快照，不再每分钟读取云端进度。关书后仍由独立进度流程提交 Kindle 最新精确位置。
• 阅读时间采用 best-effort：不跨会话补报断网/失败时长，不重复提交无法确认的 POST。旧 Worker 协议升至 v31，登录身份与书籍映射验证保留。首次成功提醒只显示「本次阅读时间已开始同步」。
• 评论获取菜单默认“自选范围”：当前章起最多十章或自选起止；另保留当前章节、更新指定范围。批量获取使用独立子进程，支持章节级进度、暂停、继续、后台运行和取消；不再自动打开本章评论长列表。
• 此版本未改变 Schema 136、正文与带评论 EPUB 格式、章节下载、多设备登录、进度确认、OTA 通道与现有发布入口。真实微信读书记账、Kindle UI、GitHub Actions 的线上验证仍需完成。

6.2 beta.1 阅读时间与发布修复

• 阅读时间恢复首次约 15 秒、之后约每 60 秒的分段上报；阅读进度仍在结束阅读或手动同步时上传。
• 兼容时间请求每次必须先读取微信 Web 当前真实位置，然后原样回显给 /web/book/read，不使用本地推算章节偏移覆盖云端。
• Web 位置不可核实时安全阻止时间请求；保留明确未发出的时长，结果未知时不重复提交。
• 正式版可通过 Actions 手动输入版本号自动维护版本文件；直接 Tag 发布只校验不可变 Tag 自身的正式版本源码。
• 当前仅完成离线代码与模拟验收；真机和微信读书在线接口仍须测试。

历史机制：5.9 beta.5 highlights

• 开书立即恢复本机页面，云端 position metadata 在后台确认；已有精确本地快照时先走轻量 freshness 判断，remote 确认更新后才启动重型定位。
• 删除“用户已经翻页 → local wins”的旧语义；以可信 verified anchor + 真实阅读事件时间统一判断 LOCAL_NEWER / REMOTE_NEWER / ALIGNED / CONFLICT。
• 新增 progress write fence：remote 未确认、remote newer 或 conflict 时禁止自动本机写回，避免旧 Kindle 位置覆盖更新云端。
• raw_percent 仅保留为诊断字段；canonical progress、finished、CloudAnchor 与 ReadReport 均以精确位置状态为准。
• exact-co 定位加入已验证 XPointer 缓存和 text-anchor rescue，percent correction 最多一次 bounded fallback。
• 当时阅读时间采用 best-effort 策略；该规则已被后续版本的 SAFE 时长持久化和 6.2 beta.1 分段上报机制取代。
• Schema 136 与 beta.4 的 position-state stack overflow StoreRepair 保持不变。

Installation

1. 在 GitHub Releases 下载需要的版本。
2. 解压后将完整的 miuread.koplugin 目录放入 KOReader 的插件目录。
3. 完整重启 KOReader。
4. 支持双更新通道的版本可在“觅阅设置 → 更新与关于 → 更新通道”中选择正式通道或内测通道。

接口通道

在“觅阅设置 → 同步与下载 → 接口通道”选择“自动（E-Ink 优先）”或“Web”。这一设置适用于书架、书籍信息、目录、搜索、推荐、分类、阅读统计、批注读取及下载，下次操作时生效。在账号设置的“E-Ink 客户端授权”中，使用同一微信读书账号扫码授权；账号状态页可查看或取消授权。

业务模块通过统一 Api 调用，两套后端分别负责协议与响应解析，公共通道策略负责选择和回退。E-Ink 未授权、不支持或普通读取失败时使用 Web；同一下载或书架变更事务回退后固定 Web，独立操作重新按偏好选择。Web 后端内部保留尚未替换的 Skills 只读兼容请求，不向业务层提供第三套通道。

遇到限频、取消或休眠立即停止，不切通道继续请求。写入前允许验证和续期授权，发出写入后遇到超时等不确定结果不会换通道重发，继续由业务流程核实云端状态。Web 书架移除没有经过验证的接口，需使用自动模式及 E-Ink 授权。

批注上传、精确进度坐标校验和阅读上报明确使用 Web 上下文；普通进度展示可优先读取 E-Ink。轻量书架请求不支持完整快照回退时使用 Web 索引，避免将分页读取变成整架下载。公众号正文和静态资源保留其现有 Web 路径。

书城分类标识、翻页游标及推荐会话绑定产生它们的通道；后续页面失败时保留当前列表，重新打开列表再按偏好选择通道，避免混用两套分页状态。普通进度展示的 Web 后端先读取 Cookie 接口，必要时使用旧只读接口；精确同步单独获取两份独立观测。

原文、划线与想法版、译文及自动准备章节均使用上述策略，支持整本、范围和单章。E-Ink 的原文及译文下载方式如下。

E-Ink 获取章节包并解密，按包内清单合并正文和整理图片。首次 EPUB 请求同时获取公共资源章 0，后续复用样式；包内及缓存均缺少样式时，从 Web 补取一次。只下载客户端目录明确标为免费或已购买的章节，其他权限情况回退 Web。

划线和想法通过 E-Ink 接口获取，使用同通道原始章节验证位置，再映射到 EPUB。无法确认位置或批注接口失败时，本章正文与批注一起回退 Web；两通道的批注断点分开保存，避免混用坐标。

译文的会员检查、模式切换、生成及状态轮询也优先使用 E-Ink。保留当前章/下一章请求、会员校验及已有译文保护，不开启免费试用。章节包必须实际包含译文才计为完成；缺少译文则回退 Web 获取，不能用原文冒充译文。译文仍受微信读书会员和书籍支持范围限制。

E-Ink 普通失败后，本次剩余任务固定使用 Web，断点续传保留该决定。任一通道遇到限频立即停止，不换通道继续请求；取消和休眠也直接停止。公众号内容和精确进度坐标校验继续使用 Web，E-Ink 正文不作为 Web 坐标的可信来源。选择“Web”可固定使用网页接口。

离线检查：tools/test_eink_download.py --zlib PATH 包含公共路由、两套后端请求、下载、批注和译文事务回归；新增接口参数对照了客户端协议目录与参考实现。合成响应测试不代替已登录设备的服务端验收。

阅读时长同步

6.3.0-beta.5 新增默认关闭的「仅使用 E-Ink 上传阅读时间」开关。开启后，无论普通接口设置为自动或 Web，阅读时间都只能走 E-Ink 本地 SQLite 记录和 /book/batchUploadProgress；联网时尝试上传，断网时保留，恢复后按队列重试规则继续。E-Ink 授权或统计不可用时不会回退 Web 时间；需恢复条件。Web 精确阅读进度仍使用 rt=0 独立同步。 阅读过程中修改时间通道将停止旧 Web 计时（不补交尾段），需要关闭并重新打开当前书籍才能启动新模式；已发出的请求无法撤销。关闭该选项后恢复原有自动时间通道选择，不影响保留的 E-Ink 历史队列。

在“同步 → 自动同步设置 → 阅读时长同步”管理。E-Ink 模式需要开启 KOReader 阅读统计； 觅阅复用统计插件的有效阅读规则，将开启同步后的新片段保存在独立 SQLite 队列。 升级保留原有阅读时长开关及测试版待传记录，不补传开启之前的历史统计。

自动接口模式且同账号 E-Ink 授权可用时，在线和离线片段都通过 /book/batchUploadProgress 上传，携带原始小时及当地时区。联网、唤醒及关闭书籍后可继续处理待传队列。 没有 E-Ink 授权或固定使用 Web 时，完整沿用上游 Web 在线上报链路：首次约 15 秒、随后约 60 秒， 关书时处理尾段；使用上游校验的会话位置，不调用旧 Legacy GET，也不补传离线队列。 每次开书固定一种计时来源；阅读中修改授权或接口设置，不会将已记录的同一时段再交给另一条链路。 通道选择在下次开书时重新确定。E-Ink 队列不降级为 Web；已有待传记录等待 E-Ink 可用后处理， 也不会与正在运行或收尾中的 Web 服务同时写入。 沿用上游尽力同步策略，旧版跨会话 Web 补报默认关闭；旧记录不复制到新队列，也不猜测历史时间后补传。

请求发出后若无明确回执，记录转为“待确认”，重启或重连也不会自动重发。可在详情中核对书籍、 时间和时长，先在微信读书核对后选择“忽略该记录”。上传后检测到云端位置改变会暂停后续补传； 可点击“核对云端位置并恢复补传”，核对成功后继续处理未发送记录，待确认记录仍保留。 关闭同步保留已有队列。失败重试及限频冷却跨重启保留；空闲且无可发送记录时停止轮询。

完成的记录及其窗口元数据会清理。每个账号最多保留 50,000 个待处理片段；达到上限时明确提示并 暂停收集，先同步或处理待确认记录再重新打开书籍。该上限不会静默删除尚未处理的时长。 2026-10-26 的测试构建实机验证过 E-Ink 补传基础流程；当前 rebase 版本尚未重新实机验收。 跨日、通道隔离和异常恢复有自动化回归。

与 E-Ink 2.1.2 的逐项对照见离线阅读时长协议核对。 新片段会保存当时的异常标记和可信文件版本，上传时合并标记并隔离不同版本；旧记录缺失的信息不猜测回填。 小时结算和失败恢复等行为仍有差异；接口可用不等于与官方客户端完全一致或保证账号安全。

问题反馈

正常日志保留阅读时长同步结果和异常。需要排查时，在“阅读时长同步”开启“详细诊断日志”， 复现后导出运行日志，可看到批次、小时、参数来源及补传前后云端位置；不记录实际签名令牌。 tools/test_offline_readtime.py 使用 LuaJIT 与真实 SQLite 验证队列和生命周期，并纳入 Beta 工作流。 python tools/build_package.py 可生成普通本地安装包及 SHA-256。

遇到问题时，可在“觅阅菜单 → 系统维护 → 导出运行日志”导出日志，文件保存在下载目录。反馈时附上操作步骤、设备及 KOReader 版本，以及导出的日志。

日志记录调用通道、耗时、回退原因、错误阶段和冷却信息，不包含正文、请求内容或登录凭据。日志自动限制保存大小，前台操作与后台下载使用同一日志文件。

微信读书书城

在觅阅菜单中选择“微信读书书城”，可浏览为你推荐、排行榜、分类及子分类，并搜索微信读书全库。主页推荐快捷栏默认显示“书城”；长按“书城”可直接搜索微信读书、我的书架或批注。“搜索”仍可单独启用，默认顺序紧挨“书城”；这两个入口均可配置到主页快捷栏，“书城”也可配置到下拉控制中心或 KOReader 手势。升级时仅将未自定义的旧推荐快捷栏中的“搜索”替换为“书城”，已有的自定义开关与排序保留；旧版自动追加在末尾的“书城”会移到“搜索”旁。

列表显示封面、作者、推荐值和推荐理由。每次获取一批书籍，使用“上一批 / 下一批”继续浏览；已获取的列表在当前会话中缓存，超过 15 分钟会标记为缓存，可点击“刷新”获取最新内容。排行榜和分类可直接联网浏览；个性化推荐、相似推荐与管理微信书架需要登录。

点击书籍后可查看详情、相似推荐、下载到本机或“加入微信书架”。已在微信书架的书籍显示“从微信书架移除”，也可在主页或微信书架中长按微信读书书籍找到此入口；移除前会确认，本机已下载的文件会保留。添加和移除均在回读云端确认后刷新书架；若请求中断或结果不明，后续操作只核对原操作的结果，需确认当前状态后才可再次提交。

从微信书架移除书籍需要 E-Ink 客户端授权，并使用自动模式。点击“微信扫码授权”，使用当前账号对应的微信扫描二维码；也可提前在账号设置中授权。授权完成后再次选择移除；原有网页登录保持不变。

书架阅读状态

桌面模式刷新微信书架会同步手机端的“已读完”标记，并在后台更新当前页的阅读百分比，无需先下载书籍。手动点击书架的“刷新”也会触发更新；翻页后会补齐该页的进度。离线时保留缓存，Kindle 上尚未上传的阅读进度优先显示。

长按微信书架中的书籍，或在阅读菜单的“当前书籍”中，可标记或取消“已读完”，无需先下载。操作保留阅读位置，并在微信读书回读确认后更新状态。离线操作会保存；联网刷新书架或唤醒后继续同步。未确认的操作可从同一菜单重试或更改。

精确阅读位置在打开书籍时检查云端、在关闭或休眠时上传（选择手动上传模式时需手动操作）。离线补传也会先检查云端，按已确认的共同位置和阅读事件时间判断新旧；无法可靠判断时，保留本机位置等待选择。

双语阅读与离线译文

阅读菜单的“外文翻译”分为“阅读方式”和“离线译文”。阅读方式可选原文、双语或仅译文，译文大小可单独调整。已有译文可直接显示；选择双语或仅译文时，当前章没有译文会在后台准备接下来几章，尚未翻译的段落继续显示原文。

“仅译文”只隐藏能确认与译文逐段对应的原文。部分段落无法对应时，其余部分仍可使用仅译文，无法对应处保留双语；整本都无法确认对应关系时，会标记“暂不可用”，点击可查看原因及使用条件。尚未下载或应用译文时也会说明下一步。下载后才发现不支持仅译文的，会保留下载结果并提示使用双语阅读。

“离线译文”的主按钮会随状态显示“下载整本译文”“查看下载进度”“继续下载译文”或“应用译文”。也可选择“先下载接下来几章”，较快开始阅读。所有下载均在后台进行，可以继续读原文；单独下载译文不会改变当前阅读方式。已有其他下载时可加入队列，暂停或中断后可从已有进度继续。

译文就绪后会轻提示，不自动切走阅读页面。回到“外文翻译”，点击“应用译文”即可在当前位置重新载入本书，并保留划线及下载期间选择的阅读方式。旧版 KOReader 若不支持此操作，会提示关闭后重新打开；安装前仍会校验阅读记录，校验失败时保留原文件。

译文来自微信读书官方服务，下载需要付费会员。原文已下载整本时，可补齐全书译文；单章版、章节范围版和试读版会明确显示为下载这些章节的译文，保持已有文件范围。下载正文时会重新确认暂未就绪的章节；个别章节仍无译文时保留原文并继续后续章节，完成后显示实际数量，可稍后补齐。已有译文会保留，没有新增译文时不会提示更新完成。

Release Process

• Stable tag：vX.Y.Z
• Beta tag：vX.Y.Z-beta.N
• 正式版发布到 stable-channel
• 内测版发布到 beta-channel
• 创建 Tag 后，发布工作流会自动同步分支源码中的版本号、发布通道与 CHANGELOG.md，再把 Tag 指向同步后的提交。
• Beta Tag 必须创建在 beta 最新提交；Stable Tag 必须创建在 main 最新提交。
• 最终分支源码、Tag 源码、Release 安装包与 OTA 清单保持同一版本。

仓库根目录 update.json 仅保留为旧正式版 OTA 桥接入口，不作为当前正式版实时更新清单。

Origin and License

MiuRead originated as a modified version of finlater/weread.koplugin v0.1.1 and has since undergone substantial restructuring, modification, and extension.

MiuRead is an unofficial community project and is not affiliated with or endorsed by WeRead, Tencent, KOReader, or their maintainers.

This project is distributed under the GNU Affero General Public License version 3 only (AGPL-3.0-only). See LICENSE, NOTICE, and THIRD_PARTY_NOTICES for details.