pull-request

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Pull Request 助手

GitHub Pull Request Assistant

協助使用者建立或修改 GitHub Pull Request，自動分析分支 commits 並產生繁體中文 PR 標題與描述。

Assists users in creating or modifying GitHub Pull Request, automatically analyzes branch commits and generates Traditional Chinese PR titles and descriptions.

功能

Features

建立 PR：從當前分支建立 Pull Request 到目標分支
修改 PR：更新現有 PR 的標題或描述
分析 commits：自動彙整分支變更產生 PR 內容

Create PR: Create a Pull Request from the current branch to the target branch
Modify PR: Update the title or description of an existing PR
Analyze commits: Automatically aggregate branch changes to generate PR content

決策流程

Decision Flow

使用者請求 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：執行對應流程並回報結果

User requests PR-related operation
│
├─ Step 1: Check if the current branch has a corresponding PR
│  │
│  │  gh pr view --json number,title,state 2>&1
│  │
│  ├─ 【Has output and state="OPEN"】→ PR already exists
│  │  │
│  │  └─ Enter 【PR Modification Flow】
│  │     - Display existing PR information
│  │     - Ask the user what content to modify
│  │     - Execute gh pr edit command
│  │
│  └─ 【No output or error】→ PR does not exist
│     │
│     └─ Enter 【PR Creation Flow】
│        - Perform pre-checks
│        - Analyze commits
│        - Generate title and description
│        - Execute gh pr create command
│
└─ Step 2: Execute the corresponding process and report results

檢查 PR 是否存在

Check if PR exists

bash

undefined

bash

undefined

檢查當前分支是否已有 PR

Check if the current branch already has a 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 不存在 | 進入建立流程 |

gh pr view --json number,title,state,url


**Judgment Logic:**

| Output Result | Judgment | Follow-up Action |
|---------|------|---------|
| Returns JSON and `state: "OPEN"` | PR exists and is open | Enter modification flow |
| Returns JSON and `state: "MERGED"` | PR has been merged | Ask if you want to create a new PR |
| Returns JSON and `state: "CLOSED"` | PR has been closed | Ask if you want to reopen or create a new PR |
| Error message `no pull requests found` | PR does not exist | Enter creation flow |

建立 PR 流程

PR Creation Flow

步驟 0：前置檢查

Step 0: Pre-check

確認當前分支已推送至遠端：

bash

undefined

Confirm that the current branch has been pushed to the remote:

bash

undefined

取得當前分支名稱

Get current branch name

git rev-parse --abbrev-ref HEAD

檢查分支是否存在於遠端

Check if the branch exists on the remote

git ls-remote --heads origin $(git rev-parse --abbrev-ref HEAD)


**若無輸出**：分支尚未推上遠端，需先執行：
```bash
git push -u origin <當前分支>

git ls-remote --heads origin $(git rev-parse --abbrev-ref HEAD)


**If there is no output**: The branch has not been pushed to the remote, you need to execute first:
```bash
git push -u origin <current branch>

步驟 1：取得 commits 清單

Step 1: Get commits list

取得當前分支相對於目標分支（預設

main

）的 commits：

bash

git --no-pager log --oneline <目標分支>..<當前分支>

