GitHub Copilot 企業級軟體開發教學手冊

Enterprise GitHub Copilot AI Software Engineering Handbook
把 GitHub Copilot 當成 企業級 AI 軟體工程平台（AI Software Engineering Platform） 導入 Web 應用開發、Legacy 逆向工程、Framework 升版、測試、Code Review、DevSecOps、CI/CD 與 AI 治理的完整實作手冊

文件資訊

可信度標示制度（請務必先讀）

GitHub Copilot 在 2025–2026 年間的產品架構變動幅度極大：功能改名、機制日落、新機制 GA，全部發生在 12 個月內。網路上（包含中文技術部落格、影片教學、AI 產生的文章）有大量內容已經過時，而且過時的部分往往正是企業最在意的治理與安全設定。

為避免讀者把「本手冊的企業實務建議」誤讀成「GitHub 官方規範」，本手冊在每個小節標題後標註來源等級：

凡涉及版本行為差異之處，一律以下列格式標註：

⚠️ Version Note

說明哪個版本 / 哪個時間點之前與之後的行為不同。

本手冊的提示方塊符號約定：

十一個必須先知道的事實與版本差異

在讀任何舊教學、舊部落格文章、或任何 AI 產生的 Copilot 教學之前，先記住這十一件事。它們每一項都足以讓整篇教學寫錯，而其中 Version Note 9、10 與 11 是 2026 年下半年新增、且會在管理員未採取任何動作的情況下自動生效的變更。

⚠️ Version Note 1：「Copilot coding agent」已更名為「Copilot cloud agent」

官方文件現行正式名稱是 GitHub Copilot cloud agent。舊名 Copilot coding agent 仍大量存在於 2025 至 2026 上半年的文章、影片與部分尚未更新的 URL 路徑中（例如舊路徑 /concepts/agents/coding-agent/about-coding-agent 仍可存取，但現行路徑是 /concepts/agents/cloud-agent/about-cloud-agent）。 更名之後，連 Copilot usage metrics API 都新增了 used_copilot_cloud_agent 欄位。若你的稽核報表、儀表板或內部規範文件還在用 coding agent 一詞，請一併更新，否則跨團隊溝通會出現「兩個東西還是同一個東西」的混淆。 本手冊全書一律使用 Copilot cloud agent。

⚠️ Version Note 2：Copilot cloud agent ≠ IDE Agent Mode，這是兩個完全不同的東西

這是企業導入時最常見、也最昂貴的誤解。

• IDE Agent Mode（自主代理模式）：跑在你的本機，直接改你工作目錄裡的檔案，你在 IDE 裡逐步核可。
• Copilot cloud agent：跑在 GitHub Actions 驅動的雲端臨時環境（ephemeral environment），clone 你的 repository，在分支上改 code，最後開一個 Pull Request。單一 session 的執行時間硬上限為 59 分鐘，且一次只能在一個分支上工作、一個任務只能開一個 PR。

兩者的權限模型、治理方式、稽核方式、成本模型全部不同。把它們寫成同一件事的企業規範，一定會出事。詳見第 3 章 與第 9 章。

⚠️ Version Note 3：.chatmode.md 已更名為 .agent.md（Custom Agents）

早期的「自訂交談模式（custom chat modes）」使用 .chatmode.md 副檔名。官方已正式更名為 Custom Agents，檔案格式改為 .agent.md（或在 .github/agents/ 下的 .md）。功能本質未變，但所有文件、範例與內部規範都必須更新命名，否則新進人員會找不到官方文件對應章節。

🚨 Version Note 4：GitHub Copilot Extensions（GitHub App 機制）已日落，與現行的 Copilot Plugins 完全不同

舊的 Copilot Extensions（以 GitHub App 形式擴充 Copilot Chat）已於 2025-11-10 正式終止。 現行的擴充機制是 Copilot Plugins（Agent Plugins 1.0，2026-08-12 GA），是一種以 plugin.json 為 manifest 的可散布套件，可以打包 Custom Agents、Skills、Hooks、MCP 設定與 LSP 設定。 兩者是完全不同的機制，不可混為一談。 若企業內部還有依賴 Copilot Extensions 的自建整合，必須排入汰換計畫。詳見第 15 章。

⚠️ Version Note 5：Custom Agent、Agent Skill、Custom Instructions、Prompt File、MCP、Plugin 是六種不同的機制

這六者經常被混用，但它們的檔案位置、觸發方式、支援介面都不同：

