bump-version 默认不提交，改为 --commit 显式提交

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

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

- 同步 AGC 更新技术方案文档的用法示例与说明

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 包条目',
 ]);

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`）**