Get commits of the current branch relative to the target branch (default

main

bash

git --no-pager log --oneline <target branch>..<current branch>

步驟 2：取得 commit 詳細資訊

Step 2: Get commit detailed information

針對每個 commit 取得變更統計：

bash

git --no-pager show <commit-hash> --stat

Get change statistics for each commit:

bash

git --no-pager show <commit-hash> --stat

步驟 3：產生 PR 標題

Step 3: Generate PR title

根據 commit 數量決定標題策略：

情況	標題策略
單一 commit	直接使用該 commit 訊息
多個 commits	總結所有變更的描述性標題

Decide the title strategy based on the number of commits:

Scenario	Title Strategy
Single commit	Use the commit message directly
Multiple commits	Descriptive title summarizing all changes

步驟 4：產生 PR 描述

Step 4: Generate PR description

必須嚴格遵守以下格式，確保輸出為真正的 Markdown 換行，而非包含

\n

的字串：

完整範本請參考
references/pr-template.md

markdown

undefined

Must strictly follow the format below, ensure the output is real Markdown line breaks, not strings containing

\n

For the full template, please refer to
references/pr-template.md

markdown

undefined

摘要

Summary

[一句話總結此 PR 的主要目的]

[One sentence summarizing the main purpose of this PR]

修改內容

Modification Content

變更項目 1：描述具體的修改內容
變更項目 2：描述具體的修改內容
變更項目 3：描述具體的修改內容

Change item 1: Describe the specific modification content
Change item 2: Describe the specific modification content
Change item 3: Describe the specific modification content

⚠️ 風險評估

⚠️ Risk Assessment

[評估此 PR 是否有破壞性變更、需要特別注意的地方]

常見風險類型：

資料庫變更（migration、schema 修改）
API 變更（endpoint 修改、參數變更）
設定檔變更（環境變數、設定參數）
相依性更新（套件版本升級）

若無風險，可註明：「無破壞性變更」

[Assess whether this PR has breaking changes, points that need special attention]

Common risk types:

Database changes (migration, schema modification)
API changes (endpoint modification, parameter modification)
Configuration file changes (environment variables, configuration parameters)
Dependency updates (package version upgrade)

If there is no risk, you can note: "No breaking changes"

備註

Remarks

[其他需要審查者注意的地方，如測試方式、部署注意事項、相關 Issue 連結等]

undefined

[Other points that reviewers need to pay attention to, such as testing methods, deployment precautions, related Issue links, etc.]

undefined

步驟 5：建立 Pull Request

Step 5: Create Pull Request

使用 GitHub CLI 建立 PR。

⚠️ 絕對禁止直接使用
--body
參數。必須先將內容寫入暫存檔案，再使用
--body-file
讀取內容，以避免換行符被轉義為
\n
字串。

bash

undefined

Use GitHub CLI to create PR.

⚠️ It is strictly forbidden to use the
--body
parameter directly. You must first write the content to a temporary file, then use
--body-file
to read the content to avoid line breaks being escaped as
\n
strings.

bash

undefined

正確做法：

Correct approach:

1. 建立暫存檔案 pr-body.md，寫入 PR 描述內容（確保內容中是真正的換行）

1. Create temporary file pr-body.md, write PR description content (ensure real line breaks in the content)

2. 使用 --body-file 讀取檔案

2. Use --body-file to read the file

gh pr create --base <目標分支> --head <當前分支> --title "<標題>" --body-file pr-body.md

gh pr create --base <target branch> --head <current branch> --title "<title>" --body-file pr-body.md

3. 建立完成後刪除暫存檔案

3. Delete the temporary file after creation is complete


**PowerShell 範例：**

```powershell


**PowerShell Example:**

```powershell

將 PR 描述寫入檔案

Write PR description to file

摘要

Summary

實作使用者登入功能

Implement user login function

修改內容

Modification Content

新增登入 API 端點
實作 JWT 驗證機制

Add login API endpoint
Implement JWT authentication mechanism

⚠️ 風險評估

⚠️ Risk Assessment

無破壞性變更 "@ | Out-File -FilePath pr-body.md -Encoding UTF8

No breaking changes "@ | Out-File -FilePath pr-body.md -Encoding UTF8

建立 PR

Create PR

gh pr create --base main --title "feat: 實作登入功能" --body-file pr-body.md

清理暫存檔案

Clean up temporary files

Remove-Item pr-body.md


**Bash 範例：**

```bash

Remove-Item pr-body.md


**Bash Example:**

```bash

將 PR 描述寫入檔案

Write PR description to file

cat << 'EOF' > pr-body.md

摘要

Summary

實作使用者登入功能

修改內容

新增登入 API 端點
實作 JWT 驗證機制

新增登入 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>` | 新增標籤 |

rm pr-body.md


**Common Options:**

| Option | Description |
|------|------|
| `--body-file <file>` | Read PR description from file (recommended) |
| `--draft` | Create draft PR |
| `--reviewer <users>` | Specify reviewers (comma separated) |
| `--assignee <users>` | Specify assignee |
| `--label <labels>` | Add labels |

修改 PR 流程

PR Modification Flow

當 PR 已存在時，進入此流程。

Enter this flow when PR already exists.

步驟 1：取得現有 PR 資訊

Step 1: Get existing PR information

bash

gh pr view --json number,title,body,state,url,headRefName,baseRefName

bash

gh pr view --json number,title,body,state,url,headRefName,baseRefName

步驟 2：顯示 PR 摘要

Step 2: Display PR summary

向使用者顯示：

PR 編號與標題
目前狀態（OPEN/DRAFT）
來源分支 → 目標分支
PR 連結

Display to the user:

PR number and title
Current status (OPEN/DRAFT)
Source branch → Target branch
PR link

步驟 3：確認修改內容

Step 3: Confirm modification content

根據使用者需求執行對應操作：

Perform corresponding operations according to user requirements:

修改標題

Modify title

bash

gh pr edit <PR編號或URL> --title "<新標題>"

bash

gh pr edit <PR number or URL> --title "<new title>"

修改描述

Modify description

bash

gh pr edit <PR編號或URL> --body "<新描述>"

bash

gh pr edit <PR number or URL> --body "<new description>"

新增審核者/標籤

Add reviewers/labels

bash

gh pr edit <PR編號或URL> --add-reviewer <users>
gh pr edit <PR編號或URL> --add-label <labels>

bash

gh pr edit <PR number or URL> --add-reviewer <users>
gh pr edit <PR number or URL> --add-label <labels>

查看現有 PR

View existing PR

bash

undefined

bash

undefined

列出當前 repo 的 PR

List PRs of current repo

gh pr list

查看特定 PR 詳情

View details of specific PR

gh pr view <PR編號>

undefined

gh pr view <PR number>

undefined

注意事項

Notes

僅處理已提交的變更：忽略未 staged 的變更
語言要求：PR 標題與描述使用繁體中文 (zh-TW)
目標分支預設：若使用者未指定，預設為
```
main
```
需要 GitHub CLI：確保已安裝並登入
```
gh
```
工具

Only process committed changes: Ignore unstaged changes are ignored
Language requirement: PR title and description use Traditional Chinese (zh-TW)
Default target branch: If not specified by the user, the default is
```
main
```
GitHub CLI required: Ensure that the
```
gh
```
tool is installed and logged in

範例

Examples

範例 1：PR 不存在 - 建立新 PR

Example 1: PR does not exist - Create new 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 "..."

User request: "Help me create a PR to develop"

Execution flow:

Check PR:
```
gh pr view
```
→ Error "no pull requests found"
Judgment: PR does not exist, enter creation flow
Pre-check: Confirm that the branch is on the remote

Get commits:

git --no-pager log --oneline develop..HEAD

Analyze changes to generate title and description

Execute:

gh pr create --base develop --head feature/login --title "feat: 實作使用者登入功能" --body "..."

範例 2：PR 已存在 - 自動進入修改模式

Example 2: PR already exists - Automatically enter modification mode

使用者請求： 「幫我開 PR」

執行流程：

檢查 PR：

gh pr view --json number,title,state

json

{"number": 42, "title": "feat: 新增登入功能", "state": "OPEN"}

判斷：PR 已存在，進入修改流程
回報：「此分支已有 PR #42『feat: 新增登入功能』，請問要進行什麼修改？」
等待使用者指示

User request: "Help me open a PR"

Execution flow:

Check PR:

gh pr view --json number,title,state

json

{"number": 42, "title": "feat: 新增登入功能", "state": "OPEN"}

Judgment: PR already exists, enter modification flow
Report: "There is already PR #42 'feat: 新增登入功能' for this branch, what modification do you want to make?"
Wait for user instructions

範例 3：明確修改 PR

Example 3: Explicitly modify PR

使用者請求： 「修改 PR #42 的標題為『修正購物車計算錯誤』」

執行：

bash

gh pr edit 42 --title "修正購物車計算錯誤"

User request: "Modify the title of PR #42 to 'Fix shopping cart calculation error'"

Execution:

bash

gh pr edit 42 --title "修正購物車計算錯誤"

範例 4：PR 已合併

Example 4: PR has been merged

使用者請求： 「幫我建 PR」

執行流程：

檢查 PR：

gh pr view --json number,title,state

json

{"number": 38, "title": "feat: 舊功能", "state": "MERGED"}

判斷：PR 已合併
回報：「此分支的 PR #38 已合併。若有新的變更需要建立 PR，請確認已有新的 commits。」

User request: "Help me create a PR"

Execution flow:

Check PR:

gh pr view --json number,title,state

json

{"number": 38, "title": "feat: 舊功能", "state": "MERGED"}

Judgment: PR has been merged
Report: "PR #38 for this branch has been merged. If you have new changes that need to create a PR, please confirm that there are new commits."

參考資料

References

```
references/pr-template.md
```
- PR 描述範本與編寫指南
```
references/gh-pr-commands.md
```
- GitHub CLI PR 相關指令完整參考

```
references/pr-template.md
```
- PR description template and writing guide
```
references/gh-pr-commands.md
```
- Complete reference for GitHub CLI PR related commands