| name | git-smart-batch-commit |
| description | 掃描 repo 中所有已變動的檔案，依照功能/類別自動分組，為每個分組產生詳細的 commit message（支援語言參數，預設英文）。產出後強制暫停等待使用者確認，使用者確認指定批次後才依序執行 git add + commit，絕對嚴格禁止自動 push。 |
| version | 1.1.0 |
| last_updated | "2026-05-01T00:00:00.000Z" |
| effective_date | "2026-05-01T00:00:00.000Z" |
Git Smart Batch Commit
路徑基準
本文件中提到的 templates/、scripts/、skills/，皆以目前語系內容根目錄為相對基準（例如 zh-TW/），不綁定 repo 根目錄固定路徑。
目的
當同一個 repo 一次混入了多個不同功能的修改，自動將變動檔案依類別分組，為每組產生獨立、詳細的 commit message（語言由參數決定，預設英文），並在使用者明確確認後才逐批執行 git add + commit。
快速使用範例
-
觸發（無參數）：$git-smart-batch-commit
-
觸發（含路徑）：$git-smart-batch-commit /path/to/repo
-
觸發（含路徑 + 語言）：$git-smart-batch-commit /path/to/repo zh
-
觸發（全域，僅語言）：$git-smart-batch-commit . 中文
-
語言切換（關鍵字方式）：若需求中包含 中文commit、zh、tw commit，亦可觸發語言切換（優先級低於明確參數）。
-
AI 產出分組與 commit message 後：強制暫停，等待使用者確認。
-
使用者確認後輸入例如：
現在我同意你，依序依照批次，git add and git commit，先完成 1 and 2
AI 才依序執行指定的批次。
觸發語意
- 啟用 skill 後，立即進入「掃描 → 分組 → 產生 commit message → 強制暫停」流程。
- 若使用者有提供路徑：僅掃描該路徑範圍內的變動；否則從 repo 根目錄掃描。
- commit message 語言：可透過參數指定（例如
zh、en、日文），若未指定且無關鍵字則預設英文。
- 分組完成並產出 commit message 後：絕對必須停下等待使用者確認，嚴禁自動執行任何 git 操作。
語言參數對應表
明確語言參數優先級高於關鍵字偵測，支援以下輸入形式：
| 輸入值（不分大小寫） | 對應語言 | 說明 |
|---|
zh、zh-tw、tw、中文、繁體中文、chinese | 繁體中文（台灣用語） | |
zh-cn、cn、简体中文、簡體中文 | 簡體中文 | |
en、english、英文、英語 | 英文 | 預設值 |
jp、ja、japanese、日文、日語、日本語 | 日文 | |
ko、korean、韓文、韓語 | 韓文 | |
| 其他未知值 | 視為英文（預設） | 並輸出警告提示 |
語言優先級順序（由高到低）：
- 明確語言參數
- 訊息中的關鍵字偵測（
中文commit、zh、tw commit 等）
- 預設英文
必做步驟
階段一：掃描與分組（自動執行）
-
執行 git status --porcelain（限定於指定路徑範圍，若無指定則為 repo 根目錄），取得所有已變動的檔案清單。
-
對每一個變動檔案，執行 git diff HEAD -- <file> 或 git diff --cached -- <file>（視檔案狀態而定），讀取實際修改內容（diff）。
-
依照修改內容與路徑語意，將所有檔案分組，分組原則如下：
- 盡可能細拆：同一功能點的修改歸一組，避免多個不相關功能混入同一批次。
- 分組依據（參考順序）：
- 功能語意（例如：auth 流程、UI 元件、API 邏輯、資料庫 schema、CI/CD 設定）
- 路徑結構（例如：
src/auth/、src/ui/、.github/）
- 修改目的（例如：bugfix、refactor、feat、chore、docs）
- 若某個檔案難以歸類，單獨列為一組並標註
[需確認]。
-
輸出分組結果，格式如下：
=== 變動檔案分組結果 ===
【批次 1】<功能簡述>
- path/to/file1.ts
- path/to/file2.ts
【批次 2】<功能簡述>
- path/to/file3.ts
...（依此類推）
階段二：產生 commit message（自動執行）
-
針對每個批次，依照批次內檔案的實際 diff 內容，產生一段詳細且完整的 commit message（語言依上述語言參數與優先級決定）。
-
commit message 格式必須遵循 Conventional Commits：
<type>(<scope>): <subject>
<body>
<footer>
type：feat、fix、refactor、chore、docs、test、style、ci 等body：至少包含主要修改目的、重要行為變更、涉及檔案與影響面footer：若已知對應 task 文件，必須標註 task 檔名；若未知則省略
-
輸出所有批次的 commit message，格式如下：
=== Commit Message 草稿 ===
【批次 1】
feat(auth): implement token refresh logic
- Add automatic token refresh in AuthService
- Handle 401 responses globally in HTTP interceptor
- Affected files: src/auth/auth.service.ts, src/interceptors/http.interceptor.ts
Task: [plan-XXXXX]-auth-token-refresh.md
---
【批次 2】
...
階段三：強制暫停（必須遵守）
-
輸出完所有分組與 commit message 後，必須立即停止，絕對不可自動執行任何 git 操作。
-
輸出以下等待確認提示：
✅ 已完成分組與 commit message 草稿。
請確認以上內容是否正確：
- 如需調整分組或 commit message，請告知。
- 若確認無誤，請告訴我要執行哪些批次，例如：
「現在我同意你，依序依照批次，git add and git commit，先完成 1 and 2」
⚠️ 在收到你的明確確認前，我不會執行任何 git 操作。
階段四：依序執行（使用者確認後才執行）
-
收到使用者確認訊息後，只執行使用者明確指定的批次編號，其餘批次繼續等待。
-
對每個指定批次，依序執行：
-
每個批次 commit 完成後，立即回報結果，格式如下：
✅ 批次 1 已完成 commit。
Commit hash: <hash>
Files committed: file1.ts, file2.ts
-
全部指定批次完成後，若仍有未執行的批次，提示使用者：
⏸ 批次 3、4 尚未執行，請告訴我是否繼續。
禁止事項
⛔ 以下規則為最高優先級，任何情況下均不得違反。
- 永遠嚴格禁止執行
git push，無論使用者是否要求，無論任何理由，絕無例外。
- 禁止在使用者明確確認前，執行任何
git add 或 git commit。
- 禁止使用
git add .、git add -A、git add --all，必須逐一列出檔案路徑。
- 禁止將不同批次的檔案混在同一個 commit 中。
- 禁止跳過「強制暫停等待確認」步驟，即使使用者沒有明確要求暫停也必須暫停。
- 若 staged 結果中出現非該批次的檔案，必須立即中止並告知使用者，等待指示。
- 禁止在同一次指令中連續執行多個批次（除非使用者在同一則確認訊息中明確指定多個批次）。