機制	檔案	觸發方式
Custom Instructions	.github/copilot-instructions.md、.github/instructions/**/*.instructions.md、AGENTS.md	自動套用
Prompt Files	.github/prompts/*.prompt.md	手動叫用
Custom Agents	.github/agents/AGENT-NAME.md	下拉選單手動選擇 / 模型自動調度
Agent Skills	.github/skills/<skill-name>/SKILL.md	模型依 description 自動判斷載入，或以 /skill-name 叫用
MCP	mcp-config.json、.mcp.json、IDE 專屬設定	提供工具給模型呼叫
Plugins	plugin.json	安裝後啟用，內含上述多種資源

完整比較見第 12 章。

⚠️ Version Note 6：Copilot 的個人方案已經有五階，不再只有 Free / Pro

目前個人方案為 Free、Pro、Pro+、Max，組織／企業方案為 Business、Enterprise。 同時計費模型已從舊的「Premium requests（進階請求）」轉向 GitHub AI Credits（AI 額度），官方文件把舊制標示為 request-based billing (legacy)。若你的內部成本模型還在用 premium request 換算，數字會對不上。詳見第 5 章。

⚠️ Version Note 7：企業管控檔案是 managed-settings.json，不是 IDE 的 settings.json

企業層級的強制設定使用 Enterprise Managed Settings，檔名 managed-settings.json，透過 MDM（行動裝置管理）或組態管理工具佈署到終端機。 它與開發者自己的 ~/.copilot/settings.json、repository 的 .github/copilot/settings.json 是不同的檔案、不同的優先權層級。設定優先權由低到高為：內建預設 → MDM 管控設定 → 使用者設定 → Repository 設定 → 本機設定 → 環境變數 → 命令列參數；但其中 permissions.disableBypassPermissionsMode 設為 "disable" 時永遠優先，而 MDM 的 sandbox 設定建立的是使用者無法放寬的最低基線。詳見第 6 章。

🚨 Version Note 8：不要把 Claude Code / Cursor / Codex CLI 的設定方式套到 Copilot

這幾個工具的概念詞彙高度重疊（agent、skill、hook、MCP、sandbox），但設定檔位置與 schema 完全不同。 唯一的例外是 GitHub 官方明確宣告相容的部分：Copilot 會讀取 AGENTS.md、CLAUDE.md、GEMINI.md 作為 agent instructions，Agent Skills 也會掃描 .claude/skills/ 與 .agents/skills/ 目錄——這是刻意設計的跨工具開放標準相容性，不代表其他設定可以互通。 除此之外，任何「把 .cursorrules 改個名字就能用」「Claude Code 的 settings.json 直接複製過來」的說法都是錯的。

🚨 Version Note 9：Global Model Policy 已 GA——「沒設定」現在等於「全部開放」

2026-08-26，Global model policy 正式 GA（先前於 2026-07-29 公告並給予 28 天設定緩衝期）。 這項變更反轉了 Copilot Business / Enterprise 沿用已久的預設行為：

	GA 之前	GA 之後（現行）
新模型 GA 時	預設關閉，管理員必須逐一手動啟用	預設開啟，除非管理員曾明確設定過該模型
管理員未做任何設定	等同「全部擋住」	等同「全部放行」

也就是說，過去「不設定」是安全的，現在「不設定」是最不安全的。任何管理員從未明確配置過的模型，都會自動對使用者開放——包含新上架的第三方供應商模型（xAI Grok、Moonshot Kimi、Google Gemini、Anthropic Claude、Microsoft MAI 等）。

若貴司有「僅允許特定資料處理地區／特定供應商」的法遵要求，必須主動維護模型政策白名單，不能再依賴預設值。詳見第 5.6 節 與第 6.10 節。

🚨 Version Note 10：Copilot Chat 的資料保留期限將從 28 天延長為「帳號生命週期」

隨著 2026-09-28（官方措辭為「不早於」該日） 的**統一 Copilot 體驗（unified Copilot experience）**上線，github.com 的 Copilot Chat、GitHub Mobile 的 Copilot Chat 與 Copilot cloud agent 將合併為單一體驗、套用單一政策，同時：

• Chat 資料保留期限由 28 天延長為帳號存續期間；
• 統一體驗預設啟用；
• 選擇退出（opt out）的代價是失去 github.com 與 GitHub Mobile 上的 Copilot 存取權——這不是「關掉一個功能」，而是「關掉整個介面」。

對於受 GDPR、個資法或內部資料保留政策約束的企業，這是必須在上線日前完成評估與內部公告的變更。詳見第 6.12 節。

📌 v1.2 狀態更新（2026-09-25）：官方仍維持「不早於 2026-09-28」的措辭，截至查證日尚未公告確切上線日。

🚨 Version Note 11：2026-10-22 起，「未設定」的 GA 功能將依企業全域預設自動開啟

🆕 v1.2 新增

繼 Global Model Policy（Version Note 9）之後，官方把同樣的「預設開放」邏輯延伸到功能層：Copilot Business／Enterprise 的 「Default policy for new features」 政策將於 2026-10-22 開始生效（2026-09-24 公告；官方文件載明此政策本身預設為 Enabled）。

項目	內容
適用對象	新 GA 的功能、由預覽轉 GA 的功能，以及目前狀態為 Unconfigured 的既有 GA 功能
明確納入	AI Controls「Features & clients」頁上的所有政策，加上 Copilot code review 與 MCP servers in Copilot 兩項政策
不受影響	預覽功能；資料落地／FedRAMP 模型限制政策；「Store local sessions in the Cloud」
已明確設定者	保留原設定，不會被覆寫

🚨 對本手冊讀者最直接的衝擊：本手冊一再強調「MCP servers in Copilot 預設停用」是企業 MCP 治理的第一道閘門。10-22 之後，若該政策仍是 Unconfigured，它會依全域預設被開啟。 唯一不受未來預設變更影響的狀態，是明確設定。詳見第 6.13 節。

本手冊的引用與誠實原則

1. 本手冊不是官方文件的翻譯。 所有官方事實均經查證後以繁體中文重新組織，並大量補充企業導入實務、Agent 定義、Prompt 範例、比較表、SOP 與 Checklist。
2. 不虛構。 本手冊不編造 URL、CLI 指令、設定 key、frontmatter 欄位或 API。查不到官方說明者，一律明寫「官方文件未說明」或標示【⚠️ 文件不一致】。
3. 價格與方案以官方公告為準。 本手冊引述查證當日的方案結構，但價格與額度會變動，任何商務決策請以 GitHub 官方目前公告為準。
4. 企業案例聲明。 本手冊出現的所有企業情境（common_platform、逆向工程專案、Framework 升版專案、AI Agent Team 等）均為教學示範用途之原創設計，非真實客戶專案，亦不含任何真實 Secret、憑證或個資。
5. 其他 AI 工具的比較為定性比較。 本手冊僅對 GitHub Copilot 欄位做逐項官方查證；比較表中 Claude Code、Codex CLI、Cursor、Gemini 等欄位以各自官方文件既有認知做定性比較，不將任一工具的機制寫成另一工具的規格。

依角色的建議入口【建議】

全書 51 章不必從頭讀到尾。以下是各角色的最短路徑：

目錄

全書共 8 部、51 章、403 個小節、124 個編號子節，另有 附錄 A–H（45 個小節）。
以下為完整的章、小節與編號子節目錄，每一項都可直接點擊跳至本文對應位置。
為維持可讀性，目錄省略各標題末端的來源等級標記（【Official】/【建議】/【Preview】/【Community】）——標記本身仍完整保留在本文的標題上。

第一部　概念與架構

• 1. GitHub Copilot 簡介
  • 1.1 GitHub Copilot 是什麼
  • 1.2 Copilot 解決什麼問題
  • 1.3 AI Coding Assistant 與 AI Coding Agent 的差異
  • 1.4 從 Code Completion 到 Agentic Development 的演進
  • 1.5 Copilot 在現代 SDLC 中的位置
  • 1.6 Copilot 與傳統 IDE Plugin 的差異
  • 1.7 Copilot 與 ChatGPT / 一般 LLM Chatbot 的差異
  • 1.8 Copilot 與其他 AI Coding Agent 的比較
  • 1.9 本章實務案例
  • 1.10 注意事項
• 2. GitHub Copilot 演進歷史
  • 2.1 為什麼企業必須理解演進史
  • 2.2 能力演進 Timeline
  • 2.3 各階段的能力與開發模式變化
  • 2.4 重要的更名與日落事件
  • 2.5 本章實務案例
  • 2.6 注意事項
• 3. GitHub Copilot 整體系統架構
  • 3.1 完整架構圖
  • 3.2 三個執行體的關鍵差異
  • 3.3 Context 是怎麼組裝的
  • 3.4 Agent Skills 的漸進揭露（Progressive Disclosure）
  • 3.5 本章實務案例
  • 3.6 注意事項
• 4. GitHub Copilot 各產品／功能比較
  • 4.1 功能 × 介面總覽表
  • 4.2 治理能力 × 層級對照表
  • 4.3 該用哪個介面？決策樹
  • 4.4 成本模型比較
  • 4.5 本章實務案例
  • 4.6 注意事項

第二部　授權與企業治理

• 5. GitHub Copilot Plan 與企業授權
  • 5.1 方案總覽
  • 5.2 Business 與 Enterprise 的實質差異
  • 5.3 授權層級與管理責任
  • 5.4 席次與用量管理實務
  • 5.5 AI Credits 成本模型
  • 5.6 模型存取權與 Global Model Policy
    • 5.6.1 Copilot 是多供應商模型平台
    • 5.6.2 三個彼此獨立的限制維度
    • 5.6.3 Global Model Policy
  • 5.7 2026 年計費與預算制度變更
    • 5.7.1 席次改為預先付費
    • 5.7.2 使用者預算可設定到期日
    • 5.7.3 Copilot Code Review 預設效力等級變更
    • 5.7.4 預算提高申請（Budget increase requests）
  • 5.8 Auto 模型選擇、Base／LTS／Utility 模型與 BYOK
    • 5.8.1 Auto model selection 與三種分級
    • 5.8.2 Base 與 LTS 模型
    • 5.8.3 Utility models
    • 5.8.4 BYOK（自帶模型金鑰）
  • 5.9 本章實務案例
  • 5.10 注意事項
• 6. Enterprise Governance
  • 6.1 治理架構全貌
  • 6.2 Enterprise 與 Organization Policies
  • 6.3 AI Controls 與 Agent Management
  • 6.4 Enterprise Managed Settings（managed-settings.json）
    • 6.4.1 完整設定鍵一覽
    • 6.4.2 Permissions 選擇器語法
    • 6.4.3 企業基線範例
    • 6.4.4 設定優先權
    • 6.4.5 團隊層覆寫
    • 6.4.6 Agent 操作權限的企業強制管控
  • 6.5 Content Exclusion（內容排除）
    • 6.5.1 它做什麼、不做什麼
    • 6.5.2 Repository 層語法
    • 6.5.3 Organization 層語法
    • 6.5.4 生效時間與驗證
    • 6.5.5 企業建議排除清單
  • 6.6 MCP 治理
  • 6.7 網路、Proxy 與防火牆
  • 6.8 稽核與可觀測性
  • 6.9 如何避免「每個開發者自己設定一套 AI」
  • 6.10 模型治理與模型退役管理
    • 6.10.1 模型退役是常態，不是意外
    • 6.10.2 模型退役會打壞什麼
    • 6.10.3 企業模型治理 SOP
  • 6.11 團隊專屬設定（Team Specialization）與設定合併規則
    • 6.11.1 overridable 與 unmanaged
    • 6.11.2 多來源設定的合併語意（極易誤解）
    • 6.11.3 MCP Server URL 的正規化規則
  • 6.12 統一 Copilot 體驗與資料保留期限變更
    • 6.12.1 變更內容
    • 6.12.2 為什麼這對企業是重大變更
    • 6.12.3 上線前的必辦清單
  • 6.13 新功能預設啟用政策（Default policy for new features）
    • 6.13.1 兩個「預設可用性」政策
    • 6.13.2 政策的精確涵蓋範圍
    • 6.13.3 本手冊既有建議會受到什麼影響
    • 6.13.4 全域預設的選擇建議
    • 6.13.5 10-22 前的盤點 SOP
  • 6.14 本章實務案例
  • 6.15 注意事項

第三部　安裝與使用介面

• 7. GitHub Copilot 安裝
  • 7.1 安裝前檢查清單
  • 7.2 Windows 安裝
    • 7.2.1 前置環境
    • 7.2.2 企業 Proxy 設定
    • 7.2.3 企業憑證設定
  • 7.3 macOS 安裝
  • 7.4 Linux 安裝
  • 7.5 VS Code 安裝與設定
  • 7.6 Visual Studio 安裝
  • 7.7 JetBrains IDE 安裝
  • 7.8 Eclipse 與 Xcode
  • 7.9 Copilot CLI 安裝
  • 7.10 GitHub Enterprise Server / GHE.com 環境
  • 7.11 安裝驗證 SOP
  • 7.12 JetBrains 企業級佈署（2026 年重大補強）
    • 7.12.1 三項關鍵補強
    • 7.12.2 什麼是 Copilot harness
    • 7.12.3 JetBrains 治理能力現況重評
    • 7.12.4 多 IDE 企業的治理策略
    • 7.12.5 JetBrains 1.18（2026-09-22）企業相關更新
  • 7.13 本章實務案例
  • 7.14 注意事項
• 8. GitHub Copilot CLI
  • 8.1 Copilot CLI 是什麼
  • 8.2 支援能力總覽
  • 8.3 CLI 指令總覽
  • 8.4 互動式 Slash Commands
  • 8.5 鍵盤快捷鍵
  • 8.6 權限與工具核可模型
  • 8.7 本機 Sandbox
  • 8.8 設定目錄結構
  • 8.9 settings.json 常用設定
  • 8.10 Context 管理與壓縮
  • 8.11 自動化與 CI/CD 整合
  • 8.12 Fleet 模式與平行任務
  • 8.13 Session、遠端操控與 Chronicle
  • 8.14 內建代理、Subagent 限制與權限輔助模式
    • 8.14.1 七個內建代理
    • 8.14.2 Subagent 的深度與並行上限
    • 8.14.3 CLI 專屬的 Custom Agent 欄位與 Sidekick Agents
    • 8.14.4 權限輔助模式與 allow-all 的企業限制
  • 8.15 本章實務案例
  • 8.16 注意事項
• 9. Copilot IDE Agent Mode
  • 9.1 Agent Mode 是什麼
  • 9.2 Chat / Edit / Agent 三種模式的差異
  • 9.3 Agent Mode 的完整工作流
  • 9.4 如何寫好一個 Agent Mode 的 Prompt
  • 9.5 Agent 如何理解你的 Repository
  • 9.6 Checkpoints 與回溯
  • 9.7 Human-in-the-loop 的落地方式
  • 9.8 Agent Merge、多根工作區與 Chat Sessions
    • 9.8.1 Agent Merge
    • 9.8.2 多根工作區（Multi-root Workspaces）
    • 9.8.3 Chat Sessions 與 Chat Backgrounds
  • 9.9 VS Code 權限層級、Autopilot 與 Agent Host
    • 9.9.1 兩層安全控制
    • 9.9.2 三種權限層級
    • 9.9.3 Autopilot 是「代理模式」，不是權限層級
    • 9.9.4 企業建議設定
  • 9.10 本章實務案例
  • 9.11 注意事項

第四部　客製化機制

• 10. Custom Instructions
  • 10.1 Custom Instructions 是什麼
  • 10.2 三層指令的正確分工
  • 10.3 企業級 copilot-instructions.md 範例
  • 10.4 路徑層指令（*.instructions.md）
  • 10.5 AGENTS.md 的角色
  • 10.6 如何避免指令衝突
  • 10.7 Prompt Files
  • 10.8 本章實務案例
  • 10.9 注意事項
• 11. Custom Agents
  • 11.1 Custom Agent 是什麼
  • 11.2 Frontmatter 欄位完整參考
  • 11.3 Custom Agent 與其他機制的界線
  • 11.4 企業 Agent Matrix：13 個標準 Agent
    • 11.4.1 總覽表
    • 11.4.2 backend-agent 完整定義
    • 11.4.3 test-agent 完整定義
    • 11.4.4 security-agent 完整定義
    • 11.4.5 reverse-eng-agent 完整定義
    • 11.4.6 其餘 Agent 的定義要點
  • 11.5 tools 欄位的治理意義
  • 11.6 Agent 之間如何交接
  • 11.7 Agent 的測試與發布
  • 11.8 本章實務案例
  • 11.9 注意事項
• 12. Agent Skills
  • 12.1 Skill 是什麼
  • 12.2 SKILL.md 格式
  • 12.3 description 是 Skill 的成敗關鍵
  • 12.4 六種機制的完整比較表
  • 12.5 企業 Skill 範例：資料庫 Migration
  • 12.6 企業 Skill 範例：Legacy 程式碼分析
  • 12.7 Skill 的治理
  • 12.8 本章實務案例
  • 12.9 注意事項
• 13. Hooks
  • 13.1 Hook 是什麼
  • 13.2 JSON 結構
  • 13.3 全部 14 種生命週期事件
  • 13.4 三種 Hook 類型
    • 13.4.1 Command Hook
    • 13.4.2 HTTP Hook
    • 13.4.3 Prompt Hook
  • 13.5 失敗行為與離開碼（企業最關鍵的一節）
  • 13.6 Matcher 語法
  • 13.7 輸入／輸出契約
  • 13.8 進度訊息
  • 13.9 企業 Hook 範例：Java 變更品質閘門
  • 13.10 企業 Hook 範例：危險指令阻擋
  • 13.11 企業 Hook 範例：稽核記錄
  • 13.12 停用 Hook
  • 13.13 本章實務案例
  • 13.14 注意事項
• 14. MCP
  • 14.1 MCP 是什麼
  • 14.2 MCP 架構圖
  • 14.3 設定位置
  • 14.4 GitHub MCP Server
  • 14.5 企業 MCP 治理（本章最重要的一節）
    • 14.5.1 五層防護
    • 14.5.2 Matcher 語法
  • 14.6 MCP 的安全風險
  • 14.7 企業 MCP 清單建議
  • 14.8 本章實務案例
  • 14.9 注意事項
• 15. Plugins
  • 15.1 Plugin 是什麼
  • 15.2 Plugin 與 Copilot Extensions 的區別
  • 15.3 安裝方式
  • 15.4 Marketplace
  • 15.5 企業 Plugin 治理
  • 15.6 企業 Plugin 範例：Java 後端標準包
  • 15.7 本章實務案例
  • 15.8 注意事項
• 16. GitHub Copilot Memory
  • 16.1 Memory 是什麼
  • 16.2 啟用與管理
  • 16.3 Memory 的風險
  • 16.4 企業採用建議
  • 16.5 Copilot Spaces 與 Memory、Custom Instructions 的分工
    • 16.5.1 Copilot Spaces 是什麼
    • 16.5.2 企業必須知道的兩個治理缺口
    • 16.5.3 四種「給 Copilot 知識」機制的分工
  • 16.6 本章實務案例
  • 16.7 注意事項

第五部　AI 驅動的軟體開發

• 17. Prompt Engineering
  • 17.1 企業級 Prompt 的八段結構
  • 17.2 從弱到強：同一個需求的四種寫法
  • 17.3 八種標準 Prompt 樣板
    • 17.3.1 Coding Prompt
    • 17.3.2 Debug Prompt
    • 17.3.3 Refactoring Prompt
    • 17.3.4 Testing Prompt
    • 17.3.5 Review Prompt
    • 17.3.6 Architecture Prompt
    • 17.3.7 Reverse Engineering Prompt
    • 17.3.8 Migration Prompt
  • 17.4 Prompt 的反模式
  • 17.5 本章實務案例
  • 17.6 注意事項
• 18. AI Agent 開發 Web Application
  • 18.1 AI-assisted SDLC 全貌
  • 18.2 各階段的 Copilot 應用與人類把關點
  • 18.3 端到端實例：客戶訂單查詢功能
  • 18.4 本章實務案例
  • 18.5 注意事項
• 19. Enterprise Web Application 建議架構
  • 19.1 整體架構
  • 19.2 前端技術棧
    • 19.2.1 Vue 3 技術選型
    • 19.2.2 給 Copilot 的前端指令
    • 19.2.3 Angular 技術棧
    • 19.2.4 Micro Frontend
  • 19.3 後端技術棧
  • 19.4 資料庫策略
  • 19.5 整合層
  • 19.6 本章實務案例
  • 19.7 注意事項
• 20. Clean Architecture + Copilot
  • 20.1 為什麼 Clean Architecture 對 AI 開發特別重要
  • 20.2 四層結構與依賴規則
  • 20.3 完整專案結構
  • 20.4 給 Copilot 的分層指令
  • 20.5 依賴反轉的具體實作
  • 20.6 本章實務案例
  • 20.7 注意事項
• 21. ArchUnit + Copilot
  • 21.1 為什麼 ArchUnit 是 AI 開發的必要配套
  • 21.2 完整的 ArchUnit 測試
  • 21.3 讓 Copilot 幫你產生 ArchUnit 測試
  • 21.4 Baseline 機制（導入既有專案的關鍵）
  • 21.5 CI 整合
  • 21.6 本章實務案例
  • 21.7 注意事項
• 22. Reverse Engineering
  • 22.1 為什麼這是企業最重要的使用案例
  • 22.2 完整逆向工程流程
  • 22.3 各類 Legacy 的分析要點
    • 22.3.1 VB / VB.NET
    • 22.3.2 Stored Procedure
    • 22.3.3 Java Legacy
  • 22.4 逆向工程產出範本
  • 22.5 從逆向工程到現代化
  • 22.6 本章實務案例
  • 22.7 注意事項
• 23. Framework Upgrade / Migration
  • 23.1 升版的黃金原則
  • 23.2 Java 版本升級路徑
  • 23.3 Spring Boot 升級路徑
  • 23.4 完整升級 SOP
  • 23.5 相依性分析 Prompt
  • 23.6 javax → jakarta 遷移
  • 23.7 Spring Security 設定遷移
  • 23.8 升級 Migration Agent
  • 23.9 本章實務案例
  • 23.10 注意事項
• 24. Legacy Modernization
  • 24.1 現代化流程全貌
  • 24.2 絞殺者模式（Strangler Fig）
  • 24.3 各階段 Copilot 的角色
  • 24.4 本章實務案例
  • 24.5 注意事項
• 25. TDD / BDD
  • 25.1 AI 時代 TDD 的新意義
  • 25.2 AI 輔助的 TDD 循環
  • 25.3 從需求到 BDD 場景
  • 25.4 JUnit 5 實作
  • 25.5 本章實務案例
  • 25.6 注意事項
• 26. Automated Testing
  • 26.1 測試金字塔與 AI 的關係
  • 26.2 各類測試的 AI 協作策略
  • 26.3 有意義的測試 vs. 為覆蓋率的測試
  • 26.4 整合測試範例（Testcontainers）
  • 26.5 不穩定測試（Flaky Test）的處理
  • 26.6 本章實務案例
  • 26.7 注意事項

第六部　安全與工程流程

• 27. Security
  • 27.1 企業 AI Coding Security Standard
  • 27.2 輸入面風險
    • 27.2.1 原始碼外洩
    • 27.2.2 Prompt Injection（最被低估的風險）
  • 27.3 輸出面：AI 產生的程式碼安全問題
  • 27.4 安全指令範本
  • 27.5 相依性與供應鏈風險
  • 27.6 SAST / DAST / Secret Scanning 整合
  • 27.7 公開程式碼比對（Code Referencing）與智慧財產權治理
    • 27.7.1 「Suggestions matching public code」政策的兩種結果
    • 27.7.2 必須知道的例外：GitHub Copilot app
    • 27.7.3 智慧財產權保障與政策設定的關係
    • 27.7.4 企業 IP 治理 SOP
  • 27.8 Copilot Autofix、Security Campaigns 與代理產出的安全驗證
    • 27.8.1 兩種修復路徑：Copilot Autofix 與 Agentic Autofix
    • 27.8.2 Security Campaigns：批次清償安全債
    • 27.8.3 代理產出的平台層安全驗證
    • 27.8.4 企業安全修復的分工模型
  • 27.9 本章實務案例
  • 27.10 注意事項
• 28. AI Agent 安全治理
  • 28.1 Agent Security Model
  • 28.2 最小權限原則的落地
  • 28.3 Sandbox 策略
  • 28.4 憑證與機密保護
  • 28.5 Agent 行為監控
  • 28.6 本章實務案例
  • 28.7 注意事項
• 29. GitHub Copilot + Git Workflow
  • 29.1 標準工作流
  • 29.2 分支與 Commit 規範
  • 29.3 PR 模板
  • 29.4 分支保護與 Rulesets
  • 29.5 Copilot 不應該取代的四件事
  • 29.6 本章實務案例
  • 29.7 注意事項
• 30. Copilot Code Review
  • 30.1 Copilot code review 是什麼
  • 30.2 四層 Review 模型
  • 30.3 各層的檢查清單
  • 30.4 用 Custom Instructions 強化 Copilot code review
  • 30.5 效力等級與成本
  • 30.6 Copilot 核准 Pull Request 的治理
    • 30.6.1 功能行為
    • 30.6.2 三層設定架構
    • 30.6.3 為什麼企業必須非常謹慎
    • 30.6.4 企業建議設定
  • 30.7 2026 年 9 月 Code Review 更新與治理要點
    • 30.7.1 審查體驗的更新（2026-09-11、2026-09-18）
    • 30.7.2 設定入口與效力等級的決定順序（2026-09-23）
    • 30.7.3 企業必須知道的六個治理事實
    • 30.7.4 企業設定建議
  • 30.8 本章實務案例
  • 30.9 注意事項
• 31. CI/CD
  • 31.1 AI 時代 CI/CD 的新職責
  • 31.2 完整 CI Pipeline
  • 31.3 CD 與部署核准
  • 31.4 用 Copilot CLI 做 CI 內的智慧任務
  • 31.5 Copilot cloud agent 的執行環境：copilot-setup-steps.yml、Runner 與防火牆
    • 31.5.1 copilot-setup-steps.yml
    • 31.5.2 Runner 的選擇
    • 31.5.3 防火牆：預設行為與限制
  • 31.6 Copilot Automations 與 GitHub Agentic Workflows
    • 31.6.1 Copilot Automations
    • 31.6.2 GitHub Agentic Workflows（Public Preview）
    • 31.6.3 三種 CI 內 AI 自動化的比較與選用
  • 31.7 本章實務案例
  • 31.8 注意事項

第七部　組織、方法與營運

• 32. Copilot Agent Team
  • 32.1 企業 AI Virtual Software Team
  • 32.2 Agent 職責矩陣
  • 32.3 交接規則（本章最重要）
  • 32.4 Agent Context 汙染
  • 32.5 避免重複工作
  • 32.6 Slack / Microsoft Teams 協作平台整合
    • 32.6.1 兩個平台的能力
    • 32.6.2 這改變了什麼
    • 32.6.3 人在迴路的保護機制
    • 32.6.4 企業導入清單
    • 32.6.5 與 Agent Team 模型的關係
  • 32.7 第三方 Coding Agent、Agent Apps 與 GitHub Copilot app
    • 32.7.1 第三方 coding agents：Anthropic Claude 與 OpenAI Codex（Public Preview）
    • 32.7.2 Agent apps（Public Preview）
    • 32.7.3 GitHub Copilot app
    • 32.7.4 多代理環境的企業治理矩陣
  • 32.8 本章實務案例
  • 32.9 注意事項
• 33. AI Software Development 工作方法改變
  • 33.1 傳統 vs. AI-assisted 全面比較
  • 33.2 三個根本性的改變
  • 33.3 為什麼這不只是「Coding 變快」
  • 33.4 本章實務案例
  • 33.5 注意事項
• 34. PM / SA / Architect / SD / PG 的工作方式改變
  • 34.1 PM：從管理人，到管理需求、Context 與驗收標準
  • 34.2 SA：從寫文件，到建立 AI 可執行的規格
  • 34.3 Architect：從設計架構，到建立 Architecture Guardrails
  • 34.4 SD（系統設計 / 資深開發）：從寫程式，到指揮與驗證
  • 34.5 PG（程式設計師）：從執行 Coding，到 AI Pair Programmer
  • 34.6 QA、Security、DevOps 的轉變
  • 34.7 本章實務案例
  • 34.8 注意事項
• 35. 企業 AI Coding Governance
  • 35.1 Governance Framework
  • 35.2 各層的具體內容與負責人
  • 35.3 治理成熟度模型
  • 35.4 本章實務案例
  • 35.5 注意事項
• 36. 企業禁止事項
  • 36.1 企業 GitHub Copilot 使用規範（可直接採用）
  • 36.2 例外申請流程
  • 36.3 違規的偵測與處理
  • 36.4 本章實務案例
  • 36.5 注意事項
• 37. Developer 使用標準
  • 37.1 每日標準流程（Daily SOP）
  • 37.2 Diff 審查的正確方法
  • 37.3 什麼時候該停下來問人
  • 37.4 任務拆解準則
  • 37.5 Session 管理
  • 37.6 本章實務案例
  • 37.7 注意事項
• 38. Copilot 使用最佳實務
  • 38.1 Prompt（1–6）
  • 38.2 Context（7–12）
  • 38.3 Coding（13–18）
  • 38.4 Architecture（19–23）
  • 38.5 Testing（24–28）
  • 38.6 Security（29–33）
  • 38.7 Agent（34–36）
  • 38.8 MCP（37–38）
  • 38.9 Git & Review（39–40）
  • 38.10 本章實務案例
• 39. 常見錯誤
  • 39.1 錯誤清單與對策
  • 39.2 五個「看起來對但其實錯」的做法
  • 39.3 本章實務案例
  • 39.4 注意事項
• 40. Troubleshooting
  • 40.1 快速診斷流程
  • 40.2 登入與認證問題
  • 40.3 License 與 Policy 問題
  • 40.4 網路、Proxy 與防火牆
  • 40.5 CLI 問題
  • 40.6 權限、Tool 與 Hook 問題
  • 40.7 MCP / Skill / Plugin / Agent 問題
  • 40.8 品質、Context 與成本問題
  • 40.9 本章實務案例
  • 40.10 注意事項
• 41. 系統維護
  • 41.1 企業 Copilot 維運模型
  • 41.2 維運行事曆
  • 41.3 治理有效性演練（季度）
  • 41.4 企業 Agent / Skill 庫的維護
  • 41.5 本章實務案例
  • 41.6 注意事項
• 42. 系統升級
  • 42.1 升級的六個面向
  • 42.2 升級 SOP
  • 42.3 模型升級的特殊處理
  • 42.4 升級檢查清單
  • 42.5 本章實務案例
  • 42.6 注意事項
• 43. GitHub Copilot 企業導入 Roadmap
  • 43.1 五階段全貌
  • 43.2 Phase 1：Pilot（試辦）
  • 43.3 Phase 2：Developer Adoption（開發者採用）
  • 43.4 Phase 3：Team Standardization（團隊標準化）
  • 43.5 Phase 4：Enterprise Governance（企業治理）
  • 43.6 Phase 5：AI Agent Software Factory
  • 43.7 各階段的常見失敗
  • 43.8 本章實務案例
  • 43.9 注意事項
• 44. KPI / 成效衡量
  • 44.1 為什麼 Lines of Code 不適合當主要 KPI
  • 44.2 建議的 KPI 體系
    • 44.2.1 交付效能（DORA 四大指標）
    • 44.2.2 品質指標
    • 44.2.3 流程指標
    • 44.2.4 AI 特有指標
    • 44.2.5 成本與採用指標
  • 44.3 KPI 儀表板設計
  • 44.4 KPI 的陷阱
  • 44.5 2026 年 9 月新增的量測能力與儀表板重設計
    • 44.5.1 新增的官方指標
    • 44.5.2 重新設計後的治理儀表板
  • 44.6 本章實務案例
  • 44.7 注意事項

第八部　企業落地

• 45. 企業實際導入案例
  • 45.1 Case 1：新建 Web Application
  • 45.2 Case 2：Legacy Reverse Engineering
  • 45.3 Case 3：Spring Boot Framework Upgrade
  • 45.4 Case 4：Java Version Upgrade
  • 45.5 Case 5：Vue / Angular Frontend Modernization
  • 45.6 Case 6：Database Migration
  • 45.7 Case 7：Security Remediation
  • 45.8 Case 8：大型企業共用平台開發
  • 45.9 八個案例的共同模式
• 46. 企業共用平台導入方案
  • 46.1 common_platform 定位
  • 46.2 Repository 結構
  • 46.3 共用 ArchUnit 規則庫
  • 46.4 Instructions 分發機制
  • 46.5 導入計畫
  • 46.6 治理設計
  • 46.7 本章實務案例
  • 46.8 注意事項
• 47. 建議企業 Repository 結構
  • 47.1 官方確認支援的路徑
  • 47.2 建議的完整結構
  • 47.3 CODEOWNERS 完整範本
  • 47.4 .gitignore 必要項目
  • 47.5 Repository Template 設計
  • 47.6 本章實務案例
  • 47.7 注意事項
• 48. 建議企業 Agent Matrix
  • 48.1 完整 Agent Matrix
  • 48.2 Agent 選用決策表
  • 48.3 Agent 職責邊界圖
  • 48.4 注意事項
• 49. Prompt Library
  • 49.1 需求與分析（1–4）
  • 49.2 開發（5–9）
  • 49.3 測試（10–13）
  • 49.4 審查（14–17）
  • 49.5 逆向工程與資料（18–21）
  • 49.6 升級與遷移（22–26）
  • 49.7 文件與圖表（27–30）
  • 49.8 維運（31–32）
  • 49.9 Prompt Library 的維護
• 50. 最終企業使用 Checklist
  • 50.1 Developer Checklist
  • 50.2 Team Checklist
  • 50.3 Enterprise Checklist
• 51. 最終結論
  • 51.1 GitHub Copilot 究竟應該被定位成什麼？
  • 51.2 逐層分析
  • 51.3 本手冊的定位建議
  • 51.4 三個最終提醒
  • 51.5 一頁總結

附錄

• 附錄 A：企業 AI 開發核心原則
  • A.1 十五條核心原則
  • A.2 AI 可以做的事
  • A.3 AI 不應自行決定的事
• 附錄 B：各角色的導入建議
  • B.1 CIO / CTO
  • B.2 Enterprise Architect
  • B.3 AI Architect
  • B.4 Software Architect
  • B.5 PM
  • B.6 SA（系統分析）
  • B.7 SD（資深開發 / 系統設計）
  • B.8 PG（程式設計師）
  • B.9 QA
  • B.10 Security
  • B.11 DevOps / SRE
• 附錄 C：GitHub Copilot 企業開發快速開始
  • C.1 十七步流程
  • C.2 逐步操作
  • C.3 新人第一週建議
• 附錄 D：Command / Configuration Reference
  • D.1 Copilot CLI 指令速查
  • D.2 Slash Commands 速查
  • D.3 鍵盤快捷鍵速查
  • D.4 環境變數
  • D.5 設定檔位置速查
  • D.6 設定優先權
  • D.7 Hook 事件速查
  • D.8 managed-settings.json 鍵速查
  • D.9 Custom Agent Frontmatter 速查
  • D.10 SKILL.md Frontmatter 速查
• 附錄 E：Enterprise Adoption Recommendation
  • E.1 十六個問題的回答
  • E.2 Enterprise GitHub Copilot Target Operating Model
  • E.3 Target Operating Model 的五個設計原則
• 附錄 F：版本查證記錄與自我審查
  • F.1 版本查證記錄表
  • F.2 本手冊自我審查清單
  • F.3 引用原則
  • F.4 最後提醒
• 附錄 G：2026 年 8–9 月官方變更對照表與模型參考
  • G.1 需要企業採取行動的變更（優先處理）
  • G.2 增強治理能力的變更（應盡快採用）
  • G.3 新介面與新能力（需先評估再開放）
  • G.4 可觀測性與成效衡量的增強
  • G.5 模型參考表（查證日快照）
  • G.6 本附錄的維護方式
• 附錄 H：v1.2 查證紀錄
  • H.1 查證基準
  • H.2 已查閱的主要官方頁面
  • H.3 更正對照表（v1.1 → v1.2）
  • H.4 v1.2 新增章節
  • H.5 待追蹤項目
• 文件結束

第一部　概念與架構

這一部要建立的是概念模型，不是操作步驟。 企業導入 AI 開發工具失敗的第一個原因，幾乎都不是「工具不好用」，而是「團隊裡每個人腦中的 Copilot 是不同的東西」。 讀完這一部，你應該能在白板上畫出 Copilot 的完整架構，並清楚說出 IDE Agent Mode 與 Cloud Agent 的差異。

1. GitHub Copilot 簡介

1.1 GitHub Copilot 是什麼【Official】

GitHub Copilot 是 GitHub 提供的 AI 軟體開發平台。它最初以「AI 程式碼補全工具」被認識，但在目前的產品定位下，這個描述已經嚴重低估它的範圍。

以官方文件目前的架構來看，GitHub Copilot 至少涵蓋五個層次：

再往上，還有一層企業治理層：Enterprise Policies、AI Controls、Agent Management、Enterprise Managed Settings、Content Exclusion、Audit Log。這一層在個人使用時完全看不到，卻是企業導入的成敗關鍵。

🎯 結論 對企業而言，GitHub Copilot 不是「一個 IDE 外掛」，而是一個橫跨 IDE、終端機、GitHub 平台與 CI/CD 的 AI 工程執行環境，外加一層企業治理控制平面。用「外掛」的心態導入，治理一定會失控。

1.2 Copilot 解決什麼問題【建議】

企業軟體開發的成本，從來不是集中在「打字」。真正吃掉工時的是下面這些事：

注意這張表的共同點：它們全部都是「理解成本」與「重複性驗證成本」，不是「輸入速度」。

⚠️ 警告 如果你的導入論述是「工程師打字變快了」，你會在第一次 KPI 檢討會被問倒。正確的論述是「縮短理解時間、縮短驗證迴圈、把資深工程師的時間從重複性審查中解放出來」。詳見第 44 章。

1.3 AI Coding Assistant 與 AI Coding Agent 的差異【建議】

這是本手冊最重要的一組概念區分。

Agent 的核心是 Agent Loop（代理迴圈）：

flowchart LR
    G["目標<br/>Goal / Prompt"] --> P["規劃<br/>Plan"]
    P --> T["選擇工具<br/>Tool Selection"]
    T --> E["執行<br/>Execute<br/>(讀檔/寫檔/Shell/MCP)"]
    E --> O["觀察結果<br/>Observe<br/>(編譯錯誤/測試失敗/輸出)"]
    O --> D{"目標達成？"}
    D -->|"否"| P
    D -->|"是"| R["產出<br/>Diff / PR / 報告"]
    R --> H["人類審查<br/>Human Review"]
    H -->|"退回"| P
    H -->|"核准"| M["合併<br/>Merge"]

🚨 高風險提醒 Agent 最危險的失敗模式不是「做不出來」，而是「做出了看起來很合理、測試也過了，但業務邏輯是錯的東西」。 因為 Agent 會為了讓測試通過而修改測試。企業導入時，測試檔案的修改必須列為 Review 重點，這一點寫進第 37 章 的每日 SOP。

1.4 從 Code Completion 到 Agentic Development 的演進【Official】

Copilot 的能力演進不是線性加功能，而是開發者角色的四次位移：

🎯 結論 每往下走一階，開發者的驗證單位就變大一級。 這代表：驗證能力不變的團隊，導入 Agent 之後品質一定會下降。這就是為什麼本手冊花了整整第六部談安全與工程流程——不是因為 Copilot 不安全，而是因為驗證能力必須同步升級。

1.5 Copilot 在現代 SDLC 中的位置【建議】

很多人以為 Copilot 只在「Coding」那一格。實際上它已經橫跨整個軟體開發生命週期（Software Development Life Cycle，SDLC）：

flowchart TD
    subgraph REQ["需求與分析"]
        R1["Issue 分析"]
        R2["需求規格草稿"]
        R3["逆向工程<br/>Legacy 需求還原"]
    end
    subgraph DES["設計"]
        D1["架構方案比較"]
        D2["資料模型設計"]
        D3["API 契約設計"]
        D4["圖表產生<br/>Mermaid / PlantUML"]
    end
    subgraph DEV["開發"]
        V1["Code Completion"]
        V2["IDE Agent Mode"]
        V3["Copilot CLI"]
        V4["Cloud Agent<br/>批次任務"]
    end
    subgraph QA["品質"]
        Q1["單元測試產生"]
        Q2["整合測試"]
        Q3["ArchUnit 架構測試"]
        Q4["Copilot code review"]
    end
    subgraph OPS["交付與維運"]
        O1["GitHub Actions"]
        O2["SAST / 相依性掃描"]
        O3["Release Notes"]
        O4["Incident 分析"]
    end

    REQ --> DES --> DEV --> QA --> OPS
    OPS -.->|"回饋"| REQ

    GOV["企業治理層<br/>Policies / AI Controls / Audit"]
    GOV -.->|"約束"| REQ
    GOV -.->|"約束"| DES
    GOV -.->|"約束"| DEV
    GOV -.->|"約束"| QA
    GOV -.->|"約束"| OPS

📌 註記：圖中虛線代表治理約束——治理不是流程中的一個「關卡」，而是貫穿所有階段的橫切面。把治理放在最後一關（例如只在 PR 前掃描），等於讓風險累積到最貴的時候才處理。

1.6 Copilot 與傳統 IDE Plugin 的差異【建議】

⚠️ 警告 「模型會被替換，行為會變」這一點被嚴重低估。 你上個月建立的 Prompt 樣板、Custom Agent 定義，可能因為後端模型換代而效果改變。這就是為什麼第 42 章 要求企業建立 Model Upgrade Regression Test。

1.7 Copilot 與 ChatGPT / 一般 LLM Chatbot 的差異【建議】

🚨 這是企業最該理解的一點 「禁止工程師使用 AI」在實務上不可行——他們會用手機。 正確的策略是提供一個受治理的 AI 通道，讓資料留在企業可稽核的邊界內。這才是導入 Copilot Business / Enterprise 的資安論述，而不只是生產力論述。

1.8 Copilot 與其他 AI Coding Agent 的比較【建議】

📌 註記：下表中 GitHub Copilot 欄位已逐項對照官方文件查證；其餘工具欄位為依各自官方文件的定性比較，不保證與該工具最新版本完全一致。各工具迭代極快，採購決策請以各家官方文件為準。

🎯 選型結論【建議】 如果你的程式碼已經在 GitHub（尤其是 GitHub Enterprise Cloud），Copilot 的決定性優勢不是模型品質，而是治理能力與平台整合深度。 模型可以換（Copilot 本身就支援多家模型與 BYOK），但「Issue → Agent → PR → code review → Actions → Audit Log」這條原生鏈路，其他工具需要大量自建。 反過來說，如果你的程式碼不在 GitHub，Copilot 的優勢會少掉一半以上，此時應重新評估。

1.9 本章實務案例【建議】

情境：某金融業導入前，Tech Lead 在部門會議被問：「這跟我們去年評估的 AI 補全工具有什麼不一樣？」

錯誤回答：

「它更準、支援更多語言。」

這個回答會讓 Copilot 被歸類成「開發工具採購案」，預算會被砍到最低，也不會有治理配套。

建議回答【建議】：

「去年評估的是補全工具，驗證單位是一行程式碼。 現在要導入的是代理平台，驗證單位是一個 Pull Request。 這代表三件事： 第一，我們可以把 Legacy 系統的理解成本從三個月壓到兩週； 第二，我們必須升級 Code Review 與測試能力，否則品質會下降； 第三，我們必須先建立企業治理設定（Policy、Content Exclusion、MCP Allowlist），否則工程師會各自接上不受控的外部工具。 所以這不是工具採購，是開發流程改造專案，需要架構師、資安與 QA 一起參與。」

1.10 注意事項

• ❌ 不要用「AI 幫我們寫程式」當導入論述，這會讓資深工程師抗拒、讓管理層期待錯誤。
• ❌ 不要在還沒設定 Content Exclusion 與 Policy 之前就大規模發 License。
• ❌ 不要把 IDE Agent Mode 與 Copilot cloud agent 寫進同一條規範。
• ✅ 先確認你的原始碼託管位置——這決定 Copilot 能發揮多少價值。
• ✅ 導入第一天就把「驗證能力升級」列為專案範圍，而不是事後補。

2. GitHub Copilot 演進歷史

2.1 為什麼企業必須理解演進史【建議】

這一章不是懷舊。它的實際用途只有一個：讓你能一眼判斷一份文件是不是過時的。

當你在網路上看到一篇 Copilot 教學，只要它提到 .chatmode.md、Copilot Extensions、premium requests，你就知道它至少落後一個世代，裡面的治理建議不能直接用。

2.2 能力演進 Timeline【Official】

flowchart TD
    S1["<b>1. Code Completion</b><br/>行內建議<br/>驗證單位：一行"]
    S2["<b>2. Copilot Chat</b><br/>對話、解釋、產生<br/>驗證單位：一個片段"]
    S3["<b>3. IDE Agent Mode</b><br/>本機多檔案自主修改<br/>驗證單位：一個 Commit"]
    S4["<b>4. Copilot cloud agent</b><br/>雲端非同步、自動開 PR<br/>驗證單位：一個 Pull Request"]
    S5["<b>5. Custom Agents</b><br/>角色專責化<br/>.github/agents/*.md"]
    S6["<b>6. Skills / Hooks / MCP</b><br/>能力、攔截、工具三層擴充"]
    S7["<b>7. Plugins</b><br/>可散布、可版本化的能力套件"]
    S8["<b>8. Enterprise Agent Governance</b><br/>AI Controls / Agent Management<br/>managed-settings.json"]
    S9["<b>9. AI Software Engineering Platform</b><br/>SDK / 自動化 / OpenTelemetry"]

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9

2.3 各階段的能力與開發模式變化【建議】

🎯 結論 這張表最重要的是最右欄。 每一次能力躍進，企業都必須同步建立對應的治理能力。企業如果只升級能力、不升級治理，風險是指數成長的。 實務上最常見的失敗：直接從階段 1 跳到階段 5（「我們來建一堆 Custom Agent 吧」），但階段 2 的 Content Exclusion 從來沒設定過。

2.4 重要的更名與日落事件【Official】

2.5 本章實務案例【建議】

情境：資安部門拿來一份 2025 年撰寫的內部《AI 工具使用規範》，要求工程部門遵守。

問題盤點：

1. 規範中寫「禁止使用 Copilot Extensions 連接內部系統」——該機制已日落，這條規範現在保護不到任何東西，反而讓人以為外部整合已被禁止。
2. 規範中沒有提到 MCP——而 MCP 才是目前工程師連接外部系統的實際管道，完全沒有被治理。
3. 規範中沒有提到 Custom Agent 與 Skills——這代表任何人都可以在 repository 裡放入自訂 Agent 定義，且不需審查。
4. 規範中的成本控管以 premium request 計算——與現行 AI Credits 制度對不上。

處理建議【建議】：

不要「修訂」這份規範，應該重寫。 因為它的架構是以「Copilot 是一個 IDE 外掛」為前提寫的，逐條修補只會留下概念錯誤。 重寫的骨架請直接採用第 35 章 的 Governance Framework。

2.6 注意事項

• ⚠️ 判斷文件是否過時的三個關鍵字：.chatmode.md、Copilot Extensions、premium requests。看到任一個，該文件的治理建議都不能直接採用。
• ⚠️ 官方文件的舊 URL 路徑（例如 coding-agent）有時仍可存取，不代表該名稱仍是現行說法。
• ✅ 在企業內部 Wiki 為 Copilot 相關頁面加上「最後查證日期」欄位，超過 90 天自動標記為待覆核。

3. GitHub Copilot 整體系統架構

3.1 完整架構圖【Official + 建議】

下圖整合了官方文件中確認存在的元件，並以虛線標示企業治理的約束關係。

flowchart TD
    subgraph GOV["企業治理層 Enterprise Governance"]
        ENT["Enterprise<br/>企業帳戶"]
        POL["Policies<br/>功能 / 模型 / Agent / MCP"]
        AIC["AI Controls<br/>Agent Management"]
        MS["Enterprise Managed Settings<br/>managed-settings.json (MDM)"]
        CE["Content Exclusion<br/>Repo / Org"]
        AUD["Audit Log<br/>+ Agent 事件"]
        OTEL["OpenTelemetry<br/>Agent 監控"]
    end

    subgraph ORG["組織層 Organization"]
        O1["Organization Policies"]
        O2["Organization Instructions"]
        O3["Org Custom Agents<br/>.github / .github-private"]
        O4["MCP Registry / Allowlist"]
    end

    subgraph REPO["儲存庫層 Repository"]
        R1[".github/copilot-instructions.md"]
        R2[".github/instructions/**"]
        R3[".github/agents/*.md"]
        R4[".github/skills/*/SKILL.md"]
        R5[".github/hooks/*.json"]
        R6[".github/copilot/settings.json"]
        R7["AGENTS.md"]
        R8["原始碼 / 測試 / Workflows"]
    end

    subgraph SURF["使用介面 Surfaces"]
        IDE["IDE<br/>VS Code / VS / JetBrains<br/>Eclipse / Xcode"]
        CLI["GitHub Copilot CLI<br/>copilot"]
        WEB["github.com<br/>Chat / Agents Panel"]
        APP["GitHub Copilot app"]
        SDK["Copilot SDK"]
    end

    subgraph EXEC["執行體 Execution"]
        COMP["Code Completion"]
        CHAT["Copilot Chat"]
        AM["IDE Agent Mode<br/>本機工作目錄"]
        CA["Copilot cloud agent<br/>GitHub Actions 臨時環境"]
        CR["Copilot code review"]
    end

    subgraph EXT["擴充機制 Extensibility"]
        SK["Agent Skills"]
        HK["Hooks<br/>14 種生命週期事件"]
        MCP["MCP Servers"]
        PLG["Plugins<br/>plugin.json"]
        MEM["Copilot Memory"]
    end

    MODEL["模型層 Models<br/>多供應商 + BYOK"]

    subgraph GH["GitHub 平台"]
        ISS["Issues"]
        PR["Pull Requests"]
        ACT["GitHub Actions / CI"]
        SEC["Code Scanning<br/>Secret Scanning<br/>Dependabot"]
    end

    ENT --> POL --> ORG
    ENT --> AIC --> ORG
    ENT --> MS
    ORG --> REPO
    CE -.->|"遮蔽檔案"| SURF
    MS -.->|"強制設定"| SURF

    REPO --> SURF
    SURF --> EXEC
    EXT --> EXEC
    EXEC --> MODEL
    EXEC --> GH
    GH --> AUD
    EXEC --> AUD
    EXEC --> OTEL
    PR --> CR
    ISS --> CA
    CA --> PR
    ACT --> PR

