GitHub Copilot CLI = AI Agent + Terminal + GitHub 深度整合 + 多代理協作 + 擴充生態系 + ACP 開放標準 + OpenTelemetry 可觀測性

# 在 CLI 中使用 /plan 模式規劃任務
> /plan 重構 UserService 為 Clean Architecture

# 完成規劃後，切換到 VS Code 繼續
> /ide
# Copilot CLI 會自動在 VS Code 中開啟相關檔案

# Fleet 模式使用範例
> /fleet 重構訂單模組：前端 API 對接、後端 CRUD、單元測試、E2E 測試，各自平行處理

# Delegate 使用範例
> /delegate 在 develop 分支上修復所有 SonarQube 發現的 Code Smell

# 快捷方式（& 前綴等同 /delegate）
> & 幫我把所有 Java 檔案的 System.out.println 改為 Logger

# 使用程式化介面執行完整流程
copilot -p "在 Spring Boot 專案建立 /api/v1/users 的 CRUD API，
遵循 Clean Architecture，使用 JPA + PostgreSQL，
並產生 JUnit 5 測試，最後建立 PR" \
  --allow-tool='shell(mvn)' \
  --allow-tool='shell(git)' \
  --allow-tool='write'

# 安裝最新穩定版
npm install -g @github/copilot

# 安裝預發佈版本
npm install -g @github/copilot@prerelease

# 安裝穩定版
winget install GitHub.Copilot

# 安裝預發佈版
winget install GitHub.Copilot.Prerelease

# 安裝穩定版
brew install copilot-cli

# 安裝預發佈版
brew install copilot-cli@prerelease

# 使用 curl
curl -fsSL https://gh.io/copilot-install | bash

# 使用 wget
wget -qO- https://gh.io/copilot-install | bash

# 以 root 安裝到 /usr/local/bin
curl -fsSL https://gh.io/copilot-install | sudo bash

# 安裝指定版本到自訂目錄
curl -fsSL https://gh.io/copilot-install | VERSION="v0.0.369" PREFIX="$HOME/custom" bash

# 查看安裝版本
copilot --version

# 查看二進位版本（不啟動完整 CLI）
copilot --binary-version

# 啟動 Copilot CLI
copilot

# 首次啟動會提示登入，輸入：
/login
# 跟隨畫面指示完成 GitHub OAuth 驗證

# 方式 1（最高優先）
export COPILOT_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# 方式 2
export GH_TOKEN="ghp_xxxxxxxxxxxx"

# 方式 3
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

# 查看所有設定選項
copilot help config

# 設定檔位置（預設）
# ~/.copilot/config.json

# 變更設定檔位置
export COPILOT_HOME="$HOME/.my-copilot"

// ~/.copilot/config.json 範例
{
  "model": "claude-sonnet-4-5",
  "theme": "dark",
  "autoCompact": true,
  "includeCoAuthoredBy": true,
  "effortLevel": "medium",
  "autoUpdatesChannel": "stable",
  "trustedDirectories": [
    "/home/dev/projects",
    "/workspace"
  ]
}

> 找出佔用 8080 port 的 process 並終止它

Copilot 建議：
$ lsof -i :8080 | grep LISTEN | awk '{print $2}' | xargs kill -9

> 找出 src 目錄下所有超過 500 行的 Java 檔案

Copilot 建議：
$ find src -name "*.java" -exec awk 'END{if(NR>500) print FILENAME": "NR" lines"}' {} \;

> 分析最近 1 小時的 Spring Boot 日誌，找出所有 ERROR 等級的錯誤

Copilot 建議：
$ grep "ERROR" logs/application.log | awk -v d="$(date -d '1 hour ago' '+%Y-%m-%d %H')" '$0 >= d'

> 建立一個新的 feature 分支，基於最新的 develop 分支

Copilot 執行：
$ git fetch origin
$ git checkout develop
$ git pull origin develop
$ git checkout -b feature/new-feature

> 把目前分支 rebase 到 main，保持線性歷史

Copilot 執行：
$ git fetch origin
$ git rebase origin/main

> 把 commit abc1234 從 hotfix 分支 cherry-pick 到 release 分支

Copilot 執行：
$ git checkout release
$ git cherry-pick abc1234

> 互動式 rebase 最近 5 個 commit，合併成一個

Copilot 執行：
$ git rebase -i HEAD~5

> 在 Spring Boot 專案中建立一個 UserController，實作 CRUD API，
  使用 Clean Architecture，包含 Service 層和 Repository 層

Copilot 會自動：
1. 掃描現有專案結構（找到 src/main/java 目錄）
2. 分析現有程式碼風格（包名、命名慣例）
3. 建立以下檔案：
   - UserController.java
   - UserService.java
   - UserServiceImpl.java
   - UserRepository.java
   - UserDTO.java
   - User.java (Entity)
4. 自動處理依賴注入和 Spring 註解

> 應用程式在 UserService.getUserById 拋出 NullPointerException，
  請幫我找到原因並修復

Copilot 會自動：
1. 讀取 UserService.java 的程式碼
2. 分析可能的 null 來源
3. 檢查 Repository 回傳值
4. 添加適當的 null 檢查或 Optional 處理
5. 驗證修復（如果有測試的話，會執行測試）

> 為 UserService 產生完整的 JUnit 5 測試，包含正常流程和邊界案例，
  使用 Mockito 模擬 Repository

