今天要做什麼外掛（Plugins）

1. 名稱：antigravity-git-flow
2. GitHub：https://github.com/AndyAWD/antigravity-git-flow

為什麼要做這個外掛（Plugins）

原本只打算做 Git 提交，但做完後發現只有提交不夠方便，還缺少推送，然後推送前還要檢查有沒有開分支等 GitFlow 的基本功能，再來是建立 PR，還有 GitHub 的 Release，所以就從一個提交功能，變成有推送、合併、建立 Release 分支、發PR、建立 GitHub Release、打 Tag、專案 Git 初始化等功能

全部都做完後我想到，既然基本功能都有了，能不能做一個 Auto 的功能，讓 AI 自動判斷目前要執行什麼指令呢，這樣不會 Git 的人只要一直無腦 Auto 就好，就跟現在用 AI 的方法一樣，所以這個 Plugins

這個外掛做的過程

1. 踩坑：竄改 Git Author 導致貢獻圖表（小綠點）消失事件！

在最一開始的原型版本（Commit 45f4abe）中，我寫了一支名為 commit.js 的腳本。當時的想法非常直觀：「既然提交都是 AI 代理（Agent）幫忙完成的，那版本控制作者（Git Author）理所當然要登記為 Google Antigravity！」於是我在腳本中覆寫了環境變數：

// 早期踩坑程式碼（Commit 45f4abe）：
execFileSync('git', ['commit', '-m', msg], {
  stdio: 'inherit',
  env: {
    ...process.env,
    GIT_AUTHOR_NAME: 'Google Antigravity',
    GIT_AUTHOR_EMAIL: 'google-antigravity@users.noreply.github.com',
    GIT_COMMITTER_NAME: 'Google Antigravity',
    GIT_COMMITTER_EMAIL: 'google-antigravity@users.noreply.github.com',
  },
});

程式碼一推送到 GitHub 後，慘劇立刻發生：

• 貢獻圖表（小綠點）完全蒸發：GitHub 的個人貢獻圖表（Contribution Graph）是依據提交者的電子郵件信箱綁定計算的。當作者與提交者全都被置換成虛構帳號，我自己在 GitHub 上的個人連續提交紀錄直接被「沒收」！
• 信箱前綴引發的連續踩坑：在 Commit 9b46b7a 中，我一開始以為是信箱缺少了 GitHub 專屬的使用者識別碼前綴，便將其修改為 242056456+google-antigravity@users.noreply.github.com。但測試後發現，只要作者身分不是我本人，圖表依然不會亮起小綠點！

直到 Commit a0677d1，我徹底重構了提交架構：使用者的 Git Author 身分絕對不能被竄改。提交的所有權必須百分之百屬於開發者本人；取而代之的標準解法，是在提交訊息的結尾自動加入共同作者標籤：

Co-authored-by: Google Antigravity <242056456+google-antigravity@users.noreply.github.com>

隨後在 Commit f6a8cec 中，我進一步在腳本中加入 msg.includes('Co-authored-by: Google Antigravity') 檢查，具備等冪性（Idempotence）防止重複簽名。如此一來，既能讓 GitHub 正確呈現雙作者協作頭像，也完全捍衛了開發者本人的貢獻紀錄！

2. 踩坑：終端機提示字元凍結與背景 Fetch 逾時防禦機制

在團隊協作或多裝置切換情境下，若本地未先抓取遠端進度，直接合併或推播容易引發非快進（Non-fast-forward）衝突。

在 Commit db26732 中，我全面為涉及遠端操作的技能加入背景遠端抓取（git fetch）。但在後續測試中發現了新的系統陷阱：當使用者尚未設定好安全外殼協定（Secure Shell Protocol，SSH）金鑰或權杖過期時，終端機底層會彈出密碼輸入提示字元（Prompt），導致整個 AI 代理無止境地卡死等待！

為此，在 Commit f6a8cec 中，我在 analyze.js 補齊了雙層防禦措施：