3.2 三個執行體的關鍵差異【Official】

這是全書最需要記住的一張表。

🚨 企業必讀 「Cloud agent 的 ask 視同 deny」這一點極容易被忽略。 如果你寫了一個 preToolUse hook，在不確定時回傳 "ask"，在 CLI 上它會跳出詢問，在 cloud agent 上它會直接拒絕。同一份 hook 在兩個環境的行為不同——這必須寫進 Hook 開發規範（第 13 章）。

3.3 Context 是怎麼組裝的【建議】

Agent 的行為品質，八成取決於送進模型的 Context 品質。以下是概念層級的組裝順序（實際實作依介面與版本而異）：

1. 系統層          →  Copilot 內建的 agent 指令與工具定義
2. 企業層          →  Organization Instructions（github.com）
3. Repository 層   →  .github/copilot-instructions.md
                      AGENTS.md / CLAUDE.md / GEMINI.md
4. 路徑層          →  .github/instructions/**/*.instructions.md（依檔案路徑匹配）
5. 個人層          →  Personal Instructions / ~/.copilot/copilot-instructions.md
6. Agent 層        →  被選用的 Custom Agent（.github/agents/*.md）的 prompt 內容
7. Skill 層        →  模型依 description 判斷需要時，才載入 SKILL.md 全文
8. 工具層          →  MCP Server 提供的 tools / resources 定義
9. Memory 層       →  Copilot Memory 中的 repository facts 與 user preferences
10. 即時 Context   →  開啟的檔案、選取範圍、@ 附加檔案、# Issue/PR、workspace 索引
11. 對話歷史       →  本次 session 的訊息（超量時會被壓縮 compaction）

⚠️ 警告：Context 不是越多越好 每一層都會吃掉 token 預算。企業最常犯的錯是把 copilot-instructions.md 寫成 800 行的公司規章，結果：

1. 真正重要的架構規則被稀釋，模型不一定遵守；
2. 每一次請求都付出額外成本；
3. 可用於實際程式碼的 context 變少，Agent 探索能力下降。

正確做法是分層：短而強制的規則放 copilot-instructions.md，細節放 .instructions.md（依路徑生效）或 Skills（依需要才載入）。詳見第 10 章 與第 12 章。

3.4 Agent Skills 的漸進揭露（Progressive Disclosure）【Official + 建議】

Skills 的設計精神值得單獨說明，因為它直接解決了上面的 Context 膨脹問題。

flowchart LR
    A["Agent 啟動"] --> B["只載入所有 Skill 的<br/>name + description<br/>（極少 token）"]
    B --> C{"使用者任務<br/>與哪個 description 相關？"}
    C -->|"無相關"| D["不載入任何 SKILL.md<br/>Context 保持精簡"]
    C -->|"相關"| E["載入該 skill 目錄下的<br/>SKILL.md 全文 + 附帶檔案"]
    E --> F["依 Skill 指示執行"]

🎯 結論 這代表 description 欄位是 Skill 最重要的部分，不是內文。 description 寫得含糊，Skill 永遠不會被載入；寫得太廣，每次都被載入而浪費 token。企業 Skill 撰寫規範必須明確要求 description 包含「這是什麼」+「什麼時候該用」。

3.5 本章實務案例【建議】

情境：某團隊抱怨「Copilot 都不遵守我們的架構規範」。

診斷步驟【建議】：

1. 檢查規範放在哪裡。 結果發現規範寫在 Confluence，而不是 repository。→ Copilot 看不到它。
2. 移到 .github/copilot-instructions.md 後仍不遵守。 檢查發現該檔案有 620 行，包含公司歷史、部門介紹、聯絡窗口。→ 重要規則被雜訊淹沒。
3. 精簡到 80 行核心規則後，多數情況遵守，但 Repository 層的資料存取規則仍常被違反。 → 改用路徑層指令：把資料存取規則放進 .github/instructions/persistence.instructions.md，讓它只在改到 infrastructure/persistence/** 時生效。
4. 仍有少數情況失守。 → 加上 ArchUnit 測試 + Hook，讓違規在 Agent 送出前就被擋下（第 21 章、第 13 章）。

🎯 這個案例的核心教訓 Instructions 是「請求」，Hook 與測試才是「強制」。 任何真正不能違反的規則，都必須有一個機械化的驗證機制，不能只靠 Prompt。這是本手冊反覆強調的原則。

3.6 注意事項

• ⚠️ copilot-instructions.md 不是公司規章存放處，是給模型看的短指令。
• ⚠️ Cloud agent 只讀 .github/hooks/*.json，你在 ~/.copilot/hooks/ 放的 hook 對它無效。
• ⚠️ Content Exclusion 目前不支援 Copilot Chat 的 Edit 與 Agent 模式（官方明載），不要把它當成 Agent 的資料防護唯一手段。
• ✅ 把架構圖印出來貼在團隊看板上——概念模型統一的價值遠大於任何一份操作手冊。

4. GitHub Copilot 各產品／功能比較

4.1 功能 × 介面總覽表【Official】

📌 註記：下表整合自官方 Copilot customization cheat sheet 與 feature matrix。符號：✅ 支援｜🅿️ 預覽（Preview）｜❌ 不支援｜— 不適用。功能與支援狀態變動頻繁，採用前請以官方文件當日狀態為準。

⚠️ v1.2 更正：Custom Agents 在 Eclipse 的支援狀態由 ✅ 更正為 🅿️——官方「Custom agents configuration」參考頁明載 custom agents 在 JetBrains、Eclipse、Xcode 皆為 public preview。

⚠️ 這張表最重要的三個觀察

1. Hooks 的支援面極不平均：CLI、cloud agent、github.com 支援，但主流 IDE 幾乎不支援（VS Code 為預覽）。這代表「用 Hook 強制企業政策」的策略，在 IDE 上目前不可靠，必須改用 CI/CD 與 Managed Settings 補位。
2. Prompt Files 只在 IDE 有效，CLI 與 GitHub 端都不支援。不要把企業 Prompt Library 全押在 Prompt Files 上。
3. MCP 是唯一全介面支援的擴充機制。這既是好消息（統一擴充點），也是壞消息（它是最需要治理的攻擊面）。

4.2 治理能力 × 層級對照表【Official】

📌 註記：官方文件明載 Copilot 的 Enterprise Policy 可以「啟用、停用，或委派給組織決定」。跨授權衝突時的規則是：同一企業內多個授權來源時通常採最寬鬆者；跨不同企業時採最嚴格者。企業如果同時讓工程師掛在多個 Organization 底下，務必實測實際生效值。

4.3 該用哪個介面？決策樹【建議】

flowchart TD
    A["我要做什麼？"] --> B{"需要我全程盯著嗎？"}
    B -->|"是，我要邊看邊改"| C{"在哪裡工作？"}
    C -->|"編輯器內"| D["<b>IDE Agent Mode</b><br/>多檔重構、加功能、修 bug"]
    C -->|"終端機"| E["<b>Copilot CLI</b><br/>批次改檔、跨專案、腳本化"]
    B -->|"否，我要派出去"| F{"任務邊界清楚嗎？"}
    F -->|"清楚，可寫成 Issue"| G["<b>Copilot cloud agent</b><br/>補測試、修 lint、小型功能<br/>→ 產出 PR"]
    F -->|"不清楚，要先探索"| H["先用 <b>CLI 或 IDE</b> 探索<br/>再把明確任務交給 cloud agent"]
    B -->|"我只是想問問題"| I{"問什麼？"}
    I -->|"這段程式在幹嘛"| J["<b>Chat</b>（IDE 內）"]
    I -->|"這個 PR / Issue 在幹嘛"| K["<b>Chat</b>（github.com）"]
    I -->|"跨 repo 的架構問題"| L["<b>Copilot CLI</b> + MCP"]
    A --> M{"要自動化嗎？"}
    M -->|"排程 / CI"| N["<b>Copilot CLI</b> 程式化模式<br/>(-p) + GitHub Actions"]
    M -->|"事件驅動"| O["<b>Cloud agent</b> 自動化<br/>(Automations)"]

4.4 成本模型比較【Official + 建議】

⚠️ 企業成本控管的三個實務重點【建議】

1. Cloud agent 是雙重計費（AI Credits + Actions 分鐘數）。試辦階段務必開啟預算控管（Budgets），否則第一個月帳單會嚇到財務。
2. Agent 的成本與「任務大小」高度相關，不是與「使用者人數」相關。一個定義模糊的任務可能燒掉 59 分鐘還沒產出。任務拆小是最有效的成本控管。
3. 模型倍率差異巨大。企業應設定預設模型政策（例如日常用中階模型、複雜架構任務才允許高階模型），而不是放任所有人預設用最貴的。

4.5 本章實務案例【建議】

情境：某企業 40 人的開發部門，導入第一個月 AI Credits 超支 3 倍。

根因分析：

處置後：第二個月降至預算內，且 PR 品質上升（因為任務變小、Diff 變小、Review 變容易）。

🎯 這個案例的教訓 成本失控通常是「使用方式」問題，不是「工具太貴」問題。 而且好消息是：讓成本下降的措施（任務拆小、Context 精簡），同時也會讓品質上升。這兩個目標不衝突。

4.6 注意事項

• ⚠️ 不要假設「IDE 支援的功能，CLI 也支援」——Prompt Files 就是反例。
• ⚠️ 不要假設「Hook 能在所有介面強制企業政策」——IDE 目前不支援或僅預覽。
• ⚠️ Cloud agent 的 59 分鐘上限是硬限制，長任務必須自行拆解。
• ✅ 導入前先做一次「功能 × 介面」盤點，確認你打算依賴的機制在你的主力 IDE 上真的可用。
• ✅ 第一個月一定要開預算控管與用量儀表板，不要等帳單來。

第二部　授權與企業治理

這一部要回答的是：在工程師寫第一行 Prompt 之前，企業必須先做完哪些事。 順序錯了，後面全部都是補救。

5. GitHub Copilot Plan 與企業授權

5.1 方案總覽【Official】

⚠️ 價格與額度以官方公告為準 本節引述查證當日（2026-09-25）官方 Plans for GitHub Copilot 頁面的方案結構。價格、AI Credits 額度與功能分配會隨時間調整，任何預算編列與商務決策，請以 GitHub 官方目前公告為準，不要引用本手冊的數字。

📌 註記：base credits 與 flex credits 官方方案頁面區分兩種額度。實務上企業採購時應向 GitHub 或代理商確認兩者的結轉規則、超額計費方式與是否可跨月累積，這會直接影響年度預算模型。本手冊不對此做推測。

📌 v1.2 補充【Official】：官方方案頁明載「所有方案皆包含 Copilot CLI 與 Copilot app」；Copilot Free 的 code review 僅限 VS Code 的「Review selection」；Copilot 目前不適用於 GitHub Enterprise Server（GHE.com 環境見第 7.10 節）。

5.2 Business 與 Enterprise 的實質差異【Official + 建議】

企業最常問的問題是「我們該買 Business 還是 Enterprise？」

🎯 選擇建議【建議】

• 只有一個 Organization、人數在 100 以內、沒有嚴格法遵稽核需求 → Business 起步，再依需求升級。
• 有多個 Organization、金融／醫療／公部門等受監管產業、需要企業層統一發布 Custom Agent 與集中稽核 → 直接 Enterprise。
• 決定關鍵不是「AI Credits 多寡」（那可以加購），而是**「你需不需要在企業層強制統一治理」**。

5.3 授權層級與管理責任【Official + 建議】

flowchart TD
    E["<b>Enterprise 帳戶</b><br/>企業管理員"] --> P1["購買席次<br/>設定企業政策<br/>AI Controls<br/>Audit Log"]
    E --> O1["Organization A"]
    E --> O2["Organization B"]
    O1 --> P2["組織政策<br/>Organization Instructions<br/>Content Exclusion<br/>MCP Registry"]
    O1 --> T1["Team / 使用者<br/>指派席次"]
    O2 --> T2["Team / 使用者"]
    T1 --> R1["Repository<br/>instructions / agents<br/>skills / hooks"]
    T2 --> R2["Repository"]
    R1 --> D1["Developer<br/>個人設定<br/>~/.copilot/"]

    MDM["<b>MDM / 組態管理</b><br/>managed-settings.json"] -.->|"強制下發至終端"| D1

管理責任分工【建議】：

🚨 最常見的治理失敗 企業把所有設定責任都丟給 Developer，結果每個人的 ~/.copilot/settings.json 都不一樣、每個 repo 的規則都不一樣、有人接了不該接的 MCP Server。 解法不是發公告，是用 managed-settings.json 從技術上下發。 詳見第 6 章。

5.4 席次與用量管理實務【Official + 建議】

官方提供的管理能力【Official】：

• 席次指派／撤銷（Organization、Enterprise 層）
• 席次使用狀況檢視（View license usage）
• 使用量與採用率儀表板（Usage metrics dashboard）
• 程式碼產生儀表板（Code generation dashboard）
• 影響力儀表板（Impact dashboard）
• 活動報表下載（Activity report）
• 預算控管（Budgets for usage-based billing）
• Copilot Business 的存取申請流程（Manage requests for access）

企業實務流程【建議】：

新人報到
   ↓
IT 建立 GitHub 帳號 → 加入 Organization → 加入 Team
   ↓
自助申請 Copilot 席次（或由 Team Lead 核准）
   ↓
MDM 自動下發 managed-settings.json
   ↓
首次登入 → 閱讀企業 Copilot 使用規範（第 36 章）
   ↓
完成 Onboarding 訓練（附錄 C 快速開始）
   ↓
30 天後檢視使用率
   ↓
連續 30 天未使用 → 提醒；連續 60 天未使用 → 回收席次

✅ 建議 席次回收政策一定要在導入第一天就宣告，而且要自動化。 沒有回收機制的企業，一年後會發現 30–40% 的席次是閒置的，這是最容易被財務挑戰的浪費。官方也提供了「提醒未使用者」的做法可參考。

5.5 AI Credits 成本模型【Official + 建議】

⚠️ Version Note：計費模型已從 premium requests 轉向 AI Credits 官方文件把舊的 request-based billing 標示為 legacy。舊制的「每月 N 次 premium request、每個模型有倍率」與新制的 AI Credits 不能直接換算。若你的內部成本試算表還是舊制，必須重做。

成本的四個變數【建議】：

企業成本控管 SOP【建議】：

1. 設定企業預設模型（managed-settings.json 的 "model"）
2. 開啟預算控管（Budgets），設定告警門檻（建議 70% / 90%）
3. 每週檢視 Usage metrics dashboard，找出 top 5 消耗者
4. 對 top 5 做使用方式訪談（通常是任務拆解問題，不是濫用）
5. 每月檢視席次使用率，回收閒置席次
6. 每季重新評估模型政策（新模型可能更便宜或更有效）

5.6 模型存取權與 Global Model Policy【Official】

Copilot 的授權方案不只決定「能不能用」，也決定「能用哪些模型」。企業在做 Plan 決策時，模型存取權往往比席次單價更影響實際體驗，但它經常被忽略。

5.6.1 Copilot 是多供應商模型平台【Official】

Copilot 並非單一模型產品，而是一個多供應商模型聚合平台。截至查證日，官方 Supported models 參考頁同時列出下列供應商的模型家族：

† 預定 2026-10-02 退役；‡ 預定 2026-10-19 退役（替代模型見第 6.10.1 節）。

⚠️ v1.2 更正：移除已於 2026-09-10 退役的 MAI-Code-1-Flash；新增 2026-09-21／22 上架的 Grok 4.7、GPT-6 Sol／Luna、Claude Opus 5.5；標示 10 月兩批退役。

📌 本表僅為查證日快照。 模型清單的變動頻率是以週為單位——2026 年 8 至 9 月間就發生了多次新增與 4 波退役（含已預告者）。 請勿把任何模型名稱寫死進企業規範文件；規範應該寫選型準則，而不是模型清單。正確做法見第 6.10 節。

5.6.2 三個彼此獨立的限制維度【Official】

一個模型「能不能用」，取決於三個彼此獨立的維度，缺一不可：

🎯 這三個維度是 AND 關係。 使用者回報「文件說有這個模型，但我下拉選單裡沒有」時，請依 Plan → Surface → Policy 的順序排查，九成以上的案例落在 Policy 這一層。

5.6.3 Global Model Policy【Official】

⚠️ Version Note

• 2026-07-29：公告「Default model enablement for Copilot Business and Enterprise」，並提供 28 天設定緩衝期。
• 2026-08-26：Global model policy 正式 GA。

行為變更：GA 之後，任何管理員從未明確配置過的模型，在 GA 時會自動對使用者開放；GA 之前則是預設關閉、需管理員逐一啟用。

這項變更的企業意涵，遠比字面看起來嚴重：

✅ 企業必要動作【建議】：

1. 建立模型白名單，而非依賴預設值。 在 Enterprise 或 Organization 的 Copilot 模型政策中，對每一個模型做出明確的啟用／停用決定——包含你想擋掉的那些。「不動作」現在等於「同意」。
2. 對未來的新模型預先定調。 由於新模型 GA 後會自動開放，企業必須指定一位負責人（建議為 AI Governance Owner，見第 35 章）定期覆核模型清單，建議頻率為每月一次。
3. 把模型政策納入變更管理。 模型政策的每一次調整都應留下工單紀錄與理由，供稽核追溯。
4. 對照 managed-settings.json 的 model 鍵。 組織層的模型政策決定「哪些模型可用」，managed-settings.json 的 model 鍵決定「新對話預設用哪一個」。兩者是不同層次，必須同時設定，詳見第 6.4 節。

📌 v1.2 補充：一律預設停用、不受預設政策影響的模型【Official】 官方明列下列模型不在預設政策範圍內，無論設定為何都預設停用，必須由管理員明確開啟：

• Pre-GA 模型
• 開放權重模型（DeepSeek、Kimi K2.7 Code、Kimi K3）
• 不在 GitHub 資料保留協議涵蓋範圍內的模型（Claude Fable 5、Claude Fable 5.1）
• 已限制為資料落地或 FedRAMP 模型的企業中，不符合該限制的模型

尚未明確設定的模型，在設定頁會標示為 Delegate to Default Policy。同樣的「預設開放」邏輯自 2026-10-22 起延伸到功能，見第 6.13 節。

5.7 2026 年計費與預算制度變更【Official】

⚠️ Version Note

官方於 2026-08-28 公告「Upcoming changes to GitHub Copilot policies and billing」，其中包含兩項會影響採購與預算流程的實質變更，生效日分別為 2026-09-01 與 2026-10-01。

5.7.1 席次改為預先付費【Official】

維持不變的部分【Official】：定價未調整；席次回收（revocation）不會產生按比例退款；週期中新增席次仍適用比例計算；支出控制（spend controls）與用量追蹤機制維持不變。

🚨 對企業流程的三個實質衝擊【建議】

1. 「先給人、後補預算」的做法失效。 過去可以先指派席次、月底再結算；現在未付款＝該同仁完全無法使用 Copilot。新人報到流程（onboarding）中的席次指派，必須排在付款流程之後。
2. 席次回收不退款，讓「浮動席次池」策略的經濟性下降。 原本「閒置 30 天即回收」的做法可以省錢；現在回收不退費，省下的只有下一個週期的費用。回收政策仍應保留（資安理由），但不要再用「省錢」當作它的主要 KPI。
3. 年度預算編列必須改為「席次數 × 12 個月」全額預估，不能再假設「平均在職率」折扣。

5.7.2 使用者預算可設定到期日【Official】

2026-09-01 起，使用者預算（user budgets）可以設定到期日。

這解決了一個實務痛點：過去預算一旦設定就長期有效，導致專案結束後預算殘留、或臨時性的額度提升忘記收回。

✅ 企業建議用法【建議】：

✅ 建議：把「預算到期日」設為強制欄位寫進內部申請單。沒有到期日的預算申請一律退回。這是成本治理最省力的一個槓桿。

5.7.3 Copilot Code Review 預設效力等級變更【Official】

🚨 這是一項會自動生效、且會直接影響帳單的變更。

由於 Balanced 會消耗較多 AI Credits、並可能多用一些 GitHub Actions 分鐘數，未採取動作的組織會在 9 月底之後看到 review 相關成本上升。詳見第 30.5 節。

📌 v1.2 補充（2026-09-23）：企業管理員現在可以為整個企業設定預設效力等級（Lite、Balanced 或 GitHub default）。但依官方的決定順序，PR 請求者的個人設定優先於 repository 與 organization 設定——企業無法單靠預設值把成本鎖在 Lite，必須搭配預算控管。詳見第 30.7.2 節。

5.7.4 預算提高申請（Budget increase requests）【Official】

🆕 v1.2 新增

2026-09-16 起 GA，適用採 usage-based billing 的 Copilot Business 與 Copilot Enterprise（不適用 Enterprise Managed Users）。

✅ 企業建議【建議】：把預算提高申請納入既有的簽核流程——核准時一併設定到期日（5.7.2），避免臨時額度變成永久額度；每月檢視申請次數最多的前 10 名，這通常反映的是任務拆解或模型選擇問題，而不是額度不足。

5.8 Auto 模型選擇、Base／LTS／Utility 模型與 BYOK【Official + 建議】

🆕 v1.2 新增

第 5.6 節處理的是「哪些模型可以用」；本節處理的是「在你沒有明確指定時，平台會替你用哪一個模型」。

企業最容易忽略的是：有好幾類模型不會出現在模型政策的逐一決策裡，卻同樣影響成本、品質、可重現性與法遵。

5.8.1 Auto model selection 與三種分級【Official】

運作方式：Auto with task optimization 結合兩個系統——一個追蹤各模型的即時健康度與可用性，另一個評估任務複雜度——再把每個 prompt 路由到最適合的模型。路由只在快取邊界發生，官方明言在 session 中途切換模型「成本增加但品質沒有相應提升」。

支援介面【Official】：

三種分級（2026-09-14 起陸續推出，僅 VS Code、Copilot CLI、GitHub Copilot app）【Official】：

📌 分級不是「換一組模型」。三個分級可用的模型相同，只改變路由的偏好；即使選 Intelligence，簡單的 prompt 仍可能被送到小模型。

Evaluation models（評估模型）【Official】：個人方案在 Auto 下可能被分派到評估模型——這些模型可能以代號出現、未經正式發布，官方明言它們「在安全相關類別的提示上可能表現較差」。個人可在 AI controls → Evaluation models in Copilot auto model selection 停用。

🚨 企業意涵：這是「禁止以個人方案處理公司程式碼」的另一個具體理由——企業無法管控個人方案是否被分派到評估模型。

查看實際使用的模型【Official】：Copilot Chat 將滑鼠移到回應上；Copilot CLI 在終端機顯示；cloud agent 在回應結尾顯示；Copilot app 顯示在 Auto 旁的模型選擇器。

企業建議【建議】：

⚠️ 稽核注意：Auto 讓「這次用了哪個模型」變成事後才知道的資訊。企業若要做成本歸因或品質回溯，必須依賴 usage report 的每模型 token 明細（附錄 G.4），不能只看模型政策設定。

5.8.2 Base 與 LTS 模型【Official】

兩者僅適用於 Copilot Business 與 Copilot Enterprise。

企業建議【建議】：

1. CI 中必須寫死模型時，優先選 LTS 模型——它是唯一有官方「一年內不下架」承諾的模型。
2. 把 LTS 承諾到期日（依指定日推算約為 2027-03） 寫進第 41 章 的維運行事曆，並在到期前 90 天啟動替代評估。
3. 新的 base model 公告後，60 天內要完成 IDE 擴充套件升級——這與第 42 章 的升級 SOP 直接相關。

5.8.3 Utility models【Official】

Utility models 負責背景功能，例如產生 commit 訊息、產生 chat session 標題，跨 IDE、GitHub、Copilot CLI、GitHub Copilot app 生效。

📌 法遵盤點提醒【建議】：DPIA 或「AI 服務資料流清單」列出模型時，必須把 utility models 一併列入。它們會處理 diff 與對話內容（用以產生標題與訊息），而且無法透過模型政策關閉——只看模型政策頁面做盤點，一定會漏掉。

5.8.4 BYOK（自帶模型金鑰）【Official + Preview】

官方提供兩種完全不同的 BYOK 機制：

🚨 Local BYOK 的治理風險【建議】

Local BYOK 的資料直接送往使用者自行設定的模型供應商，適用的是該供應商與使用者個人之間的條款，而不是企業與 GitHub 之間的資料處理合約。

• ✅ 企業預設應停用 IDE 的 Local BYOK；確有需求者改走 Enterprise BYOK，由企業集中管理金鑰與供應商合約。
• 【⚠️ 文件不一致】官方僅明載政策可停用「IDE 中的 Local BYOK」，未說明 Copilot CLI 與 GitHub Copilot app 的 Local BYOK 是否受同一政策約束。企業必須在目標用戶端實測；在確認前，以網路出口管制（只放行核准的模型供應商端點）作為補償控制。

5.9 本章實務案例【建議】

情境：某 300 人 IT 部門評估導入，財務要求提供三年 TCO。

建議的成本結構呈現方式：

必須同時呈現的效益面【建議】（不要只給成本）：

⚠️ 警告 上表的百分比是本手冊的保守估計區間，不是官方數據，也不是保證值。 正確做法是：在 Pilot 階段實測你自己的數字（第 43 章 Phase 1），再拿實測值去做 TCO。用別人的數字做預算，會在驗收時出事。

5.10 注意事項

• ⚠️ 不要在本手冊或任何內部文件中固化價格數字，一律寫「以官方公告為準」。
• ⚠️ 不要用舊的 premium request 模型估算新的 AI Credits 成本。
• ⚠️ Cloud agent 是雙重計費，別忘了 Actions 分鐘數。
• ✅ 席次回收政策要在第一天宣告並自動化。
• ✅ TCO 一定要同時給成本與效益，且效益數字要來自自家 Pilot。
• 🚨 Global model policy GA 後，「沒設定模型政策」等於「全部開放」——必須主動維護白名單。
• 🚨 2026-10-01 起既有客戶的席次改為預先付費：未付款的席次，使用者完全無法使用。
• ⚠️ 席次回收不產生按比例退款，「浮動席次池」不要再以省錢為主要 KPI。
• ⚠️ 2026-09-28 起 code review 預設效力等級改為 Balanced，未動作者成本會自動上升。
• ✅ 使用者預算一律強制填寫到期日，這是成本治理最省力的槓桿。
• ✅ 指派一位負責人每月覆核模型政策清單，並留下工單紀錄。
• 🚨 Claude Fable 系列與開放權重模型（Kimi）一律預設停用，開啟前必須完成資料保留條款的法遵評估。
• ⚠️ Auto 模型選擇依實際選中的模型計費；成本歸因必須依賴每模型 token 明細。
• ⚠️ Utility models 無法停用且不計費，但仍會處理程式碼與對話內容，DPIA 必須列入。
• ✅ 需要可重現性的 CI 優先指定 LTS 模型，並追蹤其一年承諾到期日。
• ✅ 核准預算提高申請時，一併設定到期日。

6. Enterprise Governance

這是全書最重要的一章。 一句話總結：企業導入 Copilot 的核心工作不是「教大家用」，而是「讓每個人用的是同一套受控的 AI」。

6.1 治理架構全貌【Official + 建議】

flowchart TD
    subgraph L1["第一層：存取控制"]
        A1["Enterprise / Organization Policies"]
        A2["席次指派與回收"]
        A3["模型可用性"]
    end
    subgraph L2["第二層：終端強制設定"]
        B1["Enterprise Managed Settings<br/>managed-settings.json"]
        B2["MDM / 組態管理佈署"]
        B3["Permissions（allow / ask / deny）"]
        B4["Sandbox 基線"]
    end
    subgraph L3["第三層：資料邊界"]
        C1["Content Exclusion<br/>Repo / Org"]
        C2["網路設定 / Proxy / 憑證"]
        C3["防火牆（cloud agent）"]
    end
    subgraph L4["第四層：擴充治理"]
        D1["MCP Allowlist / Denylist"]
        D2["MCP Registry 強制"]
        D3["Plugin Marketplace 限制"]
        D4["Agent Management / AI Controls"]
    end
    subgraph L5["第五層：品質閘門"]
        E1["Repository Rulesets / 分支保護"]
        E2["CI Quality Gate"]
        E3["Copilot code review + 人工 Review"]
        E4["Hooks（CLI / cloud agent）"]
    end
    subgraph L6["第六層：可觀測與稽核"]
        F1["Audit Log（含 agent 事件）"]
        F2["Agent session 監控"]
        F3["Usage Metrics / Dashboards"]
        F4["OpenTelemetry 匯出"]
    end

    L1 --> L2 --> L3 --> L4 --> L5 --> L6
    L6 -.->|"發現問題 → 調整政策"| L1

🎯 這六層的設計原則 越上層越「宣告式」，越下層越「機械式」。 政策（第一層）靠設定；Instructions（不在此圖，屬引導）靠請求；Hooks 與 CI（第五層）靠強制。 不能違反的事情，一定要放在第五層，不能只寫在 Instructions 裡。

6.2 Enterprise 與 Organization Policies【Official】

官方確認的政策運作方式：

• 政策控制「使用者可以存取哪些 Copilot 功能、Agent 與模型」。
• 企業層政策可以：啟用、停用，或委派給組織決定（delegate）。
• 政策適用於 IDE、GitHub 網站與 Copilot CLI。
• 衝突規則：當使用者同時擁有多個授權來源時，「通常適用限制最少的政策」；但跨不同企業時，適用限制最嚴格的政策。
  • ⚠️ v1.2 補充：官方「Feature availability when policies conflict」明列少數敏感功能採「最嚴格組織」原則：Copilot Metrics API、Suggestions matching public code、Allow members without a Copilot license to use Copilot code review，以及非 GitHub repository 的語意索引（僅在所有組織都明確設為 Enabled 時才開放）。其餘多數功能採「最寬鬆組織」原則。

官方文件中出現的政策分類【Official】：

【⚠️ 文件不一致】 官方的政策概念頁沒有提供完整的政策名稱清單與逐項可選值，而是把細節分散在「企業／組織政策管理」的操作頁面，且該頁面主要描述介面操作而非枚舉政策項目。 因此本手冊不列出完整政策清單——任何聲稱列出「Copilot 全部政策」的第三方文章都應該被懷疑。 ✅ 正確做法：由 Enterprise 管理員登入 Settings → Copilot → Policies 逐項截圖存檔，作為企業基線文件，並每季覆核一次（第 41 章）。

企業政策基線建議【建議】：

6.3 AI Controls 與 Agent Management【Official】

官方文件將 Agent Management 描述為「集中管理與監控企業內 AI 政策與 Agent 的平台」，涵蓋 Copilot cloud agent、code review、Custom Agents 與第三方 Agent。

官方確認的能力【Official】：

📌 註記 官方的 Agent Management 概念頁未說明 .github-private repository 的角色，也未描述 Custom Agent 的審核／測試／發布流程細節；這些內容分散在「Preparing to use custom agents in your enterprise」「Creating a .github-private repository」「Testing and releasing custom agents」等操作頁面。 企業實作前請直接查閱這三頁，不要依賴二手整理。

企業 Agent 治理流程【建議】：

flowchart LR
    A["提案<br/>需要一個新 Agent"] --> B["撰寫 Agent 定義<br/>.agent.md"]
    B --> C["在試辦 repository 驗證<br/>10–20 個真實任務"]
    C --> D{"通過 Quality Gate？"}
    D -->|"否"| B
    D -->|"是"| E["資安審查<br/>tools / MCP / 權限"]
    E --> F["架構審查<br/>是否與企業規範一致"]
    F --> G["發布到組織層<br/>.github / .github-private"]
    G --> H["納入版本控管與變更紀錄"]
    H --> I["每季覆核<br/>模型換代後回歸測試"]

6.4 Enterprise Managed Settings（managed-settings.json）【Official】

這是企業治理最強的工具，也是最常被忽略的。

檔名：managed-settings.json【Official】

佈署方式：透過 MDM（行動裝置管理）解決方案或企業組態管理工具下發到開發者終端【Official】。

【⚠️ 文件不一致】 官方參考頁在描述檔案路徑時，同時給出了各平台路徑，卻又註明「文件未指定確切路徑；佈署通常透過 MDM 或企業組態管理工具進行」。 本手冊列出的路徑僅供參考，企業實作前必須在目標平台實測驗證：

平台	參考路徑
Windows	%APPDATA%\GitHub Copilot\managed-settings.json
macOS	~/Library/Application Support/GitHub Copilot/managed-settings.json
Linux	~/.config/GitHub Copilot/managed-settings.json

✅ 驗證方法：在測試機放入一個明顯可觀察的設定（例如 permissions.deny 封鎖某個指令），實際執行 Copilot CLI 確認是否生效。不要只靠文件。

6.4.1 完整設定鍵一覽【Official】

6.4.2 Permissions 選擇器語法【Official】

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "deny":  ["Shell(...)", "Read(...)", "Edit(...)", "Domain(...)"],
    "ask":   ["Shell(...)", "Read(...)", "Edit(...)", "Domain(...)"],
    "allow": ["Shell(...)", "Read(...)", "Edit(...)", "Domain(...)"]
  }
}

優先權：deny > ask > allow【Official】

6.4.3 企業基線範例【建議】

以下是一份可直接作為企業起點的 managed-settings.json。請依自家環境調整後再佈署。

{
  "model": "auto",

  "permissions": {
    "disableBypassPermissionsMode": "disable",

    "deny": [
      "Shell(rm -rf *)",
      "Shell(curl * | sh)",
      "Shell(wget * | sh)",
      "Shell(chmod 777 *)",
      "Shell(git push --force *)",
      "Shell(kubectl delete *)",
      "Shell(terraform destroy *)",
      "Shell(mvn deploy *)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Read(**/.env)",
      "Read(**/*.p12)",
      "Read(**/*.jks)",
      "Read(**/id_rsa*)",
      "Edit(//etc/**)",
      "Edit(**/.github/workflows/**)",
      "Domain(*.pastebin.com)",
      "Domain(*.transfer.sh)"
    ],

    "ask": [
      "Shell(git push *)",
      "Shell(gh pr merge *)",
      "Shell(docker *)",
      "Shell(npm publish *)",
      "Edit(**/src/main/resources/application*.yml)",
      "Edit(**/pom.xml)",
      "Edit(**/package.json)",
      "Domain(api.github.com)"
    ],

    "allow": [
      "Shell(mvn test*)",
      "Shell(mvn -q compile*)",
      "Shell(npm test*)",
      "Shell(npm run lint*)",
      "Shell(git status*)",
      "Shell(git diff*)",
      "Shell(git log*)",
      "Read(**/src/**)",
      "Read(**/docs/**)",
      "Domain(repo.maven.apache.org)",
      "Domain(registry.npmjs.org)"
    ]
  },

  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverName": "enterprise-jira" },
    { "serverName": "enterprise-confluence" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] }
  ],

  "deniedMcpServers": [
    {
      "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/"]
    }
  ],

  "strictKnownMarketplaces": [
    { "source": "github", "repo": "our-enterprise/copilot-plugins" }
  ],

  "extraKnownMarketplaces": {
    "enterprise-plugins": {
      "source": {
        "source": "github",
        "repo": "our-enterprise/copilot-plugins",
        "ref": "main"
      },
      "autoUpdate": true
    }
  },

  "enabledPlugins": {
    "java-backend-standard@enterprise-plugins": true,
    "vue-frontend-standard@enterprise-plugins": true
  },

  "remoteControl": {
    "mode": "requireSSO",
    "githubDotComOrganizations": ["our-enterprise-org"]
  },

  "telemetry": {
    "enabled": true,
    "endpoint": "https://otel-collector.internal.example.com",
    "protocol": "http/protobuf",
    "captureContent": false,
    "lockCaptureContent": true,
    "serviceName": "copilot-cli",
    "resourceAttributes": {
      "deployment.environment": "production"
    }
  },

  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowBypass": false,
    "sandboxMcpServers": true,
    "sandboxLspServers": true,
    "gitAuth": false,
    "ghAuth": false,
    "allowDevToolAccess": false,
    "userPolicy": {
      "filesystem": {
        "readwritePaths": ["/workspace"],
        "readonlyPaths": ["/usr/share/maven"],
        "deniedPaths": ["/etc", "/var/run/docker.sock"]
      },
      "network": {
        "allowOutbound": false,
        "allowLocalNetwork": false
      }
    }
  }
}

