GitHub Pull Request 助手
協助使用者建立或修改 GitHub Pull Request，自動分析分支 commits 並產生繁體中文 PR 標題與描述。
功能
-
建立 PR：從當前分支建立 Pull Request 到目標分支
-
修改 PR：更新現有 PR 的標題或描述
-
分析 commits：自動彙整分支變更產生 PR 內容
決策流程
使用者請求 PR 相關操作 │ ├─ 步驟 1：檢查當前分支是否有對應的 PR │ │ │ │ gh pr view --json number,title,state 2>&1 │ │ │ ├─ 【有輸出且 state="OPEN"】→ PR 已存在 │ │ │ │ │ └─ 進入【修改 PR 流程】 │ │ - 顯示現有 PR 資訊 │ │ - 詢問使用者要修改的內容 │ │ - 執行 gh pr edit 指令 │ │ │ └─ 【無輸出或錯誤】→ PR 不存在 │ │ │ └─ 進入【建立 PR 流程】 │ - 執行前置檢查 │ - 分析 commits │ - 產生標題與描述 │ - 執行 gh pr create 指令 │ └─ 步驟 2：執行對應流程並回報結果
檢查 PR 是否存在
檢查當前分支是否已有 PR
gh pr view --json number,title,state,url
判斷邏輯：
輸出結果 判斷 後續動作
返回 JSON 且 state: "OPEN"
PR 已存在且開啟中 進入修改流程
返回 JSON 且 state: "MERGED"
PR 已合併 詢問是否建立新 PR
返回 JSON 且 state: "CLOSED"
PR 已關閉 詢問是否重開或建立新 PR
錯誤訊息 no pull requests found
PR 不存在 進入建立流程
建立 PR 流程
步驟 0：前置檢查
確認當前分支已推送至遠端：
取得當前分支名稱
git rev-parse --abbrev-ref HEAD
檢查分支是否存在於遠端
git ls-remote --heads origin $(git rev-parse --abbrev-ref HEAD)
若無輸出：分支尚未推上遠端，需先執行：
git push -u origin <當前分支>
步驟 1：取得 commits 清單
取得當前分支相對於目標分支（預設 main ）的 commits：
git --no-pager log --oneline <目標分支>..<當前分支>
步驟 2：取得 commit 詳細資訊
針對每個 commit 取得變更統計：
git --no-pager show <commit-hash> --stat
步驟 3：產生 PR 標題
根據 commit 數量決定標題策略：
情況 標題策略
單一 commit 直接使用該 commit 訊息
多個 commits 總結所有變更的描述性標題
步驟 4：產生 PR 描述
必須嚴格遵守以下格式，確保輸出為真正的 Markdown 換行，而非包含 \n 的字串：
完整範本請參考 references/pr-template.md
摘要
[一句話總結此 PR 的主要目的]
修改內容
- 變更項目 1：描述具體的修改內容
- 變更項目 2：描述具體的修改內容
- 變更項目 3：描述具體的修改內容
⚠️ 風險評估
[評估此 PR 是否有破壞性變更、需要特別注意的地方]
常見風險類型：
- 資料庫變更（migration、schema 修改）
- API 變更（endpoint 修改、參數變更）
- 設定檔變更（環境變數、設定參數）
- 相依性更新（套件版本升級）
若無風險，可註明：「無破壞性變更」
備註
[其他需要審查者注意的地方，如測試方式、部署注意事項、相關 Issue 連結等]
步驟 5：建立 Pull Request
使用 GitHub CLI 建立 PR。
⚠️ 絕對禁止直接使用 --body 參數。必須先將內容寫入暫存檔案，再使用 --body-file 讀取內容，以避免換行符被轉義為 \n 字串。
正確做法：
1. 建立暫存檔案 pr-body.md，寫入 PR 描述內容（確保內容中是真正的換行）
2. 使用 --body-file 讀取檔案
gh pr create --base <目標分支> --head <當前分支> --title "<標題>" --body-file pr-body.md
3. 建立完成後刪除暫存檔案
PowerShell 範例：
將 PR 描述寫入檔案
@"
摘要
實作使用者登入功能
修改內容
- 新增登入 API 端點
- 實作 JWT 驗證機制
⚠️ 風險評估
無破壞性變更 "@ | Out-File -FilePath pr-body.md -Encoding UTF8
建立 PR
gh pr create --base main --title "feat: 實作登入功能" --body-file pr-body.md
清理暫存檔案
Remove-Item pr-body.md
Bash 範例：
將 PR 描述寫入檔案
cat << 'EOF' > pr-body.md
摘要
實作使用者登入功能
修改內容
- 新增登入 API 端點
- 實作 JWT 驗證機制
⚠️ 風險評估
無破壞性變更 EOF
建立 PR
gh pr create --base main --title "feat: 實作登入功能" --body-file pr-body.md
清理暫存檔案
rm pr-body.md
常用選項：
選項 說明
--body-file <file>
從檔案讀取 PR 描述（推薦）
--draft
建立草稿 PR
--reviewer <users>
指定審核者（逗號分隔）
--assignee <users>
指定負責人
--label <labels>
新增標籤
修改 PR 流程
當 PR 已存在時，進入此流程。
步驟 1：取得現有 PR 資訊
gh pr view --json number,title,body,state,url,headRefName,baseRefName
步驟 2：顯示 PR 摘要
向使用者顯示：
-
PR 編號與標題
-
目前狀態（OPEN/DRAFT）
-
來源分支 → 目標分支
-
PR 連結
步驟 3：確認修改內容
根據使用者需求執行對應操作：
修改標題
gh pr edit <PR編號或URL> --title "<新標題>"
修改描述
gh pr edit <PR編號或URL> --body "<新描述>"
新增審核者/標籤
gh pr edit <PR編號或URL> --add-reviewer <users> gh pr edit <PR編號或URL> --add-label <labels>
查看現有 PR
列出當前 repo 的 PR
gh pr list
查看特定 PR 詳情
gh pr view <PR編號>
注意事項
-
僅處理已提交的變更：忽略未 staged 的變更
-
語言要求：PR 標題與描述使用繁體中文 (zh-TW)
-
目標分支預設：若使用者未指定，預設為 main
-
需要 GitHub CLI：確保已安裝並登入 gh 工具
範例
範例 1：PR 不存在 - 建立新 PR
使用者請求： 「幫我建立 PR 到 develop」
執行流程：
-
檢查 PR：gh pr view → 錯誤「no pull requests found」
-
判斷：PR 不存在，進入建立流程
-
前置檢查：確認分支已在遠端
-
取得 commits：git --no-pager log --oneline develop..HEAD
-
分析變更產生標題與描述
-
執行：gh pr create --base develop --head feature/login --title "feat: 實作使用者登入功能" --body "..."
範例 2：PR 已存在 - 自動進入修改模式
使用者請求： 「幫我開 PR」
執行流程：
- 檢查 PR：gh pr view --json number,title,state
{"number": 42, "title": "feat: 新增登入功能", "state": "OPEN"}
-
判斷：PR 已存在，進入修改流程
-
回報：「此分支已有 PR #42『feat: 新增登入功能』，請問要進行什麼修改？」
-
等待使用者指示
範例 3：明確修改 PR
使用者請求： 「修改 PR #42 的標題為『修正購物車計算錯誤』」
執行：
gh pr edit 42 --title "修正購物車計算錯誤"
範例 4：PR 已合併
使用者請求： 「幫我建 PR」
執行流程：
- 檢查 PR：gh pr view --json number,title,state
{"number": 38, "title": "feat: 舊功能", "state": "MERGED"}
-
判斷：PR 已合併
-
回報：「此分支的 PR #38 已合併。若有新的變更需要建立 PR，請確認已有新的 commits。」
參考資料
-
references/pr-template.md
-
PR 描述範本與編寫指南
-
references/gh-pr-commands.md
-
GitHub CLI PR 相關指令完整參考