1. 注入環境變數 GIT_TERMINAL_PROMPT: '0'：強制關閉終端機互動式帳密輸入提示，遭遇憑證問題時立即失敗返回，避免背景行程凍結。
2. 10 秒逾時中斷防護：加入 { timeout: 10000 } 設定，若網路延遲或中斷，逾時後立即釋放執行緒並回報狀態。

3. 踩坑：防敏審查與主分支功能分支阻擋機制

自動化版本控制最讓人擔心的，就是 AI 不小心把密鑰或本地設定檔送入版本庫：

• 未追蹤檔案防敏審查：在 Commit c63f647 中，提交技能在執行 git add -A 之前，強制插入第二步驟：執行 git ls-files --others --exclude-standard 檢查是否有未追蹤檔案。一旦偵測到新檔案，立即透過 ask_question 工具跳出安全確認對話框，避免 .env 等敏感檔案被無意間提交。
• 嚴格主分支隔離：在 branch-guard.js 中嚴格貫徹 Git Flow 哲學。若開發者位於 main 主分支且 develop 分支已存在，試圖建立 feature 功能分支時，腳本會立即以狀態代碼 2 阻擋中斷，防止破壞雙軌主幹架構。

5. 四個關鍵演進階段

回顧專案的 39 筆 Git 歷史紀錄，外掛架構經歷了四個清楚的演變階段：

1. 初始原型階段（Commit 45f4abe ~ 5b9f069）：
   專案最初命名為 conventional-commits-agy，僅具備基礎的慣例式提交與工作區多任務自動拆分腳本。
2. 擴展為 Git Flow 核心（Commit 7001e3e ~ 860909b）：
   意識到僅有提交無法滿足日常開發，正式更名為 git-flow-agy，並實作 merge、pr 與 push 三大流程技能。
3. 功能大滿貫與自動模式（Commit fd8c33f ~ 3b8ee61）：
   陸續補齊專案初始化（init）、語意化發布準備（release）、版本標籤（tag）與雙語發布說明（github-release），最終淬鍊出專為新手打造的智慧導航管家 auto-next。
4. 命名空間標準化與生態系整合（Commit c7528e9 ~ 78ab47f）：
   專案正式定名為 antigravity-git-flow（標記 v1.0.0 標籤），並將所有 9 大技能全面納入 antigravity-git-flow:git-flow:* 專屬命名空間，徹底杜絕指令碰撞問題。

目錄結構

一個符合 Google Antigravity 生態系標準的外掛程式結構清晰分明：

antigravity-git-flow/
├── plugin.json                    # 外掛程式資訊清單（外掛名稱、版本與說明）
├── package.json                   # Node.js 模組設定檔（宣告 ES 模組規範）
├── LICENSE                        # MIT 開源授權條款
├── README.md                      # 完整繁體中文說明文件
└── skills/                        # 核心技能目錄（共 9 大 Git Flow 技能）
    ├── auto-next/
    │   └── SKILL.md               # 智慧導航管家技能（六階段自動推導流程）
    ├── commit/
    │   ├── SKILL.md               # 慣例式提交技能（8 個標準操作步驟與安全審查規範）
    │   └── scripts/
    │       ├── analyze.js         # 工作區狀態與差異分析腳本（背景自動 fetch 與逾時防護）
    │       ├── branch-guard.js    # 主分支保護與分支切換腳本（Git Flow 守門員）
    │       └── commit.js          # 自動附加共同作者簽名與提交腳本
    ├── init/
    │   └── SKILL.md               # 專案初始化技能（建立 main 與 develop 雙軌架構）
    ├── push/
    │   └── SKILL.md               # 遠端推播技能（防呆落後檢查與標籤同步）
    ├── merge/
    │   └── SKILL.md               # 分支合併技能（支援 feature 至 develop，以及 release/hotfix 雙向合併）
    ├── github-pr/
    │   └── SKILL.md               # 拉取請求技能（限定 release/hotfix 發起並自動撰寫繁中 PR）
    ├── release/
    │   └── SKILL.md               # 發布準備技能（從 develop 切出分支並跨平台智慧更新版號）
    ├── tag/
    │   └── SKILL.md               # 自動標記技能（SemVer 2.0.0 分析與打 Tag）
    └── github-release/
        └── SKILL.md               # GitHub 發布技能（自動產生中英雙語 Changelog）

