release

# FluxDown 发布与版本查看 FluxDown 用 **SemVer 预发布后缀**区分双渠道：**稳定版 `vX.Y.Z`**、**预览版 `vX.Y.Z-rc.N`**。 推送 `v*` tag 会**立即触发 GitHub Actions 全平台发布流水线（不可逆）**，本次全部组件发布到**同一个** `vX.Y.Z` release。本 skill 覆盖三件事：**发布前校验版本可用** + **快速查看已有版本** + **失败组件补发**。 > 红线（`.omp/RULES.md`）：**未经用户明确要求，禁止 `git commit` / `push` / tag**。 > 本 skill 的推送命令仅在用户明确要求发布时执行。 ## 1. 快速查看已有版本 ```bash # 客户端主线（稳定+预览）最新在前 git tag -l 'v[0-9]*' --sort=-v:refname | head # 仅稳定版（排除 -rc 预发布） git tag -l 'v[0-9]*' --sort=-v:refname | grep -v -- '-rc' | head # 仅预览版（预发布 -rc） git tag -l 'v[0-9]*-rc*' --sort=-v:refname | head # 某个 release 已完整发布的组件（统一 release 以 SHA256SUMS-<组件>.txt 哨兵为准） gh release view "$V" --json assets -q '.assets[].name' | grep '^SHA256SUMS-' # 历史组件线（拆分时代，已不再新建）最新稳定一个 for p in server-v cli-v mobile-v extension-v; do \ echo "$p -> $(git tag -l "${p}[0-9]*" --sort=-v:refname | grep -v -- '-rc' | head -1)"; done # 已发布 release（含 prerelease 标记，需 gh 已登录该私有仓库） gh release list --limit 20 ``` `--sort=-v:refname` 对纯三段式排序精确；混入 `-rc` 时排名近似，需精确按时间用 `--sort=-creatordate`。 ## 2. Tag 约定（发布契约） | 渠道 | tag | 打自分支 | GitHub prerelease | make_latest | 打包范围 | |---|---|---|---|---|---| | 稳定版 | `vX.Y.Z` | `stable` | false | true | 客户端 / web / 移动 / NAS / 扩展 全部 | | 预览版 | `vX.Y.Z-rc.N` | `main` | true | false | 客户端 / web / 移动 / NAS，**不含浏览器扩展** | - 同一次 `v*` push 按目录 diff 决定本次打包哪些组件（app / server / cli / mobile / extension），产物全部上传到这一个 `vX.Y.Z` release；未改动的组件不重建，官网自动沿用它上一个完整版本。历史上的 `server-v*` / `cli-v*` / `mobile-v*` / `extension-v*` 组件 release 不再新建，官网仍兼容读取。 - **扩展发布后无法改版本号**，故 `-rc` tag 跳过 `build-extension`（`changes` 判定 extension=false）。 - latest：`publish-release` 只在「稳定版 + 桌面端完整 + 最高稳定版本」时标记；Rust `FLUXDOWN_APP_VERSION` 与原生 Android `versionName` 保留完整 tag 版本。 - **分支模型**：`main` = 开发分支（超集 / 最新），`stable` = 稳定分支（子集）；`stable` 只经合并/cherry-pick `main` 前进。稳定发布前 `git log stable --not main` 必须为空。 - **CI 分支守卫**（`changes` job 首步）：tag 提交必须在对应分支上——`vX.Y.Z` ∈ `origin/stable`、`vX.Y.Z-rc.N` ∈ `origin/main`，否则整条流水线立即失败（`git merge-base --is-ancestor` 判定）。 ## 3. 发布前校验（保证版本可用） ```bash V=v0.3.0 # 稳定版；预览版示例：V=v0.3.0-rc.1 # 1) 格式合法：稳定 ^v[0-9]+\.[0-9]+\.[0-9]+$ ；预览 ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ printf '%s\n' "$V" | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$' && echo OK || echo "格式非法" # 2) tag 不重复 git rev-parse -q --verify "refs/tags/$V" >/dev/null && echo "已存在，换号" || echo "可用" # 3) 单调递增：新版须高于最新同类（对照下面输出） git tag -l 'v[0-9]*' --sort=-v:refname | head -3 # 4) 工作树干净、停在目标分支的目标提交（稳定=stable，预览=main） git status --porcelain # 须为空 git branch --show-current && git log -1 --oneline # 4b) 稳定发布额外：stable 不得含 main 没有的提交 git log stable --not main --oneline # 须为空 # 5) 可选：本地预览 release notes（需装 git-cliff；未装则跳过，CI 仍会生成，无规范 commit 时用默认标题） command -v git-cliff >/dev/null && git cliff --latest --strip header | head -40 ``` 版本"可用"的硬条件：格式合法 · tag 不重复 · 高于同渠道最新 · 停在正确分支且工作树干净 · 稳定版 `stable --not main` 为空。构建绿由调用者在发布前自行保证。 预览版额外确认：后缀是 `-rc.N` 且 N 递增（预览用户按 SemVer 收 `rc.1 < rc.2 < … < 转正 X.Y.Z`）。 ## 4. 发布（不可逆，仅用户明确要求时） ```bash # ⚠️ 推送后立即触发全平台构建与 GitHub Release，无法撤回。 # 先切到正确分支：稳定版 stable，预览版 main（CI 守卫会拒绝打错分支的 tag）。 git checkout stable # 预览版改为: git checkout main git tag -a "$V" -m "$V" git push origin "$V" # 观察流水线 gh run watch ``` ## 4b. 组件打包失败 → 补发（不重跑其余组件） 某组件失败时其余组件照常发布，`publish-release` 以失败结束并在 job summary 列出缺失组件与补发命令。 ```bash # 偶发失败（源码无需改动）：在该运行页点 “Re-run failed jobs”，或 gh run rerun <run-id> --failed # 需改代码/打包脚本：修复先合入发布分支（稳定版 = stable，预览版 = main），再补发该组件 gh workflow run release.yml --ref main -f tag="$V" -f component=mobile # 源码 = tag 本身 gh workflow run release.yml --ref main -f tag="$V" -f component=mobile -f source_ref=stable # 源码含修复 ``` - `component`：`app` / `extension` / `server` / `cli` / `mobile`，或 `changed`（按该 tag 的变更检测补发全部应发组件）。 - `source_ref` 必须包含该 tag 且在发布分支上；版本号、预发布标记恒取 tag。产物以 `--clobber` 覆盖同名资产，旧清单里不再产出的资产会被删除。 - 补发属于 CI 触发，等同发布动作：仅在用户明确要求时执行。 ## 5. 各渠道发布后可见性（自检预期） - **官网下载 / `/releases/latest`**：永远只给稳定版（`/api/release` 缺省 = stable；下载页从不带 channel）。 - **预览版**：仅 `/api/release?channel=frontier` 与客户端"更新渠道 = 预览版"可见；预览资产经 `/api/download/<name>?tag=<rc-tag>` 下载。 - **客户端更新判定**：桌面/headless 由 `native/agent/src/update/` 承担，使用 protocol 更新状态；原生移动端见 `mobile/Android` 与 `mobile/FluxDown`。Android 正式包用 `ANDROID_NATIVE_*` 签名，不能覆盖旧 Flutter APK，发布说明必须保留换签名安装提示。 细节见根 `AGENTS.md`「git · 分支 · 发布」、`.omp/knowledge/ops.md`「发布与 CI」与 `.github/workflows/release.yml`。