Copilot 會自動：
1. 讀取 UserService.java 的程式碼
2. 分析所有 public 方法
3. 產生 UserServiceTest.java：
   - @BeforeEach 設定
   - 正常案例測試
   - 邊界條件測試（null、空值、不存在的 ID）
   - Exception 測試
4. 執行測試確認通過

> [Plan Mode] 重構 UserService，將單體式的 Service 拆分成符合
  SOLID 原則的多個小 Service

Copilot Plan：
 ✅ Phase 1：分析現有 UserService（12 個 public 方法）
 ✅ Phase 2：識別職責（認證、Profile、Permission）
 ✅ Phase 3：建立 UserAuthService（登入、登出、驗證）
 ✅ Phase 4：建立 UserProfileService（查詢、更新 Profile）
 ✅ Phase 5：建立 UserPermissionService（權限管理）
 ✅ Phase 6：更新 UserController 的依賴注入
 ✅ Phase 7：遷移測試
 ✅ Phase 8：執行所有測試確認

是否開始執行？(Y/N)

> 分析這個專案的架構，告訴我主要的模組和它們之間的關係

Copilot 會讀取：
- pom.xml / build.gradle（依賴關係）
- 目錄結構（模組劃分）
- package-info.java（如果有的話）
- README.md / docs/
- .github/copilot-instructions.md（自訂指令）

# 在互動式介面中引用檔案
> 解釋 @src/main/java/com/tutorial/java/App.java 的功能

# 引用多個檔案
> 比較 @UserController.java 和 @AdminController.java 的差異

# 引用設定檔
> 根據 @pom.xml 的依賴，建議我該升級哪些套件

<!-- .github/copilot-instructions.md -->
# 專案開發規範

## 架構
- 使用 Clean Architecture
- Controller -> Service -> Repository -> Entity

## 命名慣例
- 類別名：PascalCase
- 方法名：camelCase
- 常數：UPPER_SNAKE_CASE
- REST API 路徑：kebab-case

## 測試
- 使用 JUnit 5 + Mockito
- 測試覆蓋率需達 80%
- 命名格式：should_DoSomething_When_Condition

## 日誌
- 使用 Log4j2
- ERROR：系統錯誤
- WARN：業務異常
- INFO：關鍵操作
- DEBUG：開發除錯

> 將目前分支的變更建立一個 PR 到 develop 分支，
  自動產生 Summary 並加上 "feature" 標籤

Copilot 執行：
1. git push origin feature/user-auth
2. 建立 PR（含自動生成的 Summary）
3. 添加標籤
4. 指派 Reviewer（如果有設定）

> 為 PR #42 產生詳細的 Summary

Copilot 生成：
## Summary
本 PR 實作使用者認證模組，包含：
- JWT Token 認證機制
- Refresh Token 支援
- 角色權限控管（RBAC）

## Changes
- 新增 `AuthController.java`（4 個 API endpoint）
- 新增 `JwtTokenService.java`（Token 生成與驗證）
- 更新 `SecurityConfig.java`（Spring Security 設定）
- 新增 `AuthServiceTest.java`（23 個測試案例）

## Testing
- 單元測試：23/23 通過
- 整合測試：8/8 通過

# 列出分配給我的 Issue
> List all open issues assigned to me in my-org/my-repo

# 從 Issue 開始開發
> 我被指派了這個 Issue：https://github.com/my-org/my-repo/issues/42
  開始處理它，建立合適的分支名稱

# 建立新 Issue
> 在 my-org/my-repo 建立一個 Bug Report Issue，
  描述 UserService.getUserById 在 ID 不存在時拋出 500 而非 404

# 檢查 PR 的程式碼變更
> 檢查 PR https://github.com/my-org/my-repo/pull/57 的變更，
  回報任何嚴重的錯誤

# 查看 workflow
> 列出這個 repo 中所有的 Actions workflows

# 建立新 workflow
> 建立一個 GitHub Actions workflow，在 PR 上執行：
  1. Maven 編譯
  2. JUnit 測試
  3. SonarQube 分析
  4. 安全掃描
  若有錯誤則阻止 Merge

# 查看 workflow 執行結果
> 顯示上次 CI 執行的結果和錯誤日誌

# TypeScript
npm install -g typescript-language-server

# Python（由 Plugin 或獨立安裝提供）
pip install python-lsp-server

# Java
# 使用 Eclipse JDT Language Server 或其他 LSP 實作

{
  "lspServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "fileExtensions": {
        ".ts": "typescript",
        ".tsx": "typescript"
      }
    },
    "java": {
      "command": "jdtls",
      "args": ["--stdio"],
      "fileExtensions": {
        ".java": "java"
      }
    }
  }
}

# 在互動式介面中查看 LSP 狀態
/lsp

# 查看特定伺服器的詳細資訊
/lsp show

// .github/hooks/hooks.json
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "shell",
        "command": "echo 'Tool about to execute: $TOOL_NAME'",
        "timeout": 10
      }
    ],
    "postToolUse": [
      {
        "matcher": "write",
        "command": "echo 'File written: $FILE_PATH' >> .copilot-audit.log"
      }
    ]
  }
}

<!-- .agents/skills/database-migration.md -->
---
name: database-migration
description: 執行資料庫 Migration 操作
allowed-tools:
  - shell(mvn)
  - shell(flyway)
  - write
---

# Database Migration Skill