🚨 關於 telemetry.captureContent 設為 true 會把對話內容送到你的 OTel collector。在受監管產業，這可能構成新的資料留存風險（而且那份資料可能包含原始碼）。 本手冊範例刻意設為 false 並加上 lockCaptureContent: true（鎖定不允許使用者自行開啟）。若要開啟，必須先過資安與法遵評估。

6.4.4 設定優先權【Official】

Copilot CLI 的設定套用順序（後者覆蓋前者）：

1. 內建預設值
2. MDM 管控設定（managed-settings.json）
3. 使用者設定（~/.copilot/settings.json）
4. Repository 設定（.github/copilot/settings.json）
5. 本機設定（.github/copilot/settings.local.json）
6. 環境變數
7. 命令列參數

MDM 的兩個例外【Official】：

1. permissions.disableBypassPermissionsMode 設為 "disable" 時永遠優先，使用者無法覆寫。
2. MDM 的 sandbox 設定建立的是最低基線，使用者設定只能收緊、不能放寬。

🎯 這兩個例外就是企業治理的著力點 其他設定都可能被使用者用更高優先權覆蓋掉。真正要強制的東西，只能放在這兩個例外裡，或放在 CI/CD 這種使用者管不到的地方。

6.4.5 團隊層覆寫【Official】

