From f7a0adc6165584a456b4f5f0d6e12b80b4263c29 Mon Sep 17 00:00:00 2001
From: Suzumiya <suzmii@qq.com>
Date: Mon, 7 Sep 2026 13:38:17 +0800
Subject: [PATCH] =?UTF-8?q?bump-version=20=E9=BB=98=E8=AE=A4=E4=B8=8D?=
 =?UTF-8?q?=E6=8F=90=E4=BA=A4=EF=BC=8C=E6=94=B9=E4=B8=BA=20--commit=20?=
 =?UTF-8?q?=E6=98=BE=E5=BC=8F=E6=8F=90=E4=BA=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- bump-version.mjs 默认只写入版本文件、不创建提交；需要提交时加 --commit

- 增加保护：若工作区已带着一次未提交的提升，再 --commit 不会重复递增，直接提交现有改动

- 同步 AGC 更新技术方案文档的用法示例与说明
---
 .../scripts/bump-version.mjs                  | 26 ++++++++++++++-----
 ...��方案】AGC客户端更新检查与下载-2026-08-31.md | 14 +++++++---
 2 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/apps/ai-game-creator-shell/scripts/bump-version.mjs b/apps/ai-game-creator-shell/scripts/bump-version.mjs
index 33205b4f3..3911ce972 100644
--- a/apps/ai-game-creator-shell/scripts/bump-version.mjs
+++ b/apps/ai-game-creator-shell/scripts/bump-version.mjs
@@ -27,7 +27,7 @@ function parseArgs(argv) {
     explicit ??
     args.find((arg) => arg === 'patch' || arg === 'minor' || arg === 'major') ??
     'patch';
-  return { target, noCommit: args.includes('--no-commit') };
+  return { target, commit: args.includes('--commit') };
 }
 
 function runGit(args) {
@@ -36,14 +36,28 @@ function runGit(args) {
   return result.status ?? 1;
 }
 
-const { target, noCommit } = parseArgs(process.argv);
+function hasUncommittedVersionChanges() {
+  return (
+    spawnSync('git', ['diff', '--quiet', '--', ...versionFiles], {
+      cwd: repoRoot,
+    }).status === 1
+  );
+}
+
+const { target, commit } = parseArgs(process.argv);
 const current = readLocalVersion();
-const next = bumpVersion(current, target);
+
+// 若版本文件已带着一次未提交的提升（例如先默认跑过一次），再 --commit 时不再重复递增，直接提交现有改动。
+const next =
+  commit && hasUncommittedVersionChanges()
+    ? current
+    : bumpVersion(current, target);
+
 writeVersionFiles(next);
 
-if (noCommit) {
+if (!commit) {
   console.log(
-    `[bump-version] 版本 ${current} -> ${next}（已写入版本文件，未创建提交，可用 git diff 复核；去掉 --no-commit 即提交）`,
+    `[bump-version] 版本 ${current} -> ${next}（已写入版本文件，未创建提交；如需提交加 --commit）`,
   );
   process.exit(0);
 }
@@ -66,7 +80,7 @@ const commitStatus = runGit([
   '-m',
   `提升 AGC 版本至 ${next}`,
   '-m',
-  `- AGC 客户端版本由 ${current} 提升至 ${next}`,
+  `- AGC 客户端版本提升至 ${next}`,
   '-m',
   '- 同步更新 package.json、根 package-lock.json、tauri.conf.json、Cargo.toml、Cargo.lock 中的 AGC 包条目',
 ]);
diff --git a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
index 73de52a2f..4d6fa256a 100644
--- a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
+++ b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
@@ -36,22 +36,30 @@ AGC 每次启动时由根窗口检查一次公开 OSS 更新清单。清单默
 **发布前先提升版本（开发者执行）**
 
 执行以下任一命令，会把 AGC 版本写入 `package.json`、根 `package-lock.json`、
-`tauri.conf.json`、`Cargo.toml`、`Cargo.lock` 五处并**本地提交**（不会推送）：
+`tauri.conf.json`、`Cargo.toml`、`Cargo.lock` 五处。**默认只写入版本文件、不会创建提交**；
+需要创建提交时在命令末尾加 `--commit`（只做本地提交，push 由开发者自行确认）：
 
 ```bash
-# 提升一个 patch（默认），例如 0.1.19 -> 0.1.20
+# 提升一个 patch（默认），只写入版本文件，例如 0.1.19 -> 0.1.20
 npm run ai-game-creator-shell:bump-version
 npm run ai-game-creator-shell:bump-version -- patch
 
+# 提升版本并本地提交
+npm run ai-game-creator-shell:bump-version -- --commit
+
 # 提升 minor / major
 npm run ai-game-creator-shell:bump-version -- minor
 npm run ai-game-creator-shell:bump-version -- major
 
 # 指定明确的三段版本（一般只用于复现/回填）
 npm run ai-game-creator-shell:bump-version -- --version 0.1.25
+
+# 指定版本并提交
+npm run ai-game-creator-shell:bump-version -- --version 0.1.25 --commit
 ```
 
-提交标题固定为“提升 AGC 版本至 x.y.z”。只做本地提交，push 由开发者自行确认。
+若先用默认方式写入版本（未提交），再补 `--commit`，命令会识别到工作区已提升、直接提交现有改动，
+**不会重复递增**。提交标题固定为“提升 AGC 版本至 x.y.z”。
 
 **发布只读仓库版本（`npm run ai-game-creator-shell:build` 与 `release:upload`）**