你是資料庫 Migration 專家，負責：
1. 建立 Flyway migration 腳本
2. 驗證 Migration 相容性
3. 執行 Migration 並驗證結果

# 查看所有已載入的 Skills
/skills

# 新增 Skill
/skills add <path>

# 以 Slash Command 方式呼叫 Skill
/database-migration

# 開啟 Plugin Marketplace
/plugin marketplace add

# 從 GitHub Repo 安裝
/plugin install <github-repo-url>

# 從本機目錄安裝
/plugin install /path/to/plugin

# 從 SSH URL 安裝
/plugin install ssh://git@github.com/org/plugin.git

# 更新已安裝的 Plugin
/plugin update

# 解除安裝
/plugin uninstall <name>

# 查看已安裝的 Plugin 清單
/plugin list

// plugin.json
{
  "name": "my-enterprise-plugin",
  "version": "1.0.0",
  "description": "企業內部開發輔助工具",
  "mcpServers": { ... },
  "lspServers": { ... },
  "agents": [ ... ],
  "skills": [ ... ],
  "hooks": { ... }
}

# 查看、啟用與停用 Extensions
/extensions

# 啟動時載入外部 Extension
copilot --plugin-dir /path/to/extension

# 詢問過去的工作記錄
> 我上次在哪個分支做了什麼修改？

# 查詢之前的 PR
> 顯示我最近建立的 PR 清單和摘要

# 啟動 ACP 模式
copilot --acp

# ACP 模式支援的功能
# - 載入現有 Session
# - 管理 Agent / Plan / Autopilot 模式
# - 設定推理強度（reasoning effort）
# - 完整的 MCP 設定支援
# - 工具權限控制（--yolo, --allow-all 等）

# 安裝 Copilot CLI（即包含 SDK Runtime）
npm install -g @github/copilot

# 使用 Copilot SDK 為應用程式內建 Agent 能力
# 參閱：https://github.com/github/copilot-sdk

# 查看 OpenTelemetry 配置說明
copilot help monitoring

# 啟用 OTEL 追蹤（透過環境變數設定 Exporter）
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_SERVICE_NAME="copilot-cli"
copilot

# 需要實驗性模式 + Claude 模型
copilot --experimental
# Critic Agent 會在 Plan 審核和複雜實作時自動觸發

# 啟動帶有遠端控制功能的 Session
copilot --remote

# 在互動式介面中啟用/停用
/remote on
/remote off

# 查看目前遠端控制狀態（含連線狀態提示）
/remote

# 從 --resume 選擇器連接遠端 Session
copilot --resume
# 在選擇器中會顯示遠端 Session

# 直接透過 Session ID 連接
copilot --connect <session-id>

# 恢復遠端 Session 時自動繼承 --remote 旗標
copilot --resume  # 自動繼承

# 連接本地 Ollama 實例
export COPILOT_PROVIDER_BASE_URL="http://localhost:11434/v1"
export COPILOT_PROVIDER_TYPE="openai"
export COPILOT_MODEL="llama3.1:70b"
copilot

# 連接 Azure OpenAI
export COPILOT_PROVIDER_BASE_URL="https://my-resource.openai.azure.com"
export COPILOT_PROVIDER_TYPE="azure"
export COPILOT_PROVIDER_API_KEY="your-azure-key"
export COPILOT_MODEL="gpt-4o"
copilot

# 連接自託管 Anthropic 端點
export COPILOT_PROVIDER_BASE_URL="https://my-anthropic-proxy.internal.com"
export COPILOT_PROVIDER_TYPE="anthropic"
export COPILOT_PROVIDER_API_KEY="your-api-key"
export COPILOT_MODEL="claude-sonnet-4-5"
copilot

# 引用圖片檔案實作設計
> 根據 @mockup.png 實作這個頁面的 HTML/CSS，精確匹配佈局和間距

# 截圖分析錯誤
> [Ctrl+V 貼上錯誤截圖] 請分析這個錯誤訊息並提供修復方案

# UI 比對
> 比較 @design-v1.png 和 @design-v2.png 的差異，列出需要修改的 CSS 屬性

# 方式 1：使用 /agent 指令選擇
/agent

# 方式 2：在 Prompt 中自然呼叫
> 使用 refactoring agent 重構這段程式碼

# 方式 3：命令列選項指定
copilot --agent=backend-expert --prompt "重構 UserService"

在 @src/main/java/com/example/controller/ 新增 OrderController.java：
- 實作 POST /api/v1/orders（建立訂單）
- 使用 @OrderService.java 的 createOrder 方法
- Request Body 包含：customerId, items[], totalAmount
- 成功回傳 201 + OrderDTO
- 驗證失敗回傳 400 + ErrorResponse
- 使用 @Valid 驗證
- 添加 @Operation (Swagger) 註解
- 日誌使用 Log4j2

Bug 描述：當使用者同時發送多個下單請求時，庫存扣減出現 Race Condition。
相關檔案：@InventoryService.java, @OrderService.java
現象：庫存變成負數
要求：
1. 分析 Race Condition 的根因
2. 使用悲觀鎖或樂觀鎖修復
3. 新增對應的並發測試
4. 不要影響現有的單元測試

<!-- .github/copilot-instructions.md -->

# 專案：企業級訂單管理系統

## 技術棧
- Java 21 + Spring Boot 3.x
- PostgreSQL 15 + JPA/Hibernate
- Redis 7.x（快取）
- Kafka（事件驅動）

