release

name	release
description	发布 FluxDown 新版本或查看已有版本时使用。校验版本 tag（稳定版 vX.Y.Z / 预览版 vX.Y.Z-rc.N）在推送前合法可用，并按渠道/组件快速列出已有版本。关键词：发布, 发版, release, publish, 版本, version, tag, 打标签, 稳定版, 预览版, stable, frontier, rc, 预发布, prerelease, 查看版本, 已有版本, 最新版本, 更新渠道, changelog, git-cliff

FluxDown 发布与版本查看

FluxDown 用 SemVer 预发布后缀区分双渠道：稳定版 vX.Y.Z、预览版 vX.Y.Z-rc.N。 推送 v* tag 会立即触发 GitHub Actions 全平台发布流水线（不可逆），同一次 push 自动派生 各组件 tag。本 skill 覆盖两件事：发布前校验版本可用 + 快速查看已有版本。

红线（.omp/RULES.md）：未经用户明确要求，禁止 git commit / push / tag。 本 skill 的推送命令仅在用户明确要求发布时执行。

1. 快速查看已有版本

# 客户端主线（稳定+预览）最新在前
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
# 各组件线最新稳定一个（组件前缀本身含 '-'，故用 '-rc' 判别预发布）
for p in v 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，不含浏览器扩展

• 组件线（server-v* / cli-v* / mobile-v* / extension-v*）由同一次 v* push 按目录 diff 自动派生，make_latest:false。预览 push 同步给组件打 -rc.N 并标 prerelease。
• 扩展发布后无法改版本号，故 -rc tag 跳过 build-extension/release-extension。
• 判据全在 .github/workflows/release.yml：prerelease/make_latest = contains(github.ref_name, '-')；Flutter --build-name 用剥后缀的 CLEAN_VERSION，APP_VERSION 保留完整版号。
• 分支模型：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. 发布前校验（保证版本可用）

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. 发布（不可逆，仅用户明确要求时）

# ⚠️ 推送后立即触发全平台构建与 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

5. 各渠道发布后可见性（自检预期）

• 官网下载 / /releases/latest：永远只给稳定版（/api/release 缺省 = stable；下载页从不带 channel）。
• 预览版：仅 /api/release?channel=frontier 与客户端"更新渠道 = 预览版"可见；预览资产经 /api/download/<name>?tag=<rc-tag> 下载。
• 客户端更新判定：native/hub/src/updater.rs 的 SemVer 比较器（含预发布精度）；渠道存于配置 update_channel（桌面/移动）、web_update_channel（web SPA）。

细节见根 AGENTS.md「git · 分支 · 发布」、.omp/knowledge/ops.md「发布与 CI」与 .github/workflows/release.yml。