關鍵檔案解析

1. 外掛資訊清單：plugin.json

外掛的身分證明文件，定義了套件名稱、版本與職責：

{
  "name": "antigravity-git-flow",
  "version": "0.1.0",
  "description": "Antigravity plugin for generating Conventional Commits with Git Flow branching."
}

2. 分支守門員腳本：skills/commit/scripts/branch-guard.js

嚴格貫徹 Git Flow 雙軌主幹保護策略。若在 main 上偵測到 hotfix 需求，會引導建立修復分支；若開發者企圖直接在 main 上建立功能分支且 develop 已存在時，會主動阻擋以防止破壞分支拓撲：

if (cur === 'main' || cur === 'master') {
  if (kind === 'hotfix') {
    if (!branchExists('develop')) {
      create('develop');
      gitLoud(['checkout', cur]);
    }
    create(`hotfix/${name}`);
  } else {
    if (branchExists('develop')) {
      console.error(`ERROR: 目前在 ${cur}，但 develop 分支已存在。`);
      console.error('可能在錯誤分支 — 請先手動切到 develop 或適當分支後重試。');
      process.exit(2);
    }
    create('develop');
    create(`feature/${name}`);
  }
}

3. 共同作者簽署腳本：skills/commit/scripts/commit.js

保留使用者原本的 Git Author 身分，並於提交訊息結尾精準補上共同作者簽名，同時避免重複簽署：

const coAuthorSignature = 'Co-authored-by: Google Antigravity <242056456+google-antigravity@users.noreply.github.com>';
const fullMsg = msg.includes('Co-authored-by: Google Antigravity')
  ? msg
  : `${msg}\n\n${coAuthorSignature}`;

try {
  execFileSync('git', ['commit', '-m', fullMsg], {
    stdio: 'inherit',
  });
} catch (e) {
  process.exit(e.status || 1);
}

這外掛怎麼用

本外掛程式相容於 Antigravity 命令列介面（Command Line Interface，CLI）（agy）、整合開發環境（Integrated Development Environment，IDE）以及 Antigravity 2.0 桌面應用程式，提供從儲存庫初始化、分支提交、發布準備到正式標籤釋出的完整生命週期。

安裝方式

你可以依照習慣與團隊需求選擇以下三種安裝途徑：

方式 1：GitHub 遠端一鍵安裝（最推薦，全平台通用）

開啟終端機，直接輸入以下指令即可由 Agy CLI 自動完成下載與註冊：

agy plugin install https://github.com/AndyAWD/antigravity-git-flow

方式 2：本機開發模式安裝

若你複製（clone）了原始碼至本地，想自行客製化規則或除錯：

# 在專案目錄下執行：
agy plugin install .

# 或是指定本地絕對路徑：
agy plugin install /path/to/antigravity-git-flow

方式 3：專案工作區共享（團隊共用）

若希望將外掛跟著特定專案的版本控制系統（Version Control System，VCS）一同分享給團隊成員，直接將外掛資料夾放置於專案根目錄的 .agents/plugins/ 底下即可：

你的專案/
└── .agents/
    └── plugins/
        └── antigravity-git-flow/
            ├── plugin.json
            ├── package.json
            └── skills/

外掛生命週期管理

安裝完成後，可透過 Agy CLI 隨時管理外掛狀態：

# 查看目前已安裝外掛
agy plugin list

# 暫時停用外掛
agy plugin disable antigravity-git-flow