## 架構規範
- Clean Architecture（4 層）
- Domain 層不依賴 Infrastructure
- 使用 Port/Adapter 模式

## API 規範
- RESTful API，版本化（/api/v1/）
- 回傳格式統一使用 ApiResponse<T>
- 錯誤碼：業務錯誤 4xxxx，系統錯誤 5xxxx

<!-- .github/instructions/api-controllers.instructions.md -->
---
applyTo: "**/controller/**"
---

# Controller 層開發規範

- 只負責 HTTP 層的轉換與驗證
- 不包含業務邏輯
- 使用 @Valid 驗證 Request
- 使用 @Operation 產生 OpenAPI 文件
- 每個 endpoint 需有 @ApiResponse 定義

<!-- .github/agents/backend-expert.md -->
---
name: backend-expert
description: 後端開發專家
tools:
  - shell(mvn)
  - shell(git)
  - write
---

# Backend Expert Agent

你是一位資深 Java 後端工程師，專精於：
- Spring Boot 3.x 開發
- Clean Architecture 設計
- 高效能 API 開發
- 資料庫最佳化

## 工作原則
1. 所有程式碼必須有測試
2. 遵循 SOLID 原則
3. 使用 Log4j2 記錄關鍵操作
4. Controller 不直接存取 Repository

# Step 1：建立功能分支
copilot -p "建立一個名為 feature/order-api 的分支" \
  --allow-tool='shell(git)'

# Step 2：產生程式碼
copilot -p "在 Spring Boot 專案中實作 Order API 的 CRUD" \
  --allow-tool='write' \
  --allow-tool='shell(mvn)'

# Step 3：產生測試
copilot -p "為剛建立的 Order API 產生 JUnit 5 測試" \
  --allow-tool='write' \
  --allow-tool='shell(mvn test)'

# Step 4：建立 PR
copilot -p "Commit 所有變更並建立 PR 到 develop 分支" \
  --allow-tool='shell(git)'

#!/bin/bash
# scripts/dev-workflow.sh - 自動化開發工作流

FEATURE_NAME=$1
DESCRIPTION=$2

echo "🚀 開始開發：${FEATURE_NAME}"

# 建立分支
copilot -p "建立 feature/${FEATURE_NAME} 分支" \
  --allow-tool='shell(git)'

# 實作功能
copilot -p "${DESCRIPTION}" \
  --allow-tool='write' \
  --allow-tool='shell(mvn)'

# 測試
copilot -p "執行所有測試，確認新功能沒有破壞現有功能" \
  --allow-tool='shell(mvn test)'

# 建立 PR
copilot -p "建立 PR，標題為 'feat: ${FEATURE_NAME}'，
  自動產生 Summary" \
  --allow-tool='shell(git)' \
  --allow-tool='shell(gh)'

echo "✅ 完成！"

> 為這個 Spring Boot 專案建立一個多階段 Dockerfile，
  使用 Eclipse Temurin JDK 21 作為 base image，
  最終映像使用 JRE，暴露 8080 port

> 建立 docker-compose.yml，包含：
  - Spring Boot 應用（2 個實例）
  - PostgreSQL 15
  - Redis 7
  - Nginx 作為 Load Balancer

> 為應用程式建立 Kubernetes 部署清單：
  - Deployment（3 replicas）
  - Service（ClusterIP）
  - Ingress
  - ConfigMap（從 application.yml 轉換）
  - HPA（CPU > 70% 時自動擴展到 10）

# 在互動式介面中新增 MCP Server
/mcp add

# 從 MCP Registry 安裝 MCP Server（引導式配置，v1.0.25+）
# 系統會引導您完成配置

# 查看已配置的 MCP Server
/mcp

# 查看特定 MCP Server 的工具清單
/mcp show <server-name>

# 啟用 / 停用 MCP Server（跨 Session 持久化，v1.0.19+）
/mcp enable <name>
/mcp disable <name>

# 重新載入 MCP 設定
/mcp reload

# MCP OAuth 認證管理（v1.0.15+）
/mcp auth

# 非互動式 MCP 管理（v1.0.21+）
copilot mcp

# MCP 設定檔位置（v1.0.22+ 變更）
# .mcp.json（Repository 根目錄，唯一讀取的工作區 MCP 設定檔）
# ~/.copilot/mcp-config.json（使用者層級）

{
  "mcpServers": {
    "github": {
      "type": "builtin"
    },
    "postgres-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "docker-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-docker"]
    }
  }
}

~/.copilot/session-state/{session-id}/
├── events.jsonl      # 完整 Session 歷史記錄
├── workspace.yaml    # Session 中繼資料
├── plan.md           # 實作計畫（若有建立）
├── checkpoints/      # Context 壓縮歷史（Compaction）
└── files/            # 持久化產出物（非 Repo 內容）

# 查看 Session 資訊
/session

# 查看壓縮檢查點清單
/session checkpoints

# 查看特定檢查點詳情
/session checkpoints 2

# 查看 Session 中的暫存檔案
/session files

# 查看目前實作計畫
/session plan

# 繼續最近的 Session（偏好從目前工作目錄恢復，v1.0.35+）
copilot --continue

# 選擇並恢復歷史 Session（支援短 ID 前綴 7+ 字元，v1.0.32+）
copilot --resume
# Session 選擇器支援 / 搜尋過濾