官方支援以 { "overridable": <VALUE> } 語法讓企業層設定在團隊層可被覆寫。

使用時機【建議】：企業設定嚴格基線，但允許特定團隊（例如需要跑 Docker 的平台團隊）在經核准後放寬特定項目。務必搭配變更紀錄與定期覆核。

6.4.6 Agent 操作權限的企業強制管控【Official】

⚠️ Version Note（2026-09-09）

官方於 2026-09-09 發布「Enterprise managed permissions for GitHub Copilot agent operations」，讓企業管理員能集中決定哪些 agent 操作被封鎖、哪些需要人工核可、哪些可直接放行。

這項機制的三個關鍵特性【Official】：

支援介面【Official】：GitHub Copilot app、GitHub Copilot CLI、以及 Visual Studio Code（需搭配 Agent Host）。

🎯 為什麼「不可被弱化」這句話值得單獨強調

在此機制之前，企業的 deny 規則存在一個實務破口：開發者在 IDE 或 CLI 中對某個危險操作按下「總是允許」，該核可會被持久化儲存，之後同類操作就不再詢問。 稽核時管理員看到的是「我們有設 ask 規則」，實際上該規則對這台機器已經形同虛設。

現在官方明確保證企業管控不會被既有的已儲存核可覆寫。這讓 permissions.ask 從「第一次會問」升級為真正可稽核的控制點。

⚠️ 【⚠️ 文件不一致】 該公告本身未列出新增的 JSON 鍵名或結構，而是指向 enterprise-managed-settings 參考頁的 deny／ask／allow 段落。 本手冊的判讀是：此功能沿用既有的 permissions.deny / ask / allow 結構（見第 6.4.2 小節），公告強調的是強制力（不可被弱化）與涵蓋介面的擴大，而非新增語法。 企業導入前請自行實測驗證，特別是「先前已按過 Always allow 的機器，套用管控後是否確實恢復詢問」這一點。

✅ 建議的驗收測試【建議】：

□ 1. 在測試機以開發者身分對某危險指令按下「總是允許」
□ 2. 佈署含該指令 deny 規則的 managed-settings.json
□ 3. 重新執行該指令 → 應被封鎖（驗證「不可被弱化」）
□ 4. 嘗試在使用者層 settings.json 中加入 allow 規則覆寫 → 應無效
□ 5. 嘗試以 --allow-all-tools 之類的旗標繞過 → 應無效
□ 6. 檢查稽核記錄是否留下被封鎖的紀錄

6.5 Content Exclusion（內容排除）【Official】

6.5.1 它做什麼、不做什麼

會做的事【Official】：

• 受影響檔案不會有行內建議
• 受影響檔案的內容不會影響其他檔案的行內建議
• 受影響檔案的內容不會用於 Copilot 的回應
• 受影響檔案不會被 Copilot code review 審查

不會做的事 / 限制【Official】：

• 🚨 目前不支援 Copilot Chat 的 Edit 與 Agent 模式
• Copilot 仍可能透過 IDE 提供的型別資訊與建置設定，間接取得被排除檔案的語意資料
• 不支援符號連結（symbolic link）與遠端檔案系統 repository
• Xcode 與 Eclipse 不支援 chat/agent 的內容排除

🚨 這是本章最重要的警告 Content Exclusion 不能當作 Agent 的資料防護唯一手段。 官方明載它在 Agent 模式下不生效。如果你的機密檔案必須被 Agent 完全隔絕，正確做法是：

