REFACTOR: 版本号方案重构 - tag 用纯 SemVer，versionCode 自动用 commit count

根因：Android 升降级只看 versionCode（整数），不看 versionName。
旧方案在 minor 升级时把 +N 重置回 1，导致 v1.0.10+4 (versionCode=4)
之后的 v1.0.11+1 (versionCode=1) 被系统拒绝安装。

改动：
- scripts/lib/build_number.sh: calculate_build_number 用 git rev-list
  --count HEAD，TAG_NAME 改为纯 SemVer (v1.0.11)；parse_tag 兼容
  新旧两种格式
- scripts/release_{android,ios,macos}.sh: tag 正则放宽 +N 可选；
  不带 +N 时 BUILD_NUMBER 兜底用 commit count
- .github/workflows/release.yml: 重写 Parse version step，兼容新旧
  tag 格式，加 versionCode 严格大于历史最大值的校验，保留 pubspec
  一致性校验
- lib/screens/settings_screen.dart: 用户可见版本只显示 versionName，
  不再拼接 +buildNumber
- CLAUDE.md: 加 7.3 Android versionCode 单调递增踩坑记录

Author: echo-loop

.github/workflows/release.yml

@@ -4,15 +4,20 @@ name: Release
 # 同时把 APK 作为 GitHub Release 附件挂出（IPA 不公开）。
 #
 # 触发：
-#   - push tag 形如 v1.0.8+1
+#   - push tag 形如 v1.0.11（推荐，新格式）或 v1.0.8+1（兼容旧格式）
 #   - 或在 Actions 页面手动 dispatch 选 tag
+#
+# 版本号约定：
+#   - tag 用纯 SemVer（v1.0.11），不带 +N
+#   - versionCode 由 CI 自动用 git rev-list --count <tag> 生成，全局单调递增
+#   - 详见 CLAUDE.md "Android versionCode 单调递增" 章节
 on:
   push:
     tags: ['v*']
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Tag to release (e.g. v1.0.8+1)'
+        description: 'Tag to release (e.g. v1.0.11)'
         required: true
 
 env:
@@ -61,23 +66,56 @@ jobs:
         env:
           TAG_REF: ${{ github.event.inputs.tag || github.ref_name }}
         run: |