# 以名稱恢復 Session（v1.0.35+）
copilot --resume=my-session-name

# 以名稱啟動 Session（v1.0.35+）
copilot --name "訂單模組重構"

# 直接連接遠端 Session（v1.0.32+）
copilot --connect <session-id>

# 在互動式介面中恢復 Session
/resume

# 開始新 Session（保留舊 Session 在背景）
/new

# 完全放棄目前 Session，重新開始
/clear

# /new 和 /clear 可帶 Prompt 直接開始新對話
/new 幫我分析 pom.xml 的依賴

# 重新命名 Session（不帶參數時自動從對話歷史生成名稱，v1.0.12+）
/rename 訂單模組重構
# 或
/session rename 訂單模組重構

# 匯出 / 分享 Session
/share              # 儲存為 Markdown 檔案
/share html         # 匯出為自包含的互動式 HTML 檔案（v1.0.15+）
/share gist         # 上傳為 GitHub Gist

# Session 使用統計（含 GitHub 風格的貢獻圖表，v1.0.35+）
/session

# Session 刪除管理（v1.0.35+）
/session delete          # 刪除指定 Session
/session delete-all      # 刪除所有 Session
# 或在 Session 選擇器中按 x 刪除

# 在 Session 選擇器中按 s 循環排序：相關性、最後使用、建立時間、名稱（v1.0.37+）

# 引用 Issue（會顯示自動完成選單）
> 修復 #42 描述的 NullPointerException 問題

# 引用 PR
> 檢查 #57 的程式碼變更，報告潛在問題

# 引用 Discussion
> 總結 #100 中團隊討論的架構決策

# 查看 Token 使用情況
/context

# 手動壓縮 Context（可帶自訂提示，v1.0.15+）
/compact
/compact 保留所有關於認證流程的對話

# 自動壓縮：當達到 Token 上限的 95% 時自動在背景執行
# 支援 preCompact hook 在壓縮前執行自訂邏輯

# /ask 指令：「一次性」查詢，不汙染 Context（v1.0.15+）
/ask 什麼是 SOLID 原則？
# 回覆完成後不保留在對話歷史中

# 從包含多個 Repo 的父目錄啟動
cd ~/projects
copilot

# Copilot 可同時存取所有子目錄中的 Repository
# 適用於：微服務架構、跨 Repo 協調變更、重構共用模式

# 從一個 Repo 啟動後，動態新增其他 Repo
copilot
/add-dir /Users/dev/projects/backend-service
/add-dir /Users/dev/projects/shared-libs
/add-dir /Users/dev/projects/documentation

# 查看目前已允許的目錄清單
/list-dirs

# 跨三個 Repo 的 API 變更
> 我需要更新使用者認證 API。變更跨越：
  - @/projects/api-gateway（路由變更）
  - @/projects/auth-service（核心邏輯）
  - @/projects/frontend（客戶端更新）
  請先展示目前認證流程在三個 Repo 間的運作方式。

# Step 1：輸入設計稿
> 根據 @mockup/login-page.png 實作登入頁面
  使用 Vue 3 + Tailwind CSS
  精確匹配佈局和間距

# Step 2：微調
> [Ctrl+V 貼上修改後截圖] 這個按鈕間距需要加大，其他都正確

# Step 3：遷移清單
> 執行 linter 並將所有錯誤寫入 `migration-checklist.md` 作為清單
  然後逐一修復，邊修邊打勾

Copilot 想要執行：rm -rf ./build/

1. Yes（僅此次）
2. Yes, and approve 'rm' for the rest of the running session（本次 session 永久允許）
3. No, and tell Copilot what to do differently (Esc)（拒絕並指引）

# 查看目前 allow-all 狀態
/allow-all show

# 啟用允許所有工具（需雙次 Esc 確認，v1.0.36+）
/allow-all on

# 關閉允許所有工具
/allow-all off

# 開發環境：允許編譯和測試，禁止推送和刪除
copilot \
  --allow-tool='shell(mvn)' \
  --allow-tool='shell(gradle)' \
  --allow-tool='write' \
  --deny-tool='shell(rm)' \
  --deny-tool='shell(git push)' \
  --deny-tool='shell(git push --force)'

# CI/CD 環境：全自動但限制特定操作
copilot -p "執行測試並產生報告" \
  --allow-tool='shell(mvn test)' \
  --deny-tool='shell(rm)' \
  --deny-tool='shell(curl)' \
  --deny-tool='shell(wget)'

# 啟用 YOLO Mode（互動式）
/yolo

# 或使用命令列選項
copilot --yolo
copilot --allow-all

// .github/hooks/hooks.json
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "shell",
        "command": "python3 .github/hooks/validate-command.py",
        "timeout": 5,
        "permission": "deny"
      }
    ]
  }
}

# .github/hooks/validate-command.py
import sys, os, json

# 從環境變數取得即將執行的指令
command = os.environ.get("TOOL_INPUT", "")

# 定義黑名單指令
BLACKLIST = [
    "rm -rf /", "rm -rf ~", "rm -rf .",
    "git push --force", "git reset --hard",
    "curl | bash", "wget | bash",
    "chmod 777", "dd if=",
]

for blocked in BLACKLIST:
    if blocked in command:
        print(f"BLOCKED: 危險指令被 Hook 攔截 - {blocked}", file=sys.stderr)
        sys.exit(1)