# 重新啟用外掛
agy plugin enable antigravity-git-flow

# 移除外掛
agy plugin uninstall antigravity-git-flow

在 Antigravity 2.0 桌面端中，亦可在左側面板的「Settings > Plugins」直接透過圖形化開關進行啟閉。

完整使用生命週期與實戰情境

情境 1：全新專案一鍵搭建雙軌架構（/init）

對於剛建立的新專案，呼叫初始化技能，外掛會自動建立 Git 儲存庫、起始提交，並搭建標準的 main 與 develop 雙軌架構：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:init
────────────────────────────────────────────────
正在檢查儲存庫狀態...
偵測到全新專案，執行 git init...
建立起始提交：chore: 初始化專案
建立雙軌分支：
✓ main 分支就緒
✓ 切換並建立 develop 分支
專案已成功初始化為 Git Flow 架構，已就緒於 develop 分支！
────────────────────────────────────────────────

情境 2：全自動智慧導航管家（/auto-next）

專為不熟悉 Git 或不知道下一步該做什麼的使用者設計，AI 會依序檢查六大階段（遠端更新、基礎建設、工作保護、遠端同步、流程推進、迷航求助）：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:auto-next
────────────────────────────────────────────────
[Auto Next] 正在分析專案狀態...
在背景執行遠端同步檢查（git fetch）...
發現工作區有 2 個已修改的檔案，先幫您把目前的進度妥善存檔！
自動觸發慣例式提交流程...
────────────────────────────────────────────────

若專案處於健康且完全同步的狀態，則會主動彈出迷航求助選單：

────────────────────────────────────────────────
? 目前的專案狀態很健康，都已經妥善儲存囉！接下來您想做什麼呢？
  ▸ (Recommended) 開發新功能（建立 feature 分支）
    準備發布新版本（執行 release 技能）
    修復緊急 Bug（建立 hotfix 分支）
    從雲端更新程式碼（執行 git pull）
────────────────────────────────────────────────

情境 3：敏感檔案攔截、分支防呆與慣例式提交（/commit）

完成開發階段後呼叫提交技能。若工作區包含新檔案，首先進入防敏審查；若停留在 main 主分支，則會主動跳出分支確認對話框：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:commit
────────────────────────────────────────────────
[步驟 1] 分支檢查：目前位於 main 分支。
? 目前在 main 分支，請問您要建立 hotfix 還是 feature 分支？
  ▸ (Recommended) 我要建立 feature 分支
    我要建立 hotfix 分支
    取消目前操作

[步驟 2] 未追蹤檔案安全檢查：
發現 1 個未追蹤檔案：config/secret.json
? 偵測到新的未追蹤檔案，請確認安全性：
    (Recommended) 這些檔案都安全，全部加入
  ▸ 裡面有敏感檔案，我要加入 .gitignore
    這次先不提交這些新檔案
────────────────────────────────────────────────

確認安全並切出分支後，腳本會自動分析變更並聰明拆分為多個獨立提交：

────────────────────────────────────────────────
從 develop 建立並切換至 feature/payment-gateway...
分析工作區變更：偵測到 2 項獨立任務，自動拆分提交：

[1/2] 提交支付核心模組
[feature/payment-gateway a1b2c3d] feat(payment): 實作第三方金流串接介面
 2 files changed, 84 insertions(+)
 create mode 100644 src/payment.ts

[2/2] 提交設定檔變更
[feature/payment-gateway e4f5g6h] chore(config): 更新環境變數設定檔範本
 1 file changed, 4 insertions(+)

已完成所有變更之慣例式提交，末端已簽署共同作者。
────────────────────────────────────────────────

產生的提交紀錄將完整保留共同作者資訊：

feat(payment): 實作第三方金流串接介面

Co-authored-by: Google Antigravity <242056456+google-antigravity@users.noreply.github.com>

情境 4：開啟發布分支與跨平台版號更新（/release）