-          NAME="${TAG_REF#v}"
-          NAME="${NAME%+*}"
-          NUMBER="${TAG_REF##*+}"
-          if [[ "$NAME" == "$TAG_REF" || "$NUMBER" == "$TAG_REF" || -z "$NAME" || -z "$NUMBER" ]]; then
-            echo "ERROR: tag '$TAG_REF' is not in vX.Y.Z+N format" >&2
+          # 兼容新格式 vX.Y.Z 和旧格式 vX.Y.Z+N
+          if [[ "$TAG_REF" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            NAME="${BASH_REMATCH[1]}"
+            # versionCode = 该 tag 指向 commit 的 git rev-list count
+            NUMBER="$(git rev-list --count "$TAG_REF")"
+          elif [[ "$TAG_REF" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)\+([0-9]+)$ ]]; then
+            NAME="${BASH_REMATCH[1]}"
+            NUMBER="${BASH_REMATCH[2]}"
+          else
+            echo "ERROR: tag '$TAG_REF' is not in vX.Y.Z or vX.Y.Z+N format" >&2
+            exit 1
+          fi
+          if [[ -z "$NUMBER" || "$NUMBER" -le 0 ]]; then
+            echo "ERROR: invalid build number ($NUMBER) for tag $TAG_REF" >&2
             exit 1
           fi
+
+          # 校验 versionCode 严格大于所有历史 tag 的 versionCode
+          # 防止人为意外打了倒退的 +N 旧格式 tag
+          git fetch --tags --force
+          MAX_CODE=0
+          for t in $(git tag -l 'v*'); do
+            if [[ "$t" == "$TAG_REF" ]]; then continue; fi
+            if [[ "$t" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)\+([0-9]+)$ ]]; then
+              CODE="${BASH_REMATCH[2]}"
+            elif [[ "$t" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+              CODE="$(git rev-list --count "$t" 2>/dev/null || echo 0)"
+            else
+              continue
+            fi
+            if [[ "$CODE" -gt "$MAX_CODE" ]]; then MAX_CODE="$CODE"; fi
+          done
+          if [[ "$NUMBER" -le "$MAX_CODE" ]]; then
+            echo "ERROR: versionCode $NUMBER must be strictly greater than max existing $MAX_CODE" >&2
+            echo "如需重新构建已发布的 tag，请在最新 commit 上加空 commit 后再打新 tag" >&2
+            exit 1
+          fi
+
+          # 校验 pubspec.yaml 版本号一致
           PUBSPEC_VERSION="$(grep '^version:' pubspec.yaml | awk '{print $2}' | cut -d'+' -f1)"
           if [[ "$NAME" != "$PUBSPEC_VERSION" ]]; then
             echo "ERROR: tag version ($NAME) does not match pubspec.yaml ($PUBSPEC_VERSION)" >&2
             echo "请先升级 pubspec.yaml 的 version 字段，再打 tag。" >&2
             exit 1
           fi
+
           echo "name=$NAME" >> "$GITHUB_OUTPUT"
           echo "number=$NUMBER" >> "$GITHUB_OUTPUT"
           echo "version=${NAME}+${NUMBER}" >> "$GITHUB_OUTPUT"
-          echo "Parsed: name=$NAME number=$NUMBER (pubspec OK)"
+          echo "Parsed: name=$NAME number=$NUMBER (pubspec OK, max existing code=$MAX_CODE)"
 
       # ---------- Android ----------
 

CLAUDE.md

@@ -184,3 +184,16 @@ flutter test integration_test -d macos
 - **规则**：TTS 的 stop 和 speak 之间不能依赖 flutter_tts 内部的完成信号隔离，必须自行管理
 - **相关代码**：`lib/services/tts_service.dart`
 - **修复时间**：2026-04-06
+
+### 7.3 Android versionCode 必须全局单调递增，与 versionName 解耦
+
+- **现象**：已装 1.0.10+4 的设备无法安装 1.0.11+1/+2，系统提示「已存在更高版本」
+- **根因**：Android 升降级**只看 versionCode（整数）**，不看 versionName。Flutter `pubspec.yaml` 的 `+N` 直接映射到 Android versionCode。minor 升级时把 buildNumber 重置回 1，导致 versionCode 倒退（4 → 1）
+- **解法**：
+  - Git tag 改用纯 SemVer 格式 `v1.0.11`（**不带 `+N`**）
+  - versionCode 由 CI 用 `git rev-list --count <tag>` 自动生成，全局单调递增
+  - App 内"关于"页只显示 versionName，buildNumber 不暴露给用户
+  - 同 versionName 内需重新构建时：加空 commit (`git commit --allow-empty`) → commit count +1
+- **规则**：所有平台（Android/iOS/macOS）的发布脚本和 CI workflow 都按"tag = 纯 SemVer，versionCode = commit count"约定走。打 tag 前必须先升级 `pubspec.yaml` 的 version 字段（workflow 会强制校验一致）
+- **相关代码**：`scripts/lib/build_number.sh`、`scripts/release_*.sh`、`.github/workflows/release.yml`、`lib/screens/settings_screen.dart`
+- **修复时间**：2026-05-20

lib/screens/settings_screen.dart

@@ -315,12 +315,9 @@ class _SettingsScreenState extends ConsumerState<SettingsScreen> {
     AppLocalizations l10n,
   ) {
     final packageInfo = ref.watch(packageInfoProvider);
-    final version = packageInfo.version;
-    final buildNumber = packageInfo.buildNumber;
-    // 仅当 buildNumber 是纯数字时显示 +N（空时默认 +1）
-    final buildNumberInt = int.tryParse(buildNumber);
-    final effectiveBuildNumber = buildNumberInt?.toString() ?? '1';
-    final versionDisplay = '$version+$effectiveBuildNumber';
+    // 仅向用户展示 versionName。Android versionCode（commit count）
+    // 是内部递增数字，对用户无意义，不显示。
+    final versionDisplay = packageInfo.version;
     final updateState = ref.watch(appUpdateProvider);
     final isChecking = updateState is AppUpdateChecking;
 

scripts/lib/build_number.sh

@@ -5,9 +5,16 @@
 #       calculate_build_number "1.0.8"
 #
 # 输出变量：
-#   BUILD_NUMBER  - 构建号（数字，首次构建为 1）
-#   TAG_NAME      - 要创建的 tag 名
+#   BUILD_NUMBER  - 构建号（commit count，全局单调递增）
+#   TAG_NAME      - 要创建的 tag 名（纯 SemVer，如 v1.0.11）
 #   SKIP_TAG_CREATION - 是否跳过 tag 创建（当前 commit 已有同版本 tag）
+#
+# 设计原则：
+# - Android versionCode 必须单调递增。跨 versionName 重置 +N 会导致
+#   旧版本（如 v1.0.10+4）已被 Android 记下 versionCode=4，新版本
+#   v1.0.11+1 的 versionCode=1 反而被系统拒绝安装。
+# - 改用 commit count 作为 versionCode：每次 commit 自动 +1，永不倒退。
+# - tag 只用纯 SemVer 形式（v1.0.11），用户和系统通过 versionName 识别版本。
 
 # 从 pubspec.yaml 读取版本号（不含构建号）
 get_build_name() {
@@ -21,39 +28,21 @@ get_build_name() {
 }
 
 # 计算构建号
-# 参数：BUILD_NAME - 版本号（如 1.0.8）
+# 参数：BUILD_NAME - 版本号（如 1.0.11）
 # 输出：设置 BUILD_NUMBER, TAG_NAME, SKIP_TAG_CREATION 变量
 calculate_build_number() {
   local BUILD_NAME="$1"
   BUILD_NUMBER=""
-  TAG_NAME=""
+  TAG_NAME="v${BUILD_NAME}"   # 纯 SemVer，不带 +N
   SKIP_TAG_CREATION=0
 
-  # 1. 检查当前 commit 是否已有同版本 tag（格式：v版本号+构建号）
-  local EXISTING_TAG="$(git tag --points-at HEAD | grep -E "^v${BUILD_NAME}[+][0-9]+$" || true)"
-  if [[ -n "$EXISTING_TAG" ]]; then
-    # 提取构建号
-    BUILD_NUMBER="${EXISTING_TAG##*+}"
-    SKIP_TAG_CREATION=1
-    TAG_NAME="$EXISTING_TAG"
-    return 0
-  fi
-
-  # 2. 获取同版本号的最大构建号
-  local MAX_BUILD="$(git tag -l "v${BUILD_NAME}+*" | grep -Eo '[+][0-9]+$' | grep -Eo '[0-9]+' | sort -n | tail -1 || true)"
+  # versionCode 全局单调递增：直接用 commit count
+  BUILD_NUMBER="$(git rev-list --count HEAD)"
 
-  # 3. 计算新构建号和 tag 名（统一格式：v版本号+构建号）
-  # 构建号从 1 开始（Android versionCode 必须是正整数）
-  if [[ -n "$MAX_BUILD" ]]; then
-    # 有 +N tag，构建号递增
-    BUILD_NUMBER=$((MAX_BUILD + 1))
-  else
-    # 无任何同版本 tag，第一次构建
-    BUILD_NUMBER="1"
+  # 当前 commit 已有同 tag → 跳过 tag 创建
+  if git tag --points-at HEAD | grep -qx "$TAG_NAME"; then
+    SKIP_TAG_CREATION=1
   fi
-  TAG_NAME="v${BUILD_NAME}+${BUILD_NUMBER}"
-
-  SKIP_TAG_CREATION=0
 }
 
 # 创建 tag（用于 CI 成功后）
@@ -69,17 +58,21 @@ create_build_tag() {
 }
 
 # 从 tag 提取版本号和构建号
+# 支持两种格式：
+#   v1.0.11      新格式 → BUILD_NUMBER 用 git rev-list --count <tag> 算
+#   v1.0.11+5    旧格式 → BUILD_NUMBER=5（兼容历史 tag 回放）
 parse_tag() {
   local TAG="$1"
-  # v1.0.8+1 → 提取 1.0.8 和构建号
   local build_name="${TAG#v}"
   build_name="${build_name%+*}"
-  # 使用参数展开提取构建号（更可靠）
-  local build_number="1"  # 默认为 1（对应无 +N 的旧 tag）
+  local build_number=""
   if [[ "$TAG" == *+* ]]; then
+    # 旧格式：直接取 +N
     build_number="${TAG##*+}"
+  else
+    # 新格式：用 commit count（基于 tag 指向的 commit，不是 HEAD）
+    build_number="$(git rev-list --count "$TAG" 2>/dev/null || echo "")"
   fi
-  # 输出供 eval 解析
   echo "BUILD_NAME=${build_name}"
   echo "BUILD_NUMBER=${build_number}"
-}
+}

scripts/release_android.sh

@@ -95,11 +95,16 @@ fi
 
 # 如果参数和环境变量都没提供，尝试从当前 commit 的 tag 或现有 APK 解析
 if [[ -z "$BUILD_NAME" && -z "$BUILD_NUMBER" ]]; then
-  # 先尝试 tag
-  TAG="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+[+][0-9]+$' | head -1 || true)"
+  # 先尝试 tag（兼容新格式 vX.Y.Z 和旧格式 vX.Y.Z+N）
+  TAG="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+([+][0-9]+)?$' | head -1 || true)"
   if [[ -n "$TAG" ]]; then
     log "Using tag: $TAG"
     eval "$(parse_tag "$TAG")"
+    # 新格式 tag 不带 +N，BUILD_NUMBER 兜底用 commit count
+    if [[ -z "$BUILD_NUMBER" ]]; then
+      BUILD_NUMBER="$(git rev-list --count HEAD)"
+      log "BUILD_NUMBER from commit count: $BUILD_NUMBER"
+    fi
   elif [[ "$SKIP_BUILD" == true ]]; then
     # --skip-build 时从现有 APK 文件名推断
     APK_PATTERN="build/release/Echo-Loop-*-arm64.apk"

scripts/release_ios.sh

@@ -130,12 +130,18 @@ fi
 
 # 如果参数和环境变量都没提供，从当前 commit 的 tag 解析
 if [[ -z "$BUILD_NAME" || -z "$BUILD_NUMBER" ]]; then
-  TAG="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+[+][0-9]+$' | head -1 || true)"
+  # 兼容新格式 vX.Y.Z 和旧格式 vX.Y.Z+N
+  TAG="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+([+][0-9]+)?$' | head -1 || true)"
   if [[ -z "$TAG" ]]; then
     fail "No version tag on current commit. Run ci.sh first, or provide --build-name and --build-number."
   fi
   log "Using tag: $TAG"
   eval "$(parse_tag "$TAG")"
+  # 新格式 tag 不带 +N，BUILD_NUMBER 兜底用 commit count
+  if [[ -z "$BUILD_NUMBER" ]]; then
+    BUILD_NUMBER="$(git rev-list --count HEAD)"
+    log "BUILD_NUMBER from commit count: $BUILD_NUMBER"
+  fi
 fi
 
 log "Using build name: $BUILD_NAME"

scripts/release_macos.sh

@@ -55,12 +55,18 @@ fi
 
 # 如果参数和环境变量都没提供，从当前 commit 的 tag 解析
 if [[ -z "$BUILD_NAME" || -z "$BUILD_NUMBER" ]]; then
-  TAG="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+[+][0-9]+$' | head -1 || true)"
+  # 兼容新格式 vX.Y.Z 和旧格式 vX.Y.Z+N
+  TAG="$(git tag --points-at HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+([+][0-9]+)?$' | head -1 || true)"
   if [[ -z "$TAG" ]]; then
     fail "No version tag on current commit. Run ci.sh first, or provide --build-name and --build-number."
   fi
   log "Using tag: $TAG"
   eval "$(parse_tag "$TAG")"
+  # 新格式 tag 不带 +N，BUILD_NUMBER 兜底用 commit count
+  if [[ -z "$BUILD_NUMBER" ]]; then
+    BUILD_NUMBER="$(git rev-list --count HEAD)"
+    log "BUILD_NUMBER from commit count: $BUILD_NUMBER"
+  fi
 fi
 
 # 安装包名字统一包含构建号

test/screens/settings_screen_test.dart

@@ -98,7 +98,7 @@ void main() {
         expect(find.text('Terms of Service'), findsOneWidget);
         expect(find.text('Privacy Policy'), findsOneWidget);
         expect(find.text('Write Feedback'), findsOneWidget);
-        expect(find.text('Version 1.0.0+1 (Debug)'), findsOneWidget);
+        expect(find.text('Version 1.0.0 (Debug)'), findsOneWidget);
       });
 
       testWidgets('显示外观标题', (tester) async {