1. 不要把它放進 repository（用外部 Secret 管理）；
2. 用 managed-settings.json 的 permissions.deny 加上 Read(**/secrets/**) 之類的規則；
3. 用 sandbox.userPolicy.filesystem.deniedPaths 從檔案系統層阻擋；
4. Content Exclusion 作為補強，不是主要防線。

⚠️ Version Note（2026-09-02）：Copilot app 與 CLI 的 Content Exclusion 已 GA

官方於 2026-09-02 宣布 content exclusion 在 GitHub Copilot app 與 GitHub Copilot CLI 正式 GA，敏感程式碼會在這兩個介面的 agentic 工作流程中被排除於 context 之外。

這修補了本手冊先前版本反覆提醒的一個缺口：在此之前，內容排除幾乎只在行內建議與 Chat 的部分情境生效，agent 類流程形同不設防。

但請注意兩件事：

1. 這項 GA 涵蓋的是 Copilot app 與 Copilot CLI。IDE 內 Copilot Chat 的 Edit / Agent 模式是否已全面涵蓋，官方文件的限制清單尚未同步更新——本手冊標示為【⚠️ 文件不一致】，企業必須在自家 IDE 版本上實測驗證，不要僅憑本節或官方任一頁面下結論。
2. 上述「不能當作唯一防線」的結論依然成立。內容排除是平台側的 context 過濾，不是檔案系統層的存取控制；只要 Agent 能執行 shell 指令，它就可能用 cat 讀到檔案。真正的隔離仍必須靠 permissions.deny 與 sandbox.userPolicy.filesystem.deniedPaths。

✅ 實測方法：在測試 repo 放一個被排除的檔案（內含可辨識的唯一字串），分別在 IDE Agent 模式、Copilot CLI、Copilot app 中要求 Copilot「總結這個 repo 的所有設定值」，檢查該字串是否出現在回應中。同時也要測試「請執行 cat <該檔案>」——兩種路徑的結果通常不同。

6.5.2 Repository 層語法【Official】

於 Repository Settings → Copilot → Content exclusion 設定：

# 排除本 repository 的 /src/some-dir/kernel.rs
- "/src/some-dir/kernel.rs"

# 排除任何位置名為 secrets.json 的檔案
- "secrets.json"

# 排除任何位置檔名以 secret 開頭的檔案
- "secret*"

# 排除任何位置副檔名為 .cfg 的檔案
- "*.cfg"

# 排除 /scripts 目錄及其下所有檔案
- "/scripts/**"

6.5.3 Organization 層語法【Official】

於 Organization Settings → Copilot → Content exclusion 設定：

# 對所有 repository 生效（含非 Git 檔案）
"*":
  - "**/.env"
  - "**/application-prod.yml"
  - "**/*.jks"
  - "**/*.p12"

# 指定 repository 名稱
octo-repo:
  - "/src/some-dir/kernel.rs"

# 指定完整 HTTPS URL
https://github.com/primer/react.git:
  - "secrets.json"
  - "/src/**/temp.rb"

# 使用 SSH 格式並搭配萬用字元
git@github.com:*/copilot:
  - "/__tests__/**"
  - "/scripts/*"

# 非 GitHub 託管的 repository 也可指定
git@gitlab.com:gitlab-org/gitlab-runner.git:
  - "/main_test.go"
  - "{server,session}*"
  - "*.m[dk]"
  - "**/package?/*"
  - "**/security/**"

支援的 repository 參照格式【Official】：

http[s]://host.xz[:port]/path/to/repo.git/
git://host.xz[:port]/path/to/repo.git/
[user@]host.xz:path/to/repo.git/
ssh://[user@]host.xz[:port]/path/to/repo.git/

📌 官方註明：user@ 與 :port 部分在計算排除路徑時會被忽略。比對採 fnmatch 樣式且不分大小寫。

6.5.4 生效時間與驗證【Official】

• 變更後，IDE 中已載入的設定最多需要 30 分鐘才生效。
• 手動重載方式：
  • JetBrains / Visual Studio：關閉並重新開啟應用程式
  • VS Code：命令面板 → Developer: Reload Window
  • Vim / Neovim：開啟檔案時自動取得

驗證步驟【Official】：

1. 開啟一個「未被排除」的檔案 → 確認行內建議正常出現
2. 開啟一個「已被排除」的檔案 → 確認沒有建議出現
3. Copilot Chat：把被排除檔案附加為 context，輸入 "explain this file"
   → 若排除正確，Copilot 不會回應該檔案內容

6.5.5 企業建議排除清單【建議】

"*":
  # 憑證與金鑰
  - "**/*.p12"
  - "**/*.pfx"
  - "**/*.jks"
  - "**/*.keystore"
  - "**/*.pem"
  - "**/*.key"
  - "**/id_rsa*"
  # 環境與機密設定
  - "**/.env"
  - "**/.env.*"
  - "**/application-prod.yml"
  - "**/application-prod.properties"
  - "**/secrets/**"
  - "**/credentials*"
  # 個資與測試資料
  - "**/testdata/pii/**"
  - "**/fixtures/customers*"
  # 法遵與合約
  - "**/legal/**"
  - "**/contracts/**"

6.6 MCP 治理【Official】

📌 官方限制註記 官方 CLI 概念頁明載：MCP server 的使用控制政策與 registry URL 限制，目前在組織層級尚未支援於 Copilot CLI。 這代表：如果你只靠組織政策治理 MCP，CLI 使用者可能繞過。 企業必須同時使用 managed-settings.json 的 allowedMcpServers / deniedMcpServers（MDM 下發）。這是本手冊強烈建議雙軌治理的原因。

⚠️ v1.2 更正與補充：官方 CLI 參考頁另載明，Copilot CLI 會執行企業層的 MCP allowlist——偵測到 GitHub Enterprise registry 政策時，CLI 會依每個非預設 server 的 command、參數與遠端 URL 計算指紋，送到企業 allowlist 評估端點，只允許核准者連線；評估端點無法連線或回傳錯誤時一律封鎖（fail-closed）；內建預設 server 不受此限制。 因此精確的說法是：組織層的 MCP servers in Copilot 與 MCP Registry URL 政策仍不支援 CLI；企業層 allowlist 則會在 CLI 執行。雙軌治理的建議不變——managed-settings.json（MDM 下發）是以裝置為單位、不受帳號切換影響的終端控制。

詳見第 14 章。

6.7 網路、Proxy 與防火牆【Official + 建議】

官方提供的相關文件【Official】：

• Network settings for GitHub Copilot（概念）
• Configuring network settings for GitHub Copilot（個人設定）
• Managing GitHub Copilot access to your organization's network
• Managing GitHub Copilot access to your enterprise's network
• Copilot allowlist reference（企業防火牆需放行的網域清單）
• Customizing or disabling the firewall for GitHub Copilot（cloud agent 防火牆）
• Troubleshooting firewall settings / Troubleshooting network errors

✅ 企業導入前必做 在發放第一張 License 之前，先請網路團隊依 Copilot allowlist reference 放行必要網域。 不要用「先試試看再說」——大規模導入時才發現網路擋住，會產生大量無效的 Helpdesk 工單，並嚴重打擊使用者信心。

Cloud agent 的防火牆【Official】：cloud agent 執行環境預設受防火牆限制，並預設啟用建議允許清單（作業系統與語言套件庫、容器 registry、憑證授權機構等）。若你的 hook 是 HTTP 型且指向內部服務，該主機必須在允許清單內，否則 hook 會失敗。

⚠️ v1.2 更正：v1.1 寫「預設僅允許 GitHub／Copilot 主機」並不精確。防火牆的完整預設值、組織層「Internet access」設定，以及不涵蓋 MCP server 與 setup steps 程序的限制，詳見第 31.5.3 節。

6.8 稽核與可觀測性【Official】

企業稽核 SOP【建議】：

每日   → 檢視失敗率異常的 agent session
每週   → 檢視 Usage metrics，找出用量異常者（過高或為零）
每月   → 匯出 Audit Log，比對政策變更紀錄
每季   → 政策基線覆核（截圖比對）＋ Agent / Skill / MCP 清單覆核
每半年 → 完整治理稽核，含 managed-settings.json 實際生效驗證

6.9 如何避免「每個開發者自己設定一套 AI」【建議】

這是本章標題背後的真正問題。以下是可執行的五步法：

🎯 關鍵洞察 這五步中，只有第 4 步是「文件」，其他四步都是「技術強制」。 企業治理失敗的典型模式，就是五步全部寫成文件、沒有一步做成技術強制。 文件治理 AI 的效果，等於用 email 治理防火牆。

6.10 模型治理與模型退役管理【Official + 建議】

大多數企業把「模型」當成技術細節交給開發者自己選。在 Copilot 的現行架構下，這是錯的：模型清單直接牽動法遵（資料送往哪個供應商）、成本（AI Credits 乘數）、以及產出品質（不同模型的指令遵循度差異極大）。

6.10.1 模型退役是常態，不是意外【Official】

2026 年的實際退役紀錄足以說明頻率：

📌 v1.2 補充：10/19 這一批包含 GPT-5 mini、GPT-5.4 mini 等常被當作「低成本預設」的模型，也包含第三方 OpenAI Codex agent 的可選模型 GPT-5.4。官方公告指出，已啟用預設政策的 Business／Enterprise 會自動啟用替代模型（除非管理員曾停用）。另請注意：查證日官方「Model retirement history」表尚未列入 10/19 這一批，僅見於 Changelog——這再次印證 6.10.3 要求「同時監控 Changelog」的必要。

🎯 結論：模型的平均壽命是「月」，不是「年」。 任何把模型名稱寫死的資產——Custom Agent 的 model 欄位、CI 腳本、managed-settings.json 的 model 鍵、內部規範文件——都是會定期腐化的技術債。

6.10.2 模型退役會打壞什麼【建議】

🚨 最危險的不是「報錯」，是「靜默回退」。 模型退役後，系統通常會自動改用另一個模型繼續服務。表面上一切正常，但指令遵循度、輸出格式穩定度、對 Custom Instructions 的服從程度可能明顯不同。 這種劣化不會出現在任何錯誤日誌裡，只會表現為「最近 Copilot 好像變笨了」的模糊抱怨。必須靠回歸測試主動偵測。

6.10.3 企業模型治理 SOP【建議】

原則：規範寫「準則」，設定寫「清單」。

規範文件（會被人閱讀、更新慢）只寫選型準則；實際的模型清單放在設定檔與政策介面（可被腳本稽核、更新快）。

【每月】模型政策覆核
  1. 匯出目前 Enterprise / Organization 的模型政策啟用清單
  2. 對照官方 Supported models 頁，找出「新增但未經決策」的模型
  3. 對每個新模型做出明確決定（啟用 / 停用），並記錄理由
  4. 檢查官方 Changelog 是否有退役預告
  5. 若有退役預告 → 進入【退役應變】流程

【退役應變】（收到退役預告起算，須在生效日前完成）
  1. 全 repo 掃描：grep -rn "model:" .github/agents/ .github/workflows/
  2. 盤點受影響資產，指派負責人
  3. 選定替代模型，於測試 repo 執行 Agent 行為回歸測試
  4. 比對回歸測試結果，確認品質未劣化
  5. 更新設定 → 更新文件 → 內部公告
  6. 生效日後 7 天內覆核使用者回饋

【季度】模型選型準則覆核
  1. 檢視各 Agent 的模型指派是否仍為最佳選擇
  2. 檢視成本結構是否需要調整（高階模型的使用比例）

✅ 模型指派的企業選型準則【建議】：

✅ 一個實用的折衷：在 managed-settings.json 中把預設值設為 "model": "auto"，讓日常互動自動跟隨平台演進；只有需要可重現性的 CI 步驟才寫死版本，並把這些寫死的位置集中在少數幾個檔案，方便退役時盤點。

6.11 團隊專屬設定（Team Specialization）與設定合併規則【Official】

企業層的一份 managed-settings.json 很難同時滿足所有團隊：資安團隊需要最嚴格的沙箱，資料團隊需要存取特定 MCP Server，前端團隊需要不同的預設模型。

官方提供 **team specialization（企業團隊專屬設定）**機制解決這個問題（2026-08-03 加入 managed settings）。

6.11.1 overridable 與 unmanaged【Official】

支援 team specialization 的鍵包含 model 與 allowedMcpServers 等。

⚠️ 【⚠️ 文件不一致】 官方參考頁對「哪些鍵支援 overridable」的列舉不完整，且各鍵的支援用戶端（Copilot CLI／VS Code／Copilot app／JetBrains）並不一致。 企業實作前，必須對每一個要用 overridable 的鍵，在目標用戶端逐一實測驗證。

6.11.2 多來源設定的合併語意（極易誤解）【Official】

不同的設定鍵，在多來源合併時採用不同的合併邏輯。搞錯這一點，會做出「以為擋住了、其實沒擋住」的設定。

🎯 記憶法：白名單取交集，黑名單取聯集——兩者都朝「更嚴格」的方向收斂。 這是刻意的安全設計：多層治理疊加時，永遠不會因為疊加而變寬鬆。

另外兩條必須知道的規則【Official】：

• 第一方 Copilot MCP Server 無法被封鎖。 deniedMcpServers 對官方第一方 Server 不生效。
• 省略 allowedMcpServers 等於「允許黑名單以外的全部」。 若你的意圖是「只允許清單上的」，必須明確宣告該鍵——省略不是嚴格模式。

6.11.3 MCP Server URL 的正規化規則【Official】

在寫 serverUrl 比對規則時，官方會先對 URL 做**正規化（canonicalization）**再比對。不了解這些規則，很容易寫出繞得過去的白名單：

🚨 實務警告：撰寫白名單後，務必用「看起來很像但不該通過」的 URL 實測，例如 https://api.githubcopilot.com.attacker.example。 正規化規則保護的是規則撰寫者的意圖，但它保護不了寫錯的規則。

6.12 統一 Copilot 體驗與資料保留期限變更【Official】

🚨 這是本章對法遵團隊最重要的一節。

6.12.1 變更內容【Official】

官方於 2026-08-28 公告，不早於 2026-09-28，將把三個介面合併為單一體驗、套用單一政策：

• github.com 上的 Copilot Chat
• GitHub Mobile 上的 Copilot Chat
• GitHub Copilot cloud agent

📌 v1.2 狀態更新（2026-09-25）：官方仍維持「不早於 2026-09-28」的措辭，截至查證日尚未公告確切上線日（列入附錄 H.5 待追蹤）。

6.12.2 為什麼這對企業是重大變更【建議】

6.12.3 上線前的必辦清單【建議】

□ 1. 取得並閱讀官方公告全文，確認最終生效日（官方措辭為「不早於」9/28，可能延後）
□ 2. 比對本企業的「第三方服務資料保留政策」，確認是否衝突
□ 3. 若衝突 → 啟動例外核准流程，或評估退出的營運衝擊
□ 4. 更新 DPIA / 個資盤點表中「GitHub Copilot」條目的保留期限欄位
□ 5. 確認 Copilot Chat 的使用規範是否需要收緊
        （保留期限延長 → 誤貼機密資料的風險曝險期同步延長）
□ 6. 更新開發者行為守則：明確禁止在 Chat 中貼入
        Secret、憑證、個資、客戶資料、未公開財務資訊
□ 7. 內部公告：說明變更、生效日、以及使用者該注意什麼
□ 8. 生效後覆核：確認 cloud agent 的行為與稽核記錄未受影響

✅ 本節與第 27 章 的關聯： 資料保留期限延長，等於放大了「誤貼」事件的影響半徑。原本 28 天後自然消失的誤貼內容，現在會長期存在。 因此本變更生效後，Content Exclusion（第 6.5 節）的重要性顯著提升——它是少數能在資料離開終端前就攔截的機制。

📌 好消息：2026-09-02 起，GitHub Copilot app 與 Copilot CLI 的 content exclusion 已 GA。 在此之前，content exclusion 僅在部分介面生效，這是本手冊先前版本中反覆提醒的缺口。現在 app 與 CLI 的 agentic 流程也會遵守內容排除設定，企業的 content exclusion 投資報酬率因此提高。詳見第 6.5 節。

6.13 新功能預設啟用政策（Default policy for new features）【Official + 建議】

🆕 v1.2 新增

🚨 生效日：2026-10-22。 官方文件明載此政策本身預設為 Enabled——不採取任何動作，所有 Unconfigured 的 GA 功能會在當日開啟。

6.13.1 兩個「預設可用性」政策【Official】

Copilot Business／Enterprise 現在有兩個彼此獨立的預設可用性政策：

可選設定【Official】：

6.13.2 政策的精確涵蓋範圍【Official】

會受影響的功能：

• 新推出的 GA 功能
• 由預覽（preview）轉為 GA 的功能
• 在政策設定中標示為 Unconfigured 的既有 GA 功能

層級規則：

• 企業層：適用於標示為 Unconfigured 的功能。
• 組織層：適用於企業擁有者設為 Let organizations decide、而組織擁有者尚未明確設定的功能。

「功能」的官方定義：企業「Features & clients」頁（github.com/enterprises/ENTERPRISE/ai-controls/copilot/features）上的所有政策，再加上：

• 「Agents」頁上的 Copilot code review 政策
• 「MCP」頁上的 MCP servers in Copilot 政策

明確排除（不受此政策影響）：

• 所有預覽中的功能
• GHE.com 上的限制型模型政策：Restrict Copilot to data residency models、Restrict Copilot to FedRAMP models
• Copilot CLI 與 VS Code 的 Store local sessions in the Cloud

模型預設政策的排除項目（對照用）：Pre-GA 模型、開放權重模型（DeepSeek、Kimi K2.7 Code、Kimi K3）、不在 GitHub 資料保留協議涵蓋範圍內的模型（Claude Fable 5、Claude Fable 5.1），以及已限制為資料落地／FedRAMP 模型之企業中不符規範的模型——這些模型無論預設政策為何都預設停用，未經明確開啟就不會出現在模型選單。

📌 官方在政策設定頁會顯示一個橫幅，列出目前仍為 Unconfigured 的合格政策數量，讓管理員在 10-22 前評估影響範圍。

6.13.3 本手冊既有建議會受到什麼影響【建議】

🎯 核心原則：官方明載「若你已明確啟用或停用某功能，我們不會覆寫該選擇」。 因此，「明確設定」是唯一不會被未來任何預設變更影響的狀態。Unconfigured 從今以後應被視為「將來可能被開啟」，而不是「關閉」。

6.13.4 全域預設的選擇建議【建議】

6.13.5 10-22 前的盤點 SOP【建議】

□ 1. 由 Enterprise 管理員登入 AI Controls，記錄橫幅顯示的 Unconfigured 政策數量
□ 2. 匯出（截圖）Features & clients、Agents、MCP 三個頁面的現況，存為基線
□ 3. 依 6.13.4 決定全域預設值，並於變更管理系統留下決策紀錄與理由
□ 4. 對下列高風險政策「逐一明確設定」（不論全域預設為何）：
       - MCP servers in Copilot
       - Copilot code review（含預設效力等級）
       - Copilot cloud agent、Agent apps、第三方 coding agents
       - Copilot Memory、Copilot Spaces
       - Suggestions matching public code
□ 5. 若全域預設為 Let organizations decide，通知各組織擁有者完成同樣的盤點
□ 6. 在第 41 章的維運行事曆加入「每月新功能 GA 審查」，
       依附錄 G.6 的分類準則處理每一則 Changelog
□ 7. 內部公告：說明 10-22 的變更、企業的選擇，以及使用者可能看到的新功能
□ 8. 10-23 驗證：確認 Unconfigured 數量為 0，或剩餘項目皆為刻意保留

🚨 最常見的錯誤：只設定了全域預設為 Disabled，卻沒有逐項明確設定高風險政策。 這在今天是安全的，但只要未來有人把全域預設改回 Enabled，所有 Unconfigured 項目會同時被打開。高風險項目一定要逐項明確設定，不要依賴全域預設。

6.14 本章實務案例【建議】

情境：某金融業導入 6 個月後的內稽發現三個問題。

🎯 三個問題的共同根因 治理只做了「宣告層」，沒做「強制層」。 政策設了，但覆蓋不到 CLI；Content Exclusion 設了，但 Agent 模式不生效；Agent 規範寫了，但沒有 CODEOWNERS 把關。 每一條治理規則，都要問一句：「如果有人不遵守，系統會擋下來嗎？」如果答案是「不會」，那它只是建議，不是治理。

6.15 注意事項

• 🚨 2026-10-22 起「Default policy for new features」生效：高風險政策（MCP、code review、cloud agent、agent apps）必須逐項明確設定，不可停留在 Unconfigured。
• ⚠️ Cloud agent 防火牆不涵蓋 MCP server 與 setup steps 程序，不能視為完整的出口管制。
• 🚨 Content Exclusion 在 Agent 模式不生效 ——這是最容易致命的誤解。
• 🚨 組織層 MCP 政策不涵蓋 Copilot CLI ——必須用 managed-settings.json 補位。
• ⚠️ managed-settings.json 的實際路徑務必在目標平台實測驗證，不要只依文件。
• ⚠️ 政策衝突規則：同企業內多授權通常取最寬鬆，跨企業取最嚴格——多 Org 環境務必實測。
• ✅ 真正要強制的只有兩個著力點：disableBypassPermissionsMode: "disable" 與 MDM sandbox 基線，其餘都可能被覆寫。
• ✅ 每一條治理規則都要能回答「不遵守時系統會不會擋」。
• 🚨 2026-09-28 起 Chat 資料保留延長為帳號生命週期，法遵團隊必須在生效日前完成評估。
• 🚨 模型退役最危險的不是報錯，是靜默回退——必須靠 Agent 行為回歸測試主動偵測。
• ⚠️ 白名單（allowedMcpServers）取交集、黑名單（deniedMcpServers）取聯集，兩者都朝更嚴格收斂。
• ⚠️ 省略 allowedMcpServers 等於「允許黑名單以外的全部」，不是嚴格模式。
• ⚠️ 第一方 Copilot MCP Server 無法被 deniedMcpServers 封鎖。
• ⚠️ Content exclusion 已在 app／CLI GA，但它仍是 context 過濾，不是檔案系統存取控制。
• ✅ 企業管控權限「不可被使用者先前的 Always allow 弱化」——請把這一點納入驗收測試。
• ✅ 模型政策改為「主動白名單」，並指派負責人每月覆核。

第三部　安裝與使用介面

這一部是動手章。 但請注意順序：第二部的治理設定要先做完，再做這一部。先發 License 再想治理，就是在賭運氣。

7. GitHub Copilot 安裝

7.1 安裝前檢查清單【建議】

在任何一台機器上安裝之前，先確認這六項：

□ 使用者已加入企業 Organization，且已取得 Copilot 席次
□ 網路團隊已依 Copilot allowlist reference 放行必要網域
□ Proxy / TLS 攔截設備的憑證已佈署到開發機
□ managed-settings.json 已透過 MDM 下發（或已確認佈署管道）
□ Content Exclusion 已在 Organization 層設定基線
□ 企業 Copilot 使用規範已公告（第 36 章）

⚠️ 順序很重要 特別是 Proxy 憑證。企業內最常見的安裝失敗原因不是「Copilot 有問題」，而是 TLS 攔截設備讓 Copilot 無法驗證憑證。這在第 40 章 有完整處理流程。

7.2 Windows 安裝【Official + 建議】

Windows 範例一律以 PowerShell 7+（pwsh） 為主。

7.2.1 前置環境

# 確認 PowerShell 版本（建議 7.x 以上）
$PSVersionTable.PSVersion

# 確認 Node.js（Copilot CLI 需要）
node --version
npm --version

# 確認 Git
git --version

# 確認 GitHub CLI（選用，但企業建議安裝）
gh --version

若尚未安裝，建議透過 winget 統一佈署：

winget install --id Microsoft.PowerShell --source winget
winget install --id OpenJS.NodeJS.LTS --source winget
winget install --id Git.Git --source winget
winget install --id GitHub.cli --source winget
winget install --id Microsoft.VisualStudioCode --source winget

✅ 企業建議 把上面這段做成 MDM 的軟體佈署腳本，讓新機開箱即具備完整環境。不要讓每位工程師自己 Google 安裝步驟——版本不一致是後續疑難排解的主要噪音來源。

7.2.2 企業 Proxy 設定

# 設定 npm proxy（若企業有 Proxy）
npm config set proxy "http://proxy.corp.example.com:8080"
npm config set https-proxy "http://proxy.corp.example.com:8080"

# 設定系統層級環境變數（供 CLI 使用）
[Environment]::SetEnvironmentVariable("HTTP_PROXY",  "http://proxy.corp.example.com:8080", "User")
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.corp.example.com:8080", "User")
[Environment]::SetEnvironmentVariable("NO_PROXY",    "localhost,127.0.0.1,.corp.example.com", "User")

7.2.3 企業憑證設定

若企業使用 TLS 攔截（SSL Inspection），必須讓工具信任企業根憑證：

# 匯出企業根憑證（由資安提供 .crt 檔）
$certPath = "C:\ProgramData\Corp\corp-root-ca.crt"

# Node.js / npm 信任企業憑證
[Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", $certPath, "User")
npm config set cafile $certPath

# Git 信任企業憑證
git config --global http.sslCAInfo $certPath

🚨 絕對不要做的事

# ❌ 千萬不要用這招「解決」憑證問題
npm config set strict-ssl false
git config --global http.sslVerify false
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"

這會關閉所有 TLS 驗證，等於把整台開發機暴露在中間人攻擊下。網路上大量教學會這樣教，企業環境一律禁止，應寫進第 36 章 的禁止清單。

7.3 macOS 安裝【建議】

# 使用 Homebrew 統一佈署
brew install node
brew install git
brew install gh
brew install --cask visual-studio-code

# 企業 Proxy
export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com"

# 企業憑證
export NODE_EXTRA_CA_CERTS="/Library/Application Support/Corp/corp-root-ca.pem"

建議把 Proxy 與憑證設定寫進 ~/.zshrc，並由 MDM（例如 Jamf）統一佈署。

7.4 Linux 安裝【建議】

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y curl git
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# RHEL / Rocky
sudo dnf install -y nodejs git

# 企業憑證（系統層）
sudo cp corp-root-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

7.5 VS Code 安裝與設定【Official + 建議】

VS Code 是目前 Copilot 功能覆蓋最完整的 IDE（見第 4.1 節）。

安裝步驟：

1. 開啟 VS Code → 側邊欄 Extensions
2. 搜尋並安裝 GitHub Copilot（同時會安裝 GitHub Copilot Chat）
3. 右下角出現 Copilot 圖示 → 點擊 → Sign in to GitHub
4. 瀏覽器完成 OAuth 授權 → 回到 VS Code
5. 確認狀態列 Copilot 圖示為正常狀態（非斜線）

企業建議的 workspace 設定【建議】：

在專案的 .vscode/settings.json 中：

{
  // 對特定語言關閉行內建議（例如敏感設定檔）
  "github.copilot.enable": {
    "*": true,
    "plaintext": false,
    "markdown": true,
    "yaml": true,
    "properties": false,
    "dotenv": false
  },

  // 讓 Copilot 讀取專案指令
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,

  // 團隊統一的 workspace 索引行為
  "search.exclude": {
    "**/target": true,
    "**/node_modules": true,
    "**/dist": true
  }
}

📌 註記 VS Code 的 Copilot 設定鍵會隨版本演進而變動。上面的鍵名請以你安裝版本的官方 VS Code 文件為準（code.visualstudio.com/docs/copilot）。本手冊不保證跨版本一致。

7.6 Visual Studio 安裝【Official】

Visual Studio 2022 以上版本內建 GitHub Copilot 支援。

步驟：

1. Visual Studio Installer → 修改 → 確認勾選 GitHub Copilot 元件
2. 開啟 Visual Studio → 右上角帳戶 → 登入 GitHub 帳號
3. 工具 → 選項 → GitHub → Copilot 確認狀態

Visual Studio 的獨特能力【Official】：依官方 feature matrix，Visual Studio 是唯一支援 .NET Upgrade Agent 的環境，且 Vision（圖片輸入） 與 BYOK 為完整支援（非預覽）。若企業有 .NET Legacy 升版需求，Visual Studio 是首選。

7.7 JetBrains IDE 安裝【Official】

適用 IntelliJ IDEA、PyCharm、WebStorm、Rider、GoLand 等。

步驟：

1. Settings → Plugins → Marketplace 搜尋 GitHub Copilot → Install
2. 重啟 IDE
3. Tools → GitHub Copilot → Login to GitHub
4. 複製 device code → 於瀏覽器完成驗證

⚠️ JetBrains 使用者必讀 依官方 customization cheat sheet，JetBrains 在多項客製化機制上仍屬 Preview：Custom Instructions（P）、Prompt Files（P）、Custom Agents（P）、Agent Skills（P）、Subagents（P）；而 Hooks 完全不支援（❌）。 這代表：如果你的企業治理策略依賴 Hooks 在 IDE 端強制執行，JetBrains 使用者是治理缺口。 必須改由 CI/CD 與 Copilot CLI 補位。這一點在多語言團隊（Java 用 IntelliJ、前端用 VS Code）特別重要。

7.8 Eclipse 與 Xcode【Official】

🚨 企業必須知道的資安缺口 官方明載 Xcode 與 Eclipse 不支援 chat/agent 的內容排除。 如果你的 iOS 團隊用 Xcode、Java 老專案用 Eclipse，這兩群人的 Content Exclusion 保護是不完整的。企業必須以其他手段補強（不要把機密檔案放進 repository、用 managed-settings.json 的檔案權限限制）。

7.9 Copilot CLI 安裝【Official】

Copilot CLI 的執行檔名稱是 copilot【Official】。

⚠️ 不要與 gh copilot 混淆 gh copilot 是 GitHub CLI 的一個 extension（官方文件中的「Using the GitHub CLI Copilot extension」）。 copilot 是獨立的 Copilot CLI agent，功能完全不同、能力層級也完全不同。本手冊第 8 章 談的是後者。

支援作業系統【Official】：Linux、macOS、Windows（透過 PowerShell 與 WSL）。

安裝（PowerShell）：

# 依官方「Installing GitHub Copilot CLI」頁面的方式安裝
# 安裝完成後驗證：
copilot --version

# 首次登入
copilot login

# 檢視可用的登入選項
copilot login --help

登入選項【Official】：

認證環境變數優先權【Official】：

COPILOT_GITHUB_TOKEN   （最高優先權）
GH_TOKEN
GITHUB_TOKEN

✅ 企業建議

• 開發者機器：使用 copilot login（OAuth），不要把 PAT 寫進環境變數。
• CI/CD：使用 GITHUB_TOKEN（官方有「Using Copilot CLI in GitHub Actions with GITHUB_TOKEN」專頁）。
• 無瀏覽器的跳板機／堡壘主機：使用 --device-code。

設定目錄【Official】：預設為 ~/.copilot（Windows 為 C:\Users\YOUR-USER\.copilot），可用環境變數 COPILOT_HOME 覆寫。

7.10 GitHub Enterprise Server / GHE.com 環境【Official】

若企業使用 GHE.com（GitHub Enterprise Cloud with data residency），官方有專頁「Using GitHub Copilot with an account on GHE.com」。

要點【Official + 建議】：

• CLI 登入需指定 --host
• IDE 需設定對應的 GitHub host
• MCP Server 若要連 GitHub，需使用「Configuring the GitHub MCP Server for GitHub Enterprise」的設定
• 網路允許清單需包含你的 GHE.com 子網域

7.11 安裝驗證 SOP【建議】

安裝完成後，用這份 SOP 驗證，而不是「看起來能用就好」：

【1. 補全驗證】
   開啟一個 .java 檔 → 輸入 // 建立一個計算訂單總金額的方法
   → 確認出現行內建議

【2. Chat 驗證】
   在 IDE Chat 中輸入：解釋這個專案的架構
   → 確認能讀取 workspace context

【3. Instructions 驗證】
   確認 .github/copilot-instructions.md 存在
   → 在 Chat 問：我們的架構規範是什麼？
   → 確認回答內容來自該檔案

【4. Content Exclusion 驗證】
   開啟被排除的檔案 → 確認無行內建議
   Chat 附加該檔案 → 輸入 explain this file → 確認無回應

【5. CLI 驗證】
   copilot --version
   copilot        （進入互動模式）
   /context       （確認 token 用量顯示正常）
   /exit

【6. Managed Settings 驗證】
   在 CLI 中嘗試執行一個被 deny 的指令
   → 確認被阻擋（證明 MDM 設定確實生效）

【7. MCP 驗證】
   copilot 進入互動模式 → /mcp 或 copilot mcp
   → 確認只看得到企業核准的 MCP Server

🎯 第 6 步是最重要的 大多數企業從來沒驗證過 managed-settings.json 是否真的生效。 沒驗證過的治理設定，等於沒有治理設定。

7.12 JetBrains 企業級佈署（2026 年重大補強）【Official】

⚠️ Version Note

JetBrains 在 2026 年 8–9 月間補上了三塊長期缺失的企業能力。任何 2026 年 8 月以前撰寫的「JetBrains 治理缺口」評估，都必須重新做。

7.12.1 三項關鍵補強【Official】

7.12.2 什麼是 Copilot harness【Official + 建議】

Harness 是 Copilot 的共用代理執行核心——負責工具呼叫、context 組裝、權限詢問、session 管理的那一層。

過去各 IDE 各自實作這一層，導致：

• 同一份 Custom Agent 定義，在 VS Code 與 JetBrains 的行為不一致；
• 新功能必須在每個 IDE 重寫一次，JetBrains 永遠落後數個月；
• 治理機制（權限、沙箱）在不同 IDE 的涵蓋率不同。

Harness GA 之後，JetBrains 改用與其他介面共用的執行核心，因此官方說明強調「更快的功能交付與更好的程式碼品質」。

🎯 對企業的真正意義：治理的一致性。 共用 harness 代表 managed-settings.json 的 permissions、sandbox 等機制有機會在各介面有一致行為，而不是每個 IDE 一套規則。這是本手冊第 6 章 治理策略能否落地的關鍵前提。

7.12.3 JetBrains 治理能力現況重評【建議】

⚠️ 【⚠️ 文件不一致】 官方 customization cheat sheet 的 JetBrains 欄位更新速度落後於 Changelog。查證日當天，cheat sheet 仍將多項機制標為 Preview 或不支援，但 Changelog 已宣告 managed settings 與 sandbox 支援 JetBrains。 本手冊無法確認兩者的落差是文件延遲，還是涵蓋範圍確實不同。企業必須實測。

✅ JetBrains 佈署驗收清單【建議】（請逐項實測，不要依賴文件）：

□ 1. managed-settings.json 是否被 JetBrains 讀取
       驗證法：設一條明顯的 permissions.deny，在 JetBrains 中觸發該操作
□ 2. enabledPlugins / strictKnownMarketplaces 是否生效
□ 3. sandbox 設定在 JetBrains 的實際涵蓋範圍
       （官方 sandbox 完整鍵原本標示為「Copilot CLI only」，
         JetBrains 支援的子集需實測確認）
□ 4. Custom Instructions / AGENTS.md 是否被讀取
□ 5. Custom Agents（.agent.md）是否可用、frontmatter 欄位是否完整支援
□ 6. Agent Skills 是否被載入
□ 7. Hooks 是否支援（若仍為 ❌，治理必須靠 CI/CD 補位）
□ 8. Memory 是否可由企業層停用
□ 9. Ollama 等本地模型連線是否可被企業封鎖
□ 10. Content exclusion 在 JetBrains 的 chat / agent 模式是否生效

🚨 Ollama 支援是一個容易被忽略的資安面向。 允許 JetBrains 連接本地或自建模型端點，等於在企業的 AI 資料流中開了一條不經過 GitHub 的旁路。 這條旁路的優點是資料不出企業；缺點是它不受 Copilot 的稽核記錄、content exclusion 與模型政策管轄。 企業必須明確決定：允許（並自行建立稽核）或封鎖。「沒想過」是最糟的狀態。

7.12.4 多 IDE 企業的治理策略【建議】

大多數企業是混合 IDE 環境（Java 用 IntelliJ、前端用 VS Code、iOS 用 Xcode）。治理策略應遵循最小共同分母原則：

7.12.5 JetBrains 1.18（2026-09-22）企業相關更新【Official】

🆕 v1.2 新增

📌 同月（2026-09-08）JetBrains 的 enterprise-managed sandbox 以 Public Preview 推出，可集中設定檔案系統、網路與 proxy（見第 7.12.1 節）。

7.13 本章實務案例【建議】

情境：某企業 200 人同步導入，第一週 Helpdesk 收到 60 張工單。

工單分類與根因：

改善後：第二批 100 人導入時，工單降至 6 張。

關鍵改變：把安裝從「發一份 PDF 讓大家自己裝」改成「MDM 自動佈署 + 一份 7 步驗證 SOP」。

7.14 注意事項

• 🚨 禁止用關閉 TLS 驗證的方式「解決」憑證問題。
• ⚠️ Eclipse 與 Xcode 的 chat/agent 不支援 Content Exclusion，需其他手段補強。
• ⚠️ JetBrains 不支援 Hooks，治理需由 CI/CD 補位。
• ⚠️ copilot 與 gh copilot 是兩個不同的東西。
• ✅ 安裝完成後必須跑完 7 步驗證 SOP，特別是第 6 步的 managed settings 驗證。
• ✅ 大規模導入前先做 10 人試裝，收斂工單類型再擴大。

8. GitHub Copilot CLI

這一章是全書篇幅最重的技術章之一。 原因：Copilot CLI 是企業唯一能同時做到「Agent 能力完整」+「可自動化」+「可被 MDM 強制治理」的介面。 IDE 的 Hooks 支援不完整、cloud agent 只能非同步——CLI 是治理與能力的交集點。

8.1 Copilot CLI 是什麼【Official】

Copilot CLI 讓你直接在終端機使用 Copilot，用於問答、寫程式、除錯與 GitHub 操作。

兩種運作模式【Official】：

互動模式中的子模式【Official】：

• 預設 ask/execute 模式
• Plan 模式（以 Shift+Tab 切換）：「Copilot 分析你的請求、提出釐清問題以理解範圍與需求，並在寫任何程式碼之前先建立計畫」
• Autopilot 模式（/autopilot 或 Shift+Tab 循環切換）：讓 Copilot 自主工作

✅ 企業強烈建議：預設使用 Plan 模式 直接 execute 的最大問題不是它會做錯，而是你不知道它打算做什麼。 Plan 模式先產出計畫、你核准後才動手，這讓 Diff 可預期、成本可控、Review 容易。 這一點應寫進第 37 章 的每日 SOP。

8.2 支援能力總覽【Official】

8.3 CLI 指令總覽【Official】

8.4 互動式 Slash Commands【Official】

📌 註記 官方參考頁另有提及 /fleet、/pr、/lsp、/model、/settings、/skill 等指令（散見於各功能頁面）。 完整且權威的清單請在 CLI 內執行 /help 取得——這是唯一保證與你安裝版本一致的來源。本手冊不宣稱列出全部指令。

8.5 鍵盤快捷鍵【Official】

輸入與編輯：

指令與導覽：

Session 管理：

8.6 權限與工具核可模型【Official】

這是 CLI 治理的核心。

預設行為【Official】：當 Copilot 要使用會修改檔案或執行程式的工具時，會請求核可，提供三個選項——單次允許、整個 session 允許、換個做法。

自動核可參數【Official】：

官方明確警告：自動核可「增加了非預期操作導致資料遺失或損毀的風險」。

企業使用建議【建議】：

# ✅ 建議：明確列舉允許的工具（CI 場景）
copilot -p "修正 checkstyle 違規並確保 mvn test 通過" \
  --allow-tool "shell(mvn *)" \
  --allow-tool "write" \
  --deny-tool "shell(git push *)" \
  --deny-tool "shell(rm *)"

# ❌ 禁止：在企業環境使用
copilot --allow-all-tools

🚨 --allow-all-tools 應列入企業禁止清單 唯一可接受的例外是：在完全隔離的一次性容器中，且該容器沒有任何生產憑證、沒有掛載企業網路磁碟、執行後即銷毀。 這一點請寫進第 36 章。

8.7 本機 Sandbox【Official】

CLI 支援本機沙箱（local sandboxing），限制檔案系統與網路存取。官方有專頁「Using local sandboxing」「Configuring local sandbox settings」「Understanding filesystem policies for local sandboxing」。

企業層強制（透過 managed-settings.json）【Official】：

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowBypass": false,
    "addCurrentWorkingDirectory": false,
    "sandboxMcpServers": true,
    "sandboxLspServers": true,
    "gitAuth": false,
    "ghAuth": false,
    "allowDevToolAccess": false,
    "userPolicy": {
      "filesystem": {
        "readwritePaths": ["/workspace"],
        "readonlyPaths": ["/usr/share/maven"],
        "deniedPaths": ["/etc", "/var/run/docker.sock"]
      },
      "network": {
        "allowOutbound": false,
        "allowLocalNetwork": false
      },
      "seatbelt": {
        "keychainAccess": false
      }
    }
  }
}

