feigeCode · Oct 31, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/.github/RELEASE.md b/.github/RELEASE.md
@@ -52,6 +52,50 @@ A release pull request keeps the fast path after `main` is merged back into `dev
 - `main` is the stable release branch and is protected: changes land via pull request, and CI must pass before merging.
 - Cut a release by merging the validated work from `dev` into `main` — including the `main/Cargo.toml` / `Cargo.lock` version bump — then creating the `v*` tag on `main` with `script/release-tag.sh`. The version bump must ride the pull request because direct pushes to `main` are rejected (GH006); only the tag is pushed directly.
 
+## Beta 发布通道
+
+beta 通道把测试版与稳定版的更新清单彻底分开：稳定通道继续读写 `updates/latest.json`（老客户端唯一认识的地址），beta 只写 `updates/beta/latest.json`。beta tag 仍然是完整的 GitHub Release，只是会被显式标记为 prerelease。
+
+> 首次使用前的前置条件：`release-trigger.yml` 用 `--ref main` 取 workflow 定义，所以 channel/prerelease 的改动必须已合入 `main`。否则跑的是 main 上的旧版 `release.yml`——不带 `--prerelease`、也不传 `channel`。
+
+### 版本线约定
+
+- beta 的 base 永远是**下一个稳定版**：`0.23.0-beta.1 → 0.23.0`。beta 稳定后就地转正，版本号去掉 `-beta.N`。
+- 不要给已发布的稳定版开补丁 beta 线（例如 `0.22.1-beta`）：那会让老客户端把测试版当成同一版本线的修复更新。
+- 同一 base 的 beta 依次递增：`0.23.0-beta.1`、`0.23.0-beta.2`……每个 beta 都是独立 tag、独立 Release、独立安装包前缀 `releases/<tag>/`。
+
+### 一条命令发 beta
+
+beta 版本线走 `dev` 分支，前置条件是工作区干净、`dev` 已同步。脚本会改 `main/Cargo.toml` 与 `Cargo.lock`、写入 `CHANGELOG.md` 双语条目、提交、打 tag，并推送 `dev` 与 tag：
+
+```bash
+script/beta-release.sh --base 0.23.0 --notes-file /private/tmp/navop-v0.23.0-beta.1.md
+script/beta-release.sh --next --notes-file /private/tmp/navop-v0.23.0-beta.2.md
+```
+
+- `--base X.Y.Z`：把版本设为 `X.Y.Z-beta.1`。
+- `--next`：要求当前版本是 `X.Y.Z-beta.N`，递增为 `beta.N+1`。
+- `--notes-file`：必填，内容规则与正常发布相同（中文 `更新内容` / `修复与优化` + 英文 `What's New` / `Fixes and Improvements` + CNB 镜像行）；`release.yml` 会硬校验 `CHANGELOG.md` 里有 `## [v<tag>] - YYYY-MM-DD` 条目。
+- `--dry-run`：只打印将要执行的步骤与最终 tag，不写任何文件、不提交、不打 tag、不推送。
+
+### 发一个 beta 会发生什么
+
+1. `git push cnb <tag>` 触发 `Release Trigger`。
+2. `Release` 始终取 `main` 分支上的 workflow 定义运行，`prepare` job 按 tag 推导出 `channel=beta`。
+3. 构建完成后创建/更新 GitHub Release，并追加 `--prerelease`。必须如此：否则 GitHub 的 `/releases/latest` 会把 beta 当成最新稳定版推给所有老客户端。
+4. 派发 `upload-r2.yml` 时显式带 `-f channel=beta`：安装包照常上传到 `releases/<tag>/`，更新清单写到 `updates/beta/latest.json`。
+5. 稳定清单 `updates/latest.json` 完全不动，所有走稳定通道的现有用户不受影响。
+
+### 转正（promotion）
+
+beta 验证稳定后，按正常发布流程把 `dev` 合进 `main`：在 release PR 里把 `main/Cargo.toml` / `Cargo.lock` 的版本从 `X.Y.Z-beta.N` 改成 `X.Y.Z`，整理 `CHANGELOG.md` 中该版本的条目，合并后在 `main` 上执行 `script/release-tag.sh vX.Y.Z`。这条稳定 tag 会把同一版本写回 `updates/latest.json`，beta 清单留在原地作为历史。
+
+### 回滚
+
+- beta 发布失败（tag 打错、changelog 缺条目）：`git tag -d vX.Y.Z-beta.N`、`git push cnb :refs/tags/vX.Y.Z-beta.N`，必要时 `git reset --hard HEAD~1`。beta 不影响稳定清单，通常无须额外回滚。
+- 万一稳定清单被污染（例如误用 beta tag 跑了 stable 通道）：用一个已知正确的稳定 tag 重跑 `upload-r2.yml`（`-f tag=vX.Y.Z -f channel=stable`），脚本会幂等重建 `updates/latest.json` 与 `releases/<tag>/` 下的安装包。
+- `node script/test-release-packaging.mjs` 里有一组回归断言（含假 aws 仿真），保证 beta tag 永远只写 `updates/beta/latest.json`。
+
 ## Changelog format
 
 The newest entry belongs immediately after the `<!-- NAVOP_RELEASES -->` marker:
