
如果 AI 能一次看見你的整個程式碼庫,而不只是單一檔案,會怎樣?
在本章中,你將解鎖 GitHub Copilot CLI 的真正威力:情境。你將學會使用 @ 語法來參照檔案與目錄,讓 Copilot CLI 能深入理解你的程式碼庫。你會發現如何在多個工作階段間維持對話、在數天後精確地從上次中斷處繼續工作,並了解跨檔案分析如何抓出單檔檢查完全忽略的錯誤。
完成本章後,你將能夠:
@ 語法參照檔案、目錄與圖片--resume 與 --continue 恢復先前的工作階段⏱️ 預估時間:約 50 分鐘(閱讀 20 分鐘 + 實作 30 分鐘)

就像你的同事一樣,Copilot CLI 不是讀心術專家。提供更多資訊能幫助人類與 Copilot 都給出更精準的協助!
想像你要向同事解釋一個 bug:
沒有情境:「書籍應用程式壞掉了。」
有情境:「請看
books.py,特別是find_book_by_title函式。它沒有做不分大小寫比對。」
要為 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
這就是情境成為超能力的地方。單檔分析很有用,跨檔案分析則徹底改變遊戲規則。

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
為什麼這很重要:單檔檢查會錯過整體脈絡。只有跨檔案分析才能發現:

剛加入新專案?用 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 --resume="my book app review"
💡 如何找到工作階段 ID? 你不需要記住它們。執行
copilot --resume(不帶 ID)會顯示互動式清單,列出你的所有先前工作階段、名稱、ID 及最後活動時間。直接選擇你要的即可。多個終端機怎麼辦? 每個終端機視窗都是獨立的工作階段,有自己的情境。如果你在三個終端機開啟 Copilot CLI,就是三個不同的工作階段。從任一終端機執行
--resume都能瀏覽全部。--continue旗標會優先抓取目前工作目錄的工作階段;若無則選最近活動的。可以不用重啟就切換工作階段嗎? 可以。在現有工作階段內用
/resumeslash 指令:> /resume # 顯示可切換的工作階段清單
給工作階段取有意義的名稱,方便日後查找。你可以在啟動時命名,也可在工作階段內隨時重新命名:
# 啟動時直接命名
copilot --name book-app-review
# 或在工作階段內重新命名
copilot
> /rename book-app-review
# 工作階段已重新命名,方便辨識
命名後,你可以直接用名稱恢復,不必瀏覽清單:
copilot --resume=book-app-review
要清理不需要的工作階段,可在工作階段內用 /session delete:
copilot
> /session delete # 刪除目前工作階段
> /session delete abc123 # 依 ID 刪除特定工作階段
> /session delete-all # 刪除所有工作階段(請小心使用!)
隨著你加入檔案與對話,Copilot CLI 的 情境窗口 會逐漸填滿。有多種指令可協助你掌控:
copilot
> /context
Context usage: 62k/200k tokens (31%)
> /clear
# 放棄目前工作階段(不儲存歷史),開始全新對話
> /new
# 結束目前工作階段(儲存至歷史以便搜尋/恢復),開始全新對話
> /rewind
# 開啟時間軸選擇器,讓你回到對話中的較早階段
💡 何時用
/clear或/new:如果你剛審查完 books.py,想切換討論 utils.py,請先執行 /new(或 /clear 若不需保留歷史)。否則舊主題的情境可能讓回應混亂。
💡 操作錯誤或想嘗試不同路徑? 用
/rewind(或連按兩次 Esc)開啟時間軸選擇器,可回到對話中任一早期階段,不只最近一次。這在走錯路時很實用,能回溯而不必全部重來。

結束時自動儲存工作階段。數天後恢復,完整情境(檔案、問題、進度)都會被記住。
想像這樣的多天工作流程:
# 週一:一開始就用名稱啟動書籍應用程式審查
copilot --name 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 --resume=book-app-review
> 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 仍記得:
無需重複解釋、重讀檔案,直接繼續工作。
🎉 你已掌握所有必備技巧! @ 語法、工作階段管理(--name/--continue/--resume//rename)、情境指令(/context//clear)已足夠讓你高效工作。以下內容為進階選讀,準備好時再回來即可。

這些主題建立在前述基礎之上。挑你有興趣的看,或直接跳到練習。
| 我想學習… | 跳至 |
|---|---|
| 萬用字元模式與進階工作階段指令 | 進階 @ 模式與工作階段指令 |
| 多輪提示下的情境延續 | 情境感知對話 |
Token 限制與 /compact |
理解情境窗口 |
| 如何挑選要參照的檔案 | 選擇參照對象 |
| 分析截圖與設計稿 | 圖片應用 |
*情境窗口就像一張桌子:一次只能放有限的東西。檔案、對話歷史與系統提示都會佔空間。*
#### 達到上限時會發生什麼
```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` | 移除不相關的情境 |
| 走錯路 | `/rewind` | 回到任一早期階段 |
| 對話很長 | `/compact` | 摘要歷史,釋放 token |
| 只需特定檔案 | `@file.py` 非 `@folder/` | 只載入所需內容 |
| 達到上限 | `/new` 或 `/clear` | 全新情境 |
| 多主題 | 每主題用 `/rename` | 容易恢復正確工作階段 |
#### 大型程式碼庫最佳實踐
1. **具體明確**:用 `@samples/book-app-project/books.py` 取代 `@samples/book-app-project/`
2. **主題切換時清除情境**:切換焦點時用 `/new` 或 `/clear`
3. **善用 `/compact`**:摘要對話,釋放情境
4. **多工作階段並行**:每個功能或主題用一個工作階段

是時候實際應用你的情境與工作階段管理技巧了。
本課程已附範例檔案,直接用來練習。啟動 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
完成示範後,請嘗試下列變化:1. 跨檔案挑戰:分析 book_app.py 和 books.py 如何協同運作:
copilot
> @samples/book-app-project/book_app.py @samples/book-app-project/books.py
> 這兩個檔案之間有什麼關係?有沒有任何程式碼異味?
Session 挑戰:啟動一個 session,使用 /rename my-first-session 命名,進行一些操作,然後用 /exit 離開,再執行 copilot --continue。它還記得你剛才在做什麼嗎?
Context 挑戰:在 session 進行中執行 /context。你目前用了多少 token?試試 /compact,再檢查一次。(更多關於 /compact 的說明,請參見「理解 Context Window」章節。)
自我檢查:當你能解釋為什麼 @folder/ 比逐一開啟每個檔案更強大時,就代表你已經理解 context。
前面的實作範例著重於程式碼品質審查與輸入驗證。現在請用相同的 context 技巧,練習另一個任務:追蹤資料在應用程式中的流動方式:
copilotbooks.py 和 book_app.py:
@samples/book-app-project/books.py @samples/book-app-project/book_app.py 追蹤一本書如何從使用者輸入到被儲存到 data.json。每個步驟涉及哪些函式?@samples/book-app-project/data.json 如果這個 JSON 檔案遺失或損毀會發生什麼事?哪些函式會失敗?@samples/book-app-project/books.py @samples/book-app-project/utils.py 建議一個可在這兩個檔案中一致運作的錯誤處理策略。/rename data-flow-analysis/exit 離開,然後用 copilot --continue 回到 session,並針對資料流提出後續問題成功標準:你能跨多個檔案追蹤資料流、恢復命名的 session,並獲得跨檔案的建議。