sys.exit(0)

{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "shell",
        "command": "echo \"$(date -Iseconds) | $USER | $TOOL_NAME | $TOOL_INPUT\" >> /var/log/copilot-audit.log"
      },
      {
        "matcher": "write",
        "command": "echo \"$(date -Iseconds) | FILE_WRITE | $FILE_PATH\" >> /var/log/copilot-audit.log"
      }
    ]
  }
}

# 背景任務（Ctrl+X → B）遵守 Session 的權限設定
# 不會新增額外的批准對話框
# 背景任務使用獨立的 Sub-agent，不共用主 Session 的對話歷史

[Shift+Tab 切換到 Plan Mode]

> 在現有的 Spring Boot 專案中建立客戶管理模組。
  需求：
  1. Customer Entity：id, name, email, phone, address, createdAt, updatedAt
  2. REST API：
     - GET /api/v1/customers（分頁查詢）
     - GET /api/v1/customers/{id}
     - POST /api/v1/customers
     - PUT /api/v1/customers/{id}
     - DELETE /api/v1/customers/{id}
  3. 使用 Clean Architecture
  4. 使用 JPA + PostgreSQL
  5. 包含 Swagger 文件
  6. 包含完整 JUnit 5 + Mockito 測試

📋 Implementation Plan

Phase 1: Domain Layer
  ├── 建立 Customer Entity
  ├── 建立 CustomerRepository Interface
  └── 驗證 Entity 映射

Phase 2: Service Layer
  ├── 建立 CustomerDTO
  ├── 建立 CustomerService Interface
  ├── 建立 CustomerServiceImpl
  └── 建立 CustomerMapper

Phase 3: API Layer
  ├── 建立 CustomerController
  ├── 建立 CreateCustomerRequest
  ├── 建立 UpdateCustomerRequest
  └── 設定 Swagger 標註

Phase 4: Testing
  ├── CustomerServiceTest（Unit Test）
  ├── CustomerControllerTest（MockMvc）
  └── CustomerRepositoryTest（DataJpaTest）

Phase 5: Documentation
  └── 更新 API 文件

預估產生 12 個檔案，約 1,200 行程式碼

@Entity
@Table(name = "customers")
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Customer {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String name;

    @Column(nullable = false, unique = true, length = 255)
    private String email;

    @Column(length = 20)
    private String phone;

    @Column(length = 500)
    private String address;

    @CreationTimestamp
    @Column(updatable = false)
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;
}

@RestController
@RequestMapping("/api/v1/customers")
@RequiredArgsConstructor
@Tag(name = "Customer Management", description = "客戶管理 API")
public class CustomerController {

    private final CustomerService customerService;

    @GetMapping
    @Operation(summary = "分頁查詢客戶")
    public ResponseEntity<Page<CustomerDTO>> getCustomers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return ResponseEntity.ok(customerService.findAll(PageRequest.of(page, size)));
    }

    @GetMapping("/{id}")
    @Operation(summary = "根據 ID 查詢客戶")
    public ResponseEntity<CustomerDTO> getCustomer(@PathVariable Long id) {
        return ResponseEntity.ok(customerService.findById(id));
    }

    @PostMapping
    @Operation(summary = "建立客戶")
    public ResponseEntity<CustomerDTO> createCustomer(
            @Valid @RequestBody CreateCustomerRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(customerService.create(request));
    }

    @PutMapping("/{id}")
    @Operation(summary = "更新客戶")
    public ResponseEntity<CustomerDTO> updateCustomer(
            @PathVariable Long id,
            @Valid @RequestBody UpdateCustomerRequest request) {
        return ResponseEntity.ok(customerService.update(id, request));
    }

    @DeleteMapping("/{id}")
    @Operation(summary = "刪除客戶")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteCustomer(@PathVariable Long id) {
        customerService.delete(id);
    }
}

> 線上環境在批量匯入客戶資料時，偶發 DataIntegrityViolationException。
  相關檔案：@CustomerImportService.java
  
  請:
  1. 分析可能的根因
  2. 修復問題
  3. 產生回歸測試

🔍 根因分析：

1. 讀取 CustomerImportService.java...
2. 發現問題在 batchImport() 方法：
   - 第 45 行：未檢查 email 是否已存在
   - 第 52 行：批量 saveAll() 未使用 Transaction
   - 高併發場景下可能出現 duplicate key 衝突

📝 修復方案：
1. 匯入前先檢查 email 重複
2. 使用 @Transactional 確保原子性
3. 加入 retry 機制處理 OptimisticLockException

@Test
@DisplayName("should_HandleDuplicateEmails_When_BatchImport")
void shouldHandleDuplicateEmailsWhenBatchImport() {
    // Given
    List<CustomerImportDTO> batch = List.of(
        new CustomerImportDTO("Alice", "alice@example.com"),
        new CustomerImportDTO("Alice2", "alice@example.com")  // 重複 email
    );

    // When
    ImportResult result = customerImportService.batchImport(batch);

    // Then
    assertThat(result.getSuccessCount()).isEqualTo(1);
    assertThat(result.getFailedCount()).isEqualTo(1);
    assertThat(result.getErrors()).hasSize(1);
    assertThat(result.getErrors().get(0).getReason()).contains("duplicate email");
}