@@ -118,6 +162,6 @@ For a failed matrix job in the same workflow run, prefer **Re-run failed jobs**.
 - A new release tag must contain a valid bilingual `CHANGELOG.md` entry before builds begin.
 - GitHub Release notes and R2 updater `release_notes` are extracted from the same tagged changelog entry.
 - Publishing uses `--clobber` only for newly built platform files and `sha256sums.txt`.
-- R2 keeps only the newest release. The prune step runs after the upload has been verified object by object and never carries `always()`, so a failed upload leaves the existing objects alone; it refuses to delete anything when its own tag is missing from R2, and a non-stable tag (for example `v0.20.0-rc.1`) skips pruning so it cannot take the last stable installers with it.
+- R2 keeps the newest stable release plus the beta installer that `updates/beta/latest.json` still points at, so beta-channel downloads keep working after a stable release. The prune step runs after the upload has been verified object by object and never carries `always()`, so a failed upload leaves the existing objects alone; it refuses to delete anything when its own tag is missing from R2, and a non-stable tag (for example `v0.20.0-rc.1`) skips pruning so it cannot take the last stable installers with it. Objects under `updates/` are never deleted.
 - Legacy pre-changelog repairs preserve their existing GitHub Release body.
 - All five primary platform builds belong to one matrix, so they start in parallel and a failed job can be rerun without rebuilding successful matrix jobs.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -51,6 +51,7 @@ jobs:
       tag: ${{ steps.release.outputs.tag }}
       platform: ${{ steps.release.outputs.platform }}
       build_mode: ${{ steps.release.outputs.build_mode }}
+      channel: ${{ steps.release.outputs.channel }}
 
     steps:
       - name: Validate release request
@@ -70,6 +71,9 @@ jobs:
             echo "::error::Invalid release tag: $RELEASE_TAG"
             exit 1
           fi
+          # 发布通道：纯稳定版本号（vX.Y.Z）走 stable，其余（vX.Y.Z-beta.N /
+          # -rc.N 等预发布）走 beta。与 upload-r2.yml 里的推导规则保持一字不差。
+          if [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then CHANNEL=stable; else CHANNEL=beta; fi
           gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${RELEASE_TAG}" >/dev/null
           if [ "$RELEASE_PLATFORM" != "all" ]; then
             gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null
@@ -78,7 +82,9 @@ jobs:
             echo "tag=$RELEASE_TAG"
             echo "platform=$RELEASE_PLATFORM"
             echo "build_mode=$BUILD_MODE"
+            echo "channel=$CHANNEL"
           } >> "$GITHUB_OUTPUT"
+          echo "Release channel: $CHANNEL"
 
       - name: Check out release tag
         uses: actions/checkout@v7
@@ -353,10 +359,10 @@ jobs:
             # is not worth a second shape to test and release.
             cargo zigbuild \
               --release \