關鍵欄位說明【Official + 建議】：

🎯 failIfUnavailable: true 是最重要的一個開關 若設為 false，在沙箱不可用的環境（例如某些容器）中，CLI 會在沒有沙箱保護的情況下繼續執行——而使用者完全不會察覺。 官方也註明：MDM 的 sandbox 設定建立的是使用者無法放寬的最低基線。

8.8 設定目錄結構【Official】

預設 ~/.copilot（可用 COPILOT_HOME 覆寫）。

🚨 資安提醒：mcp-secrets/ 與 session-state/

• mcp-secrets/ 存放 MCP 的機密——這個目錄不可被備份到不受控位置，也不可進版控。
• session-state/ 與 session-store.db 可能包含你曾經送出的程式碼片段與對話內容。在資料分類嚴格的企業，這兩者屬於需要保護的資產。
• 企業端點備份策略必須明確處理 ~/.copilot，這是本手冊少數會直接影響資安政策的技術細節。

8.9 settings.json 常用設定【Official】

📌 官方註明：完整 schema 包含 70 個以上的設定鍵，涵蓋行為、UI、權限、網路與整合。 請以 CLI 內的 /settings 指令檢視你安裝版本的完整清單，該指令另有 Problems 分頁會顯示無法辨識的頂層鍵——這是驗證企業設定檔正確性的好工具。

企業建議的 repository 層設定（.github/copilot/settings.json）【建議】：

{
  // 專案預設模型：日常任務用中階模型控制成本
  "model": "auto",

  // 專案通用的免詢問網域（內部 Maven / npm registry）
  "allowedUrls": [
    "https://nexus.corp.example.com",
    "https://confluence.corp.example.com"
  ],

  // 停用本專案不需要的 skill，減少 context 負擔
  "disabledSkills": [
    "dotnet-migration"
  ],

  // 專案啟用的企業 plugin
  "enabledPlugins": {
    "java-backend-standard@enterprise-plugins": true
  }
}

⚠️ .github/copilot/settings.local.json 用於個人本機覆寫，優先權更高。 這個檔案必須加入 .gitignore，否則個人設定會汙染整個團隊。

8.10 Context 管理與壓縮【Official】

官方有專頁「Managing context in GitHub Copilot CLI」，並說明 CLI 具備**自動壓縮（automatic compression）**以避免超出 token 上限。

實務要點【建議】：

⚠️ 壓縮會失去資訊 壓縮是把長對話摘要成短摘要，細節必然流失。 對長任務而言，這代表 Agent 可能「忘記」你前面交代的約束。 企業建議：長任務不要靠單一 session 撐完，而是拆成多個小任務，每個任務結束後 /clear。 這同時降低成本與提升可預期性。

8.11 自動化與 CI/CD 整合【Official】

官方提供四份自動化文件：Quickstart、程式化執行、排程提示、與 GitHub Actions 整合。

GitHub Actions 範例【建議】：

name: Nightly Test Coverage Improvement