當功能在 develop 分支累積到一個段落，準備進入發布前測試時，執行發布準備技能。AI 會自動推算版號、切出發布分支，並自動搜尋專案中的版號定義檔進行更新：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:release
────────────────────────────────────────────────
目前位於 develop 分支，同步最新進度...
分析未發布變更歷史，推算下一個合理的語意化版本：v1.2.0
建立並切換至發布分支：release/v1.2.0
執行跨平台版號智慧更新：
✓ 偵測到 package.json，自動更新 version 至 1.2.0
自動建立版號升級提交：
[release/v1.2.0 9a8b7c6] chore(release): bump version to v1.2.0
發布分支準備完畢，可在此分支進行最後測試與微調！
────────────────────────────────────────────────

情境 5：嚴格限制分支之拉取請求（/github-pr）

在 Git Flow 規範下，為確保生產環境穩定，拉取請求（Pull Request，PR）嚴格限制僅能由 release/* 或 hotfix/* 分支向 main 主分支發起：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:github-pr
────────────────────────────────────────────────
正在比對 origin/main..HEAD 之提交歷史...
自動產生繁體中文 Pull Request 內容：
- 標題：release: 發布 v1.2.0 版本
- 描述：彙整金流模組整合、更新環境變數範本並修復已知異常。

正在透過 GitHub CLI 建立 Pull Request 至 main...
✓ https://github.com/AndyAWD/antigravity-git-flow/pull/3
────────────────────────────────────────────────

情境 6：標準 Git Flow 雙軌合併與分支清理（/merge）

當功能或修復開發完畢，執行合併技能。Git Flow 會依據分支類型自動判定目標分支：

• feature/* 合併至 develop（帶有 --no-ff 保留節點）。
• release/* 或 hotfix/* 則會引導合併至 main 並同步回 develop。

合併完成後，會跳出多選選單詢問是否刪除分支以維持儲存庫整潔：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:merge
────────────────────────────────────────────────
切換至 develop 分支並同步遠端進度...
執行非快進（--no-ff）合併：git merge --no-ff feature/payment-gateway
Merge made by the 'ort' strategy.

? 合併已順利完成！請問您是否要刪除剛才合併的原始分支來保持專案乾淨？
  [x] 刪除本地分支 (feature/payment-gateway)
  [x] 刪除遠端分支 (origin/feature/payment-gateway)
  [ ] 保留分支，不刪除

✓ 已刪除本地分支 feature/payment-gateway
✓ 已刪除遠端分支 origin/feature/payment-gateway
儲存庫環境整理完畢！
────────────────────────────────────────────────

情境 7：自動語意化版號標記與雙語 Release 發布（/tag & /github-release）

當主分支合併完成後，執行標籤與 Release 技能，AI 會自動比對提交歷史，依據語意化版本（Semantic Versioning，SemVer）2.0.0 計算版號並產出中英雙語 Changelog：

────────────────────────────────────────────────
> /antigravity-git-flow:git-flow:tag
────────────────────────────────────────────────
分析自 v1.1.0 以來的合併節點：
- 偵測到 feat 類型變更，依據 SemVer 規範加算 MINOR 版本號。
建立標籤：v1.2.0
推播標籤至遠端：git push origin v1.2.0

> /antigravity-git-flow:git-flow:github-release
────────────────────────────────────────────────
正在擷取 v1.1.0..v1.2.0 之變更項目...
自動產生中英文雙語 Changelog：

### What's Changed
#### English
- Feat: implement third-party payment gateway integration by @AndyAWD
- Chore: update environment variable configuration template by @AndyAWD

#### 繁體中文
- 新功能: 實作第三方金流串接介面 by @AndyAWD
- 雜項: 更新環境變數設定檔範本 by @AndyAWD

正在建立 GitHub Release v1.2.0...
✓ https://github.com/AndyAWD/antigravity-git-flow/releases/tag/v1.2.0
────────────────────────────────────────────────