-              -p main \
+              -p navop \
               --target "${{ matrix.target }}.2.28"
           else
-            cargo build --release -p main --target "${{ matrix.target }}"
+            cargo build --release -p navop --target "${{ matrix.target }}"
           fi
           test -x "target/${{ matrix.target }}/release/${{ matrix.binary }}"
           # 体积回归在日志里可见（fat LTO + panic=abort 后约 107MiB）
@@ -417,7 +423,7 @@ jobs:
           }
           cargo build `
             --release `
-            -p main `
+            -p navop `
             @features `
             --target $target
 
@@ -868,18 +874,28 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+          CHANNEL: ${{ needs.prepare.outputs.channel }}
         run: |
           set -euo pipefail
+          # 只有 beta 通道把 Release 标成 prerelease：稳定版修复时误标会让
+          # /releases/latest 跳过它，老客户端（只认该端点）就再也收不到更新。
+          # 空数组在 `set -u` 下的展开要显式兜底，见 ${arr[@]+"${arr[@]}"}.
+          prerelease_args=()
+          if [ "$CHANNEL" = "beta" ]; then
+            prerelease_args+=(--prerelease)
+          fi
           if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
             gh release edit "$RELEASE_TAG" \
               --repo "$GITHUB_REPOSITORY" \
               --title "Navop $RELEASE_TAG" \
+              ${prerelease_args[@]+"${prerelease_args[@]}"} \
               --notes-file release-notes.md
           else
             gh release create "$RELEASE_TAG" \
               --repo "$GITHUB_REPOSITORY" \
               --verify-tag \
               --title "Navop $RELEASE_TAG" \
+              ${prerelease_args[@]+"${prerelease_args[@]}"} \
               --notes-file release-notes.md
           fi
 
@@ -898,10 +914,13 @@ jobs:
           # Dispatch R2 explicitly after the Release assets are present.
           # Relying only on workflow_run is not reliable when this workflow
           # itself is dispatched by release-trigger.yml.
+          # channel 必须显式传下去：beta 发布只能写 updates/beta/latest.json，
+          # 绝不能覆盖稳定清单 updates/latest.json。
           gh workflow run upload-r2.yml \
             --repo "$GITHUB_REPOSITORY" \
             --ref main \
-            -f tag="$RELEASE_TAG"
+            -f tag="$RELEASE_TAG" \
+            -f channel="$CHANNEL"
 
           gh workflow run sync-cnb-release-assets.yml \
             --repo "$GITHUB_REPOSITORY" \

diff --git a/.github/workflows/standalone-products.yml b/.github/workflows/standalone-products.yml
@@ -0,0 +1,169 @@
+name: Standalone Products
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to build, for example v0.22.0"
+        required: true
+        type: string
+      platform:
+        description: "Build one matrix label or all"
+        required: true
+        type: choice
+        default: all
+        options:
+          - all
+          - macos-arm64
+          - macos-x64
+          - linux-x64
+          - windows-x64
+      ref:
+        description: "Optional branch or SHA to build instead of the tag"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: standalone-products-${{ inputs.tag }}
+  cancel-in-progress: false
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  prepare:
+    name: Prepare standalone build
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.matrix.outputs.matrix }}
+      version: ${{ steps.matrix.outputs.version }}
+    steps:
+      - name: Validate tag
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Invalid tag: $TAG"
+            exit 1
+          fi
+
+      - name: Build matrix
+        id: matrix
+        env:
+          TAG: ${{ inputs.tag }}
+          PLATFORM: ${{ inputs.platform }}
+        run: |
+          set -euo pipefail
+          version="${TAG#v}"
+          entries=(
+            '{"product":"navop-shell","label":"macos-arm64","os":"macos-latest","target":"aarch64-apple-darwin","app":"Navop Shell.app"}'
+            '{"product":"navop-shell","label":"macos-x64","os":"macos-15-intel","target":"x86_64-apple-darwin","app":"Navop Shell.app"}'
+            '{"product":"navop-shell","label":"linux-x64","os":"ubuntu-latest","target":"x86_64-unknown-linux-gnu","app":""}'
+            '{"product":"navop-shell","label":"windows-x64","os":"windows-latest","target":"x86_64-pc-windows-msvc","app":""}'
+            '{"product":"navop-data","label":"macos-arm64","os":"macos-latest","target":"aarch64-apple-darwin","app":"Navop Data.app"}'
+            '{"product":"navop-data","label":"macos-x64","os":"macos-15-intel","target":"x86_64-apple-darwin","app":"Navop Data.app"}'
+            '{"product":"navop-data","label":"linux-x64","os":"ubuntu-latest","target":"x86_64-unknown-linux-gnu","app":""}'
+            '{"product":"navop-data","label":"windows-x64","os":"windows-latest","target":"x86_64-pc-windows-msvc","app":""}'
+          )
+          selected=()
+          for entry in "${entries[@]}"; do
+            if [ "$PLATFORM" = "all" ] || [[ "$entry" == *"\"label\":\"${PLATFORM}\""* ]]; then
+              selected+=("$entry")
+            fi
+          done
+          if [ "${#selected[@]}" -eq 0 ]; then
+            echo "::error::No matrix entries for platform: $PLATFORM"
+            exit 1
+          fi
+          matrix="{\"include\":[$(IFS=,; echo "${selected[*]}")]}"
+          python3 -c 'import json,sys; json.loads(sys.argv[1])' "$matrix"
+          echo "matrix=$matrix" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build (${{ matrix.product }}, ${{ matrix.label }})
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.prepare.outputs.matrix) }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 180
+    env:
+      ONETCLI_VERSION: ${{ needs.prepare.outputs.version }}
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ inputs.ref || inputs.tag }}
+
+      - name: Setup Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          target: ${{ matrix.target }}
+          cache: false
+
+      - name: Install system dependencies
+        if: runner.os != 'Windows'
+        run: script/bootstrap
+
+      - name: Install Windows build dependencies
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install nasm --no-progress --yes
+          $nasmDir = Join-Path $env:ProgramFiles "NASM"
+          $nasmDir | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+          nasm -v
+
+      - name: Build product
+        run: cargo build --release -p "${{ matrix.product }}" --target "${{ matrix.target }}"
+
+      - name: Package macOS app
+        if: runner.os == 'macOS'
+        run: |
+          set -euo pipefail
+          chmod +x script/bundle-macos.sh script/bundle-macos-dmg.sh
+          script/bundle-macos.sh "${{ matrix.target }}" "${{ matrix.product }}"
+          script/bundle-macos-dmg.sh "${{ matrix.target }}" "${{ matrix.product }}"
+          tar -czf "target/${{ matrix.product }}-${ONETCLI_VERSION}-${{ matrix.target }}.tar.gz" \
+            -C target "${{ matrix.app }}"
+
+      - name: Package Linux tarball
+        if: runner.os == 'Linux'
+        run: |
+          set -euo pipefail
+          script/package-linux-product.sh "${{ matrix.product }}" "${{ matrix.target }}"
+
+      - name: Package Windows installer
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          node script/generate-windows-license.mjs
+          dotnet tool install --global wix --version 6.0.2
+          wix extension add -g WixToolset.UI.wixext/6.0.2
+          wix extension add -g WixToolset.BootstrapperApplications.wixext/6.0.2
+          New-Item -ItemType Directory -Force -Path package | Out-Null
+          Copy-Item "target/${{ matrix.target }}/release/${{ matrix.product }}.exe" "package/${{ matrix.product }}.exe"
+          ./installer/windows/build-product-installer.ps1 `
+            -Product "${{ matrix.product }}" `
+            -Version "$env:ONETCLI_VERSION" `
+            -SourceDir package `
+            -OutDir dist `
+            -Arch x64
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.product }}-${{ matrix.label }}
+          if-no-files-found: error
+          path: |
+            target/*.dmg
+            target/${{ matrix.product }}-${{ matrix.target }}*.tar.gz
+            target/${{ matrix.product }}-*${{ matrix.target }}*.tar.gz
+            dist/*.msi
+            dist/*.exe