@Test
@DisplayName("should_RollbackAll_When_CriticalErrorOccurs")
void shouldRollbackAllWhenCriticalErrorOccurs() {
    // Given
    List<CustomerImportDTO> batch = createLargeBatch(1000);
    doThrow(new RuntimeException("DB connection lost"))
        .when(customerRepository).saveAll(anyList());

    // When & Then
    assertThrows(ImportException.class,
        () -> customerImportService.batchImport(batch));
    
    // 確認沒有部分資料被寫入
    assertThat(customerRepository.count()).isEqualTo(0);
}

> Commit 目前所有變更，使用 Conventional Commit 格式。
  然後建立 PR 到 develop 分支。
  PR 標題：feat: 實作 JWT 認證模組
  自動產生 Summary，包含：
  - 變更摘要
  - 修改的檔案清單
  - 測試結果
  - 部署注意事項
  指派 Reviewer：@tech-lead, @security-reviewer
  標籤：feature, security, needs-review

# 1. Commit
git add -A
git commit -m "feat(auth): 實作 JWT 認證模組

- 新增 JWT Token 產生與驗證服務
- 新增 Spring Security 設定
- 新增認證相關 API endpoint
- 新增 23 個單元測試"

# 2. Push 分支
git push origin feature/jwt-auth

# 3. 建立 PR（透過 GitHub API）
# 自動生成以下 Summary...

## 📋 Summary

本 PR 實作 JWT 認證模組，為系統提供完整的身份驗證機制。

### 🔧 主要變更

| 類型 | 檔案 | 說明 |
|------|------|------|
| 新增 | `AuthController.java` | 認證 API（登入/登出/Refresh） |
| 新增 | `JwtTokenService.java` | JWT Token 管理 |
| 新增 | `SecurityConfig.java` | Spring Security 設定 |
| 新增 | `JwtAuthenticationFilter.java` | JWT 過濾器 |
| 修改 | `application.yml` | JWT 相關設定 |
| 新增 | `AuthServiceTest.java` | 認證測試（23 cases） |

### ✅ 測試結果
- 單元測試：23/23 ✅
- 整合測試：8/8 ✅
- 覆蓋率：87%

### ⚠️ 部署注意事項
1. 需設定環境變數：`JWT_SECRET`, `JWT_EXPIRATION`
2. 需在 Redis 中啟用 Token 黑名單功能
3. 資料庫需執行 migration：`V2__add_refresh_token_table.sql`

### 🔒 安全考量
- Token 有效期：Access Token 30 分鐘，Refresh Token 7 天
- 使用 RS256 演算法簽名
- Refresh Token 使用一次即失效（Rotation）

> 建立一個 Spring Batch Job：
  名稱：DailyTransactionReportJob
  功能：
  1. 讀取當日所有交易（從 transactions 表）
  2. 按銀行代碼分組統計
  3. 產生 CSV 報表輸出到 /reports/ 目錄
  4. 發送統計摘要到指定 Email
  
  要求：
  - 使用 Spring Batch 5.x
  - 支持斷點續跑（Restartable）
  - 支持分區處理（Partitioning）大量資料
  - 記錄 Job 執行日誌
  - 加入 Retry 機制（最多 3 次）
  - 使用 @Scheduled 設定每日凌晨 2:00 執行

@Configuration
@EnableBatchProcessing
public class DailyTransactionReportJobConfig {

    @Bean
    public Job dailyTransactionReportJob(
            JobRepository jobRepository,
            Step partitionStep,
            Step emailNotificationStep) {
        return new JobBuilder("dailyTransactionReportJob", jobRepository)
                .incrementer(new RunIdIncrementer())
                .start(partitionStep)
                .next(emailNotificationStep)
                .listener(new JobExecutionListener() {
                    @Override
                    public void beforeJob(JobExecution jobExecution) {
                        log.info("開始執行每日交易報表 Job: {}", 
                            LocalDate.now());
                    }
                    @Override
                    public void afterJob(JobExecution jobExecution) {
                        log.info("每日交易報表 Job 完成，狀態: {}",
                            jobExecution.getStatus());
                    }
                })
                .build();
    }

    @Bean
    public Step partitionStep(
            JobRepository jobRepository,
            Step processStep,
            Partitioner bankCodePartitioner) {
        return new StepBuilder("partitionStep", jobRepository)
                .partitioner("processStep", bankCodePartitioner)
                .step(processStep)
                .gridSize(10)
                .taskExecutor(new SimpleAsyncTaskExecutor())
                .build();
    }

    @Bean
    public Step processStep(
            JobRepository jobRepository,
            PlatformTransactionManager transactionManager) {
        return new StepBuilder("processStep", jobRepository)
                .<Transaction, TransactionSummary>chunk(1000, transactionManager)
                .reader(transactionReader(null))
                .processor(transactionProcessor())
                .writer(csvReportWriter(null))
                .faultTolerant()
                .retryLimit(3)
                .retry(DataAccessException.class)
                .build();
    }
}

     具體 + 有上下文 + 有預期結果 = 好 Prompt

[任務目標]（一句話描述要做什麼）

[上下文]（參考哪些檔案，@ 引用）

[技術規範]（使用的框架、版本、設計模式）

[輸出要求]（格式、命名、結構）

[限制條件]（不要做什麼、邊界條件）

[驗證標準]（如何確認完成）

# 使用 Ask Mode 或 Explore Agent 了解既有程式碼
> 請分析 @src/auth/ 模組的架構，包含：
  - 認證流程
  - Token 管理機制
  - 與其他模組的依賴關係