on:
  schedule:
    - cron: '0 18 * * 1-5'   # 台北時間每個工作日凌晨 2 點
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  improve-coverage:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 25
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '25'
          cache: maven

      - name: Baseline coverage
        run: mvn -B -q clean verify jacoco:report

      - name: Install Copilot CLI
        run: |
          # 依官方安裝指引安裝 copilot
          copilot --version

      - name: Improve test coverage
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          copilot -p "$(cat <<'PROMPT'
          目標：提升 module order-service 的單元測試覆蓋率。

          限制：
          1. 只能新增或修改 src/test/** 底下的檔案
          2. 絕對不得修改 src/main/** 的任何程式碼
          3. 測試必須使用 JUnit 5 + AssertJ + Mockito，遵循既有測試命名慣例
          4. 不得使用 Thread.sleep，不得依賴真實外部系統
          5. 完成後必須執行 mvn -B verify 且全數通過

          產出：新增的測試檔案清單，以及覆蓋率變化摘要
          PROMPT
          )" \
            --allow-tool "shell(mvn *)" \
            --allow-tool "write" \
            --deny-tool "shell(git push *)" \
            --deny-tool "shell(rm *)" \
            --deny-tool "shell(curl *)"

      - name: Verify no production code changed
        run: |
          if ! git diff --quiet -- src/main; then
            echo "::error::Agent modified production code, aborting."
            git diff --stat -- src/main
            exit 1
          fi

      - name: Run full verification
        run: mvn -B clean verify

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          branch: auto/test-coverage-${{ github.run_number }}
          title: 'test: 自動提升 order-service 測試覆蓋率'
          body: |
            由 Copilot CLI 自動產生。

            ⚠️ 此 PR 需人工審查後才可合併。
            審查重點：
            - [ ] 測試是否真的驗證行為，而非只求覆蓋率數字
            - [ ] 是否有無意義的斷言（assertTrue(true) 之類）
            - [ ] 是否有修改到既有測試的斷言邏輯
          labels: |
            ai-generated
            needs-human-review

🎯 這個 workflow 的三個企業級設計重點

1. Verify no production code changed 步驟：不信任 prompt 裡的「不得修改」，用 git diff 機械化驗證。這就是「Instructions 是請求，CI 才是強制」的實作。
2. 明確的 --deny-tool：即使 prompt 沒寫，工具層也擋住 push 與刪除。
3. PR 標籤 needs-human-review：讓所有 AI 產出的 PR 可被識別、可被統計（這是第 44 章 KPI 的資料來源）。

8.12 Fleet 模式與平行任務【Official】

官方有「Running tasks in parallel with the /fleet command」與「Speeding up task completion with the /fleet command」兩頁。

適用情境【建議】：

• 對多個獨立 module 同時做相同的機械性變更（例如統一升級 log 寫法）
• 對多個檔案同時產生測試

不適用情境【建議】：

• 有相依關係的變更（A 改完 B 才能改）
• 需要全域一致性判斷的重構（例如改 API 契約）

⚠️ 成本警告 平行任務代表平行計費。在企業環境使用 fleet 前，先確認預算控管已設定。

8.13 Session、遠端操控與 Chronicle【Official】

remoteControl 企業設定【Official】：

{
  "remoteControl": {
    "mode": "requireSSO",
    "githubDotComOrganizations": ["our-enterprise-org"]
  }
}

模式："disabled"、"requireSSO"、"enabled"。

🚨 遠端操控是需要特別關注的功能 它允許從另一台裝置操控你的 CLI session——而那個 session 具有你本機的檔案存取權限。 企業預設建議 requireSSO 並限定組織；高度敏感環境建議 disabled。

8.14 內建代理、Subagent 限制與權限輔助模式【Official】

🆕 v1.2 新增

8.14.1 七個內建代理【Official】

Copilot CLI 內建下列代理，主代理會依任務自動委派，也可以手動指定：

📌 code-review 與 security-review 不會把整份審查再轉交給另一個審查代理（避免遞迴委派）；但 code-review 仍會把安全相關部分交給 security-review 專家處理。

【⚠️ 文件不一致】官方參考頁的「預設模型」欄在查證日仍列出 claude-sonnet-4.6，但 Claude Sonnet 4.6 已於 2026-09-01 對多數方案退役（僅個人年約訂閱者保留）。實際使用的模型請以 CLI 畫面顯示為準，不要把參考頁的預設模型寫進企業規範。

8.14.2 Subagent 的深度與並行上限【Official】

採用 usage-based billing 的使用者可用 subagents.maxConcurrency 與 subagents.maxDepth 覆寫（超出範圍會被截斷至上限）。

⚠️ 成本警告【建議】：並行 subagent 等於並行計費。Enterprise 預設可同時跑 32 個 subagent，一個模糊的指令可能在幾分鐘內消耗可觀的 AI Credits。建議在 ~/.copilot/settings.json 的團隊基線中把 subagents.maxConcurrency 調降到 4–8，並搭配第 5.7 節 的預算控管。

8.14.3 CLI 專屬的 Custom Agent 欄位與 Sidekick Agents【Official】

CLI 的 custom agent 除了第 11.2 節 的共通欄位外，另支援以下僅 CLI 使用的欄位：

🚨 include-custom-instructions 預設為 false 的治理意涵 這代表：企業寫在 copilot-instructions.md 與 AGENTS.md 裡的規則，預設不會套用到以 subagent 身分執行的 custom agent。 若企業標準 agent（例如第 11.4 節 的 13 個標準 agent）可能被主代理當作 subagent 委派，必須明確設定 include-custom-instructions: true，或把關鍵規則直接寫進 agent 本文。

Sidekick 觸發事件【Official】：user.message（每則使用者訊息）與 session.context_changed（工作目錄、repository 或分支變更時）；每個觸發條件可用 limit 限制每個 session 的觸發次數。

【⚠️ 文件不一致】CLI 參考頁的 custom agent 欄位表仍列出 infer（預設 true），但「Custom agents configuration」參考頁已將 infer 標示為已退役，並說明 disable-model-invocation: true 等同 infer: false、兩者並存時以前者為準。企業標準一律使用 disable-model-invocation 與 user-invocable，不要再新增 infer。

8.14.4 權限輔助模式與 allow-all 的企業限制【Official】

/permissions assisted（LLM 輔助核可）：每一次權限請求仍會提示，但附上一個 LLM 的安全建議，模型判定可接受的請求可以自動核可。

permissions.disableBypassPermissionsMode 的三種值：

三個可設定此限制的來源（永久性由低到高）：

🎯 企業建議：以 MDM 下發 "disable"（或評估後改為 "allow-auto-only"）。只靠伺服器端 managed settings 時，使用者切換到個人帳號就能解除限制——這正是第 6.9 節 要求「只允許企業帳號使用」的原因。

其他兩個企業必須知道的行為【Official】：

8.15 本章實務案例【建議】

情境：某團隊要把 40 個 Spring Boot module 的日誌框架從 Log4j 1.x 統一遷移到 SLF4J + Logback。

錯誤做法：

copilot --allow-all-tools -p "把整個專案的日誌改成 SLF4J"

結果：改了 400 個檔案，其中 30 個改錯，Diff 太大無法 review，最後整批 revert。

正確做法【建議】：

【階段 1：探索（不改任何檔案）】
copilot
> 進入 Plan 模式（Shift+Tab）
> 「分析本 repository 中所有使用 Log4j 1.x 的位置，
>   依 module 分組，列出每個 module 的檔案數與使用的 API 類型。
>   不要修改任何檔案。」
→ 產出遷移清單，人工確認範圍

【階段 2：建立標準（人做，不是 AI 做）】
挑一個最單純的 module，由資深工程師手工遷移
→ 作為「黃金樣本」

【階段 3：逐 module 執行】
for module in $(cat modules.txt); do
  copilot -p "參考 module common-utils 的遷移方式（黃金樣本），
              將 module $module 的 Log4j 1.x 遷移至 SLF4J + Logback。
              限制：
              - 只改 $module 目錄下的檔案
              - 保持既有的 log level 與訊息內容不變
              - 完成後執行 mvn -pl $module test 必須通過" \
    --allow-tool "shell(mvn *)" \
    --allow-tool "write" \
    --deny-tool "shell(git *)"
  # 每個 module 一個 commit，一個 PR
done

【階段 4：逐 PR 審查】
每個 PR 只含一個 module，Diff 可控，review 快

結果：40 個 PR，平均每個 review 15 分鐘，全部一次通過。

🎯 這個案例的核心教訓 Agent 的產出品質與任務大小成反比。 同樣的工具、同樣的模型，「一次全改」失敗、「逐 module 改」成功。差別只在任務拆解。 這也是為什麼第 37 章 把「任務拆解」列為每日 SOP 的第一步。

8.16 注意事項

• 🚨 以 MDM 下發 permissions.disableBypassPermissionsMode；只靠伺服器端 managed settings 時，切換帳號即可解除限制。
• ⚠️ include-custom-instructions 預設為 false：custom agent 以 subagent 身分執行時不會讀取 repository 指令。
• ⚠️ Plan-then-autopilot 會跳過計畫核准，僅限隔離環境使用。
• 🚨 --allow-all-tools 應列入企業禁止清單。
• 🚨 ~/.copilot/mcp-secrets/ 與 session-state/ 含敏感資料，需納入端點資料分類與備份策略。
• 🚨 遠端操控（remote control）必須以 managed-settings.json 限制。
• ⚠️ sandbox.failIfUnavailable 未設為 true 時，沙箱可能靜默失效。
• ⚠️ .github/copilot/settings.local.json 必須加入 .gitignore。
• ⚠️ Context 壓縮會流失細節，長任務請拆解而非靠單一 session。
• ✅ 預設使用 Plan 模式；切換任務前先 /clear。
• ✅ CI 中的「不得修改 X」一律用 git diff 機械化驗證，不要只寫在 prompt。

9. Copilot IDE Agent Mode

9.1 Agent Mode 是什麼【Official】

Agent Mode（自主代理模式） 是在 IDE 中讓 Copilot 自主編輯你本機工作目錄的模式。官方描述其與 cloud agent 的差異為：agent mode「在你的本機開發環境中直接進行自主編輯」，而 cloud agent「在 GitHub Actions 驅動的環境中自主工作」。

支援情況【Official】：VS Code ✅、Visual Studio ✅、JetBrains ✅、Eclipse ✅、Xcode ✅。

9.2 Chat / Edit / Agent 三種模式的差異【Official + 建議】

📌 註記：依官方 feature matrix，Edit 模式僅 VS Code 與 JetBrains 支援，Visual Studio、Eclipse、Xcode 不支援。

9.3 Agent Mode 的完整工作流【建議】

flowchart TD
    U["使用者<br/>描述目標與驗收標準"] --> P["Prompt"]
    P --> PL["Agent 建立計畫<br/>Plan"]
    PL --> HR1{"人：計畫合理嗎？"}
    HR1 -->|"否"| P
    HR1 -->|"是"| EX["Repository 探索<br/>讀檔 / 搜尋 / 索引"]
    EX --> CH["程式碼變更<br/>多檔案編輯"]
    CH --> BD["建置<br/>mvn compile / npm build"]
    BD --> TS["測試<br/>mvn test / npm test"]
    TS --> OK{"通過？"}
    OK -->|"否"| FX["Agent 自我修正"]
    FX --> BD
    OK -->|"是"| DIFF["<b>人：審查 Diff</b>"]
    DIFF --> Q1{"業務邏輯正確？"}
    Q1 -->|"否"| P
    Q1 -->|"是"| Q2{"架構規範符合？"}
    Q2 -->|"否"| P
    Q2 -->|"是"| Q3{"測試是真驗證<br/>還是為了變綠？"}
    Q3 -->|"為了變綠"| P
    Q3 -->|"真驗證"| CM["Commit"]
    CM --> PR["Pull Request"]
    PR --> CI["CI Quality Gate"]
    CI --> AIR["Copilot code review"]
    AIR --> HUR["<b>人工 Review</b>"]
    HUR --> MG["Merge"]

🚨 圖中三個 人： 節點是不可省略的 特別是 Q3（測試是真驗證還是為了變綠）。 Agent 為了讓建置通過，最常見的作弊手法是：把斷言改寬鬆、把失敗的測試加上 @Disabled、把例外吞掉。 企業必須把「測試檔案的變更」列為 Review 的第一優先，而不是最後才看。

9.4 如何寫好一個 Agent Mode 的 Prompt【建議】

比較兩個 prompt：

❌ 弱 Prompt

幫我加一個查詢訂單的 API

✅ 強 Prompt

【目標】
在 order-service 新增「依客戶編號查詢訂單清單」的 REST API。

【架構限制】
- 遵循本專案 Clean Architecture 分層（見 .github/copilot-instructions.md）
- Controller 只做 DTO 轉換與驗證，不得含業務邏輯
- Domain 層不得 import 任何 Spring 或 JPA 類別
- 資料存取一律透過 OrderRepository port，實作放在 infrastructure/persistence

【API 契約】
GET /api/v1/customers/{customerId}/orders
Query: page (預設 0), size (預設 20, 上限 100), status (選填)
Response: 200 OK，PageResponse<OrderSummaryDto>
錯誤：404 客戶不存在、400 參數錯誤（統一錯誤格式見 GlobalExceptionHandler）

【驗收標準】
1. mvn -pl order-service verify 全綠
2. 新增 OrderQueryServiceTest（單元測試，Mock Repository）
3. 新增 OrderControllerIT（整合測試，使用 Testcontainers PostgreSQL）
4. ArchUnit 測試必須通過（不得有新的架構違規）
5. 不得修改任何既有測試的斷言

【不要做】
- 不要新增任何第三方相依
- 不要修改資料庫 schema
- 不要動到 OrderCommandService

強 Prompt 的五個組成部分【建議】：

Context（現況與位置）
   +
Goal（要達成什麼）
   +
Constraints（架構、技術、不可違反的規則）
   +
Acceptance Criteria（怎樣算完成，且必須可機械驗證）
   +
Out of Scope（明確禁止的事）

🎯 最重要的是「Acceptance Criteria 必須可機械驗證」 「程式碼要乾淨」不是驗收標準，「mvn verify 全綠且 ArchUnit 無違規」才是。 Agent 有能力自我修正，但它需要一個它自己能執行的判斷依據。給了可執行的驗收標準，Agent 的成功率會顯著提升——因為它可以自己迴圈到通過為止。

9.5 Agent 如何理解你的 Repository【Official + 建議】

✅ 提升 Agent 理解力最有效的三件事【建議】

1. 寫一份好的 .github/copilot-instructions.md——告訴它專案的分層與慣例，省下大量探索。
2. 維持清晰的目錄結構——com.example.order.domain 比 com.example.util.helper2 好懂一百倍。這對人跟 AI 都成立。
3. 保持 README 與模組說明是最新的——Agent 會讀它們。

9.6 Checkpoints 與回溯【Official】

依官方 feature matrix，Checkpoints 在 VS Code ✅、Visual Studio ✅、JetBrains ✅、Xcode ✅ 支援，Eclipse ❌ 不支援。

企業建議【建議】：

• 在讓 Agent 動手之前，先 commit 目前的工作（即使是 WIP commit）。
• Checkpoint 是 IDE 提供的便利機制，但 Git 才是你最可靠的回退點。
• 養成 git stash 或建立 WIP commit 的習慣，比依賴任何 IDE 功能都安全。

9.7 Human-in-the-loop 的落地方式【建議】

「Human-in-the-loop」不能只是一句口號。以下是可執行的定義：

🎯 判斷準則 問一句：「如果這件事做錯了，是靠測試發現，還是靠客訴發現？」 靠測試發現的 → AI 可以決定。 靠客訴發現的 → 必須人決定。

9.8 Agent Merge、多根工作區與 Chat Sessions【Preview】

⚠️ Version Note（VS Code 1.136，2026-08-31 週次）

本節所述功能多數為 Public Preview 或 Experimental。依本手冊的可信度制度，Preview 功能不得放進生產流程的關鍵路徑，升版時應優先回歸測試。

9.8.1 Agent Merge【Preview】

Agent Merge 是 VS Code 的 public preview 功能，目的是把一個 PR 推進到「可以合併」的狀態——它會處理三類阻礙：

🚨 這是本手冊目前最需要謹慎對待的新功能。

原因不在於技術，而在於它直接作用於企業品質閘門的三個核心控制點：

控制點	風險
Review 回饋	Reviewer 的意見是人的判斷。讓 Agent 自動「解決」回饋，可能把「這個設計方向不對，請重做」誤處理成表面修補，而 reviewer 看到「已處理」就放行
失敗的 checks	這是最危險的一項。修復 CI 失敗的最短路徑往往是讓驗證本身失效——加 @Disabled、放寬斷言、調降覆蓋率門檻。本手冊在第 21 章、第 26 章、第 31 章 反覆強調的正是這一點
合併衝突	衝突解決本質上是語意決策，不是文字合併。自動解衝突可能靜默丟失一邊的變更

✅ 企業導入 Agent Merge 的前置條件【建議】（全部滿足才可開放）：

□ 1. CODEOWNERS 已保護所有 Quality Gate 設定檔
       （測試設定、ArchUnit 規則、CI workflow、覆蓋率門檻）
       —— 見第 47 章的 CODEOWNERS 範本
□ 2. CI 中已有「防作弊檢查」：
       - 偵測新增的 @Disabled / @Ignore / skip
       - 偵測被刪除或弱化的既有斷言
       - 偵測覆蓋率門檻的調降
□ 3. PR diff 審查規範已明訂：先看測試檔、再看刪除的行
□ 4. Agent Merge 產出的變更必須經過人工 review，
       且 reviewer 明確知道「這是 Agent 改的」
□ 5. 禁止在 protected branch 上直接使用
□ 6. 合併衝突的自動解決結果，必須逐一人工確認語意正確

🎯 本手冊的立場【建議】 Agent Merge 用在低風險 PR 的機械性收尾（lint 修正、格式、文件、相依性小升版）是合理的效率提升。 用在核心業務邏輯、安全相關程式碼、或任何 CI 紅燈的 PR 上，等於讓被驗證者去修理驗證機制。 建議在企業規範中明列：「CI 失敗時，禁止使用 Agent 自動修復；必須由人先判讀失敗原因。」

9.8.2 多根工作區（Multi-root Workspaces）【Experimental】

此功能讓 Copilot 與 Claude 的 agent session 延伸到 workspace 中的每一個資料夾，而非只作用於單一根目錄。

企業情境的價值【建議】：微服務架構下，一個功能常橫跨數個 repository（例如 order-service、common-platform、frontend-app）。過去 Agent 一次只能看一個，跨服務的變更必須人工搬運 context。

但同時放大了三個風險：

⚠️ 此功能標示為 Experimental。不建議在企業標準流程中採用，可開放給資深工程師在非關鍵專案試用並回報。

9.8.3 Chat Sessions 與 Chat Backgrounds【Preview / Experimental】

• Chat Sessions：把相關對話階層式組織，並突顯需要注意的 session。對同時跑多個 agent 任務的資深開發者而言，這是實質的可用性改善——它降低了「忘記某個 session 還在等我核可」的機率。
• Chat Backgrounds（Experimental）：允許以內建圖樣或自訂圖片個人化 Agents 視窗。純外觀功能，無治理意涵；但若企業有「不得在工作環境載入外部圖片」的政策，需留意自訂圖片來源。

✅ 搭配 Human-in-the-loop 的建議：Chat Sessions 的「突顯待處理」特性，正好補上第 9.7 節 提到的痛點——核可疲勞（approval fatigue）下，開發者容易漏看或無腦放行。建議團隊規範中要求：同時進行的 agent session 不超過 3 個。

9.9 VS Code 權限層級、Autopilot 與 Agent Host【Official + 建議】

🆕 v1.2 新增（依 VS Code 官方文件「Manage approvals and permissions」，2026-09-16 核定版本）

9.9.1 兩層安全控制【Official】

VS Code 用兩層機制控制 agent 的行為：

• Approvals（核可）：決定某個動作是自動執行，還是需要你確認。
• Sandboxing（沙箱）：限制 agent 執行的終端機指令可存取的檔案系統與網路資源——即使該指令已被核可。

9.9.2 三種權限層級【Official】

Assisted permissions 的限制【Official】：

• 僅適用於在 Agent Host 上執行、且受支援的 session。
• 需啟用 chat.assistedPermissions.enabled 才會出現在選單。
• 組織可以透過「停用全域自動核可（disable global auto-approval）」隱藏此選項。
• 官方明言：模型式的風險評估可能出錯，不能取代你的判斷。第一次選用時會跳出警告對話框。
• 使用 Copilot harness 時請選 Folder 隔離；worktree session 一律是 Allow all。

9.9.3 Autopilot 是「代理模式」，不是權限層級【Official】

這是最常被誤解的一點：Autopilot 從模式選單選取，不是從權限選單選取。

Autopilot 會：

• 像 Allow all 一樣自動核可所有工具；
• 遇到錯誤時自動重試；
• 自動回答原本會卡住進度的問題。

另有 Advanced Autopilot（Preview）：每一輪結束後，由另一個小型快速模型判斷原始需求是否已完成、並引導下一輪（chat.autopilot.advanced.enabled）。

🚨 官方警告（CAUTION）：Allow all 與 Autopilot 會跳過破壞性動作的確認，包含檔案編輯、終端機指令與外部工具呼叫。

沙箱與權限層級互相獨立：Allow all 與 Autopilot 跳過核可提示，但啟用中的沙箱仍會限制終端機的檔案系統與網路存取。不過沙箱只作用於終端機指令——其他動作（檔案編輯、MCP 工具、URL 擷取）只能靠 Manual permissions 下的工具與 URL 核可控制。

全域與 session 級的自動核可【Official】：

9.9.4 企業建議設定【建議】

與企業強制權限的關係：第 6.4.6 節 的 Agent 操作權限企業管控（2026-09-09）在 VS Code 需搭配 Agent Host。企業若要讓 permissions.deny／ask 在 VS Code 真正生效，必須確認開發者的 session 跑在 Agent Host 上，而不是舊的 extension host 路徑。

📌 Dev Container 隔離：VS Code 自 2026 年 9 月起陸續支援讓代理在本機 Dev Container 內執行（需要 Docker 與有效的 Dev Container 設定，逐步推出中）。對需要 Allow all 或 Autopilot 的任務，Dev Container 是比「在主機上開 Allow all」安全得多的選擇：檔案系統與網路的爆炸半徑被限縮在容器內。

9.10 本章實務案例【建議】

情境：某工程師用 Agent Mode 修一個「訂單金額計算錯誤」的 bug，測試全綠，PR 送出。

Review 時發現的問題：

// Agent 的修改（看起來很合理）
public BigDecimal calculateTotal(Order order) {
    return order.getItems().stream()
            .map(item -> item.getPrice().multiply(BigDecimal.valueOf(item.getQuantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add)
            .setScale(2, RoundingMode.HALF_UP);   // ← Agent 加上的
}

問題：RoundingMode.HALF_UP（四捨五入）是 Agent 自己選的。 但這家公司的財務規範是 RoundingMode.HALF_EVEN（銀行家捨入），寫在一份 Confluence 文件裡，沒有寫進 repository。

為什麼測試沒抓到：Agent 同時把測試的期望值改成了新的計算結果。

處置【建議】：

1. 立即：修正為 HALF_EVEN，並修回測試期望值。
2. 短期：把財務計算規範寫進 .github/instructions/money.instructions.md，並用 applyTo 限定在 **/domain/**/*.java。
3. 中期：新增 ArchUnit 測試，禁止在 domain 層直接使用 RoundingMode 以外的捨入方式，強制使用統一的 MoneyUtils。
4. 長期：把「測試期望值的變更」列為 PR review 的強制檢查項，並在 PR 模板中加入勾選項。

🎯 這個案例的三層教訓

1. AI 不知道你沒告訴它的事。 規範在 Confluence 等於不存在。
2. 測試全綠不代表正確。 Agent 會為了讓測試通過而改測試。
3. 真正的防線是機械化檢查。 ArchUnit 抓得到的，不要靠人眼。

9.11 注意事項

• ⚠️ Autopilot 是代理模式、不是權限層級；Allow all 與 Autopilot 都會跳過破壞性動作的確認。
• ✅ 以企業 AI 設定停用全域自動核可；chat.permissions.default 維持 Manual permissions。
• 🚨 測試檔案的變更必須是 Review 的第一優先，不是最後。
• ⚠️ Edit 模式僅 VS Code 與 JetBrains 支援。
• ⚠️ Eclipse 不支援 Checkpoints，回退只能靠 Git。
• ⚠️ Agent 動手前先 commit 或 stash。
• ✅ Prompt 必須包含可機械驗證的驗收標準。
• ✅ 「靠客訴才會發現的錯誤」，一律由人決定。
• ✅ 沒寫進 repository 的規範，對 AI 而言不存在。

第四部　客製化機制

這一部要解決的問題是：如何讓 Copilot 從「一個通用 AI」變成「懂我們公司規矩的專業團隊成員」。

六種機制，六種用途，不要混用：

機制	一句話定位
Custom Instructions	「我們公司的規矩」——自動套用，永遠生效
Prompt Files	「常用的請求範本」——手動叫用
Custom Agents	「專職角色」——選定後改變 AI 的身分與可用工具
Agent Skills	「專業能力包」——需要時才載入，省 token
Hooks	「攔截器」——在生命週期節點強制檢查
MCP	「外部工具的接線」——讓 AI 能操作外部系統
Plugins	「上述東西的散布包裝」——可版本化、可治理

10. Custom Instructions

10.1 Custom Instructions 是什麼【Official】

Custom Instructions（自訂指令）是自動套用的自然語言指示，讓 Copilot 在每次回應時都遵循你的規範。

官方確認的類型與位置【Official】：

環境支援對照【Official】：

※ 包含 CLAUDE.md 與 GEMINI.md 變體。

📌 兩個實務要點

1. Organization Instructions 只在 GitHub.com 生效——它管不到 IDE。若你想讓企業規範在 IDE 也生效，必須放進 repository（或用 repository template 統一散布）。
2. Eclipse 的 Chat 只支援 Repository 層——沒有 path-specific。多語言團隊要注意這個差異。

10.2 三層指令的正確分工【建議】

這是本章最重要的一節。大多數企業把所有規則塞進 copilot-instructions.md，這是錯的。

flowchart TD
    A["企業規範總量<br/>假設 500 行"] --> B{"這條規則<br/>是否<b>永遠</b>適用？"}
    B -->|"是，任何檔案都適用"| C["<b>copilot-instructions.md</b><br/>目標 ≤ 100 行<br/>只放最高層原則"]
    B -->|"否，只在特定路徑適用"| D["<b>*.instructions.md</b><br/>用 applyTo 限定路徑<br/>例：persistence / controller / test"]
    B -->|"否，只在特定任務適用"| E["<b>Agent Skills</b><br/>需要時才載入<br/>例：DB migration / 逆向工程"]
    B -->|"否，是可重複的請求範本"| F["<b>Prompt Files</b><br/>手動叫用<br/>例：產生 API 文件"]
    B -->|"這是<b>絕對不可違反</b>的"| G["<b>ArchUnit / Hook / CI</b><br/>機械化強制<br/>不要只靠指令"]

分配比例建議【建議】：

⚠️ 為什麼 copilot-instructions.md 要控制在 120 行內

1. 它每次請求都會被送出——長度直接乘上請求次數變成成本。
2. 注意力稀釋——模型對長指令的遵循度會下降，重要規則被淹沒。
3. 維護成本——沒人會維護一份 600 行的指令檔，最後它會過時。