copilot-cli-for-beginners
如果 AI 能看到你的整個程式碼庫，而不是一次只看一個檔案，會怎樣？
本章將解鎖 GitHub Copilot CLI 的真正威力：上下文（Context）。你將學習使用 @ 語法來參照檔案和目錄，讓 Copilot CLI 深入理解你的程式碼庫。你將發現如何跨工作階段維護對話、幾天後從中斷處繼續工作，並親眼看到跨檔案分析如何找出單一檔案審查完全看不到的 bug。
🎯 學習目標
完成本章後，你將能夠：
- 使用
@語法參照檔案、目錄和圖片 - 以
--resume和--continue繼續先前的工作階段 - 理解上下文視窗的運作方式
- 撰寫有效的多輪對話
- 管理多專案工作流程的目錄權限
⏱️ 預估時間：約 50 分鐘（閱讀 20 分鐘 + 實作 30 分鐘）
🧩 現實生活類比：與同事協作
就像你的同事一樣，Copilot CLI 不會讀心術。提供更多資訊能幫助人類和 Copilot 提供更有針對性的協助！
想像向同事說明一個 bug：
沒有上下文：「書籍應用程式壞了。」
有上下文：「看看
books.py，特別是find_book_by_title函式。它沒有做大小寫不敏感的比對。」
要向 Copilot CLI 提供上下文，請使用 @ 語法將 Copilot CLI 指向特定檔案。
必學：基本上下文
本節涵蓋有效使用上下文所需的一切。請先掌握這些基礎。
@ 語法
@ 符號用於在提示中參照檔案和目錄，這是你告訴 Copilot CLI「看看這個檔案」的方式。
💡 備註：本課程所有範例都使用此儲存庫內附的
samples/資料夾，讓你可以直接嘗試每個指令。
立即試試（不需任何設定）
你可以用電腦上的任何檔案嘗試：
copilot
# 指向你有的任何檔案
> Explain what @package.json does
> Summarize @README.md
> What's in @.gitignore and why?
💡 手邊沒有專案？ 快速建立一個測試檔案：
echo "def greet(name): return 'Hello ' + name" > test.py copilot > What does @test.py do?
基本 @ 模式
| 模式 | 功能 | 使用範例 |
|---|---|---|
@file.py |
參照單一檔案 | Review @samples/book-app-project/books.py |
@folder/ |
參照目錄中的所有檔案 | Review @samples/book-app-project/ |
@file1.py @file2.py |
參照多個檔案 | Compare @samples/book-app-project/book_app.py @samples/book-app-project/books.py |
參照單一檔案
copilot
> Explain what @samples/book-app-project/utils.py does
🎬 看看實際效果！
 *示範輸出僅供參考，你的模型、工具與回應內容可能與此不同。*參照多個檔案
copilot
> Compare @samples/book-app-project/book_app.py and @samples/book-app-project/books.py for consistency
參照整個目錄
copilot
> Review all files in @samples/book-app-project/ for error handling
跨檔案智慧分析
這正是上下文成為超能力的地方。單一檔案分析很有用，跨檔案分析則是革命性的。
示範：找出橫跨多個檔案的 Bug
copilot
> @samples/book-app-project/book_app.py @samples/book-app-project/books.py
>
> How do these files work together? What's the data flow?
💡 進階選項：若想進行以安全性為重點的跨檔案分析，可以試試 Python 安全性範例：
> @samples/buggy-code/python/user_service.py @samples/buggy-code/python/payment_processor.py > Find security vulnerabilities that span BOTH files
🎬 看看實際效果！
 *示範輸出僅供參考，你的模型、工具與回應內容可能與此不同。*Copilot CLI 發現的內容：