# 切換到 Plan Mode（Shift+Tab 切換）
> 基於上述分析，規劃將認證從 Session-based 改為 JWT：
  - 列出需修改的檔案
  - 標示高風險變更
  - 定義向後相容策略
  - 設計 Migration 步驟

# 切換到 Autopilot Mode，按計畫逐步實作
> 按照計畫執行 Step 1：建立 JWT Utility 類別

# 完成後建立 PR
/pr
> 為上述變更建立 PR，包含完整測試結果與部署注意事項

# 啟動時命名（便於後續 resume）
copilot --name "feat/jwt-auth-migration"

# 事後命名
/rename jwt-auth-migration

# 自動命名
/rename
# Copilot 根據對話內容自動產生名稱

大型任務（如 API 重構）
├── Session 1: Explore（探索現狀，產出分析報告）
├── Session 2: Plan（設計方案，產出 plan.md）
├── Session 3: Code - Part 1（核心邏輯）
├── Session 4: Code - Part 2（整合測試）
└── Session 5: Commit & PR

# 允許所有 git 子命令
copilot --allow-tool='shell(git:*)'

# 允許 npm 與 node 相關指令
copilot --allow-tool='shell(npm:*)' --allow-tool='shell(node:*)'

# 允許特定 MCP Server 的所有工具
copilot --allow-tool='github'

# 禁止危險操作
copilot --deny-tool='shell(git push --force)' --deny-tool='shell(rm -rf)'

# 企業開發者日常啟動指令
copilot \
  --allow-tool='shell(git:*)' \
  --allow-tool='shell(mvn:*)' \
  --allow-tool='shell(npm:*)' \
  --allow-tool='shell(docker:*)' \
  --deny-tool='shell(git push --force)' \
  --deny-tool='shell(rm -rf)' \
  --deny-tool='shell(kubectl delete)'

<!-- .github/copilot-instructions.md -->
## 工具使用規範
- 允許：git、mvn、npm、docker 相關操作
- 禁止：git push --force、rm -rf /、kubectl delete namespace
- 所有資料庫操作需人工確認
- 不得修改 .env、secrets/、certs/ 目錄中的檔案

# npm
npm update -g @github/copilot

# WinGet (Windows)
winget upgrade GitHub.Copilot

# Homebrew (macOS / Linux)
brew upgrade copilot-cli

# 安裝腳本（重新執行即可）
curl -fsSL https://gh.io/copilot-install | bash

# 查看目前版本
copilot --version

# 查看可用更新
npm outdated -g @github/copilot

# 在 CI/CD 中鎖定版本
npm install -g @github/copilot@1.0.39

# 在團隊文件中記錄版本
# docs/tool-versions.md
# - Copilot CLI: v1.0.39 (2026-04-28)
# - 上次升級日期：2026-04-28
# - 下次評估日期：2026-07-28

# 在互動式介面中查看使用統計
/usage
# 顯示：Premium Requests 使用量、session 時長、編輯行數、Token 統計

/context
# 顯示：Context Window 使用情況

# 查看更新說明並執行更新
/update

# 查看更新說明（非互動式）
copilot update

# 檢查目前版本
copilot --version

# 升級（各平台）
/upgrade    # 互動式內建指令

# 安裝 nightly 頻道
npm install -g @github/copilot@nightly

# 查看 nightly 版本資訊
copilot --version
# 顯示如：1.0.40-nightly.2026.04.28

# 回到穩定版
npm install -g @github/copilot@latest

在現有 Spring Boot 專案中建立 {模組名稱} 的 REST API：

Entity：
- {欄位定義}

API：
- GET /api/v1/{resource}（分頁查詢，支援 filter）
- GET /api/v1/{resource}/{id}
- POST /api/v1/{resource}
- PUT /api/v1/{resource}/{id}
- DELETE /api/v1/{resource}/{id}

規範：
- 使用 Clean Architecture
- DTO 與 Entity 分離
- @Valid 驗證 Request
- @Operation Swagger 註解
- 統一 ErrorResponse 處理
- Log4j2 記錄關鍵操作

請同時產生 JUnit 5 + Mockito 測試。

Bug 描述：{問題描述}
重現步驟：{步驟}
相關檔案：@{file1}, @{file2}
線上日誌：{錯誤訊息}

請：
1. 分析根因
2. 提出修復方案（不影響現有功能）
3. 產生回歸測試
4. 說明修復可能的 Side Effect

將目前分支變更建立 PR：
- 目標分支：{branch}
- 標題：{type}: {description}
- 自動產生 Summary（含變更摘要、測試結果、部署注意事項）
- 標籤：{labels}
- Reviewer：{reviewers}

建立 GitHub Actions workflow：
- 觸發條件：PR to {branch} + 手動觸發
- 步驟：
  1. Maven 編譯（JDK {version}）
  2. JUnit 測試
  3. JaCoCo 覆蓋率（最低 {percentage}%）
  4. SonarQube 靜態分析
  5. OWASP Dependency Check
  6. Docker 映像建置
- 失敗時通知 Teams

建立 Flyway migration 腳本：
- 版本：V{number}__{description}.sql
- 操作：{新增表/修改欄位/建立索引}
- 需考慮：
  - 與現有資料的相容性
  - 大資料量的加索引策略（CONCURRENTLY）
  - Rollback 方案