觅阅 MiuRead 是一款适用于 Kindle 的非官方 KOReader 微信读书（WeRead）插件，支持书架同步、书籍下载、划线与想法、阅读时长和阅读进度同步。它的版本分发没有依赖手动上传，而是由 GitHub Actions 发布工作流驱动：推一个 Git Tag，就能自动完成版本校验、回归测试、打包、校验哈希并推送 OTA 更新清单。本文带你用一张全景图看懂它的「Tag 触发 + 双通道 OTA」发布体系，以及每个环节在守护什么。

一、双通道发布：正式版与内测版各走一条流水线 🛤️

觅阅同时维护两条发布链路，源码分支与 OTA 清单一一对应：

也就是说，v6.3.0和v6.3.0-beta.1推出去之后，会分别触发两条互不干扰的流水线；设备端在「觅阅设置 → 更新与关于 → 更新通道」中选择正式或内测通道后，只会订阅对应通道的那份清单，互不打扰。

两条流水线都设置了concurrency并发组且不允许取消进行中的任务，超时 8 分钟兜底——同一通道同时只会有一次发布在进行，避免两个 Runner 互相覆盖 Release 资产。

二、Tag 触发：最小代价启动一次完整发布 🏷️

触发方式只有两种，且都强调「不可变」：

1. 推送 Tag 自动发布：推v6.3.0（正式版）或v6.3.0-beta.2（内测版）即触发。工作流会先校验 Tag 必须落在对应分支（main/beta）的最新历史上，且检出的源码 SHA 必须与 Tag 完全一致，否则直接拒绝发布——Tag 一旦发布就永不移动、永不改写。
2. 手动 dispatch 发布：在 Actions 页面填写版本号（正式版还可由 sync_release_identity.py 自动补齐版本文件），流水线会自动准备元数据、提交并创建 Tag，但绝不对已存在的 Tag 做强推或改指向。

版本号本身也有严格格式约束：正式版必须形如5.3.0，内测版必须形如5.3.0-beta.6，且必须高于该通道已有的最新版本，防止「降版发布」。

三、身份三重校验：Tag、源码、清单必须「三处一致」 🔍

发布前，流水线会把三处版本身份对齐检查：

• Git Tag（vX.Y.Z）
• 插件元数据 _meta.lua 的version
• 运行配置 config.lua 的VERSION、UPDATE_CHANNEL与UPDATE_MANIFEST
• 变更记录 CHANGELOG.md 中必须存在## 版本号二级标题且至少一条列表项

任何一处不一致都会以明确的中文错误信息中止，例如「Tag 源码版本与目标版本不同」。内测通道还有两个专用工具兜底：prepare_beta_release.py 负责准备版本与更新说明，ensure_beta_tag_changelog.py 负责在打包工作区补齐 CHANGELOG 条目——它们只修工作区副本，从不改写已发布的 Tag。

同时流水线会扫描插件目录，发现.md、.epub、.log、macOS 垃圾文件（__MACOSX）或不应外泄的本地设置文件时直接失败，确保安装包「干净离场」。

四、构建与回归：打包前先跑完整测试门 🧪

打包步骤看似简单，但它前面压着厚重的回归测试门：

• Lua 语法检查：对 miuread.koplugin/ 下全部.lua文件跑luac -p；
• 回归测试套件：内测通道会在发布门禁里跑数十个契约测试（进度同步、下载断点、评论、书架、阅读时间等，均位于 tools/ 目录），并用lua5.1与luajit双引擎交叉验证；
• 离线 E-Ink 链路验证：独立虚拟环境中执行tools/test_eink_download.py，覆盖两套接口后端、下载、批注与译文事务。

全部通过后，流水线才会把miuread.koplugin目录压缩为miuread-vX.Y.Z-full.zip（Beta 通道还会排除native/编译源码目录进一步减重），并生成对应的 OTA 清单文件。随后立刻做「装包体检」：ZIP 完整性、必备文件齐全、清单中的version、channel、size、sha256与实际包逐一比对，任何偏差都中止发布。

五、双通道 OTA 清单：设备端如何发现新版本 📡

清单本身就是一份小型 JSON，核心字段如仓库根目录的 update.json 所示：

{ "version": "6.0.0-beta.1", "channel": "beta", "package_type": "full", "package_url": "…/releases/download/v6.0.0-beta.1/miuread-…-full.zip", "package_urls": ["官方直链", "加速镜像 1", "加速镜像 2"], "size": 1763687, "sha256": "e76d7225…", "summary": "设备端展示的更新摘要（最多 4 行 / 180 字符）" }

发布流水线的最后两步是「固定地址清单」机制的关键：

1. 版本 Release：以 Tag 为名创建 Release 并上传安装包；
2. 通道清单发布：把清单文件clobber覆盖到固定 Release（stable-channel/beta-channel）上。

这样一来，设备端 updater.lua 只需订阅一个永不变化的 URL，它负责：按「官方直链 + 多镜像」顺序回退拉取清单、记住上次连通性好的线路、用sha256和size双重验证安装包、下载与安装失败时自动清理残留文件。发布侧还会对公网下载地址做一次真实回读校验，确保 CDN 可读后才宣告发布完成。

💡 仓库根目录的 update.json 仅作为旧版正式 OTA 的桥接入口保留，当前实时清单以stable-channel/beta-channel为准（详见 README.md 的 Release Process 一节）。

六、收尾细节：正式版发布后自动回同步 beta 🔄

正式版流水线还有一步容易被忽略的收尾：发布完成后，若main相对beta只是新增了发布身份与记录（且beta期间没有新提交），会把main的发布历史以 merge 提交合回beta，并保留 beta 自身的版本号与内测通道身份。这大大减少了下一轮「beta → main」发布合并时的冲突，具体分支规则见 CONTRIBUTING.md。

写在最后 📌

把整套流程串起来看：

推 Tag → 身份三重校验 → 回归测试门 → 打包 + 清单生成 → 装包体检 → Release 上传 → 固定通道清单覆盖 → 公网回读确认

觅阅 MiuRead 的发布工作流本质上是在回答一个问题：如何让 Kindle 用户在 OTA 更新时，拿到的一定是「测试过、哈希对得上、版本号三处一致」的包。双通道设计让激进的内测用户与求稳的正式用户各取所需，而所有护栏都固化在两条工作流文件里，可复现、可审计——这也是普通用户可以放心点「立即更新」的底气所在。