Cross-Module Analysis
=====================
1. DATA FLOW PATTERN
book_app.py creates BookCollection instance and calls methods
books.py defines BookCollection class and manages data persistence
Flow: book_app.py (UI) → books.py (business logic) → data.json (storage)
2. DUPLICATE DISPLAY FUNCTIONS
book_app.py:9-21 show_books() function
utils.py:28-36 print_books() function
Impact: Two nearly identical functions doing the same thing. If you update
one (like changing the format), you must remember to update the other.
3. INCONSISTENT ERROR HANDLING
book_app.py handles ValueError from year conversion
books.py silently returns None/False on errors
Pattern: No unified approach to error handling across modules
為何重要：單一檔案審查會錯過全局。只有跨檔案分析才能揭示：
- 重複程式碼，應當整合
- 資料流模式，顯示元件之間如何互動
- 架構問題，影響可維護性
示範：60 秒內理解一個程式碼庫
剛接觸新專案？用 Copilot CLI 快速了解它。
copilot
> @samples/book-app-project/
>
> In one paragraph, what does this app do and what are its biggest quality issues?
你會得到的內容：
This is a CLI book collection manager that lets users add, list, remove, and
search books stored in a JSON file. The biggest quality issues are:
1. Duplicate display logic - show_books() and print_books() do the same thing
2. Inconsistent error handling - some errors raise exceptions, others return False
3. No input validation - year can be 0, empty strings accepted for title/author
4. Missing tests - no test coverage for critical functions like find_book_by_title
Priority fix: Consolidate duplicate display functions and add input validation.
結果：原本需要一個小時閱讀程式碼的事，壓縮成 10 秒。你確切知道該把注意力放在哪裡。
實際應用範例
範例一：帶上下文的程式碼審查
copilot
> @samples/book-app-project/books.py Review this file for potential bugs
# Copilot CLI 現在擁有完整的檔案內容，可以給出具體回饋：
# "Line 49: Case-sensitive comparison may miss books..."
# "Line 29: JSON decode errors are caught but data corruption isn't logged..."
> What about @samples/book-app-project/book_app.py?
# 現在審查 book_app.py，但仍然知道 books.py 的上下文
範例二：理解程式碼庫
copilot
> @samples/book-app-project/books.py What does this module do?
# Copilot CLI 讀取 books.py 並理解 BookCollection 類別
> @samples/book-app-project/ Give me an overview of the code structure
# Copilot CLI 掃描目錄並進行摘要
> How does the app save and load books?
# Copilot CLI 可以追蹤它已看過的程式碼
🎬 看看多輪對話的實際效果！
 *示範輸出僅供參考，你的模型、工具與回應內容可能與此不同。*範例三：多檔案重構
