miuread-koreader

# MiuRead

> **6.5.0-beta.28 · 本地 EPUB 社区评论与发布前测试修复**

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`](CHANGELOG.md)。

当前 beta 开发基线：`6.5.0-beta.28`。继承 beta.27 的本地 EPUB 关联、目录与引文映射、正文评论标记及想法回复；修复 CI 本地书籍隔离测试夹具，并将本地书籍评论回归纳入 beta 发布前检查。Schema 仍为 136。



## 6.5.0-beta.27 本地 EPUB 社区评论

1. 打开自己导入的 **EPUB**，进入觅阅的“评论”界面；在插件模式中可从“评论与想法 → 公开评论与本地 EPUB 关联”进入。
2. 点击“关联微信读书书籍”，输入书名搜索，选择对应的微信读书版本；或者通过“手动输入 bookId”关联。允许一本合集 EPUB 关联多本微信读书书籍，且可以随时解除关联。
3. 默认按章节标题自动匹配。进入“章节匹配管理”可以按本地目录项指定或追加对应的远程章节；已获取评论的章节还可以尝试“按已缓存原文匹配本章”（至少两条独立引文命中）。同一个本地目录项可以关联多个远程章节。
4. 在“获取公开评论”中选择当前章节或指定远程章节范围。完成后“查看本章评论”可从本地缓存打开想法；开启“阅读评论”可在**精确命中原文**时显示正文评论标记（不修改原 EPUB）。
5. 打开想法弹窗后长按或进入评论操作菜单，选择“查看回复”。回复列表使用原微信读书账号的只读接口，30 分钟以内复用离线缓存。
6. 从微信读书下载私人上传书籍时，遇到划线列表为空可以补充尝试章节公开想法接口。**若服务端未提供公开数据，客户端不能保证获取评论**；该来源也不能保证历史想法全部分页可取。

此版本不修改 beta.26 的阅读时间、精确进度及多设备同步实现，且不会将普通本地 EPUB 当作微信读书云端阅读会话。章节标记依赖 KOReader 的 EPUB TOC、XPointer 和文内精确搜索能力；不同译本、无可用目录或无原文命中的条目仍可从评论列表阅读，不能保证正文定位。

本次完成离线语法与模拟测试；微信读书真实接口及 Kindle/KOReader 的交互和绘制仍需要设备验收。详见 `BETA27_LOCAL_COMMENTS.md`。

## 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