copilot
> @samples/book-app-project/book_app.py @samples/book-app-project/utils.py
> I see duplicate display functions: show_books() and print_books(). Help me consolidate these.
# Copilot CLI 看到兩個檔案，可以建議如何合併重複的程式碼
工作階段管理
工作階段會在你工作時自動儲存，你可以繼續先前的工作階段從中斷處接著做。
工作階段自動儲存
每次對話都會自動儲存，只需正常離開：
copilot
> @samples/book-app-project/ Let's improve error handling across all modules
[... 進行一些工作 ...]
> /exit
繼續最近的工作階段
# 從上次中斷的地方繼續
copilot --continue
繼續特定工作階段
# 從清單中互動式選擇工作階段
copilot --resume
# 或依 ID 繼續特定工作階段
copilot --resume abc123
整理你的工作階段
為工作階段取有意義的名稱，以便日後找到：
copilot
> /rename book-app-review
# 工作階段已重新命名，方便識別
檢視和管理上下文
隨著你新增檔案和對話，Copilot CLI 的上下文視窗會逐漸填滿。以下兩個指令可以幫助你掌控狀況：
copilot
> /context
Context usage: 45,000 / 128,000 tokens (35%)
> /clear
# 清除上下文並重新開始。切換話題時使用
💡 何時使用
/clear：若你一直在審查books.py，想要切換去討論utils.py，請先執行/clear。否則舊話題的過時上下文可能會干擾新話題的回應。
從上次中斷的地方繼續
工作階段在離開時自動儲存。幾天後繼續，完整上下文依然保留：檔案、問題和進度都被記住了。
想像這個跨越多天的工作流程：
# 週一：開始書籍應用程式審查
copilot
> /rename book-app-review
> @samples/book-app-project/books.py
> Review and number all code quality issues
Quality Issues Found:
1. Duplicate display functions (book_app.py & utils.py) - MEDIUM
2. No input validation for empty strings - MEDIUM
3. Year can be 0 or negative - LOW
4. No type hints on all functions - LOW
5. Missing error logging - LOW
> Fix issue #1 (duplicate functions)
# 進行修正工作...
> /exit
# 週三：從完全相同的地方繼續
copilot --continue
> What issues remain unfixed from our book app review?
Remaining issues from our book-app-review session:
2. No input validation for empty strings - MEDIUM
3. Year can be 0 or negative - LOW
4. No type hints on all functions - LOW
5. Missing error logging - LOW
Issue #1 (duplicate functions) was fixed on Monday.
> Let's tackle issue #2 next
強大之處：幾天後，Copilot CLI 仍然記得：
- 你正在處理的確切檔案
- 問題的編號清單
- 你已解決的項目
- 你的對話上下文
無需重新說明，無需重新讀取檔案，直接繼續工作。
🎉 你現在已掌握基礎知識！ @ 語法、工作階段管理（--continue/--resume//rename）和上下文指令（/context//clear）已足以讓你高效工作。以下內容為選讀，準備好再回來探索。
選讀：深入探索
以下主題建立在上述基礎之上。選擇你感興趣的，或直接跳到實作練習。
| 我想了解… | 跳至 |
|---|---|
| 萬用字元模式與進階工作階段指令 | 更多 @ 模式與工作階段指令 |
| 在多個提示中建立上下文 | 上下文感知對話 |
Token 上限與 /compact |
理解上下文視窗 |
| 如何選擇要參照的檔案 | 選擇要參照的內容 |
| 分析截圖與設計稿 | 使用圖片 |
更多 @ 模式與工作階段指令
### 更多 @ 模式 對進階用戶，Copilot CLI 支援萬用字元模式與圖片參照： | 模式 | 功能 | |------|------| | `@folder/*.py` | 資料夾中所有 .py 檔案 | | `@**/test_*.py` | 遞迴萬用字元：找出任何位置的所有測試檔案 | | `@image.png` | 圖片檔案，用於 UI 審查 | ```bash copilot > Find all TODO comments in @samples/book-app-project/**/*.py ``` ### 工作中切換工作階段 在互動式工作階段中使用 `/resume` 指令： ```bash copilot > /resume # 顯示可切換的工作階段清單 ``` ### 檢視工作階段資訊 ```bash copilot > /session # 顯示目前工作階段詳情與工作區摘要 > /usage # 顯示工作階段指標與統計 ``` ### 分享你的工作階段 ```bash copilot > /share file ./my-session.md # 將工作階段匯出為 Markdown 檔案 > /share gist # 建立包含工作階段內容的 GitHub gist ```上下文感知對話
### 上下文感知對話 多輪對話相互建立時，魔法就發生了。 #### 範例：漸進式強化 ```bash copilot > @samples/book-app-project/books.py Review the BookCollection class Copilot CLI: "The class looks functional, but I notice: 1. Missing type hints on some methods 2. No validation for empty title/author 3. Could benefit from better error handling" > Add type hints to all methods Copilot CLI: "Here's the class with complete type hints..." [Shows typed version] > Now improve error handling Copilot CLI: "Building on the typed version, here's improved error handling..." [Adds validation and proper exceptions] > Generate tests for this final version Copilot CLI: "Based on the class with types and error handling..." [Generates comprehensive tests] ``` 注意每個提示如何建立在前一次的工作上，這就是上下文的威力。理解上下文視窗
### 理解上下文視窗 你已經從基礎知識中了解 `/context` 和 `/clear`。以下是上下文視窗運作方式的深入說明。 每個 AI 都有一個「上下文視窗」，即它能同時考量的文字量。
*上下文視窗就像一張桌子：能放置的東西有限。檔案、對話歷史和系統提示都會佔用空間。*
#### 達到上限時會發生什麼
```bash
copilot
> /context
Context usage: 45,000 / 128,000 tokens (35%)
# 隨著你新增更多檔案和對話，這個數字會增長
> @large-codebase/
Context usage: 120,000 / 128,000 tokens (94%)
# 警告：即將達到上下文上限
> @another-large-file.py
Context limit reached. Older context will be summarized.
```
#### `/compact` 指令
當上下文快滿但又不想失去對話記錄時，`/compact` 可以摘要你的歷史記錄以釋放 token：
```bash
copilot
> /compact
# 摘要對話歷史，釋放上下文空間
# 你的重要發現和決策會被保留
```
#### 上下文效率技巧
| 情境 | 操作 | 原因 |
|------|------|------|
| 開始新話題 | `/clear` | 移除不相關的上下文 |
| 對話很長 | `/compact` | 摘要歷史，釋放 token |
| 需要特定檔案 | `@file.py` 而非 `@folder/` | 只載入需要的內容 |
| 達到上限 | 開始新工作階段 | 全新的 128K 上下文 |
| 多個話題 | 每個話題用 `/rename` | 方便繼續正確的工作階段 |
#### 大型程式碼庫的最佳實踐
1. **精確指定**：用 `@samples/book-app-project/books.py` 而非 `@samples/book-app-project/`
2. **話題間清除**：切換重點時使用 `/clear`
3. **使用 `/compact`**：摘要對話以釋放上下文
4. **使用多個工作階段**：每個功能或話題一個工作階段
選擇要參照的內容
### 選擇要參照的內容 在上下文方面，不是所有檔案都平等。以下是明智選擇的方法： #### 檔案大小考量 | 檔案大小 | 約略 [Token](/GLOSSARY.html#token) 數 | 策略 | |---------|--------------------------------------|------| | 小型（< 100 行） | ~500-1,500 tokens | 自由參照 | | 中型（100-500 行） | ~1,500-7,500 tokens | 參照特定檔案 | | 大型（500+ 行） | 7,500+ tokens | 謹慎選擇，使用特定檔案 | | 超大型（1000+ 行） | 15,000+ tokens | 考慮拆分或鎖定特定章節 | **具體範例：** - 書籍應用程式的 4 個 Python 檔案合計 ≈ 2,000-3,000 tokens - 典型的 Python 模組（200 行）≈ 3,000 tokens - Flask API 檔案（400 行）≈ 6,000 tokens - 你的 package.json ≈ 200-500 tokens - 簡短的提示與回應 ≈ 500-1,500 tokens > 💡 **程式碼的快速估算**：將程式碼行數乘以約 15 來估算 token 數。請注意這只是估算值。 #### 要包含什麼 vs. 排除什麼 **高價值**（包含這些）： - 進入點（`book_app.py`、`main.py`、`app.py`） - 你正在詢問的特定檔案 - 目標檔案直接匯入的檔案 - 設定檔（`requirements.txt`、`pyproject.toml`） - 資料模型或 dataclass **低價值**（考慮排除）： - 生成的檔案（編譯輸出、打包的資源） - Node modules 或 vendor 目錄 - 大型資料檔案或 fixture - 與你的問題無關的檔案 #### 精確度的光譜 ``` 較不精確 ────────────────────────► 更精確 @samples/book-app-project/ @samples/book-app-project/books.py:47-52 │ │ └─ 掃描所有內容 └─ 只取你需要的 （使用更多上下文） （保留上下文空間） ``` **何時選擇廣泛**（`@samples/book-app-project/`）： - 初步探索程式碼庫 - 跨多個檔案尋找模式 - 架構審查 **何時選擇精確**（`@samples/book-app-project/books.py`）： - 除錯特定問題 - 審查特定檔案的程式碼 - 詢問單一函式 #### 實際範例：分階段載入上下文 ```bash copilot # 步驟一：從結構開始 > @package.json What frameworks does this project use? # 步驟二：根據答案縮小範圍 > @samples/book-app-project/ Show me the project structure # 步驟三：聚焦於重要的內容 > @samples/book-app-project/books.py Review the BookCollection class # 步驟四：只在需要時加入相關檔案 > @samples/book-app-project/book_app.py @samples/book-app-project/books.py How does the CLI use the BookCollection? ``` 這種分階段的方式讓上下文保持專注且高效。使用圖片
### 使用圖片 你可以使用 `@` 語法在對話中加入圖片，也可以直接**從剪貼簿貼上**（Cmd+V / Ctrl+V）。Copilot CLI 可以分析截圖、設計稿和圖表，協助 UI 除錯、設計實作和錯誤分析。 ```bash copilot > @images/screenshot.png What is happening in this image? > @images/mockup.png Write the HTML and CSS to match this design. Place it in a new file called index.html and put the CSS in styles.css. ``` > 📖 **深入了解**：參見[附錄：額外上下文功能](/appendices/additional-context.html#working-with-images)，了解支援的格式、實際使用案例，以及將圖片與程式碼結合的技巧。實作練習
是時候應用你的上下文與工作階段管理技能了。
▶️ 自行嘗試
完整專案審查
本課程包含你可以直接審查的範例檔案。啟動 Copilot 並執行以下提示：
copilot
> @samples/book-app-project/ Give me a code quality review of this project
# Copilot CLI 會找出以下問題：
# - 重複的顯示函式
# - 缺少輸入驗證
# - 不一致的錯誤處理
💡 想用自己的檔案試試？ 建立一個小型 Python 專案（
mkdir -p my-project/src），新增一些 .py 檔案，然後用@my-project/src/來審查它們。如果需要，你可以請 Copilot 為你建立範例程式碼！
工作階段工作流程
copilot
> /rename book-app-review
> @samples/book-app-project/books.py Let's add input validation for empty titles
[Copilot CLI 建議驗證方式]
> Implement that fix
> Now consolidate the duplicate display functions in @samples/book-app-project/
> /exit
# 稍後——從上次中斷的地方繼續
copilot --continue
> Generate tests for the changes we made
完成示範後，試試這些變化：
- 跨檔案挑戰：分析 book_app.py 和 books.py 如何協作：
copilot > @samples/book-app-project/book_app.py @samples/book-app-project/books.py > What's the relationship between these files? Are there any code smells? -
工作階段挑戰：開始一個工作階段，用
/rename my-first-session命名，做些事情，用/exit離開，然後執行copilot --continue。它記得你在做什麼嗎？ - 上下文挑戰：在工作階段中途執行
/context。你使用了多少 token？試試/compact後再次確認。（更多關於/compact的說明請見「深入探索」中的理解上下文視窗。）
自我檢驗：當你能解釋為何 @folder/ 比個別開啟每個檔案更強大時，你就掌握了上下文的精髓。
📝 作業
主要挑戰：追蹤資料流
實作範例專注於程式碼品質審查和輸入驗證。現在在不同任務上練習相同的上下文技能——追蹤資料如何在應用程式中流動：
- 啟動互動式工作階段：
copilot - 同時參照
books.py和book_app.py：@samples/book-app-project/books.py @samples/book-app-project/book_app.py Trace how a book goes from user input to being saved in data.json. What functions are involved at each step? - 加入資料檔案以提供更多上下文：
@samples/book-app-project/data.json What happens if this JSON file is missing or corrupted? Which functions would fail? - 請求跨檔案改善建議：
@samples/book-app-project/books.py @samples/book-app-project/utils.py Suggest a consistent error-handling strategy that works across both files. - 重新命名工作階段：
/rename data-flow-analysis - 以
/exit離開，然後用copilot --continue繼續，並就資料流提出後續問題
成功標準：你能夠追蹤跨多個檔案的資料流、繼續已命名的工作階段，並取得跨檔案的改善建議。