awesome-copilot 教學手冊

企業軟體開發團隊使用 awesome-copilot 建立 AI Agent Development Platform 的完整實戰教科書

Repository：github.com/github/awesome-copilot（owner：GitHub 官方 org，MIT License，38.5k+ Stars、4.9k+ Forks、494 位貢獻者，內容為社群貢獻）

官方網站：awesome-copilot.github.com（含 Learning Hub、llms.txt）

查證日期：2026-08-27（初版）／2026-08-28（第二版複查：Repository 現況、External Plugins 審查流程、Plugin 宣告式安裝、企業級 Plugin 標準、VS Code Agent／Skill 規格細節）／2026-08-28（第三版增修：VS Code 官方 Agent Harness／Session Target／Agent Host 定義釐清、Agent Sandboxing、Chat Customizations Evaluations 與 Waza 評測、Agent Customizations 編輯器、Copilot SDK、awesome-copilot AI 供應鏈治理資源盤點）／2026-08-31（第四版全面複查：Hooks 事件由 6 個擴充為 14 個並新增 Policy Hooks 與 Cloud Agent 執行環境、Agent Skills 官方 frontmatter 與五個探索路徑校正、managed-settings.json 完整鍵表與 Sandbox／Telemetry／RemoteControl、企業團隊 overridable 覆寫機制、Copilot CLI Skills／Plugin 指令、MCP Allowlist 治理）

適用對象：資深軟體工程師、Tech Lead、Software Architect、AI Architect、DevSecOps 工程師

目的：協助企業軟體開發團隊安全、正確地把 awesome-copilot 的社群資源導入 GitHub Copilot 客製化流程，並建立自己的 Agent / Skill / Plugin / Instructions 標準

技術情境範例：Vue 3 + TypeScript + Tailwind CSS + PrimeVue（前端）、Java 25 + Spring Boot 4.x + Maven（後端）、PostgreSQL / Oracle / DB2（資料庫）

⚠️ 重要聲明（請務必先讀）

1. 本手冊是彙整、重組、補充企業導入實務，而不是官方文件的翻譯。 內容依 github/awesome-copilot 官方 Repository（README.md、CONTRIBUTING.md、AGENTS.md、各資源資料夾）與 docs.github.com／code.visualstudio.com 官方文件逐頁查證後，以繁體中文重新組織、延伸為企業教材，並大量補充 Scenario、AI Prompt 範例、比較表、Checklist 與企業導入建議。

2. GitHub Copilot 客製化生態系近期變動極大，本手冊撰寫前已重新查證下列六個「會讓整篇教學寫錯」的關鍵變化，全書一律採用查證後的最新說法：

   #	過時說法（網路上仍常見，本手冊不採用）	目前正確說法（本手冊採用）
   1	awesome-copilot 有 chatmodes/、prompts/、collections/ 資料夾	這三個資料夾已被移除（GitHub API 查詢回應 404），現行結構是 agents/、instructions/、skills/、plugins/、hooks/、cookbook/、extensions/、workflows/
   2	Copilot 的自訂客製化格式叫 .chatmode.md（custom chat modes）	官方已正式更名為 .agent.md（custom agents），VS Code 官方文件明文說明「功能不變，只是更名」，並建議把既有 .chatmode.md 直接改副檔名沿用
   3	Copilot 的自動化代理叫 “Copilot coding agent”；GitHub Copilot Extensions 仍是現行客製化機制	現行正式名稱是 “Copilot cloud agent”；而 GitHub Copilot Extensions（GitHub App 機制）已於 2025-11-10 23:59 PST 正式日落，與現行的 Copilot Plugins（Agent Plugins 1.0，2026-08-12 GA）是完全不同的兩個機制，絕不可混為一談
   4	Copilot Hooks 只有 6 個生命週期事件	官方 Hooks Reference 現已列出 14 個事件（含 userPromptTransformed、postToolUseFailure、preCompact、subagentStart／subagentStop、errorOccurred、permissionRequest、notification），且事件名稱同時支援 camelCase 與 PascalCase 兩種寫法，PascalCase 會切換成 VS Code 相容的 snake_case payload（見第 13.2 節）
   5	Agent Skills 只能放在 .github/skills/	官方支援 五個探索路徑：專案層 .github/skills、.claude/skills、.agents/skills，個人層 ~/.copilot/skills、~/.agents/skills（見第 8.3 節）
   6	企業只能用 managed-settings.json 管 Plugin	managed-settings.json 現已擴充為完整治理面板，涵蓋 model、permissions（deny／ask／allow／disableBypassPermissionsMode）、enabledPlugins、extraKnownMarketplaces、strictKnownMarketplaces、telemetry、remoteControl、allowedMcpServers、deniedMcpServers、sandbox 十大鍵，並支援企業團隊 overridable 分層覆寫（見第 20.5 節）

3. 查證方法論：本手冊撰寫前，逐一 fetch 並比對了 github/awesome-copilot 的 README.md、CONTRIBUTING.md、GitHub Contents API（確認資料夾真實存在與否）、docs.github.com/en/copilot 底下的 Concepts／How-tos／Reference 頁面、code.visualstudio.com 的 agent-customization 文件，以及 GitHub Changelog 中與 Copilot cloud agent、Copilot Extensions 日落、Agent Plugins 1.0 GA 相關的公告。所有版本狀態、檔案格式、CLI 指令、frontmatter 欄位皆逐字或近逐字取自官方文件，非憑空杜撰。

4. awesome-copilot 的正確定位：這個 Repository 託管在 GitHub 官方 org（github/awesome-copilot）底下，但內容本質是「社群貢獻的精選集」，不是官方產品規格文件。README 與 CONTRIBUTING 文件本身也提醒使用者：安裝任何第三方 Agent、Skill、Plugin、Hook 前都必須自行檢查內容。因此本手冊嚴格區分「GitHub Copilot 官方規格」（一律以 docs.github.com／code.visualstudio.com 為準）與「awesome-copilot 收錄的社群範例」（僅供參考、安裝前必須審查）。

5. 企業案例聲明：本手冊出現的企業案例（Web Application 開發、逆向工程、Framework Migration、12 人 Agent Team 等情境）均為教學示範用途之原創設計，用於示範如何依照 GitHub Copilot 官方驗證過的格式（.agent.md、SKILL.md、plugin.json、Hooks JSON）打造企業自己的客製化資源，並非 awesome-copilot 官方收錄的真實項目，也非真實客戶專案。

6. 關於其他 AI Coding Agent 的比較：本手冊在比較 GitHub Copilot 與 Claude Code、OpenAI Codex、Cursor 時，僅對 GitHub Copilot 欄位做到逐項官方查證；其餘工具的資訊以各自官方文件既有認知做定性比較，並在對應章節明確標示查證信心層級，不會把任一工具的機制直接套用成另一工具的規格。

7. License 聲明：awesome-copilot 授權條款請以官方 Repository 的 LICENSE（MIT）逐字內容為準，本手冊不構成法律意見。

8. 官方權威來源與研究來源分級，請見第 40 章「References」。

9. 第二版複查（2026-08-28）新增／修正的重點：plugin.json 的內容組合欄位在 awesome-copilot 已改為宣告式的 extensions.com.github.awesome-copilot（第 11.3 節已重寫）、外部 Plugin 改走 plugins/external.json 的 Issue 審查流程（第 11.5 節新增）、Plugin 可用 enabledPlugins 宣告式安裝（第 12.6 節新增）、企業可用 managed-settings.json 集中管控 Plugin 標準（第 20.5 節新增）。舊版本手冊若已列印或分發，請以本版為準。

10. 第三版增修（2026-08-28）新增／修正的重點：VS Code 官方文件已把「Agent Harness」定義為 Local／Copilot／Claude／Codex 四種執行時（runtime），與本手冊第 6.6 節所稱的「四種 Copilot 使用介面」是兩個不同軸線，第 6.7 節新增專節釐清，並補上 Session Target、Agent Host、Code Isolation（folder／worktree）三個新概念；另新增 Agent Sandboxing（第 20.6 節）、Skill／Agent 品質評測工具鏈 Chat Customizations Evaluations 與 Waza（第 8.11 節）、Agent Customizations 編輯器與使用者客製化遷移（第 9.6 節）、Copilot SDK（第 4.6 節）、awesome-copilot AI 供應鏈治理資源盤點（第 2.9 節）、Troubleshooting 診斷流程（第 27.2 節）、VS Code 原生 Claude／Codex Harness 對跨工具標準的影響（第 33.4 節）。

11. 第四版全面複查（2026-08-31）新增／修正的重點：本版以「逐章節對照官方一手文件」的方式重新查證全書，主要變更如下：

    #	章節	第三版內容	第四版修正
    1	第 13.2、13.7 節	Hooks 只列 6 個事件	擴充為官方 14 個事件完整表，新增第 13.7 節說明 Hook 載入優先序、Policy Hooks、Cloud Agent 沙箱限制、Matcher 過濾與 Exit Code 語意
    2	第 8.2、8.3 節	Skill frontmatter 只提 name／description；路徑只提 .github/skills	補上官方 license、allowed-tools 欄位及其資安含意；列出五個官方探索路徑與 gh skill
    3	第 20.5 節	managed-settings.json 只談 Plugin 治理	擴充為十大鍵完整表、四層優先序、overridable 團隊覆寫、sandbox 子欄位、Permission Selector 語法
    4	第 14.8 節（新增）	無	新增 MCP 企業治理：allowedMcpServers／deniedMcpServers 交集與聯集語意、URL 正規化防護
    5	第 12.5 節	CLI 指令不完整	補上 copilot skill、/skills 子指令與 Plugin 相關指令
    6	第 20.6 節	Agent Sandboxing 描述為一般 Preview	補上企業端可用 managed-settings.json 的 sandbox 鍵強制最低限制的實作方式
    7	第 6.6、6.7、37、40 節	與官方支援矩陣未同步	依官方 Customization Cheat Sheet 重建介面支援矩陣並同步速查表與參考資料；第 6.7 節補上 chat.agentHost.enabled 與 worktree 全 harness 支援
    8	第 11.3 節	MCP 檔名寫成「官方文件不一致、請自行實測」	依 awesome-copilot AGENTS.md 改寫為明確規則：根目錄 mcp.json + mcp.schema.json 的 $schema，禁用 plugin.json 的 mcpServers 與 legacy .mcp.json；新增 Plugin 實體化與 namespace 剝除說明
    9	第 11.5 節	External Plugin 使用自行推測的示意 JSON（source.type／source.repository）	換上 plugins/external.json 真實內容與 Claude Code marketplace spec 欄位（source.source／repo／path／ref／sha）；補上九個審查標籤、七個 slash 指令、vally lint 品質閘與六個月 closed_at 重審機制
    10	第 9.7 節（新增）	無	新增 Copilot 內建 Agent 清單（含 general-purpose 不發出 subagent 事件的官方例外），並與第 24.4 節企業 Catalog 對照
    11	第 20.7 節（新增）	無	新增權限模型四種核准層級（Default／Assisted／Bypass／Autopilot）、ChatAgentNetworkFilter／BrowserChatTools 政策，以及 VS Code 側三個 Plugin 政策設定鍵與 CLI 端的命名落差
    12	第 27.2、33.5、37.7、40.8 節	診斷入口只有 Debug Panel；跨工具標準缺分發層；Hook 速查範例格式錯誤；無版本對照	補上 /troubleshoot skill 與其資安提醒、Plugin 分發層跨工具收斂分析、修正 Hook 最小範例為官方 hooks 物件格式、新增 VS Code 版本對照表
    13	第 2.1、2.5 節	統計為 38.4k／4.8k；誤記 scripts/ 為文件差異	更新為 38.5k／4.9k 與語言組成；確認 scripts/ 確實存在；補上 AGENTS.md Pre-commit Checklist、gh aw compile --validate --no-emit、Issue #1368 與 Discussion #968

    舊版本手冊若已列印或分發，請以本版為準。

符號約定

Provenance 五層標示

本文以括號文字直接標示於句末或表格欄位中，例如「…（官方已實作）」或「…（建議架構）」。

全書一致使用此標示法。凡整段（而非單句）屬於建議架構的內容，會以區塊引言格式標示：

⚠️ 此內容為建議架構，並非 awesome-copilot 官方收錄項目或 GitHub Copilot 官方原生功能。

Mermaid 圖表慣例

• 所有架構圖、流程圖均以 Mermaid 語法呈現。
• 節點標籤若包含括號、冒號、斜線等特殊字元，一律以雙引號包住整個標籤（例如 A["Custom Agents (.agent.md)"]），避免解析錯誤。
• 實線箭頭代表已從官方文件或 Repository 結構確認的關係（Source-confirmed／官方已實作）；虛線箭頭代表建議架構的推論路徑，圖說明會另外標註。

程式碼區塊慣例

• 未特別標示「示意」的指令，均為官方文件（docs.github.com／code.visualstudio.com／CONTRIBUTING.md）中可查證的真實指令語法或檔案格式，逐字或近逐字取自原文。
• 標示「示意」的區塊為本手冊為幫助理解而重新撰寫的概念示範，不是官方逐字引用。
• 所有 Placeholder（如 <org>、<project-name>、ghp_xxx）在使用前必須替換為實際值，本文不含任何真實 Secret、API Key 或密碼。

章節固定小節

重要章節盡量包含以下小節：Scenario（具體案例）、AI Prompt 範例、本章 Checklist。

版本與相容性速查表

目錄（Table of Contents）

本目錄涵蓋全書 41 章與所有編號小節，可直接點擊跳轉。未編號的固定小節（Scenario／AI Prompt 範例／本章 Checklist）因每章重複出現，未列入目錄，請於各章末尾閱讀。

Part I：核心觀念與定位

• 1. Executive Summary：5 分鐘理解 awesome-copilot
  • 1.1 awesome-copilot 是什麼
  • 1.2 為什麼值得使用
  • 1.3 可以解決什麼問題
  • 1.4 如何協助 AI Agent 開發
  • 1.5 如何協助 Web Application 開發
  • 1.6 如何協助 Legacy Reverse Engineering
  • 1.7 如何協助 Framework Migration
  • 1.8 如何協助 Security
  • 1.9 如何導入企業
  • 1.10 最推薦的使用方式
• 2. awesome-copilot 是什麼：官方生態系定位
  • 2.1 Repository 基本事實
  • 2.2 Community-created resources 的概念
  • 2.3 Awesome Copilot Website、Learning Hub、llms.txt
  • 2.4 Resource Discovery 與 Marketplace
  • 2.5 社群貢獻模式
  • 2.6 如何挑選第三方 Agent／Skill／Plugin
  • 2.7 安全性與供應鏈風險
  • 2.8 docs/、eng/ 與 awesome-copilot MCP Server
  • 2.9 awesome-copilot 的 AI 供應鏈與 Agent 治理資源盤點
• 3. 整體架構：GitHub Copilot 客製化五層模型
  • 3.1 分層架構圖
  • 3.2 各層如何協作
  • 3.3 與 awesome-copilot 資料夾的對應關係
• 4. Resource Model 完整介紹
  • 4.1 資源類型總覽表
  • 4.2 Agentic Workflows（gh-aw）補充說明
  • 4.3 Cookbook 補充說明
  • 4.4 Canvas Extensions 補充說明
  • 4.5 GitHub Copilot app 與 Automations（新增）
  • 4.6 Copilot SDK 與 Agent Host
• 5. Agents／Instructions／Skills／Hooks／Plugins／MCP 核心差異
  • 5.1 比較表
  • 5.2 用實際軟體工程案例對照
  • 5.3 核心心法

Part II：Repository 建置與客製化深入

• 6. Repository 目錄結構
  • 6.1 企業 Web Application Repository 建議配置
  • 6.2 哪些目錄屬於哪個系統
  • 6.3 Project Scope 與 Personal Scope
  • 6.4 Root Level、Nested 與 Monorepo 設定
  • 6.5 不同 Copilot Client 的支援差異
  • 6.6 四種 Harness 的選用與設定檔對照
  • 6.7 Session Target、Agent Harness 與 Code Isolation
• 7. AGENTS.md、copilot-instructions.md 與 *.instructions.md 深入比較
  • 7.1 三者比較表
  • 7.2 AGENTS.md 支援矩陣
  • 7.3 VS Code 設定開關
  • 7.4 指令優先順序
  • 7.5 applyTo 語法範例
  • 7.6 企業 Web Application 完整範例
• 8. Skills 深入教學與四個企業 Skill 範例
  • 8.1 Agent Skills 的概念
  • 8.2 SKILL.md Frontmatter
  • 8.3 Skill Directory 與存放位置
  • 8.4 自動發現與三段式漸進載入
  • 8.5 觸發方式
  • 8.6 Skill Lifecycle、Versioning、Testing、Security
  • 8.7 Skill 1：Web Application Development
  • 8.8 Skill 2：Reverse Engineering
  • 8.9 Skill 3：Framework Migration
  • 8.10 Skill 4：Security Review
  • 8.11 Skill 與客製化檔案的品質評測：Chat Customizations Evaluations 與 Waza
• 9. Custom Agents 深入教學與企業 Agent Team
  • 9.1 從 .chatmode.md 到 .agent.md（重要遷移段落）
  • 9.2 .agent.md 完整 Frontmatter 欄位
  • 9.3 存放位置與組織層共享
  • 9.3.1 Agent 的建立與管理入口（官方已實作）
  • 9.4 企業 Agent Team Catalog（12 個 Agent）
  • 9.5 完整 .agent.md 範例
  • 9.6 Agent Customizations 編輯器與使用者客製化遷移
  • 9.7 內建 Agent（Built-in Agents）與 Subagent 事件
    • 9.7.1 內建 Agent 清單（官方已實作，2026-08-31 查證）
    • 9.7.2 企業如何定位內建 Agent（建議架構）
• 10. Agent Team 協作架構
  • 10.1 協作拓樸圖
  • 10.2 Agent Delegation 與 Handoff
  • 10.3 Context Management 與 Shared Artifacts
  • 10.4 Review Gates 與 Human Approval
  • 10.5 Failure Recovery
• 11. Plugins 深入教學與企業 Plugin 範例
  • 11.1 Plugin 概念（Agent Plugins 1.0）
  • 11.2 Plugins vs Copilot Extensions（絕不可混寫）
  • 11.3 plugin.json Schema 與目錄結構
  • 11.4 完整企業 Plugin 範例：Enterprise Web Development Plugin
  • 11.5 External Plugins：plugins/external.json 與審查流程
• 12. Plugin 安裝與管理
  • 12.1 Marketplace Discovery
  • 12.2 Plugin 安裝、更新、移除、啟用／停用（企業自建 Plugin）
  • 12.3 Version Management 與 Dependency Management
  • 12.4 VS Code 使用方式
  • 12.5 Copilot CLI 使用方式
    • 12.5.1 Plugin 相關指令
    • 12.5.2 Skill 相關指令（第四版新增，官方已實作）
  • 12.6 宣告式安裝：enabledPlugins
• 13. Hooks 深入教學
  • 13.1 定義與 Lifecycle
  • 13.2 十四個生命週期事件（第四版全面改寫）
    • 13.2.1 事件總表（官方已實作，2026-08-31 查證）
    • 13.2.2 事件名稱的兩種寫法：camelCase 與 PascalCase
    • 13.2.3 Hook 的三種型別
    • 13.2.4 決策控制與 Matcher 過濾
    • 13.2.5 Exit Code 與 Fail-Open／Fail-Closed 語意（資安關鍵）
    • 13.2.6 permissionRequest 與 Sandbox Bypass 例外
  • 13.3 設定檔格式與關鍵限制
  • 13.4 Pre-Change Quality Gate Hook 範例
  • 13.5 Agent Workflow Hook 範例
  • 13.6 安全性、Logging、Failure Handling
  • 13.7 Hook 檔案位置、載入優先序與 Cloud Agent 限制
    • 13.7.1 Copilot CLI 的五個載入來源（官方已實作）
    • 13.7.2 Copilot cloud agent 的執行環境限制（官方已實作）
• 14. MCP 整合
  • 14.1 MCP 是什麼
  • 14.2 Copilot Agent 如何使用 MCP
  • 14.3 MCP 與 Skill／Plugin 的差異
  • 14.4 各 Client 的設定位置
  • 14.5 .vscode/mcp.json 範例
  • 14.6 Web Application 開發常用 MCP 清單
  • 14.7 MCP Server 信任邊界與網域控管
  • 14.8 MCP 的企業層強制治理：Allowlist 與 Denylist
    • 14.8.1 兩個鍵的合成語意（最容易誤解的地方）
    • 14.8.2 三種比對子（每筆項目只能擇一）
    • 14.8.3 URL 正規化：官方內建的繞過防護（官方已實作）
    • 14.8.4 企業導入建議（建議架構）

Part III：企業實戰案例

• 15. Web Application 開發實戰
  • 15.1 技術堆疊
  • 15.2 開發流程
  • 15.3 各階段對應的客製化資源
• 16. 逆向工程實戰
  • 16.1 情境輸入
  • 16.2 分析流程
  • 16.3 最終產出
  • 16.4 重要限制（重申）
• 17. Framework Migration 實戰
  • 17.1 案例：Spring Boot 3.x → Spring Boot 4.x
  • 17.2 各階段使用的客製化資源
  • 17.3 六大機制如何共同完成 Migration
• 18. AI-Assisted SDLC
  • 18.1 全生命週期圖
  • 18.2 awesome-copilot 在每個階段的介入方式
• 19. Spec-Driven Development 整合
  • 19.1 整合流程
  • 19.2 避免 AI Agent 擴權的防護措施

Part IV：治理、安全與導入

• 20. 企業級 AI Coding Governance
  • 20.1 Governance 模型
  • 20.2 安全風險類別
  • 20.3 Governance Workflow
  • 20.4 已知威脅情資（2026，Source-confirmed）
  • 20.5 企業級集中管控：managed-settings.json
  • 20.6 Agent Sandboxing：OS 層級的最後一道防線
  • 20.7 權限模型：四種核准層級與 Agent 網路過濾
    • 20.7.1 四種權限層級（官方已實作）
    • 20.7.2 Agent 網路過濾與瀏覽器工具政策（官方已實作）
    • 20.7.3 企業 Plugin 政策設定鍵（官方已實作）
• 21. 社群資源安全評估 Checklist
  • 21.1 Awesome Copilot Resource Security Checklist
  • 21.2 Risk Level 與對應處理
• 22. 企業團隊導入方法
  • 22.1 六階段導入模型
  • 22.2 各階段內容
• 23. 團隊標準目錄與資源歸屬
  • 23.1 建議標準目錄
  • 23.2 資源歸屬建議

Part V：Catalog、Prompt 與 Tutorial

• 24. Agent／Skills／Instructions Catalog
  • 24.1 Agent Catalog
  • 24.2 Skills Catalog
  • 24.3 Instructions Catalog
  • 24.4 內建 Agent 對照：哪些不必自建（第四版新增）
• 25. 實戰 Prompt 範例集
  • 25.1 Reverse Engineering
  • 25.2 Framework Upgrade
  • 25.3 Security Review
  • 25.4 Architecture Review
  • 25.5 Web Application Development
• 26. 完整實戰 Tutorial（20 項）
  • 26.1 精選 Tutorial 完整逐步示範

Part VI：維運、比較與總結

• 27. Troubleshooting
  • 27.1 常見問題對照表
  • 27.2 Agent Debug Panel 與標準診斷流程
• 28. 維護策略
  • 28.1 版控與變更流程
  • 28.2 Resource Lifecycle
• 29. Upgrade Playbook
  • 29.1 Awesome Copilot Upgrade Playbook
  • 29.2 每個步驟的重點
• 30. Agent 成效 KPI
  • 30.1 KPI 清單
  • 30.2 KPI 使用原則
• 31. AI Agent Quality Gate
  • 31.1 七道 Gate
  • 31.2 各 Gate 定義
• 32. awesome-copilot／Copilot 與其他 AI Coding Agent 比較
  • 32.1 重要提醒
• 33. 與 Claude Code 概念映射
  • 33.1 相同概念、不同實作
  • 33.2 不可直接複製的部分
  • 33.3 如何建立跨 Agent 的標準
  • 33.4 VS Code 原生 Claude／Codex Harness 對跨工具標準的影響
  • 33.5 Plugin 分發層的跨工具收斂（第四版新增）
• 34. Enterprise Awesome Copilot Standard
  • 34.1 Naming Convention
  • 34.2 Documentation Standard
• 35. 團隊導入方案分級
  • 35.1 各等級進階條件（建議架構）
• 36. 30/60/90 天導入計畫
  • 36.1 Day 1-30：Learning + Pilot
  • 36.2 Day 31-60：Standardization + Agent Library
  • 36.3 Day 61-90：Governance + Enterprise Rollout
• 37. Cheat Sheet
  • 37.1 常用 CLI
  • 37.2 常用目錄
  • 37.3 Agent（.agent.md）最小範例
  • 37.4 Skill（SKILL.md）最小範例
  • 37.5 Instructions 最小範例
  • 37.6 Plugin（plugin.json）最小範例
  • 37.7 Hook 最小範例
  • 37.8 MCP 最小範例
  • 37.9 Troubleshooting 速查（詳見第 27 章）
  • 37.10 Security Checklist 速查（詳見第 21 章）
• 38. FAQ
• 39. Conclusion
• 40. References
  • 40.1 awesome-copilot 相關
  • 40.2 GitHub Copilot 官方文件
  • 40.3 VS Code 官方文件
  • 40.4 GitHub Changelog
  • 40.5 開放規範與跨產業標準
  • 40.6 2026 年資安威脅情資（呼應第 20.4 節）
  • 40.7 技術堆疊版本參考
  • 40.8 VS Code Release Notes 版本對照（第四版新增）
• 41. 全書 Checklist 總覽
  • 41.1 安裝與導入 Checklist
  • 41.2 安全 Checklist
  • 41.3 治理 Checklist
  • 41.4 新人快速上手 Checklist

1. Executive Summary：5 分鐘理解 awesome-copilot

1.1 awesome-copilot 是什麼

github/awesome-copilot 是託管在 GitHub 官方 org 底下、由社群貢獻維護的資源精選集，收錄可直接安裝到 GitHub Copilot 的 Custom Agents（.agent.md）、Instructions（*.instructions.md）、Agent Skills（SKILL.md）、Plugins（plugin.json）與 Cookbook 範例（官方已實作／Source-confirmed）。它不是 Copilot 的官方規格文件，而是「精選過的實例庫」——類似一座已經有人幫你篩過、分類好的素材倉庫，讓你不用從零開始寫客製化資源。

1.2 為什麼值得使用

• 不用重造輪子：500+ 貢獻者已經產出數百個 Agent／Skill／Instructions，涵蓋主流語言、框架、雲端平台與開發情境。
• 格式與官方同步：awesome-copilot 的資料夾結構（agents/、instructions/、skills/、plugins/、hooks/）直接對應 GitHub Copilot 官方客製化機制的五個分層，學會一個就等於學會另一個。
• 可作為企業標準的起點：與其讓每個團隊各自摸索 .agent.md／SKILL.md 該怎麼寫，不如先研究 awesome-copilot 已驗證過的範例，再依企業需求調整。

1.3 可以解決什麼問題

1.4 如何協助 AI Agent 開發

awesome-copilot 示範了如何用官方驗證的 .agent.md、SKILL.md、plugin.json、Hooks JSON 格式，組合出具備角色分工、工具授權、生命週期自動化的 Agent 平台雛形——這正是本手冊 Part II、Part III 要示範的「企業 AI Agent Development Platform」建置方法。

1.5 如何協助 Web Application 開發

透過 Custom Agents＋Skills＋Instructions 的組合（第 15 章案例），可以讓 Copilot 在企業 Vue 3 + Spring Boot 技術堆疊下，依循固定的架構規範、Coding Standard 與測試策略產出程式碼，而不是每次都要重新在 Prompt 中重述規則。

1.6 如何協助 Legacy Reverse Engineering

第 16 章示範如何設計一個 reverse-engineering Skill，引導 Copilot 依固定步驟（Repository Discovery → Dependency Analysis → Database Analysis → Business Rule Extraction → Modernization Recommendation）系統化地分析老舊 Java/JSP/Servlet 系統，避免每次分析結果格式不一致。

1.7 如何協助 Framework Migration

第 17 章示範 Spring Boot 3.x → 4.x 的 Migration 案例，說明如何用 Instructions 定義升級規則、用 Skill 封裝分析流程、用 Agent 執行變更、用 Hook 在變更前後自動跑測試與安全掃描。

1.8 如何協助 Security

第 8 章的 Security Review Skill 範例，以及第 20-21 章的 Governance／安全評估 Checklist，說明如何在導入社群資源前做好供應鏈風險把關，並讓 Security Review 成為開發流程的固定關卡而非事後補救。

1.9 如何導入企業

第 22-23 章與第 35-36 章提供從 Awareness → Pilot → Standardization → Governance 的六階段導入方法，以及具體的 30/60/90 天計畫，讓企業不是「一次全面開放」，而是分階段、可控地擴大使用範圍。

1.10 最推薦的使用方式

先讀官方規格，再挑 awesome-copilot 範例，最後才寫自己的企業版本。 順序反過來——直接複製社群範例卻不懂官方規格——是導入失敗與資安風險最常見的根因。

2. awesome-copilot 是什麼：官方生態系定位

2.1 Repository 基本事實

⚠️ 注意 docs/ 與 eng/ 常被漏列：常見的中文介紹文只列出六到八個「資源資料夾」，但 docs/（產生式資源索引）與 eng/（驗證與建置腳本）才是企業自建同等機制時最值得參考的兩個目錄（詳見第 2.8 節）。

第四版修正：scripts/ 目錄。第三版依 Contents API 實測未列出 scripts/，並將其視為「AGENTS.md 目錄樹與實際們庫的差異」。2026-08-31 複查確認：scripts/ 確實存在（AGENTS.md 的 Repository Structure 区塊也明列「├── scripts/ # Utility scripts」），先前的「差異」並不存在。這也是一個提醒：單一快照式的 API 實測不能當作長期事實，企業內部文件引用第三方們庫結構時，應註明查證日期並定期重驗。

2.2 Community-created resources 的概念

awesome-copilot 收錄的每一份 Agent、Skill、Instructions、Plugin、Hook，都是由社群貢獻者依 CONTRIBUTING.md 規範的格式提交、經 PR review 後合併進主分支。這代表：

• 內容品質參差不齊，取決於個別貢獻者的專業程度與維護意願。
• 內容不是 GitHub 官方對 Copilot 行為的保證——它只是「範例」，不是「規格」。
• 內容會隨時間變動或被移除（本手冊查證時就發現 chatmodes/、prompts/、collections/ 三個舊資料夾已被整併移除）。

⚠️ 官方生態系與社群貢獻的關係：GitHub Copilot 的官方規格永遠以 docs.github.com 與 code.visualstudio.com 為準；awesome-copilot 只是「託管在官方 org 下的社群精選集」，這一點容易被誤解為「官方認證內容」，撰寫企業內部文件時務必說清楚這個區別。

2.3 Awesome Copilot Website、Learning Hub、llms.txt

Learning Hub 現行課程地圖（2026-08-28 複查，Source-confirmed）

⚠️ 各資源分類的精確數量（例如「175 個 Agent」）在查證當下無法取得可靠且一致的官方統計（不同來源數字有落差）。企業內部文件若要引用數量，建議在撰寫當天重新用官方網站或 API 清點，而不是沿用本手冊或任何第三方部落格的舊數字（官方目前沒有找到足夠資料確認此功能）。

2.4 Resource Discovery 與 Marketplace

• 網站瀏覽：依五大分類（Agents/Instructions/Skills/Plugins/Canvas Extensions）加上 Learning Hub 瀏覽，每項資源提供「Copy Install」按鈕。
• CLI Marketplace：GitHub Copilot CLI 具備 Plugin Marketplace 機制，awesome-copilot 已是官方預設註冊的來源之一（另一個是 copilot-plugins），新版 CLI 可直接 copilot plugin install <name>@awesome-copilot，舊版才需先 copilot plugin marketplace add github/awesome-copilot（詳見第 12 章）。
• awesome-copilot MCP Server：Repository 自帶一台 MCP Server，讓 Agent 能直接從庫內搜尋與安裝資源，執行需要 Docker（詳見第 2.8 節）。
• docs/README.*.md：CI 自動產生的完整資源索引（Agents／Instructions／Skills／Plugins／Hooks／Workflows 各一份），適合離線盤點或實作企業 Catalog 時參考。
• llms.txt：供 AI Agent／LLM 工具直接讀取索引，快速了解倉庫內容結構，不需要人工爬取整個 Repository。

2.5 社群貢獻模式

依官方 CONTRIBUTING.md 與 AGENTS.md（Source-confirmed，2026-08-28 複查），每種資源類型都有固定的提交格式與（部分類型提供的）鷹架指令：

貢獻流程上容易踩到的坑（Source-confirmed）：

• PR 必須針對 main 分支；從 staged 分支開出的 PR 可能直接被退回。
• 提交前必須執行 bash eng/fix-line-endings.sh 將 CRLF 轉為 LF（Windows 開發者特別容易忽略）。
• 修改資源後需執行 npm ci → npm run build（或 npm start）重新產生 README 與 docs/ 索引，否則 CI 會失敗。
• 若是 AI Agent 代為提交的 PR，標題需附上 🤖🤖🤖 以走快速合併通道——這是目前少數明文規定「AI 產出須自我揭露」的實際例子，企業制定內部 PR 規範時可直接參考這個做法。
• marketplace.json 由 npm run plugin:generate-marketplace 自動產生於 .github/plugin/marketplace.json，不可手改。
• Agentic Workflow 的本機驗證指令為 gh aw compile --validate；CONTRIBUTING.md 進一步建議加上 --no-emit（例：gh aw compile --validate --no-emit daily-issues-report.md），只驗證不產出，避免本機多出不該 commit 的 .lock.yml。

AGENTS.md 的 Pre-commit Checklist（第四版新增，Source-confirmed）

awesome-copilot 的 AGENTS.md 內附有一份給貢獻者（含 AI Agent）的提交前檢查清單：

• Run npm install（或 npm ci）to install dependencies
• Run npm run build to generate the updated README.md
• Run bash eng/fix-line-endings.sh to normalize line endings
• Verified that all new files have proper front matter
• Tested that your contribution works with GitHub Copilot
• Checked that file names follow the naming convention

另外 AGENTS.md 還含一份 Code Review Checklist，逐項列出 Instructions、Agent、Skill、Hook、Workflow、Plugin 各自的審查項目（例如第 11.3 節引用的 mcp.json $schema 規則就出自這份清單）。

企業可直接移植的做法（建議架構）：把這兩份清單改寫成企業自己的 PR Template。重點不在於照抄項目，而在於它展示了一個關鍵模式：把審查規則寫進 AGENTS.md，讓 AI Agent 自己先跑一遍。這比只把規則寫在 Wiki 裡有效得多——因為 AGENTS.md 會被 Agent 實際讀到（見第 7 章）。

兩個值得追蹤的官方討論串（第四版新增）

awesome-copilot 明文拒收的內容（“What We Don’t Accept”，Source-confirmed）：違反 Responsible AI 原則、繞過安全控制、協助惡意行為、利用模型弱點、產生有害內容、規避政策限制、只是重述模型本來就很強的能力而無實際加值、以及未經審查的遠端來源 Plugin。這份清單可直接改寫為企業自己的「AI 客製化資源受理標準」（對應第 20 章 Governance）。

2.6 如何挑選第三方 Agent／Skill／Plugin

企業導入前的最低限度檢查（詳見第 21 章完整 Checklist）：

1. 讀完整份內容，不要只看 description。
2. 確認是否包含 Shell 指令、外部網路呼叫、對 Secret／環境變數的存取。
3. 確認貢獻者身份與最後更新時間，評估維護活躍度。
4. 若涉及 MCP Server，確認其權限範圍是否符合最小權限原則。
5. 先在沙盒/測試 Repository 安裝驗證，再推廣到正式專案。

2.7 安全性與供應鏈風險

安裝任何 Agent、Skill、Plugin、Hook 或 MCP Server 前，都必須先閱讀其內容、依賴、權限與執行行為。

awesome-copilot 是社群貢獻的資源集合，PR review 無法保證每一份資源都無害。Hooks 與 Plugins 尤其高風險，因為它們可以執行 Shell 指令；Skills 若綁定 allowed-tools 不當，也可能讓 Copilot 取得超出預期的工具存取權。詳見第 20-21 章的 Governance 與安全評估流程。

2.8 docs/、eng/ 與 awesome-copilot MCP Server

這三項是大多數介紹文漏掉、但對企業自建相同機制最有參考價值的部分（Source-confirmed，2026-08-28 Contents API 與 AGENTS.md 複查）。

產生式資源索引：docs/README.*.md

這些檔案全部由 npm run build 自動產生，不可手改。對企業的啟示：第 24 章的企業 Catalog 不應該手工維護——應該把各資源的 frontmatter 當成唯一真相來源，由 CI 產生 Catalog，否則目錄與實際資源必然會隨時間脱節（這也是第 28 章維護策略的實作重點）。

驗證與建置腳本：eng/

⚠️ 企業對應做法（建議架構）：把上表的「驗證指令」觀念搬到企業自己的客製化資源倉庫，在 CI 上強制執行 schema 驗證，可以預防大多數「Agent 沒出現」「Skill 沒觸發」類的問題（對應第 27 章 Troubleshooting 的前三項）。

awesome-copilot MCP Server

Repository 頂層的 mcp.json 定義了一台 awesome-copilot 專用 MCP Server，讓 Agent 可以直接從對話中搜尋並安裝庫內資源，而不需要人工到網站複製貼上。

• 前提條件：本機需安裝並啟動 Docker（這是企業內部隱形的導入門檳：若開發者筆電禁止安裝容器執行環境，此路徑直接不可用）。
• 使用前仍須依第 21 章 Checklist 審查：它能「直接安裝資源」這件事本身就是一個需要治理的能力，不應該在未建立 Approved Catalog 前就對全團隊開放。
• 定位上它屬於第 3 章五層模型的「連接層（MCP）」，但服務的對象是「客製化資源本身」，而非一般的外部業務系統。

2.9 awesome-copilot 的 AI 供應鏈與 Agent 治理資源盤點

2026-08-28 複查 llms.txt 索引時發現，awesome-copilot 近一年新增了一整批**「治理 AI 本身」**的資源。這批資源與第 20-21 章（Governance、Security Review）高度相關，卻最容易被忽略——多數團隊只會搜尋「Java」「Vue」這類技術關鍵字，不會主動搜尋「governance」。以下為盤點結果（Source-confirmed，取自官網 llms.txt 的 Agents／Skills 清單）：

⚠️ 企業實務建議（建議架構）：把 trojan-skill-hunter 與 agent-supply-chain 的「檢查面向」抄進企業自己的第 21 章 Checklist，但不要直接安裝這兩個社群 Agent／Skill 就當成安全防線——用一個未經審查的社群資源去審查其他未經審查的社群資源，邏輯上是循環的。正確做法是：人工閱讀它們的 SKILL.md／.agent.md 內容，萃取檢查項目，改寫成企業自建、經過 CODEOWNERS 保護的版本。

另外值得注意的是 Advanced Security plugin（advanced-security@copilot-plugins）：它由 copilot-plugins 這個 GitHub 官方預設 Marketplace 提供，讓 Agent 在 commit 前透過 GitHub MCP Server 掃描 Secret 與相依套件弱點。對已購買 GitHub Advanced Security 的企業而言，這是優先於任何社群資源的選項（官方已實作）。

Scenario

某團隊的 Tech Lead 想幫團隊導入 Code Review Agent，直接從 awesome-copilot 網站複製了一個 code-reviewer.agent.md 並安裝到全公司共用的 GitHub org 層級設定。三週後才發現該 Agent 的 tools 欄位授權了無限制的 Shell 執行權限，且沒有人在安裝前逐行讀過內容。正確做法：先在個人 Sandbox Repository 安裝、逐行閱讀 frontmatter 授權範圍、確認無誤後才提交企業版的 Fork（依第 34 章命名慣例調整），而不是直接對全組織生效。

本章 Checklist

• 已理解 awesome-copilot 是「社群精選集」而非「官方規格文件」
• 已知道現行五大資源類型與各自路徑慣例
• 已知道 chatmodes/／prompts/／collections/ 是已移除的舊結構
• 已知道 docs/README.*.md 是 CI 產生的索引，並已評估企業 Catalog 是否要改為自動產生（第 2.8 節）
• 已評估 awesome-copilot MCP Server 是否符合企業的 Docker 使用政策
• 已依第 2.9 節盤點「治理類資源」，並確認企業是否已有 Advanced Security plugin 可用
• 安裝任何資源前，已建立「先讀內容、後安裝」的團隊習慣

3. 整體架構：GitHub Copilot 客製化五層模型

3.1 分層架構圖

依查證結果，GitHub Copilot 的客製化機制可以整理成五層，awesome-copilot 的資料夾結構幾乎逐層對應：

graph TB
    Dev["Developer"] --> Copilot["GitHub Copilot"]

    Copilot --> L1

    subgraph L1["指令層 Instructions"]
        I1["copilot-instructions.md<br/>(repo 全域)"]
        I2["*.instructions.md<br/>(applyTo glob)"]
        I3["AGENTS.md / CLAUDE.md / GEMINI.md<br/>(跨 agent 相容，支援面有限)"]
        I4["個人 / 組織層級指令"]
    end

    Copilot --> L2

    subgraph L2["行為層"]
        B1["Custom Agents (.agent.md)<br/>前身 .chatmode.md"]
        B2["Agent Skills (SKILL.md)"]
        B3["Prompt files (.prompt.md)"]
    end

    Copilot --> L3

    subgraph L3["自動化層"]
        A1["Hooks (.github/hooks/*.json)"]
        A2["Agentic Workflows (gh-aw)"]
    end

    Copilot --> L4

    subgraph L4["連接層"]
        M1["MCP Servers<br/>(.vscode/mcp.json 等)"]
    end

    Copilot --> L5

    subgraph L5["打包分發層"]
        P1["Plugins (plugin.json)<br/>Agent Plugins 1.0"]
    end

    P1 -.->|"可打包"| B1
    P1 -.->|"可打包"| B2
    P1 -.->|"可打包"| A1
    P1 -.->|"可打包"| M1

    L1 --> Runtime["AI Agent Runtime<br/>(VS Code Agent Mode / Copilot CLI / Copilot cloud agent)"]
    L2 --> Runtime
    L3 --> Runtime
    L4 --> Runtime

    Runtime --> Repo["Repository"]
    Runtime --> Src["Source Code"]
    Runtime --> Test["Tests"]
    Runtime --> DB["Database"]
    Runtime --> API["APIs"]
    Runtime --> DevOps["DevOps / CI-CD"]
    Runtime --> Ext["External Systems<br/>(透過 MCP)"]

（實線＝已查證的官方機制／依賴關係；虛線＝Plugins 可打包其他層資源的建議性關係，依 Agent Plugins 1.0 規格）

3.2 各層如何協作

3.3 與 awesome-copilot 資料夾的對應關係

Scenario

企業導入初期常見的困惑是「Instructions、Agents、Skills 到底該先做哪一個？」。依這張分層圖，建議順序是：先把指令層（copilot-instructions.md + 幾個 *.instructions.md）做好，這是成本最低、影響最廣的一層；接著才依需求逐步加上行為層的 Custom Agents／Skills；自動化層（Hooks）與打包分發層（Plugins）留到團隊已經有穩定的 Agent／Skill 之後再做，因為這兩層牽涉 Shell 執行與跨團隊分發，風險與維運成本較高。

本章 Checklist

• 團隊已理解五層架構，且知道各層的觸發時機不同
• 已規劃「先做指令層，再做行為層」的漸進導入順序
• 已知道 Plugins 是「打包層」，會用到其他四層的資源

4. Resource Model 完整介紹

本章對 awesome-copilot 收錄的 11 種資源類型做總覽介紹；其中 Agents、Instructions、Skills、Hooks、Plugins、MCP 六項在第 6-14 章有專門的深入章節與完整範例，本章僅做定位與快速比較，避免重複。

4.1 資源類型總覽表

4.2 Agentic Workflows（gh-aw）補充說明

Agentic Workflows 是透過獨立的 GitHub CLI 擴充套件 gh-aw（gh extension install github/gh-aw）將以 .md 撰寫的 Agent 工作流程「編譯」成 GitHub Actions 可執行的 .lock.yml，讓 Agent 任務能排程或依 GitHub 事件觸發，跑在 CI/CD 環境中（Source-confirmed，來自 awesome-copilot workflows/ 目錄慣例）。

安裝與使用流程（示意）：

# 安裝 gh-aw 擴充套件
gh extension install github/gh-aw

# 將 workflow 定義（.md）放入 .github/workflows/
# 本地驗證與測試編譯（不產生實際檔案，僅檢查語法與權限設定是否正確）
gh aw compile --validate --no-emit

# 確認無誤後正式編譯成 GitHub Actions 可執行檔
gh aw compile

# 只提交 .md 原始定義，不要提交編譯產物 .lock.yml（依 awesome-copilot CONTRIBUTING.md 規範）
git add .github/workflows/my-workflow.md
git commit -m "feat: add agentic workflow"

.md 定義需包含的 frontmatter：name、description、on（觸發事件）、permissions、safe-outputs（Source-confirmed，來自 CONTRIBUTING.md）。

4.3 Cookbook 補充說明

cookbook/ 資料夾收錄 Copilot SDK（copilot-sdk/）的程式化範例，搭配 README.md 與 cookbook.yml 索引，適合需要「用程式碼呼叫 Copilot」而非透過 IDE 互動的情境，例如企業內部工具要整合 Copilot 能力、CI Pipeline 要自動化呼叫 Copilot 做程式碼分析等。

4.4 Canvas Extensions 補充說明

⚠️ 查證時仍未找到 docs.github.com 上針對 Canvas Extensions 的獨立官方文件頁；但 2026-08-28 複查發現，awesome-copilot 官網 Learning Hub 已有專文「Working with Canvas Extensions」，且 CONTRIBUTING.md（Source-confirmed）定義了明確的目錄與驗證規範，資料完整度已比上一版提升。

extensions/<extension-id>/
└── extension.mjs        # Canvas Extension 原始碼元件

plugins/<extension-id>/  # 需與 extensions/ 下同名，成對存在
└── plugin.json          # 對應的 Plugin manifest，name 需與資料夾同名

實作時最容易失敗的三個點（Source-confirmed，取自 CONTRIBUTING.md）：

1. plugin.json 中的 extensions.com.github.copilot.logo 必須恰好是 "assets/preview.png"，不可改成其他路徑或檔名。
2. 不可新增 canvas.json——此檔不屬於現行規格，加了反而會驗證失敗。
3. 一定要執行 npm run plugin:validate 驗證，不可僅靠目測。

建立方式上，Learning Hub 說明可在 Copilot app 中以 /create-canvas slash command 產生並逐步演進 Canvas，不必從空白手寫 extension.mjs。

企業導入時應將其視為「Plugin 生態的延伸能力、有 Repository 內部貢獻規範與 Learning Hub 教材可循，但仍缺乏 docs.github.com 獨立說明頁」的狀態，安裝前比照 Plugin 的安全審查流程處理（第 21 章），並持續關注官方文件是否補齊獨立頁面。

4.5 GitHub Copilot app 與 Automations（新增）

2026-08-28 複查時，awesome-copilot Learning Hub 的 Getting Started 區已以 GitHub Copilot app 為首選入口，這是上一版手冊尚未涵蓋的重要變化（Source-confirmed）。

⚠️ 治理提醒：Copilot app 是一個獨立的使用介面，它的 Plugin 安裝行為不會因為企業在 VS Code 做了限制而自動受控。若企業已導入 Copilot app，必須依第 20.5 節的 managed-settings.json 做跨介面的集中管控，而不是只靠 Repository 層級的設定。

4.6 Copilot SDK 與 Agent Host

上一版手冊將 cookbook/ 僅描述為「Copilot SDK 的程式化範例」；2026-08-28 複查發現 Copilot SDK 已不只是一個選配的周邊套件，而是 Copilot 本身的執行底層：VS Code 官方文件明載「Copilot harness 使用 Copilot SDK 並跑在 Agent Host 上」（官方已實作）。這對企業有三個實際意義：

另外，awesome-copilot 收錄了 copilot-sdk Skill，官方描述為「Build agentic applications with GitHub Copilot SDK」，觸發詞包含 embed Copilot、programmable agent、MCP server、custom agent（Source-confirmed）。

⚠️ 評估提醒（建議架構）：用 SDK 自建工具會把「Agent 行為的控制權」從 IDE 的審核介面移到企業自己的程式碼中。這代表第 20 章的 Governance 控制（工具授權、人工核准關卡、稽核軌跡）必須在你自己的應用層重新實作一次，不能假設「VS Code 有的防護，SDK 也有」。導入前請先完成第 21 章的安全評估。

Scenario

某團隊想幫「REST API 設計規範」建立客製化資源，卡在該用 Instructions 還是 Skill。判斷依據：如果規則是「靜態、每次都要套用、不需要多步驟推理」（例如「Controller 命名一律用 XxxController」），用 Instructions；如果是「一套需要多步驟分析、可能需要參考範本檔案的流程」（例如「依 OpenAPI 規範產生完整 API 設計文件，含版本管理、錯誤碼規範」），用 Skill。

本章 Checklist

• 已對照 4.1 總覽表，確認每種待建立的資源該歸類到哪一種類型
• 已知道 Agentic Workflows 只提交 .md，不提交 .lock.yml
• Canvas Extensions 已知悉「官方文件不完整」，安裝前需加強審查
• 若規劃以 Copilot SDK 自建工具，已確認 Governance 控制會在自家應用層重新實作（4.6）

5. Agents／Instructions／Skills／Hooks／Plugins／MCP 核心差異

5.1 比較表

5.2 用實際軟體工程案例對照

5.3 核心心法

Instructions 是長期背景與規則——每次都在，不需要觸發，只是「always-on 的規則集」。

Skills 是可重複、可發現、可封裝的能力——Copilot 依相關性自動判斷是否載入，可以攜帶腳本與參考資料。

Custom Agents 是具有特定角色、工具與工作流程的專業代理——有身份、有工具授權邊界，通常由使用者主動切換或由其他 Agent Handoff。

Hooks 是確定性的事件驅動自動化——不靠 AI 判斷，靠事件觸發執行固定的 Shell 指令，是唯一不經過「AI 推理」的一層。

Plugins 是可安裝的能力組合——把前面幾層打包成一個分發單位。

MCP 是 Agent 與外部工具／資料／系統的連接層——讓 Agent 的能力邊界能延伸到 Copilot 本身不具備的外部世界。

上述定義依查證結果與 GitHub 官方文件現況一致，若日後官方文件有調整，應以官方最新定義為準。

Scenario

某企業要建立「自動執行測試」機制，工程師一開始寫了一個 Agent 讓 Copilot「判斷是否需要跑測試」，結果因為 AI 判斷不穩定，有時候該跑測試卻沒跑。修正做法：改用 Hook 綁定 preToolUse 或 CI 層級的確定性觸發，不依賴 AI 判斷「要不要跑」，只依賴事件是否發生。

AI Prompt 範例

角色：你是資深 Software Architect。

情境：我們要幫 Java + Spring Boot + Vue 3 專案建立客製化資源，
但團隊還沒決定某個規則該用 Instructions 還是 Skill。

規則內容：「所有 REST API 的 Controller 必須有對應的 OpenAPI 註解，
且回應格式必須遵循企業統一的 ApiResponse<T> 包裝格式。」

請依「是否需要多步驟推理」「是否需要攜帶 bundled 資源」
「是否每次都要套用」三個判準，建議應該用 Instructions 或 Skill，
並說明理由。

本章 Checklist

• 團隊已用 5.1 比較表建立「元件選型」的共同語言
• 已用 5.2 案例對照表驗證過至少 3 個團隊實際案例
• 已理解 Hooks 是唯一「不經過 AI 推理」的確定性自動化層

6. Repository 目錄結構

6.1 企業 Web Application Repository 建議配置

⚠️ 下列目錄樹為建議架構，並非所有專案都需要全部目錄；實際是否存在取決於團隊已導入哪些客製化層級。

project/
├── AGENTS.md                          # 跨 agent 相容指令（Copilot／Claude／Gemini 共用，支援面有限，見第 7 章）
├── .github/
│   ├── copilot-instructions.md        # Repo 全域 Custom Instructions（官方已實作）
│   ├── instructions/
│   │   ├── java.instructions.md       # applyTo: "**/*.java"
│   │   ├── vue.instructions.md        # applyTo: "**/*.vue"
│   │   └── security.instructions.md   # applyTo: "**/*"
│   ├── agents/
│   │   ├── security-reviewer.agent.md
│   │   ├── architecture-reviewer.agent.md
│   │   └── code-reviewer.agent.md
│   ├── skills/
│   │   ├── web-application-development/
│   │   │   └── SKILL.md
│   │   ├── reverse-engineering/
│   │   │   └── SKILL.md
│   │   ├── framework-migration/
│   │   │   └── SKILL.md
│   │   └── security-review/
│   │       └── SKILL.md
│   ├── hooks/
│   │   ├── pre-commit-quality-gate.json
│   │   └── agent-workflow-guard.json
│   ├── workflows/                     # GitHub Actions（一般 CI/CD，非全部與 Copilot 相關）
│   │   └── ci.yml
│   └── prompts/                       # Prompt files（.prompt.md），若使用
│       └── api-design.prompt.md
├── src/
├── tests/
├── docs/
└── ...

6.2 哪些目錄屬於哪個系統

6.3 Project Scope 與 Personal Scope

⚠️ Agent Host 的例外：VS Code 官方文件明載，Agent Host 讀取的是 ~/.copilot/agents，而非 VS Code 自己的 profile 資料夾。若企業把個人層級 Agent 放在 VS Code profile 內，在 Agent Host 情境下會完全讀不到。

6.4 Root Level、Nested 與 Monorepo 設定

• AGENTS.md 預設只讀取 workspace root；VS Code 提供 chat.useNestedAgentsMdFiles（Experimental）讓 monorepo 子資料夾也能有各自的 AGENTS.md。
• *.instructions.md 透過 frontmatter 的 applyTo glob 決定套用範圍，本質上就是一種「巢狀/路徑範圍」機制，不需要額外的巢狀資料夾規則。
• Monorepo 父倉庫發現（官方已實作）：若專案是大 monorepo 底下的子倉庫，開啟 chat.useCustomizationsInParentRepositories 可讓 VS Code 從父倉庫 root 發現 Instructions／Skills／Agents，避免每個子專案都要複製一份相同的規則。其行為細節如下（2026-08-28 複查 VS Code 官方文件）：
  • 預設是關閉的，必須手動開啟。
  • 開啟後，VS Code 從每個 workspace folder 向上尋找到含 .git 的目錄為止，並收集**沒到的所有層級（含頭含尾）**的客製化。
  • 生效條件三項同時成立：workspace folder 本身沒有 .git、某個父目錄有 .git、且該父目錄已被信任。
  • 套用範圍涵蓋所有客製化類型：always-on instructions（copilot-instructions.md、AGENTS.md、CLAUDE.md）、檔案式 instructions、prompt files、custom agents、agent skills 與 hooks。尤其 hooks 會被継承這一點，企業須在第 20 章 Governance 中明確納入風險評估。
• 自訂存放位置：chat.agentFilesLocations（Agents）與 chat.agentSkillsLocations（Skills）可指定額外的專案級資料夾，適合企業已有自訂目錄結構、不想遯就 .github/ 的情境。

6.5 不同 Copilot Client 的支援差異

⚠️ 這是撰寫企業文件時最容易忽略、卻最容易導致「同事在 A 工具測試沒問題，換 B 工具就失效」的一段。務必在團隊內部文件中附上下表，並持續關注官方支援矩陣更新。

（本表依查證所得整理，未列出「✅」以外明確狀態的欄位一律標示「資料不足」，代表官方支援矩陣頁面未明確載明，企業導入前應自行至 docs.github.com/en/copilot/reference/custom-instructions-support 等頁面重新確認當下版本。）

6.6 四種 Harness 的選用與設定檔對照

2026 年中之後，GitHub Copilot 已明確形成四種 harness（執行宿主），awesome-copilot Learning Hub 的 Workshop 也是以這四種 harness 分軌教學（Source-confirmed）。企業制定標準前須先釐清團隊實際使用哪幾種：

⚠️ 企業實務建議（建議架構）：請在企業內部標準中明列「本公司支援哪幾種 harness」，並針對每種 harness 列出對應的設定檔與檢查方式。實務上最常見的治理破口就是「IDE 管得很嚴，但開發者自行安裝 Copilot app 後自己裝 Plugin」，這只能靠第 20.5 節的企業級設定解決。

6.7 Session Target、Agent Harness 與 Code Isolation

⚠️ 本節是第三版新增的重要術語釐清。 上一版手冊第 6.6 節把「harness」當成「VS Code／CLI／cloud agent／app 四種使用介面」。但 VS Code 官方文件（2026-08-28 複查）將 agent harness 定義為「產業界用來稱呼『統籌 Agent 的軟體』的術語」，並列出四種執行時：Local／Copilot／Claude／Codex。這是兩個完全不同的軸線，企業文件必須分開描述，否則會出現「我們只支援 VS Code harness」這種語意不明的規定。

兩個軸線的對照

四種 Agent Harness（官方已實作）

Session Target：一次工作階段的四個獨立選擇

VS Code 將這四項選擇集中在 Chat 輸入框的 Session Target 控制項，四者彼此獨立：

Session Target
├── Agent harness        Local / Copilot / Claude / Codex
├── Execution environment 本機 / 遠端機器 / 雲端
├── Agent role           Agent / Plan / Ask / 自訂 Agent（.agent.md）
└── Language model       依 harness 可用的模型清單

實務上最常被誤解的是「Agent role」與「Agent harness」的關係：你在第 9 章建立的 .agent.md 是 role，不是 harness；同一份 .agent.md 可能在不同 harness 下可用工具不同，這正是第 6.5 節支援矩陣存在的原因。

Code Isolation：Folder 與 Worktree

⚠️ 安全釐清（官方文件明文）：「worktree 是 Git 的程式碼隔離邊界，不是安全邊界。」它防的是「兩個 Agent 改到同一個檔案」，不是「Agent 執行惡意指令」。後者需要的是第 20.6 節的 Agent Sandboxing。不少企業把「我們都用 worktree」寫進安全政策，這是錯誤的安全假設。

Agent Host 與 Session Handoff

Agent Host 是一個專用程序，與「顯示該 session 的視窗」解耦執行，因此支援：

• 背景延續：關掉視窗或切換專案，Agent 仍繼續工作。
• 跨視窗同步：同一 session 可在不同視窗查看。
• 遠端執行：搭配 Execution environment 選項，把實際執行搬到遠端機器或雲端。
• Session handoff：同一個工作階段可在不同 harness／執行環境之間交接（例如本機起手、交給雲端跑完）。

如何啟用 Agent Host（第四版新增，官方已實作）：Agent Host 目前是 opt-in。啟用方式為開啟設定 chat.agentHost.enabled，再從 harness 下拉選單選擇一個 agent host harness。官方將此描述為「围繞 Agent Host Protocol（AHP） 重新架構 VS Code 的 Agent Session」——一個專用程序負責執行 Copilot、Claude、Codex 等 harness。

企業導入含意（建議架構）：因為是 opt-in，企業會出現「部分人已啟用、部分人未啟用」的行為不一致期。最直接的影響是第 20.7.1 小節的 Assisted Permissions 與 Autopilot 只在 Agent Host 上可用，以及使用者層客製化的讀取位置會隨 harness 而異（~/.copilot／~/.claude）。建議企業明確表態：要麼統一以 Settings Policy 開啟並同步更新內部教學，要麼明令暫不使用，不要放任各團隊自行決定。

Worktree 已擴及全部 harness（第四版更新，官方已實作）：跑在 Agent Host 上的 harness 現已全面支援 worktree 隱離。Agents 視窗中的 New Worktree 勾選框過去只有 Copilot harness 支援，現在 Claude 與 Codex session 也會跑在 Git worktree 中，讓同一工作區內不同功能的平行 session 更容易建立。這對第 10 章 Agent Team 平行協作是關鍵前提——但請再次注意上方的釋清：worktree 不是安全邊界。

⚠️ 治理含意（建議架構）：「背景延續」代表 Agent 可能在沒有人盯著螢幕的情況下持續修改程式碼。企業導入自主程度較高的模式（如 Autopilot）時，必須同時完成三件事：（1）開啟第 20.6 節 sandboxing；（2）使用 worktree isolation；（3）依第 31 章建立合併前的 Quality Gate。三者缺一不可。

Scenario

某企業把 .github/agents/security-reviewer.agent.md 設計好後，發現在 GitHub.com 的 PR Code Review 情境中沒有生效。查證後發現 Custom Agents 主要設計給 VS Code／Copilot CLI 的互動情境使用，GitHub.com Code Review 這個介面有自己的一套指令讀取邏輯（主要吃 AGENTS.md／copilot-instructions.md）。教訓：導入任何客製化資源前，務必先確認目標情境（IDE／CLI／cloud agent／Code Review）是否真的支援該機制，不要假設「在一個地方生效，其他地方也會生效」。

本章 Checklist

• 已依 6.1 建立企業 Repository 的客製化目錄骨架
• 已用 6.2 分清楚「哪些是 Copilot 客製化、哪些是一般 GitHub Actions」
• Monorepo 專案已評估是否開啟 chat.useCustomizationsInParentRepositories（6.4）
• 已用 6.5 支援矩陣確認團隊實際使用的 Client 是否支援目標機制
• 已依 6.6 明列企業支援的 harness 範圍，並確認 Copilot app 也在治理範圍
• 已依 6.7 區分「使用介面」與「Agent Harness（Local／Copilot／Claude／Codex）」兩個軸線，且企業文件用詞一致
• 已向團隊宣導「worktree 不是安全邊界」，避免錯誤的安全假設（6.7）
• 已對 chat.agentHost.enabled（Agent Host）明確表態：統一開啟或明令暫不使用，不放任各團隊自行決定（6.7）

7. AGENTS.md、copilot-instructions.md 與 *.instructions.md 深入比較

7.1 三者比較表

7.2 AGENTS.md 支援矩陣（最容易寫錯的一段，務必逐字核對官方原文）

依官方支援矩陣頁（docs.github.com/en/copilot/reference/custom-instructions-support）：

官方支援矩陣的重點結論：AGENTS.md 不是「放諸四海皆準」的萬用檔案，它在不同 Client、不同情境下的支援程度不同，尤其 GitHub.com 的 Code Review 功能只認 AGENTS.md，即使專案同時放了 CLAUDE.md，Code Review 也不會讀取。企業若同時使用 Claude Code 與 GitHub Copilot，建議兩份檔案都準備，內容盡量保持一致或用 @ 引入共用片段。

AGENTS.md 的治理現況（Source-confirmed，2026-08-27 查證）：AGENTS.md 原由 OpenAI 發起，目前已移交 Linux Foundation 旗下的 Agentic AI Foundation 託管，截至 2026 年中已有 28 個以上的 AI Coding 工具（含 GitHub Copilot、Claude Code、Cursor、Windsurf、Amp、Devin、Aider、Zed、JetBrains Junie 等）與超過 6 萬個開源 Repository 採用。這代表 AGENTS.md 已是跨廠商、由中立基金會治理的產業標準，而非單一供應商的自訂格式，企業採用時可以更放心地把它當成「多 Agent 共用背景」的長期基礎設施，而不用擔心單一廠商未來改變方向。

7.3 VS Code 設定開關

7.4 指令優先順序

官方文件說明的優先順序（高到低）：Personal → Path-specific → Repository-wide → Agent instructions → Organization。

⚠️ 但 Copilot CLI 的個人化指令文件另外明說：「不同檔案（copilot-instructions.md／AGENTS.md／CLAUDE.md／GEMINI.md）之間沒有定義通用優先序，應避免撰寫互相衝突的指令」（官方原文：“it does not define a general precedence order between these files. Avoid conflicting instructions."）。也就是說，優先順序規則只保證「同類型指令的個人／路徑／全域／組織層級」順序，不保證「不同檔案之間」的順序，企業撰寫規則時務必避免讓 AGENTS.md 與 copilot-instructions.md 互相矛盾。

7.5 applyTo 語法範例

---
applyTo: "**/*.ts,**/*.tsx"
---

多個 glob 用逗號分隔，整體加引號；** 代表套用到所有檔案。

7.6 企業 Web Application 完整範例

.github/copilot-instructions.md（示意）：

# 企業 Web Application 開發規範

本專案採用 Clean Architecture 分層：Controller → Service → Repository → Entity。

- 所有 REST API 回應必須包裝為 `ApiResponse<T>` 格式
- 所有 Service 層方法禁止直接回傳 Entity，必須轉換為 DTO
- 資料庫存取一律透過 Repository 介面，禁止在 Service 層直接寫 SQL
- 詳細規範請見 @docs/architecture.md

.github/instructions/java.instructions.md（示意）：

---
applyTo: "**/*.java"
---

# Java 程式碼規範

- 延續並善用 JDK 21+ 已定案的語言特性（`record`、switch pattern matching），並隨 Java 25 更新持續檢視新版本帶來的語法改進
- 所有 public 方法須有 Javadoc
- 例外處理統一使用自訂的 `BusinessException` 階層，禁止直接拋出 `RuntimeException`
- 命名慣例：Controller 類別以 `Controller` 結尾，Service 介面以 `Service` 結尾，實作類別以 `ServiceImpl` 結尾

.github/instructions/vue.instructions.md（示意）：

---
applyTo: "**/*.vue,**/*.ts"
---

# Vue 3 + TypeScript 程式碼規範

- 一律使用 Composition API（`<script setup lang="ts">`），禁止使用 Options API
- 狀態管理使用 Pinia，禁止在元件內直接操作全域變數
- 樣式一律使用 Tailwind CSS utility class，避免撰寫自訂 CSS
- UI 元件優先使用 PrimeVue，除非設計稿明確要求客製化元件

AGENTS.md（示意，跨工具共用部分）：

# 專案說明（供 AI Coding Agent 使用）

這是一個 Java 25 + Spring Boot 4.x（後端）與 Vue 3 + TypeScript（前端）的企業 Web 應用程式。

## 建置指令

- 後端：`mvn clean install`
- 前端：`npm install && npm run build`

## 測試指令

- 後端：`mvn test`
- 前端：`npm run test:unit`（Vitest）、`npm run test:e2e`（Playwright）

## 重要限制

- 不可修改 `src/main/resources/db/migration/` 下的既有 migration 檔案，新增變更一律新增檔案
- 不可跳過測試直接提交（`mvn test -DskipTests` 僅限本機除錯，禁止用於提交前）

Scenario

某團隊同時使用 GitHub Copilot（IDE 日常開發）與 Claude Code（CLI 深度重構任務），一開始只寫了 copilot-instructions.md，導致 Claude Code 完全讀不到規範、每次都要重新在 Prompt 裡貼一次規則。改用 AGENTS.md 放共用的專案說明（建置指令、測試指令、重要限制），copilot-instructions.md 只放 Copilot 專屬的細部規則後，兩個工具都能拿到一致的專案背景。若團隊仍需要 Claude Code 專屬的補充規則（例如只有 Claude Code 用得到的工具授權設定），依 7.2 建議仍可保留一份精簡的 CLAUDE.md，內容只放「AGENTS.md 沒有涵蓋」的差異化規則，並在檔案開頭用一句話指向 AGENTS.md（例如「請先閱讀 @AGENTS.md 取得專案背景」），避免兩份檔案重複維護、內容日久漂移。

AI Prompt 範例

角色：你是資深 Tech Lead。

任務：請幫我們的 Java 25 + Spring Boot 4.x + Vue 3 專案草擬一份 AGENTS.md，
內容需包含：專案簡介、建置指令、測試指令、目錄結構說明、
以及「不可修改資料庫 migration 既有檔案」這條硬性限制。

限制：
- 只寫跨工具都適用的通用資訊，不要放 Copilot 專屬的細部程式碼風格規則
  （那些已經在 .github/instructions/ 底下另外維護）
- 內容需精簡，控制在 60 行以內

本章 Checklist

• 已依 7.1 表格分清楚三種檔案的用途邊界
• 已核對 7.2 支援矩陣，確認 GitHub.com Code Review 只認 AGENTS.md
• 已避免讓 AGENTS.md 與 copilot-instructions.md 內容互相矛盾（7.4）
• 已建立企業版的三份範例檔案（7.6）

8. Skills 深入教學與四個企業 Skill 範例

8.1 Agent Skills 的概念

Agent Skills 是 GitHub Copilot 官方已實作的功能（2025-12-18 GA），定義為「Copilot 可在相關任務中載入的、由指令、腳本與資源組成的資料夾」（官方原文：“Agent skills are folders of instructions, scripts, and resources that Copilot can load when relevant to improve its performance in specialized tasks."）。

重要且容易被誤解的一點：Agent Skills 不是社群自創的慣例，也不是 Claude Code 專屬概念被硬套到 Copilot 上——GitHub 官方文件明確與 Claude Code 的 .claude/skills 相容並互通（官方原文：“If you’ve already set up skills for Claude Code in the .claude/skills directory in your repository, Copilot will pick them up automatically."）。

支援介面（官方原文）：“Agent skills work with Copilot cloud agent, Copilot code review, the GitHub Copilot CLI, the GitHub Copilot app, and agent mode in Visual Studio Code and JetBrains IDEs.”

8.2 SKILL.md Frontmatter

GitHub Docs 官方版本：

⚠️ allowed-tools 是資安決策，不是便利欄位（官方已實作，2026-08-31 查證）。GitHub Docs 對此欄位下了明確的 Warning：只有在你已審閱過這個 Skill 及其引用的所有腳本、且完全信任其來源時，才可以將 shell 或 bash 列入 allowed-tools。預先核准 shell／bash 等於移除了執行終端指令前的人工確認關卡，會讓受攻擊者控制的 Skill 或 Prompt Injection 得以在你的環境中執行任意指令。有任何疑慮時，就別把 shell／bash 寫進去。

企業實務建議（建議架構）：把「包含 allowed-tools: shell 或 bash 的 Skill」列為 CI 強制標記項目，一律進入人工資安審查佇列，並搭配第 20.5 節的 permissions.deny／permissions.ask 與第 20.6 節的 Sandbox 作為第二、第三道防線（見第 21 章）。

VS Code 官方版本的完整規格（2026-08-28 複查，官方已實作）——這一版把長度上限與命名限制寫得最清楚，也是實務上最常踩坑的地方：

⚠️ 實務上最常見的三個「Skill 沒載入」原因（1）name 與資料夾名不一致；（2）name 自作主張加了 myorg/skillname 或 myorg:skillname 前綴；（3）description 寫得太抽象。前兩項都是静默失敗，不會有任何錯誤訊息，這也是企業必須在 CI 加上 npm run skill:validate 同等驗證的原因（見第 2.8 節）。

⚠️ Skill 被打包進 Plugin 時，Plugin 名稱會被自動當成命令前綴（例如 /my-plugin:test-runner），因此更不可手動在 name 裡加前綴。

官方範例（逐字取自文件）：

---
name: github-actions-failure-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when 
asked to debug failing GitHub Actions workflows.
---

規範依據與安裝／驗證指令（Source-confirmed，來自 github/awesome-copilot 的 docs/README.skills.md 與 CONTRIBUTING.md，2026-08-27 查證）：Agent Skills 的格式依循開放規範 agentskills.io/specification，並非 GitHub 自創格式，這也是它能與 Claude Code 等其他 Agent 平台互通的原因。若要用 GitHub CLI 直接安裝他人發布的 Skill，需先確認 GitHub CLI 版本 ≥ 2.90.0（gh skills install <owner>/<repo>）；若要為 awesome-copilot 貢獻新 Skill，官方鷹架與驗證指令為 npm run skill:create -- --name <skill-name> --description "..." 建立骨架，npm run skill:validate 驗證格式，npm run build 更新索引。

8.3 Skill Directory 與存放位置

.github/skills/<skill-name>/
└── SKILL.md
    ├── scripts/          # 可選：輔助腳本
    ├── references/       # 可選：參考資料
    └── templates/        # 可選：範本檔案

存放位置（依 Client 而定）：

官方路徑定義複查（2026-08-31，官方已實作）：docs.github.com 的 About agent skills 與 Customization Cheat Sheet 兩頁一致列出 五個官方探索路徑，可分為兩類：

• 專案 Skill（Project skills），隨 Repository 版控、隨專案共享：.github/skills/<skill-name>/SKILL.md、.claude/skills/<skill-name>/SKILL.md、.agents/skills/<skill-name>/SKILL.md
• 個人 Skill（Personal skills），放在 home 目錄、跨專案通用：~/.copilot/skills/<skill-name>/SKILL.md、~/.agents/skills/<skill-name>/SKILL.md

這三個專案層路徑正是 Agent Skills 能與 Claude Code（.claude/）與其他遵循開放規範的 Agent（.agents/）共用同一份 Skill 資產的基礎；企業建置跨工具 Skill 庫時，應優先挑選 .agents/skills/ 作為中立位置（建議架構，見第 33 章）。

支援 Agent Skills 的 Surface（官方已實作）：Copilot cloud agent、Copilot code review、Copilot CLI、GitHub Copilot app，以及 VS Code 與 JetBrains IDEs 的 agent mode（JetBrains 為 Preview）。依官方 Customization Cheat Sheet 的支援矩陣，Agent Skills 在 VS Code、Visual Studio、GitHub.com、Copilot CLI 均為完整支援，JetBrains 為 Preview，Eclipse 與 Xcode 尚未支援。

用 GitHub CLI 管理 Skill（官方已實作）：docs.github.com 現已明載可使用 GitHub CLI 的 gh skill 指令群來搜尋、安裝、更新、發佈 Agent Skills，使得 Skill 的分發可以像套件一樣被腳本化、納入 CI。企業可將其寫進開發環境初始化腳本，避免工程師手動下載 zip 後解壓造成版本不一致。

⚠️ 命名差異提醒：本手冊第 8.2 節引用 awesome-copilot docs/README.skills.md 時提到的是 gh skills install（複數），而 docs.github.com 目前描述的是 gh skill（單數）。兩者來源不同且官方未就別名作出說明，企業導入前請先以 gh skill --help 實際確認您所安裝的 GitHub CLI 版本支援哪一種寫法，不要直接寫死在自動化腳本中（官方目前沒有找到足夠資料確認此差異）。

8.4 自動發現與三段式漸進載入

Skill 的載入是三段式漸進（Progressive Disclosure）機制，這是理解 Skill 為什麼比 Instructions「更省 token」的關鍵：

graph LR
    A["1. 掃描階段<br/>只讀 frontmatter 的 name/description"] --> B{"是否與當前任務相關？"}
    B -->|"是"| C["2. 載入階段<br/>讀取 SKILL.md 本文"]
    B -->|"否"| D["不載入，節省 context"]
    C --> E{"本文是否引用附屬檔案？"}
    E -->|"是"| F["3. 延伸載入階段<br/>才讀取 scripts/references/templates"]
    E -->|"否"| G["僅使用 SKILL.md 本文內容"]

也就是說：即使你的專案裝了 50 個 Skill，Copilot 平常只會掃描這 50 個 name／description（成本很低），只有在判斷「這個任務跟某個 Skill 相關」時才會真正載入該 Skill 的完整內容與附屬檔案。

8.5 觸發方式

• 自動觸發：Copilot 依任務內容與 Skill 的 description 相關性自動判斷載入（多數 Client）。
• Slash Command 明確呼叫：在 VS Code Chat 輸入 / 即可看到可用的 Skill 與 Prompt files，並可在命令後附加語絡（例如 /webapp-testing for the login page）。
• 兩個開關的四種組合（官方已實作）：

⚠️ 企業治理建議：凡是會修改程式碼、執行部署或對外連線的 Skill，一律設 disable-model-invocation: true，強制變成「人類只能主動呼叫」，這是成本最低、效果最直接的一道防線（對應第 21.2 節 Risk Level 的 HIGH／CRITICAL 層級）。

• 建立方式（官方已實作，2026-08-28 新增查證）：除了手寫，可在 VS Code Chat 輸入 /create-skill 讓 AI 依描述產生 SKILL.md 鷹架；也可在一段多輪對話結束後要求「把剛剛除錯的流程寫成 Skill」，把實際經驗沉漱成可重複使用的資產；或在 Agent Customizations 編輯器選 Generate Skill。輸入 /skills 可快速開啟 Configure Skills 選單。

8.6 Skill Lifecycle、Versioning、Testing、Security

Checklist：

• Skill 已在 Draft 階段於個人 Scope 測試過，確認觸發判斷準確
• Skill 若涉及版本管理，已建立 CHANGELOG.md
• 已跑過 npm run skill:validate（若貢獻回公開/企業共用 Repository）
• allowed-tools 已依最小權限原則設定，且所有 scripts/ 內容已經過 Code Review

8.7 Skill 1：Web Application Development

⚠️ 建議架構——本手冊原創範例，用以示範官方驗證過的 SKILL.md 格式如何應用於企業 Web 開發情境。

.github/skills/web-application-development/SKILL.md：

---
name: web-application-development
description: >-
  Guide for implementing full-stack features in this repository's Vue 3 +
  TypeScript + Tailwind CSS + PrimeVue frontend and Java 25 + Spring Boot 4.x
  REST API backend. Use this when asked to implement a new feature, endpoint,
  or UI component end-to-end.
allowed-tools: read, edit, search, terminal
---

# Web Application Development Skill

## 適用範圍
前端：Vue 3（Composition API）、TypeScript、Tailwind CSS、PrimeVue、Pinia、i18n
後端：Java 25、Spring Boot 4.x、REST API、Clean Architecture、Maven

## 實作步驟

1. **確認需求邊界**：先確認這是新增 API、修改既有 API，還是純前端功能。
2. **後端（若需要）**：
   - Controller 層只做參數驗證與轉發，不寫商業邏輯
   - Service 層實作商業邏輯，回傳 DTO 而非 Entity
   - Repository 層使用 Spring Data JPA，禁止手寫 SQL 除非有明確效能理由
   - 所有新 Endpoint 須補上對應的 JUnit 5 測試
3. **前端（若需要）**：
   - 使用 `<script setup lang="ts">`，狀態管理用 Pinia
   - API 呼叫統一透過 `src/api/` 底下的服務層，禁止在元件內直接呼叫 `fetch`/`axios`
   - UI 一律使用 PrimeVue 元件 + Tailwind utility class
   - 補上對應的 Vitest 單元測試
4. **整合驗證**：確認前後端 API 契約一致（可參考 `references/api-contract-checklist.md`）
5. **產出摘要**：列出新增/修改的檔案清單，並說明是否需要資料庫 migration

## 參考資料
- `references/api-contract-checklist.md`：前後端 API 契約檢查清單
- `templates/controller-template.java`：Controller 範本
- `templates/vue-component-template.vue`：Vue 元件範本

8.8 Skill 2：Reverse Engineering

⚠️ 建議架構——完整案例見第 16 章。

.github/skills/reverse-engineering/SKILL.md：

---
name: reverse-engineering
description: >-
  Systematic legacy system analysis workflow for Java/JSP/Servlet/SQL
  codebases. Use this when asked to analyze, document, or assess an
  undocumented legacy application before modernization.
allowed-tools: read, search
---

# Reverse Engineering Skill

## 分析步驟（依序執行，不可跳步）

1. Repository Discovery：掃描目錄結構、建置工具、技術堆疊
2. Code Inventory：列出模組、類別數量、程式碼行數統計
3. Dependency Analysis：分析 Maven/Gradle 依賴、內部模組耦合關係
4. Architecture Discovery：還原分層架構（或指出「無明確分層」）
5. Database Analysis：分析 Schema、Stored Procedure、資料表關聯
6. API Analysis：列出所有對外 API／Servlet／JSP 進入點
7. Security Analysis：檢查已知風險模式（SQL Injection、硬編碼密碼等）
8. Batch Analysis：分析排程/批次作業邏輯
9. Business Rule Extraction：從程式碼萃取商業規則，以人類可讀方式記錄
10. Architecture Diagram：產出 Mermaid 架構圖
11. Technical Debt Analysis：列出技術債與風險等級
12. Modernization Recommendation：提出現代化建議路線圖

## 產出格式

每次分析須產出以下文件（存放於 `docs/reverse-engineering/`）：
- `reverse-engineering-report.md`
- `architecture-document.md`
- `dependency-map.md`
- `api-catalog.md`
- `database-catalog.md`
- `business-rule-catalog.md`
- `risk-register.md`
- `modernization-roadmap.md`

## 重要限制
- 本 Skill **只分析、不修改任何原始碼**
- 若無法確認某個行為的商業意圖，必須在報告中明確標示「需人工確認」，不可臆測

8.9 Skill 3：Framework Migration

⚠️ 建議架構——完整案例見第 17 章。

.github/skills/framework-migration/SKILL.md：

---
name: framework-migration
description: >-
  Guided migration analysis workflow for upgrading major framework versions
  (e.g. Spring Boot 3.x to 4.x). Use this when asked to assess or plan a
  framework/dependency major-version upgrade.
allowed-tools: read, search, terminal
---

# Framework Migration Skill

## 分析流程

```text
Current System Assessment
        ↓
Dependency Analysis        ← 列出所有直接/間接依賴的版本相容性
        ↓
Breaking Change Detection  ← 對照官方 Migration Guide 逐條核對
        ↓
Configuration Analysis     ← application.yml/properties 變更點
        ↓
Source Code Analysis       ← API 呼叫點、已棄用 API 使用情況
        ↓
Security Analysis          ← 新版本的安全性變更（如 Jakarta namespace）
        ↓
Test Analysis               ← 既有測試涵蓋率是否足以驗證升級
        ↓
Migration Plan              ← 產出分階段升級計畫，附風險評估
```

## 產出格式

每次分析須產出以下文件（存放於 `docs/framework-migration/`），格式比照第 8.8 節 Reverse Engineering Skill 的產出慣例：
- `migration-assessment.md`：現況評估總結（目前版本、目標版本、預估工作量）
- `dependency-compatibility-matrix.md`：所有直接/間接依賴的版本相容性矩陣
- `breaking-changes-catalog.md`：逐條對照官方 Migration Guide 的 Breaking Change 清單，含影響範圍與修復方式
- `configuration-changes.md`：設定檔（`application.yml`/`.properties`）需要調整的項目
- `deprecated-api-usage.md`：程式碼中已呼叫、即將被移除的 API 清單
- `test-coverage-gap-analysis.md`：既有測試涵蓋率是否足以驗證升級後行為不變
- `migration-plan.md`：分階段升級計畫，每階段附風險評估與回滾方案

## 重要限制
- 產出 Migration Plan 後，**須經人工核准才可進入自動化變更階段**
- 不可一次變更全部模組，必須分階段、每階段可獨立驗證與回滾

8.10 Skill 4：Security Review

⚠️ 建議架構——涵蓋 OWASP Top 10 相關檢查面向。

.github/skills/security-review/SKILL.md：

---
name: security-review
description: >-
  Security review checklist covering OWASP Top 10 risks (SQL injection, XSS,
  CSRF, auth/authz issues, secret leakage, dependency vulnerabilities). Use
  this when asked to perform a security review of code changes.
allowed-tools: read, search
---

# Security Review Skill

## 檢查面向

| 面向 | 檢查重點 |
|---|---|
| SQL Injection | 是否使用參數化查詢／PreparedStatement，禁止字串拼接 SQL |
| XSS | 前端輸出是否經過適當跳脫；Vue 是否有不當使用 `v-html` |
| CSRF | 狀態變更 API 是否有 CSRF Token 或等效防護 |
| Authentication | 密碼儲存是否使用適當雜湊演算法，Session 管理是否安全 |
| Authorization | 是否每個 Endpoint 都有明確的權限檢查，避免 IDOR |
| Secret leakage | 程式碼／設定檔／Log 是否含硬編碼密碼、API Key |
| Dependency vulnerabilities | 依賴版本是否有已知 CVE |
| Secure configuration | 預設設定是否安全（例如生產環境是否關閉 debug/actuator 端點） |

## 輸出格式
依風險等級（Critical／High／Medium／Low）分類列出所有發現，每項須包含：檔案位置、風險說明、修復建議。**不可**只給「看起來有風險」的模糊描述，必須具體指出程式碼位置與修復方式。

## 重要限制
本 Skill 僅提出審查意見，**不可自行修改程式碼**，修復須由開發者確認後另行提交。

8.11 Skill 與客製化檔案的品質評測：Chat Customizations Evaluations 與 Waza

企業導入 Skill 一段時間後，最大的隱形成本不是「寫不出來」，而是**「寫出來的規則彼此矛盾、語意模糊、認知負荷過重，但沒有人發現」**。2026-08-28 複查 VS Code 官方文件發現，官方已針對這個問題推出專用工具（Preview）。

Chat Customizations Evaluations 擴充套件（Preview）

官方列出的偵測面向（可直接抄成企業的客製化資源 Code Review 檢查表）：

Waza 評測框架

針對 Skill，該擴充套件另整合了微軟開源的評測框架 Waza（github.com/microsoft/waza），提供以下命令：

⚠️ 企業實務建議（建議架構）：把「Skill／Agent 檔案必須通過 Chat Customizations Evaluations 零診斷」列為第 31 章 Quality Gate 的一道關卡，並在 CI 上以第 2.8 節提到的 schema 驗證作為第二道防線。兩者分工是：schema 驗證管格式正確性，Evaluations 管語意品質，缺一不可。需注意此擴充套件目前為 Preview，企業標準文件應註明版本與可能變動。

Scenario

某團隊把 Reverse Engineering Skill 的 description 寫得太模糊（例如只寫「分析程式碼」），結果 Copilot 在許多不相關的任務中都誤判為相關而載入此 Skill，浪費 context 且干擾正常開發建議。修正：把 description 寫得更精確、包含「Use this when…」的明確觸發情境描述（如 8.8 範例），大幅降低誤觸發率。

AI Prompt 範例

角色：你是資深 Software Architect，任務是設計一個新的 Agent Skill。

情境：我們需要一個「API Design Review」Skill，用來檢查新增/修改的
REST API 是否符合企業 OpenAPI 規範與版本管理策略。

請依照 GitHub Copilot 官方 SKILL.md 格式（name/description/license/
allowed-tools frontmatter），產出：
1. 完整的 SKILL.md 內容
2. description 欄位需精確描述觸發情境，避免誤觸發
3. 列出建議的 allowed-tools 範圍（採最小權限原則）

本章 Checklist

• 已理解 Agent Skills 是官方 GA 功能，且與 Claude Code .claude/skills 互通
• 每個 Skill 的 description 都寫明確的觸發情境，避免誤觸發
• 敏感／破壞性 Skill 已考慮設定 disable-model-invocation: true
• 已評估導入 Chat Customizations Evaluations（Preview）作為 Skill 語意品質檢查（8.11）
• 已建立至少一個企業版 Skill 並在沙盒環境驗證載入行為

9. Custom Agents 深入教學與企業 Agent Team

9.1 從 .chatmode.md 到 .agent.md（重要遷移段落）

VS Code 官方原文明確說明這是「更名」而非「新功能」：

“Custom agents were previously known as custom chat modes. The functionality remains the same, but the terminology has been updated to better reflect their purpose in customizing AI behavior for specific tasks.”

遷移指引原文：

“If you have existing .chatmode.md files, rename them to .agent.md to convert them to the new custom agent format and place them in the appropriate location to continue using them.”

⚠️ 本手冊全文一律使用 Custom Agents／.agent.md，不使用已過時的「custom chat mode／.chatmode.md」說法。若團隊現有專案還留著 .chatmode.md 檔案，直接改副檔名即可沿用，不需要重寫內容。

9.2 .agent.md 完整 Frontmatter 欄位

本文（body）的寫法態別：在 Agent 本文中可用 #tool:<tool-name> 直接引用工具（例如 #tool:web/fetch），也可用 Markdown 連結引用專案內的規範檔，讓 Agent 在需要時才去讀取——這是控制 Agent 本文長度、避免 context 爆量的標準做法。

9.3 存放位置與組織層共享

⚠️ Agent Host 的例外（極容易踩坑）：Agent Host 情境下的個人層 Agent 是從 ~/.copilot/agents 讀取，不是 VS Code 自己的 profile 資料夾。若發現「VS Code 設定里看得到、但 Agent Host 跑起來沒有這個 Agent」，八成是這個原因。

工具：在 VS Code Chat 面板上按右鍵 → Diagnostics，可一次列出目前實際載入的所有 Agents、Prompts、Instructions、Skills 及其錯誤，是排查「為什麼沒生效」最快的手段（規則層除錯見第 27 章）。

9.3.1 Agent 的建立與管理入口（官方已實作）

9.4 企業 Agent Team Catalog（12 個 Agent）

⚠️ 建議架構——以下 12 個 Agent 為本手冊針對企業 Web Application／Legacy Modernization 情境原創設計，非 awesome-copilot 官方收錄項目。

9.5 完整 .agent.md 範例

.github/agents/system-architect.agent.md：

---
name: system-architect
description: >-
  Senior software architect for reviewing and designing system architecture.
  Use this when asked to design new architecture, review architectural
  decisions, or evaluate technical choices for this Java/Spring Boot +
  Vue 3 web application.
tools: read, search
agents: [frontend-architect, backend-architect]
model: [claude-sonnet-5, gpt-5]
target: github-copilot
---

# System Architect Agent

你是資深軟體架構師，負責本專案的整體架構決策。

## 職責
- 審查新功能是否符合 Clean Architecture 分層原則
- 評估技術選型（新增依賴、框架升級）的長期維護成本
- 在架構決策有分歧時，提出明確建議並說明取捨

## 限制
- 你**只能**閱讀與分析程式碼，**不可直接修改**任何檔案
- 涉及前端細節，交由 `frontend-architect` 處理；涉及後端細節，交由 `backend-architect` 處理
- 任何架構決策都必須附上理由，不可只給結論

.github/agents/security-agent.agent.md：

---
name: security-agent
description: >-
  Security reviewer focused on OWASP Top 10 risks. Use this when asked to
  review code changes for security vulnerabilities before merge.
tools: read, search
disable-model-invocation: false
target: github-copilot
---

# Security Agent

你是資深資安工程師，依照 `.github/skills/security-review/SKILL.md` 定義的檢查面向，
審查程式碼變更。

## 職責
- 檢查 SQL Injection、XSS、CSRF、Authentication/Authorization、Secret Leakage、
  依賴漏洞等風險
- 依 Critical／High／Medium／Low 分類回報，每項須含具體檔案位置與修復建議

## 限制
- **絕對不可修改程式碼**，只能提出審查意見
- 發現 Critical 等級問題時，必須在回應開頭明確標示，不可埋在報告中間

.github/agents/project-coordinator.agent.md：

---
name: project-coordinator
description: >-
  Orchestrates multi-agent workflows across the enterprise agent team. Use
  this as the entry point for complex tasks spanning architecture,
  implementation, testing, security, and deployment.
tools: read, search
agents: "*"
handoffs: [system-architect, reverse-engineering-agent, migration-agent, security-agent, code-review-agent, devops-agent]
target: github-copilot
---

# Project Coordinator Agent

你是專案協調者，負責理解使用者的高階需求，並將任務拆解、分派給對應的專業 Agent。

## 職責
- 判斷任務屬於架構設計、逆向工程、Framework Migration、安全審查、部署等哪一類
- 依第 10 章協作架構圖，決定 Agent 執行順序與 Handoff 時機
- 追蹤各 Agent 的產出是否完整，若不完整需要求補件才能進入下一階段

## 限制
- 不直接執行技術實作，只負責協調與品質關卡把關
- 任何跨 Agent 交接前，必須確認上一階段的產出已符合驗收標準

9.6 Agent Customizations 編輯器與使用者客製化遷移

2026-08-28 複查 VS Code 官方文件時，發現官方已提供一個集中管理所有客製化資源的入口，這對企業推廣「人人都會寫 Agent」大幅降低門檻。

Agent Customizations 編輯器（Preview）

⚠️ 企業導入注意（建議架構）：「用 AI 產生客製化資源」對推廣很有幫助，但也代表未經審查的資源會大量出現在個人 User scope。企業標準應明訂：User scope 僅供個人實驗，任何要影響他人的資源一律必須進入 Workspace scope 並走 CODEOWNERS 審查（第 20.3 節），這條界線必須寫死。

使用者層客製化的實際存放位置

這是第 6.3 節「Agent Host 例外」的完整版本，也是企業最容易踩到的一個坑：

VS Code 官方明載，Agent Host 從與 harness 無關的資料夾讀取使用者層客製化，而不是 VS Code profile 的 user data。因此「我在 VS Code 設定裡建了個人 Agent，為什麼 Copilot harness 讀不到？」是預期行為，不是 Bug。

使用者客製化遷移（Experimental）

⚠️ 企業實務結論（建議架構）：由於遷移後不再隨 Settings Sync 漫遊，企業不應把重要的客製化資源留在使用者層。正確做法是把所有具團隊價值的資源上推到 Repository 或 Plugin（第 11-12 章），使用者層只保留個人習慣類的設定。這也順帶解決了「離職交接時個人 Agent 一起消失」的問題。

疑難排解入口

當客製化資源沒有如預期生效時，官方提供的第一手診斷工具是：

• Command Palette → Developer: Open Agent Debug Panel
• 或 Chat 檢視右上「…」選單 → Show Agent Debug Logs

詳細診斷流程見第 27.2 節。

9.7 內建 Agent（Built-in Agents）與 Subagent 事件

本節為第四版新增。前三版只教「如何自建 Agent」，卻沒有讓讀者知道 Copilot 本身已經附帶一組內建 Agent。企業在規劃自建 Agent Team（第 9.4、10 章）之前，應先盤點內建 Agent 已覆蓋的能力，避免重複造輪。

9.7.1 內建 Agent 清單（官方已實作，2026-08-31 查證）

官方 Hooks Reference 在說明 subagentStart／subagentStop 事件時，逐一列出了以下內建 Agent：

使用者自訂的 Custom Agent（第 9.2、9.5 節）一律會發出 subagentStart／subagentStop 事件。

⚠️ 這個例外有實際治理影響（建議架構）：若你依第 13.5 節的做法用 subagentStop 做「Subagent 輸出遮蔽」，請務必知悉：經由 general-purpose 跑出來的內容不會經過這道閘門。如果遮蔽是合規必要措施，就不能只靠 subagentStop，必須同時在 postToolUse（針對 task 工具）或更下層的 permissions.deny 上設防線。

9.7.2 企業如何定位內建 Agent（建議架構）

實務建議的導入順序：先讓 Pilot 團隊用內建 Agent 跑一段時間，把「內建 Agent 做不好的地方」記錄下來，再以這份清單作為自建 Agent 的需求來源。這比一開始就直接拉出 12 個 Agent（第 9.4 節）實際很多、且能避免建了一堆沒人用的 Agent。

Scenario

某團隊一開始讓 security-agent 的 tools 欄位誤設為 read, edit, search, terminal（沿用了其他 Agent 的設定範本），結果該 Agent 在某次審查中「順手」修改了程式碼，導致審查紀錄與實際變更混在一起，事後難以追溯是誰的決策。教訓：每個 Agent 的 tools 授權都必須依其職責量身設定，審查型 Agent 應嚴格限制為唯讀（read, search），不可圖方便沿用其他 Agent 的設定。

AI Prompt 範例

角色：你是資深 AI Agent 架構師。

任務：請幫我們的企業 Agent Team 新增一個 database-agent 的完整 .agent.md 檔案，
用於 PostgreSQL / Oracle / DB2 混合資料庫環境的 Schema 設計與 Migration 腳本撰寫。

要求：
1. 依 9.2 節的完整 frontmatter 欄位表撰寫
2. tools 欄位需符合最小權限原則（此 Agent 需要能讀寫 migration 腳本檔案）
3. 明確寫出「不可修改既有 migration 檔案」的限制
4. handoff 對象應設為 backend-architect

本章 Checklist

• 團隊已知悉 .chatmode.md 已更名為 .agent.md，並完成既有檔案遷移
• 每個企業 Agent 的 tools 欄位都依職責設定最小權限
• 審查型 Agent（security/code-review）已確認為唯讀，不可修改程式碼
• 已建立至少 3 個核心 Agent 並驗證 Handoff 機制運作正常
• 已明訂「User scope 僅供個人實驗、影響他人者一律進 Workspace scope 並走審查」的界線（9.6）
• 團隊已知悉使用者層客製化遷移後不隨 Settings Sync 漫遊，重要資源應上推至 Repository／Plugin（9.6）
• 已先盤點七個內建 Agent 的能力，確認自建 Agent 不是重複造輪（9.7）
• 已知悉 general-purpose 不發出 subagentStart／subagentStop，並已評估其對稽核與遮蔽機制的影響（9.7.1）

10. Agent Team 協作架構

⚠️ 本章協作架構為建議架構，示範如何組織第 9 章的 12 個 Agent 分工協作；awesome-copilot 官方並未定義固定的多 Agent 協作拓樸。

10.1 協作拓樸圖

graph TB
    PC["project-coordinator"]

    PC --> SA["system-architect"]
    PC --> REA["reverse-engineering-agent"]
    PC --> SEC["security-agent"]

    SA --> FA["frontend-architect"]
    SA --> BA["backend-architect"]

    FA --> TA["test-agent"]
    BA --> DBA["database-agent"]
    BA --> TA

    REA --> MA["migration-agent"]
    MA --> TA
    MA --> SEC

    TA --> CRA["code-review-agent"]
    SEC --> CRA
    CRA --> DA["devops-agent"]
    DA --> PC

    DOC["documentation-agent"] -.->|"任一階段完成後皆可觸發"| PC

10.2 Agent Delegation 與 Handoff

• Delegation（指派）：project-coordinator 依任務類型，透過 .agent.md 的 handoffs 欄位將任務指派給對應 Agent。
• Handoff（交接）：一個 Agent 完成階段性產出後，透過 handoffs 欄位定義的目標，將上下文與產出交給下一個 Agent，而不是讓使用者手動複製貼上。

Handoff 訊息具體範例（建議架構）：system-architect 完成架構設計後交接給 backend-architect 時，附帶的交接內容建議包含以下結構，而不是只丟一句「請開始實作」：

## Handoff：system-architect → backend-architect

### 已完成
- 架構設計文件：`docs/architecture/order-module-design.md`
- 分層決策：Controller → Service → Repository → Entity（Clean Architecture）
- API 契約草案：`docs/architecture/order-api-contract.yaml`（OpenAPI 3.1）

### 待辦事項（交由 backend-architect 執行）
1. 依 API 契約草案實作 `OrderController`、`OrderService`、`OrderRepository`
2. `OrderService` 需處理「庫存不足」與「付款逾時」兩個邊界情境（詳見設計文件第 3.2 節）
3. 完成後請交接給 `test-agent` 補齊 JUnit 5 測試

### 限制與注意事項
- 資料庫 migration 檔案已由 DBA 團隊預先建立（`V12__create_order_tables.sql`），禁止修改既有 migration
- 本次不需處理前端，前端交接另由 `frontend-architect` 獨立進行

這種「已完成／待辦事項／限制與注意事項」三段式結構，讓下一個 Agent 不需要重新理解整個任務背景，也讓人類審查者能一眼看出交接是否完整。

10.3 Context Management 與 Shared Artifacts

Shared Artifact 具體格式範例（建議架構）：以 docs/architecture/order-module-context.json 為例，作為多個 Agent 共同讀寫的上下文檔案：

{
  "task": "order-module-implementation",
  "stage": "backend-implementation",
  "artifacts": {
    "design": "docs/architecture/order-module-design.md",
    "apiContract": "docs/architecture/order-api-contract.yaml"
  },
  "completedBy": ["system-architect"],
  "pendingFor": ["backend-architect", "test-agent"],
  "constraints": [
    "不可修改既有資料庫 migration 檔案",
    "本階段不處理前端"
  ],
  "lastUpdated": "2026-08-20T10:30:00+08:00"
}

每個 Agent 在完成自己的階段後，更新 completedBy／pendingFor 欄位並附上新產出的檔案路徑，讓 project-coordinator 與人類審查者都能透過這份檔案掌握整個任務的即時進度，不需要回頭爬梳對話紀錄。

10.4 Review Gates 與 Human Approval

依第 31 章 Quality Gate 定義，關鍵節點須有人工核准才能繼續：

graph LR
    A["migration-agent 產出 Migration Plan"] --> H1{"人工核准？"}
    H1 -->|"否，退回修改"| A
    H1 -->|"是"| B["migration-agent 執行變更"]
    B --> C["test-agent 驗證"]
    C --> D["security-agent 審查"]
    D --> H2{"發現 Critical 風險？"}
    H2 -->|"是"| A
    H2 -->|"否"| E["code-review-agent 審查"]
    E --> H3{"人工核准合併？"}
    H3 -->|"否"| E
    H3 -->|"是"| F["devops-agent 部署"]

10.5 Failure Recovery

Scenario

某企業導入 Agent Team 初期，讓 migration-agent 產出 Migration Plan 後直接自動執行變更，未設任何人工關卡，結果一次升級誤動到不該變更的模組。加入 10.4 的 Review Gate（Migration Plan 必須人工核准才能執行）後，同類事故降為零。

AI Prompt 範例

角色：你是 project-coordinator Agent。

任務：使用者要求「重構訂單模組，改用新的付款閘道 API」。

請依 10.1 協作拓樸圖，規劃這個任務需要依序或並行交給哪些 Agent
（system-architect／backend-architect／test-agent／security-agent／
code-review-agent／devops-agent 等），並依 10.2 的三段式結構
（已完成／待辦事項／限制與注意事項）為第一個 Handoff
（交給 system-architect）草擬交接訊息。

限制：
- 明確標出哪些節點需要依 10.4 設置人工 Review Gate
- 若任務範圍不清楚（例如「新的付款閘道」規格未定），
  應先回報給使用者確認，不可自行假設規格

本章 Checklist

• 已依 10.1 拓樸圖確認團隊 Agent 之間的 Handoff 路徑
• 關鍵節點（Migration Plan 執行前、合併前）已設置人工 Review Gate
• 已建立 Shared Artifacts 存放慣例，避免 Agent 間僅依賴對話記憶傳遞上下文

11. Plugins 深入教學與企業 Plugin 範例

11.1 Plugin 概念（Agent Plugins 1.0）

GitHub Copilot Plugins 正式名稱為 Agent Plugins 1.0，於 2026-08-12 GA，是由 AWS、Anysphere、Microsoft、OpenAI、Vercel、Google 等共同支持的跨廠商開放標準（官方已實作）。Plugin 透過 plugin.json manifest 打包本機資源，可包含：Custom Agents、Skills、Hooks、MCP Server 設定、LSP Server 設定、Commands、Rules、Canvas Extensions。

⚠️ Plugins 與已日落的 Copilot Extensions（GitHub App 機制）是完全不同的兩個東西，詳見 11.2 對照表，切勿混淆。

11.2 Plugins vs Copilot Extensions（絕不可混寫）

日落時間軸（GitHub Changelog 原文佐證）：2025-09-24 停止建立新 Extension → 2025-11-03～07 brownout 測試 → 2025-11-10 23:59 PST 完全關閉。重要例外（Changelog 原文）：“This does NOT affect: Client-side VS Code Copilot Extensions (remain fully supported)."——VS Code 端的 chat participant extension（@mention）不受影響，這是與「Copilot Extensions（GitHub App）」不同的另一個機制，命名容易混淆，撰寫企業文件時務必註明清楚。

11.3 plugin.json Schema 與目錄結構

目錄結構

enterprise-web-plugin/
├── plugin.json              # manifest，$schema 指向 Agent Plugins 1.0 schema（唯一必要檔案）
├── agents/                  # Custom Agents，安裝後會出現在使用者的 Agent 選單
├── skills/                  # Agent Skills（每個 Skill 一個資料夾，內含 SKILL.md）
├── hooks/                   # Hooks（*.json），安裝後併入 Agent 的生命週期事件
├── mcp.json                 # MCP Server 設定，安裝後自動註冊給 Agent 使用
└── README.md                # 說明文件，awesome-copilot 貢獻規範要求每個 Plugin 都要有

依 Agent Plugins 1.0 開放規範（agent-plugins.org），所有檔案路徑須以 ./ 開頭且保持在 Plugin 根目錄內，不可引用外部路徑。

欄位分成兩區：頂層 metadata + extensions 內容組合

（2026-08-28 複查更新，Source-confirmed） 這是本手冊初版最容易寫錯的一段。awesome-copilot 現行所有 Plugin 的 plugin.json 並非在頂層直接寫 agents／skills／hooks，而是採宣告式的 extensions 命名空間——把「這個 Plugin 帶了哪些內容」放進 extensions.com.github.awesome-copilot 底下：

⚠️ 三個實測得到、文件不易看出的細節（2026-08-28 以 plugins/java-development/plugin.json、plugins/software-engineering-team/plugin.json、plugins/devops-oncall/plugin.json 三份真實檔案交叉核對）：

1. Plugin 內的 Agent 檔名是 *.md，不是 *.agent.md——因為路徑已明確寫在 agents 陣列中，不需靠副檔名被自動探索。獨立放在 .github/agents/ 的 Agent 才需要 .agent.md。
2. Skill 路徑指向資料夾且以 / 結尾，與 Agent 指向單一檔案不同。
3. author 是物件不是字串，寫成 "author": "Platform Team" 會無法通過 npm run plugin:validate。

⚠️ 為什麼要用 extensions 命名空間？ 因為 Agent Plugins 1.0 是跨廠商開放標準，同一份 Plugin 可能被不同 Client（GitHub Copilot、其他 Agent 平台）讀取。把各家專屬的內容組合放進以反向網域命名的 namespace（com.github.awesome-copilot）底下，其他 Client 遇到不認得的 namespace 可以直接忽略，不會解析失敗。這與 AndroidManifest.xml、Info.plist 的自訂欄位設計思維一致。

MCP 在 Plugin 中的正確宣告方式（第四版全面改寫）

第三版此處只寫「官方文件不一致、請自行實測」。2026-08-31 複查發現：awesome-copilot 側已把規則寫死到明文禁止的程度**，不再是「兩種寫法都行」。本小節改寫為明確規則。

四項官方明文規定（Source-confirmed，依 awesome-copilot AGENTS.md）：

重點釐清：mcp.json 是「跟在 plugin.json 旁邊、原樣出貨（shipped as-is）」的獨立檔，而不是被 plugin.json 引用的資源。這也是為什麼它不出現在 extensions 區塊中——它不屬於 Plugin 的內容組合，而是依 Agent Plugins spec 直接定義的標準檔。

⚠️ 兩邊文件仍不一致（企業必須知道）：docs.github.com 的 about-plugins 說明仍描述 .mcp.json（另有 lsp.json 用於 Language Server），而 awesome-copilot 側已明文禁用該檔名。不一致仍存在，但兩邊的說法都變了。 企業的實務建議（建議架構）：

• 若 Plugin 要投稿回 awesome-copilot 或遵循 Agent Plugins spec，一律用根目錄 mcp.json 並帶 $schema
• 若是企業內部自用且目標 Client 只有 Copilot，仍應先以一個最小 Plugin 實測（copilot mcp list 或 VS Code MCP 面板）確認註冊成功後再定案
• 不要兩個檔名都放——這會讓日後排查「到底哪份生效」變得極難

Plugin 實體化（Materialization）與 Namespace 剥除

本小節為第四版新增。這是「為什麼我寫的 plugin.json 跟安裝後看到的不一樣」背後的機制。

awesome-copilot 的來源分支並不等於發佈出去的 Marketplace 內容；中間隔著一道**實體化（materialization）**步驟（Source-confirmed）：

這對企業的三個實際含意（建議架構）：

1. 不要把 com.github.awesome-copilot 當成執行期存在的東西。它只是來源庫的編輯期命名空間，安裝到使用者機器上時已經不在了。若你寫內部文件時說「Plugin 的資源都在 com.github.awesome-copilot 下」，新人拿去實機找會找不到。
2. 自建企業 Plugin 時，namespace 要換成自己的（例如 com.acme.platform），且要意識到「自建 Plugin 不會經過 awesome-copilot 的實體化流程」——你的 namespace 不會被自動剥除。如果目標 Client 只認得標準位置，就必須自己建置實體化步驟（或直接以標準目錄結構發佈）。
3. 診斷問題時要看「實體化後」的內容。直接 clone 來源分支比對檔案會得到錯誤結論；應該比對的是安裝後实際落地的目錄。

11.4 完整企業 Plugin 範例：Enterprise Web Development Plugin

plugin.json：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "enterprise-web-plugin",
  "description": "Enterprise Web Application Development toolkit: agents, skills, and hooks for Java 25 + Spring Boot 4.x + Vue 3 projects.",
  "version": "1.0.0",
  "author": {
    "name": "Platform Engineering Team"
  },
  "repository": "https://github.com/acme-corp/enterprise-plugins",
  "license": "UNLICENSED",
  "keywords": ["java", "spring-boot", "vue", "enterprise", "web-development"],
  "extensions": {
    "com.github.awesome-copilot": {
      "agents": [
        "./agents/system-architect.md",
        "./agents/frontend-architect.md",
        "./agents/backend-architect.md",
        "./agents/security-agent.md",
        "./agents/code-review-agent.md"
      ],
      "skills": [
        "./skills/web-application-development/",
        "./skills/security-review/"
      ],
      "hooks": [
        "./hooks/pre-commit-quality-gate.json"
      ]
    }
  }
}

⚠️ 上述結構已對照 awesome-copilot 三份真實 plugin.json 逐欄核實（Source-confirmed，2026-08-28）。若企業自建 Plugin 供其他 Client 使用，com.github.awesome-copilot 這個 namespace 可能需替換為目標 Client 對應的命名空間；撰寫前務必重新核對當下最新版開放規範，因為規範仍在演進。

開放規範 vs awesome-copilot 貢獻規則的差異（容易混淆處）：Agent Plugins 1.0 開放規範本身只強制要求 $schema 與 name 兩個欄位，description／version／author 等皆為選填；但 awesome-copilot 自己的 CONTRIBUTING.md 額外要求貢獻者必填 name／description／version。這代表「符合開放規範」與「符合 awesome-copilot 收錄門檻」是兩件不同的事——企業若只是要在內部環境打包 Plugin 自用，可以只填規範要求的最低欄位；但若要投稿回 awesome-copilot，則需依其 CONTRIBUTING.md 補齊額外必要欄位。

11.5 External Plugins：plugins/external.json 與審查流程

除了直接收錄在 plugins/<name>/ 目錄內的「內建 Plugin」之外，awesome-copilot 另有一條**外部 Plugin（External Plugins）**路徑：Plugin 的原始碼留在貢獻者自己的公開 GitHub Repository，awesome-copilot 只在 plugins/external.json 中登錄一筆指標，讓它能被 Marketplace 檢索到（Source-confirmed，2026-08-28 依 CONTRIBUTING.md 與 eng/external-plugin-validation.mjs 查證）。

內建 Plugin 與 External Plugin 的差異

⚠️ 這是企業最容易忽略的供應鏈破口：External Plugin 一旦通過審查，其內容仍由外部維護者掌控。這代表「今天審查過的 Plugin」與「明天實際安裝到開發者機器上的 Plugin」不必然是同一份內容，風險模式與 npm 的 latest tag 完全相同。

登錄格式（第四版修正：換上真實規格）

**第三版此處使用的是自行推測的「示意」結構（source.type／source.repository），欄位名與官方不符。2026-08-31 複查已以 plugins/external.json 真實內容取代。

awesome-copilot 明文採用 Claude Code plugin marketplace spec：「Approved submissions are converted into plugins/external.json entries following the Claude Code plugin marketplace spec」（Source-confirmed）。真實條目如下：

{
  "name": "agent-council",
  "description": "A runtime-portable 5-agent quality gate...",
  "version": "0.1.3",
  "author": {
    "name": "Parth Sangani",
    "url": "https://github.com/Avyayalaya"
  },
  "repository": "https://github.com/Avyayalaya/agent-council",
  "license": "MIT",
  "source": {
    "source": "github",
    "repo": "Avyayalaya/agent-council",
    "ref": "v0.1.3"
  }
}

source 物件的欄位：

⚠️ 企業最重要的一條結論（建議架構）：如果企業要引用任何 External Plugin，請在內部鑑別時以 sha 而非 ref 作為決策依據。上述範例只有 ref: "v0.1.3"——這代表若上游維護者把 v0.1.3 這個 tag 強制重指向另一個 commit，你審查過的內容就不是你安裝到的內容。這與 npm 的 tag 指向風險完全相同。

審查生命週期：九個標籤與七個 Slash 指令（第四版新增，Source-confirmed）

External Plugin 不走 PR，而是以 GitHub Issue 搭配標籤驅動整個審查生命週期：

維護者以 Issue 留言的 slash 指令推進狀態：

自動品質閘（Source-confirmed）：Metadata 驗證通過後會執行兩道閘——「vally lint against the submitted plugin path/ref/sha」與「install smoke test via Copilot CLI against an ephemeral marketplace entry」。此外，「The repository’s canonical validation rules live in eng/external-plugin-validation.mjs.」

六個月重審的錪點（Source-confirmed）：「A nightly workflow looks for closed issues labeled external-plugin and approved whose closed_at is at least six months old, applies re-review-due」——注意錪點是 Issue 的 closed_at，而不是 Plugin 本身的最後更新時間。

⚠️ 這個錪點選擇有一個企業必須知道的盲點（建議架構）：重審是依時間觸發，而非依上游內容變更觸發。換句話說，一個 Plugin 可以在核准後的第一天就把內容改掉，而 awesome-copilot 要到六個月後才會重新看它一眼。因此，企業不能把 awesome-copilot 的審查當作自己的保證；若要導入 External Plugin，請依下方「企業導入建議」自行鎖定 sha 並建立監控。

收錄門檻（Source-confirmed）

1. 必須是公開的 GitHub Repository——私有 Repository 或非 GitHub 託管一律不受理。
2. 必須走 Issue 審查流程，而不是直接送 PR 修改 plugins/external.json。
3. 核准後每六個月自動 re-review——這是 awesome-copilot 對「外部內容可能事後變質」的制度性緩解措施。
4. 一併適用第 2.5 節列出的 “What We Don’t Accept” 拒收清單。

企業導入建議

⚠️ 此小節為建議架構，並非 awesome-copilot 官方規定。

Scenario

某企業原本打算沿用舊版「Copilot Extensions」教學文件幫團隊建立客製化能力，才發現該機制已於 2025-11-10 日落，現有文件全部失效。改用 Agent Plugins 1.0 重新設計後，不僅恢復功能，還額外獲得「一次打包 Agent+Skill+Hook+MCP」的能力，這是舊版 Extensions 機制原本不具備的。

AI Prompt 範例

角色：你是 Platform Engineering 團隊的 Tech Lead。

任務：請幫我們草擬一份 plugin.json，把以下資源打包成一個
「enterprise-web-plugin」：
- agents/system-architect.agent.md、agents/backend-architect.agent.md
- skills/web-application-development、skills/security-review
- hooks/pre-commit-quality-gate.json
- mcp.json（含企業內部 Jira MCP Server 設定）

限制：
- $schema 須指向 Agent Plugins 1.0 官方 Schema
  （https://agent-plugins.org/schemas/1.0.0/plugin.schema.json）
- version 從 1.0.0 開始，遵循語意化版本
- 請同時列出：若只要符合開放規範最低需求 vs
  若要投稿回 awesome-copilot，欄位需求的差異

本章 Checklist

• 團隊已確認未使用已日落的 Copilot Extensions（GitHub App）機制
• 已用 11.2 對照表跟同事說明 Plugins 與 Extensions 的差異
• 已確認企業 Plugin 的內容組合寫在 extensions.com.github.awesome-copilot 而非頂層欄位（11.3）
• 已確認 author 寫成物件、Agent 路徑為 ./agents/*.md、Skill 路徑為資料夾且以 / 結尾（11.3）
• 已確認 MCP 宣告於 Plugin 根目錄 mcp.json 並帶 mcp.schema.json 的 $schema，且未使用 plugin.json 的 mcpServers 或 legacy .mcp.json（11.3）
• 已知悉 com.github.awesome-copilot namespace 於 served manifest 會被剝除，診斷時比對的是實體化後的目錄（11.3）
• 已確認未將 *.instructions.md 錯誤地打包進 Plugin
• Plugin 打包的資源清單已對應到第 8-9 章已驗證的 Skill／Agent 範例
• 若使用 External Plugin，已以 source.sha（而非 source.ref）鎖定版本並納入企業允許清單（11.5）
• 已知悉 External Plugin 的六個月重審是依 Issue closed_at 觸發、不是依上游內容變更觸發，並已自建監控（11.5）

12. Plugin 安裝與管理

12.1 Marketplace Discovery

（2026-08-27 查證更新） Copilot CLI 現在預設已內建註冊兩個 Marketplace：copilot-plugins（官方）與 awesome-copilot，因此在當前版本的 CLI 上通常不需要手動註冊即可直接瀏覽與安裝 awesome-copilot 收錄的 Plugin（本節標題原本強調的手動註冊步驟，僅適用於較舊版本的 CLI，或企業想額外註冊自建 Marketplace 的情境）：

# 查看目前已註冊的 Marketplace（預設應已包含 copilot-plugins 與 awesome-copilot）
copilot plugin marketplace list

# 瀏覽指定 Marketplace 內的 Plugin
copilot plugin marketplace browse awesome-copilot

# 若使用較舊版 CLI 或該 Marketplace 尚未預先註冊，手動加入
copilot plugin marketplace add github/awesome-copilot

安裝格式為 PLUGIN-NAME@MARKETPLACE-NAME：

copilot plugin install database-data-management@awesome-copilot

（以上指令依 docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing 與 Copilot CLI plugin reference 頁逐字核對，官方已實作）

12.2 Plugin 安裝、更新、移除、啟用／停用（企業自建 Plugin）

# 註冊企業自建 Marketplace（來源可為 GitHub repo、本機路徑，或非 GitHub 的 git URL）
copilot plugin marketplace add <org>/enterprise-plugins

# 安裝
copilot plugin install enterprise-web-plugin@enterprise-plugins

# 更新單一 Plugin／更新全部已安裝 Plugin
copilot plugin update enterprise-web-plugin
copilot plugin update --all

# 暫時停用／重新啟用（不需要解除安裝，適合暫時排除疑難時使用）
copilot plugin disable enterprise-web-plugin
copilot plugin enable enterprise-web-plugin

# 移除
copilot plugin uninstall enterprise-web-plugin

以上全部子指令（含容易被忽略的 disable／enable）均為 Copilot CLI plugin reference 官方文件逐字核對後的真實指令（Source-confirmed，2026-08-27 查證），取代先前版本「依 CLI 慣例推論」的示意寫法。任何子指令的完整參數仍可用 copilot plugin [SUBCOMMAND] --help 查詢。

12.3 Version Management 與 Dependency Management

• plugin.json 的 version 欄位遵循語意化版本（建議架構，官方未強制規定版本策略）。
• Plugin 內部若依賴特定版本的 MCP Server 或外部工具，建議在 README.md 中明確標注相依版本範圍，避免安裝環境不一致。

12.4 VS Code 使用方式

VS Code 透過 Agent Customizations 編輯器（目前仍是 Preview 狀態）統一管理 Agent、Skill、Plugin 等客製化資源，可在其中瀏覽已註冊 Marketplace 的 Plugin、檢視已安裝清單並執行安裝／移除操作。由於此編輯器仍在 Preview 階段，實際選單路徑與畫面配置可能隨版本調整，企業內部文件建議只描述「透過 Agent Customizations 編輯器管理」這個穩定概念，具體操作截圖以當下版本 VS Code 內建說明為準，避免文件因 UI 變動而迅速過時。

12.5 Copilot CLI 使用方式

12.5.1 Plugin 相關指令

# 查看已安裝的 Plugin
copilot plugin list

# 查看目前註冊的 Marketplace 來源
copilot plugin marketplace list

# 瀏覽某個 Marketplace 內可安裝的 Plugin
copilot plugin marketplace browse awesome-copilot

# 取消註冊某個 Marketplace 來源
copilot plugin marketplace remove <marketplace-name>

以上指令均已對照 Copilot CLI 官方 plugin reference 文件核實（Source-confirmed）。

12.5.2 Skill 相關指令（第四版新增，官方已實作）

Skill 的管理分為兩個層面：互動式工作階段內用 /skills slash command，終端機命令列則用 copilot skill 子指令（後者特別適合寫進自動化腳本與開發環境初始化流程）：

在 Prompt 中以斜線加 Skill 名稱即可指定使用某個 Skill，例如：

Use the /frontend-design skill to create a responsive navigation bar in React.

⚠️ 企業 Onboarding 實務建議（建議架構）：把 copilot skill list 與 copilot plugin list 一起寫進開發環境健康檢查腳本，讓新人在第一天就能自行確認「我的環境與團隊標準一致」。遇到「Skill 沒載入」的疑難雜症時，/skills info <NAME> 是最快的診斷入口——它直接告訴你這個 Skill 實際被從哪一個路徑或哪個 Plugin 載入，可以立刻排除「同名 Skill 互相覆蓋」這類問題（對應第 8.3 節的五個探索路徑）。

12.6 宣告式安裝：enabledPlugins

前述 copilot plugin install 屬於**命令式（imperative）安裝——由每位開發者在自己的機器上逐一執行。GitHub 另提供宣告式（declarative）**安裝機制：在設定檔中以 enabledPlugins 欄位列出要啟用的 Plugin，由 Copilot 在啟動時自動取得並啟用（官方已實作）。

設定檔位置與生效範圍

Copilot CLI 讀取的完整 settings 檔案清單（第四版新增，官方已實作）：除上表兩個位置外，官方 Hooks Reference 另明確列出兩個常被忽略的檔案，企業盤點設定來源時務必一併納入：

⚠️ 治理盲點提醒（建議架構）：settings.local.json 因為不進版控，不會被 CODEOWNERS 與 PR Review 攔到。如果企業把「Plugin 清單需經核准」寫進政策，就必須同時意識到開發者可以在 local 檔中自行追加。真正不可繞過的邊界只有第 20.5 節的 managed-settings.json；Repository 層設定的定位應該是「團隊預設值」而非「強制政策」。同理，.claude/settings.json 的存在也代表從 Claude Code 專案 clone 過來的設定會被 Copilot CLI 直接套用，稽核範圍請一併涵蓋。

設定範例

{
  "enabledPlugins": [
    "enterprise-web-plugin@enterprise-plugins",
    "security-review@awesome-copilot"
  ]
}

格式為 <plugin-name>@<marketplace-name>，與 copilot plugin install 的參數格式一致。

搭配 extraKnownMarketplaces 宣告自建 Marketplace

enabledPlugins 中的 @<marketplace-name> 必須是已知（known）的 Marketplace。Copilot CLI 預設已內建 copilot-plugins 與 awesome-copilot 兩個 Known Marketplace，因此引用社群 Plugin 時不需要額外執行 copilot plugin marketplace add。但企業自建的私有 Marketplace 並不在預設清單中，必須先以 extraKnownMarketplaces 宣告，enabledPlugins 才能解析得到：

{
  "extraKnownMarketplaces": {
    "enterprise-plugins": {
      "type": "github",
      "repository": "acme-corp/enterprise-plugins"
    }
  },
  "enabledPlugins": [
    "enterprise-web-plugin@enterprise-plugins",
    "security-review@awesome-copilot"
  ]
}

⚠️ 兩者是來源與內容的分工關係：只寫 enabledPlugins 而未宣告來源，私有 Plugin 會解析失敗；只宣告 extraKnownMarketplaces 而未列入 enabledPlugins，則 Plugin 不會被啟用。企業自建 Marketplace 時兩者都必須設定。

⚠️ 第四版重要提釒：企業層與個人／Repository 層的 Schema 不同，不可直接複製貼上。本節展示的是個人／Repository 層 settings.json 的寫法（enabledPlugins 為字串陣列；extraKnownMarketplaces 項目使用 type 與 repository）。但經 2026-08-31 逐字複查，docs.github.com 的 Enterprise managed settings 參考頁面對 managed-settings.json 定義的是另一套 Schema：

• enabledPlugins 是物件，以 PLUGIN-NAME@MARKETPLACE-NAME 為 key、布林值為值（true 強制啟用，false 強制停用）
• extraKnownMarketplaces 的每筆為具名物件，內含 source 子物件（{"source": "github", "repo": "OWNER/REPO"}）與選用的 autoUpdate

因此本節範例不可直接搬到 managed-settings.json，反之亦然。兩套 Schema 的差異官方未就其原因作出說明（官方目前沒有找到足夠資料確認此差異是有意設計還是文件尚未同步）。企業實作前請先在單一台機器上實際驗證兩層各自生效，並以第 20.5 節的官方格式為企業層標準。

為什麼企業應優先採用宣告式安裝

⚠️ 關鍵限制（極易踩坑）：Copilot cloud agent 只支援宣告式的 enabledPlugins，不會執行任何 copilot plugin install 指令。若團隊的 Plugin 僅以命令式安裝在本機，cloud agent 情境下會完全取不到這些能力，症狀是「在 VS Code 好好的，交給 cloud agent 就少了某個 Agent／Skill」。

⚠️ 另需注意第 6.6 節提過的 default branch 限制：cloud agent 讀取的是 default branch 上的 .github/copilot/settings.json，在 feature branch 上新增的 enabledPlugins 不會生效，必須先合併回 default branch。

企業落地建議

⚠️ 此小節為建議架構，並非 GitHub 官方規定的部署模式。

1. 在企業 Repository 範本（第 23 章標準目錄）中預先放入 .github/copilot/settings.json，把必備 Plugin 列為預設。
2. 對 .github/copilot/ 目錄設定 CODEOWNERS，讓 Plugin 清單的變更必須經平台團隊核准。
3. 個人層級的 ~/.copilot/settings.json 僅允許加入唯讀、無 Shell 執行能力的輔助型 Plugin，其餘一律走 Repository 層級。

Scenario

某企業誤以為 Plugin 安裝後會自動更新，結果團隊成員實際使用的 Plugin 版本各不相同，導致「同一個 Agent 在不同人電腦上行為不一致」的困惑。修正：在企業 Onboarding 文件中明確要求定期執行 copilot plugin update --all，並將版本檢查納入第 26 章 Tutorial 1「安裝與第一次使用」的標準步驟。

AI Prompt 範例

角色：你是負責撰寫 Onboarding 文件的 Platform Engineer。

任務：請幫我寫一份「新人第一次安裝企業 Plugin」的操作步驟文件，
需依序涵蓋：
1. 確認 copilot-plugins／awesome-copilot 是否已預設註冊
2. 註冊企業自建 Marketplace（<org>/enterprise-plugins）
3. 安裝 enterprise-web-plugin
4. 說明如何之後定期更新（copilot plugin update --all）
5. 說明若懷疑某個 Plugin 造成問題，如何先用 disable 暫時停用
   而非直接解除安裝

限制：只使用第 12 章列出的、已對照官方文件核實的真實指令，
不要自行發明未經驗證的參數。

本章 Checklist

• 已成功註冊 awesome-copilot 為 Marketplace 來源並安裝過至少一個 Plugin
• 已建立企業自建 Plugin 的更新/移除流程文件
• 已在 Onboarding 文件中提醒「Plugin 不會自動更新」
• 團隊必備 Plugin 已改以 .github/copilot/settings.json 的 enabledPlugins 宣告式管理（12.6）
• 已確認 Copilot cloud agent 情境所需的 enabledPlugins 設定位於 default branch（12.6）

13. Hooks 深入教學

13.1 定義與 Lifecycle

GitHub Copilot Hooks 官方定義（原文）：“Hooks allow you to extend and customize the behavior of GitHub Copilot agents by executing custom shell commands at key points during agent execution."——這是確定性（Deterministic）自動化，不依賴 AI 判斷，只依賴事件是否發生（官方已實作）。

13.2 十四個生命週期事件（第四版全面改寫）

⚠️ 本節為第四版重大修正。 本手冊第一至第三版依當時官方文件僅列出六個事件；docs.github.com/en/copilot/reference/hooks-reference 現已擴充為 14 個事件，並明確區分 Copilot CLI 與 Copilot cloud agent 兩個 Surface 的差異。企業若沿用舊版的六事件模型設計治理機制，會漏掉 Subagent、Compaction、權限請求三條最關鍵的稽核路徑。

13.2.1 事件總表（官方已實作，2026-08-31 查證）

下表依英文字母排序，與官方 Reference 一致。「可影響流程」欄說明該事件的輸出是否會被 Copilot 讀回並改變後續行為——這一欄才是設計治理 Hook 的關鍵，只有標示「是」的事件才能用來「攔阻」。

其中 permissionRequest 與 notification 為 Copilot CLI 專屬；其餘 12 個事件在 CLI 與 cloud agent 皆會觸發（行為差異如上表右欄）。

13.2.2 事件名稱的兩種寫法：camelCase 與 PascalCase

官方支援兩套事件名稱，而且選哪一套會直接決定 payload 的欄位命名風格，這是跨工具移植 Hook 時最容易踩的坑（官方已實作）：

更關鍵的是Matcher 語意也會跟著切換。以 PascalCase 的 PreToolUse（或 PermissionRequest）設定的 Hook，會套用 Claude 的 matcher 語意而非 Copilot 原生的 regex 規則：

• *、** 或空字串：對所有工具觸發
• 字面名稱或用 | 分隔的列舉（例如 Bash、Edit|Write）：任一 token 等於 runtime 工具名或其 Claude 工具名時觸發
• 其他值：視為區分大小寫的 regex，錨定為 ^(?:PATTERN)$，比對的是 Claude 工具名

而且 PascalCase 的 payload 回報的 tool_name 會是 Claude 工具名（例如 Bash 而非 bash）。官方提供的對照表如下：

無 Claude 對應的工具則沿用 runtime 原名。

⚠️ 企業導入建議（建議架構）：在同一個 Repository 內不要混用兩種寫法。統一採 camelCase 可讓 payload 解析腳本只寫一套；只有在你需要把既有 Claude Code Hook 原封不動搬過來時，才選 PascalCase，並在 README.md 中明確註記「本檔採 VS Code 相容格式，payload 為 snake_case」。

13.2.3 Hook 的三種型別

官方 Hook 設定支援三種 type，第三版僅涵蓋 command 一種（官方已實作）：

command 型 Hook 另可在執行中把 {"type": "progress", "message": "..."} 單行 JSON 寫到 stdout，於 CLI 時間軸顯示進度；加上 "temporary": true 則為暫時性狀態列。CLI 會逐行掃描 stdout，把 progress 行移出輸出串流，其餘所有行在 Hook 結束後串接、trim 後以單次 JSON.parse 解析。這代表：

• Progress 行與最終決策物件混寫是官方設計的正常用法，不會干擾解析
• 每個 progress 訊息必須自成一行且為合法 JSON；多行美化排版的 progress 物件不會被辨識，會殘留在輸出串流中導致最終解析失敗
• 只能輸出「一個」最終決策物件。兩個 echo '{"permissionDecision": ...}' 會串成非法 JSON 而被整個忽略
• Hook 輸出（command 的 stdout／http 的 response body）上限為 10 MiB，超過會被截斷

13.2.4 決策控制與 Matcher 過濾

preToolUse 決策欄位：

agentStop／subagentStop 決策欄位：decision（block／allow）、reason（block 時作為下一輪的 prompt）、modifiedResponse（僅 subagentStop，用於遮蔽或重整 subagent 輸出）。官方另設有失控保護（Runaway guard）：連續 8 次 block 續跑後，CLI 會強制結束該 turn；agentStop 的輸入欄位 stop_hook_active 可用來偵測「本輪已被強制續跑過」而自我節制。

Matcher 過濾——這正是第三版所稱「官方沒有提供依工具名稱過濾的欄位」之處已經不成立。官方現已支援 matcher 欄位，編譯為 ^(?:PATTERN)$ 並必須完整比對；regex 非法時該 Hook 項目會被跳過：

13.2.5 Exit Code 與 Fail-Open／Fail-Closed 語意（資安關鍵）

這是設計「攔阻型」Hook 時最必須讀懂的一段（官方已實作）：

command 與 http 兩種型別的 preToolUse 失敗語意相反，這一點必須依資安需求選型：

• Command preToolUse：fail-closed（崩潰或非零離開＝拒絕）
• HTTP preToolUse：fail-open（網路錯誤、逾時、非 2xx 皆落回預設權限流程）

⚠️ 企業資安含意（建議架構）：若你把「阻擋機密外洩」的責任交給 HTTP Hook，攻擊者只要讓那台伺服器無法連線，Hook 就會 fail-open 而完全失效。合規等級的攔阻請一律使用 command 型 preToolUse（fail-closed），並且不要把 timeout 設得太短——因為 timeout 永遠 fail-open，過短的 timeout 等於自己開了旁路。真正的硬邊界請放在第 20.5 節的 permissions.deny 與第 20.6 節的 Sandbox，Hook 只作為可觀測性與流程自動化層。

13.2.6 permissionRequest 與 Sandbox Bypass 例外

permissionRequest（Copilot CLI 專屬）在權限服務執行之前觸發，回傳 behavior: "allow" 或 "deny" 即可短路整個權限流程；回傳空值則落回正常處理。它特別適合 CLI 的 pipe 模式（-p）與 CI 情境——那裡根本沒有互動式提示可用。輸出欄位為 behavior、message（拒絕時回饋給 LLM 的理由）、interrupt（搭配 deny 設為 true 可直接中止 Agent）。

Sandbox Bypass 例外（資安設計重點）：對於任何「要求跳出 Sandbox」的請求（toolInput 中 requestSandboxBypass: true），Hook 回傳 allow 不會預先核准、也不會短路使用者提示——因為離開 Sandbox 屬於權限提升，官方要求必須由人互動確認。只有 deny 仍會生效（讓 Policy Hook 得以封鎖此類逃逸）。此規則涵蓋「Shell 指令要求在 Sandbox 外執行」與「web_fetch 目標 URL 被 Sandbox 網路政策拒絕」兩種情況。

13.3 設定檔格式與關鍵限制

• 設定檔位置：.github/hooks/NAME.json
• 關鍵限制（官方原文）：“The hooks configuration file must be present on your repository’s default branch to be used by Copilot cloud agent."——這代表在 feature branch 上新增/修改 Hook，Copilot cloud agent 不會套用，必須先合併到 default branch。
• 預設 timeout 30 秒，可用 timeoutSec 調整（timeout 為其別名，兩者並存時以 timeoutSec 優先）。
• 需包含 "version": 1。

官方正確的 JSON 骨架（第四版校正，官方已實作）：事件名是 hooks 物件的 key，對應值是一個陣列，因此單一檔案既可綁定多個事件，同一事件也可以掛多個 Hook：

{
  "version": 1,
  "disableAllHooks": false,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "matcher": "bash|powershell",
        "bash": "./scripts/hooks/guard.sh",
        "powershell": "./scripts/hooks/guard.ps1",
        "cwd": "./",
        "env": { "LOG_LEVEL": "info" },
        "timeoutSec": 30
      }
    ],
    "sessionEnd": [
      { "type": "command", "command": "./scripts/hooks/session-end-security-scan.sh", "timeoutSec": 60 }
    ]
  }
}

其中 bash、powershell、command 三者至少必填其一；command 是跨平台 fallback，在 bash／powershell 缺席時被複製到兩者，而明寫的 bash／powershell 在各自平台優先。

寬鬆度差異（容易踩坑）：從目錄（例如 .github/hooks/）載入的檔案，若某一個 Hook 項目格式錯誤，只會丟掉該項目並記錄 log，同檔其他合法 Hook 仍會載入（但非法 JSON、錯誤的 version、非陣列的事件值這類結構性錯誤仍會整檔拒絕）；而寫在 settings.json 內的 hooks 區塊則是嚴格模式，任一項目驗證失敗就整個 hooks 欄位作廢。

一鍵停用：disableAllHooks（官方已實作）。需要保留設定但暫停執行時（偵錯、處理敏感任務、讓貢獻者本地選退），可將此旗標設為 true：

• 寫在單一 .github/hooks/*.json 檔內：只跳過該檔宣告的 Hook，CLI 與 cloud agent 皆遵守
• 寫在 Repository settings.json 頂層：Copilot CLI 專用，會跳過該 Repository 所有來源的 Hook；但 Policy Hook 不受影響，仍照常執行（這正是企業強制治理的設計重點，見第 13.7 節）

⚠️ awesome-copilot 的 hooks/<name>/ 貢獻慣例用的檔名是 hooks.json（搭配 README.md），與官方文件描述的 .github/hooks/NAME.json 兩者間的等價關係未能查證確認（官方目前沒有找到足夠資料確認此功能）。企業實作時建議以 docs.github.com 官方頁面描述的 .github/hooks/NAME.json 格式為準。

13.4 Pre-Change Quality Gate Hook 範例

⚠️ 重要語意澄清：依 13.2 定義，preToolUse 是「Agent 每次呼叫任何工具前」都會觸發，並非「只在 commit 前」觸發。下列範例的 Shell 腳本內容（secret 掃描、lint、測試）刻意設計成可以在每次工具呼叫前重複執行也不會出錯，但代價是每一次工具呼叫（包含單純讀檔）都會先跑一輪完整檢查，可能造成明顯延遲。

✅ 第四版修正：本手冊前三版在此處寫「官方 Hook 設定本身沒有提供依工具名稱／參數過濾的欄位」，此說法已不再成立。官方現已提供 matcher 欄位（見第 13.2.4 小節），preToolUse 可直接以 regex 對 toolName 過濾，例如 "matcher": "bash|powershell|edit|create" 就可以把單純讀檔（view、grep、glob）排除在完整檢查之外。請優先使用 matcher 而非在 Shell 腳本內自行判斷，因為 matcher 不符時連 Hook 進程都不會被建立，效能差異很大。下方範例已同步改寫為官方格式並加上 matcher。

.github/hooks/pre-tooluse-quality-gate.json：

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "matcher": "bash|powershell|edit|create|apply_patch",
        "command": "./scripts/hooks/pre-commit-quality-gate.sh",
        "timeoutSec": 120
      }
    ]
  }
}

scripts/hooks/pre-commit-quality-gate.sh（示意，腳本開頭加入「暫存區是否有變更」判斷，避免每次工具呼叫都重複跑完整檢查）：

#!/usr/bin/env bash
set -euo pipefail

# 依上方澄清說明：preToolUse 每次工具呼叫前都會觸發，
# 此處先判斷是否真的有暫存變更，沒有變更就直接放行，避免每次讀檔都跑一輪完整檢查
if git diff --cached --quiet; then
  echo "[hook] 無暫存變更，略過 Quality Gate"
  exit 0
fi

echo "[hook] 掃描 Secret..."
gitleaks detect --no-git -v

echo "[hook] 執行 Lint..."
npm run lint --if-present
mvn -q checkstyle:check --file pom.xml || true

echo "[hook] 執行單元測試..."
mvn -q test
npm run test:unit --if-present

echo "[hook] 檢查依賴漏洞..."
mvn -q org.owasp:dependency-check-maven:check || true

echo "[hook] Quality Gate 通過"

13.5 Agent Workflow Hook 範例

.github/hooks/agent-workflow-guard.json（第四版校正：官方格式下 一個檔案可以同時綁定多個事件，不需要拆成兩個檔）：

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      { "type": "command", "command": "./scripts/hooks/context-validation.sh", "timeoutSec": 30 }
    ],
    "sessionEnd": [
      { "type": "command", "command": "./scripts/hooks/session-end-security-scan.sh", "timeoutSec": 60 }
    ],
    "subagentStop": [
      { "type": "command", "command": "./scripts/hooks/redact-subagent-output.sh", "timeoutSec": 15 }
    ],
    "preCompact": [
      { "type": "command", "matcher": "auto", "command": "./scripts/hooks/archive-transcript.sh", "timeoutSec": 30 }
    ]
  }
}

進階範例說明（第四版新增，建議架構）：上例後兩個事件是舊版六事件模型根本無法實現、但企業非常需要的兩條治理路徑：

• subagentStop：Subagent 輸出遮蔽閘門。Subagent 常被用來做大量探索性搜尋，回傳給母 Agent 的內容可能夾帶檔案路徑、連線字串或設定值。利用 modifiedResponse 可以在內容進入母 Agent context 之前就完成遮蔽。需注意官方兩項限制：（1）有效的 block 決策會壓過 modifiedResponse；（2）多個 Hook 的改寫不會級聯，每個 Hook 都拿到相同的原始 response，最後一個回傳的勝出——所以不要把「遮蔽器」與「格式化器」分成兩個 Hook 串接。
• preCompact（matcher 限定 auto）：壓縮前的逐字稿保存。Context Compaction 發生時，先前的對話細節會被摘要取代；對於需要完整稽核軌跡的產業（金融、醫療），這等於遺失證據。preCompact 的 payload 帶有 transcriptPath，可在壓縮發生前先把逐字稿歸檔。以 "matcher": "auto" 限定只在自動壓縮時觸發，避免使用者手動壓縮時重複歸檔；cloud agent 也只會以 auto 觸發此事件。

流程示意：

graph LR
    A["Agent Start<br/>(sessionStart)"] --> B["Context Validation"]
    B --> C["Implementation<br/>(preToolUse / postToolUse)"]
    C --> D["Test"]
    D --> E["Security Check"]
    E --> F["Review"]
    F --> G["Agent End<br/>(sessionEnd)"]

13.6 安全性、Logging、Failure Handling

13.7 Hook 檔案位置、載入優先序與 Cloud Agent 限制

本節為第四版新增。第三版只描述了 .github/hooks/NAME.json 一個位置，但官方 Hooks Reference 實際定義了五個載入來源與兩個完全不同的執行環境。企業若要設計「使用者無法關閉」的治理 Hook，關鍵就在本節的 Policy Hooks。

13.7.1 Copilot CLI 的五個載入來源（官方已實作）

Hook 在 Copilot CLI 上跑在開發者本機、與 CLI 相同的 shell 中。載入順序為 Policy → Repository → User → settings.json 內嵌 → Plugin，且全部合併執行——同一事件出現在多個來源時，所有來源的 Hook 項目都會被執行，不是覆蓋關係：

Policy Hooks 的安全前提（官方已實作）：在 POSIX 系統上，Policy 檔案必須由 root 擁有，且不可被 group 或 world 寫入；官方明確定位它是「給企業 IT 管理員使用、需要提升權限才能安裝」的機制，一般使用者無法修改。

⚠️ 這正是第三版遺漏的企業治理關鍵（第四版補上）：如果你的合規要求是「工程師不得自行停用稽核 Hook」，把 Hook 放在 .github/hooks/ 是做不到的——使用者只要在自己的 settings.json 頂層設 disableAllHooks: true 就能整批跳過。唯一能達成強制性的做法是用 MDM／組態管理工具（Intune、Jamf、Ansible、GPO）把 Policy Hook 佈署到 policy.d/ 或 Windows Registry，並確保檔案權限正確。這與第 20.5 節的 managed-settings.json 是互補的兩層：managed-settings.json 管「權限與 Plugin 邊界」，Policy Hooks 管「不可繞過的稽核與自動化」。

但請同時記住第 13.2.5 小節的鐵則：timeout 對 Policy Hook 一樣 fail-open。一個連不上的 Policy Hook 端點，不會擋下任何事情。

13.7.2 Copilot cloud agent 的執行環境限制（官方已實作）

Cloud agent 的 Hook 跑在每個 job 各自佈建、結束即銷毀的 Linux 沙箱中，環境限制與 CLI 差異極大：

⚠️ 企業最常見的三個 cloud agent Hook 失敗原因（建議架構）：

1. 只寫了 powershell 欄位——在 Linux 沙箱直接被忽略，Hook 等於沒設。請務必提供 bash 或 command。
2. 把稽核 log 寫到本機檔案——job 結束即消失。請改用 http 型 Hook，並事先請管理員把你的收集端點加入防火牆允許清單。
3. 以為 user 層或 Plugin Hook 會生效——沙箱不載入這些來源。所有 cloud agent 需要的 Hook 都必須存在於 Repository default branch 的 .github/hooks/*.json。

Scenario

某團隊在 feature branch 上新增了一個 Hook 用來擋掉危險指令，測試時運作正常，合併前又臨時調整了 Hook 內容但忘記合併到 default branch，結果 Copilot cloud agent 在正式環境完全沒套用新版 Hook。教訓：牢記 13.3 的關鍵限制——Hook 設定檔必須存在於 default branch 才會被 Copilot cloud agent 使用，測試環境與 default branch 的 Hook 版本要保持同步驗證。

AI Prompt 範例

角色：你是 DevSecOps 工程師。

任務：請幫我們的 Java + Vue 專案設計一個 preToolUse Hook，
在 Agent 每次要執行「刪除檔案」相關指令前，先要求輸出將被刪除的檔案清單，
並記錄到 .github/hooks/logs/ 目錄，供事後稽核。

要求：
1. 依 13.3 節的官方 JSON 格式撰寫 hooks 設定檔
2. Shell 腳本需考慮跨平台相容性（企業內同時有 Windows 與 Linux 開發環境）
3. 說明此 Hook 為何要設在 default branch 才會生效

本章 Checklist

• 已理解 Hook 設定檔必須存在於 default branch 才會被 Copilot cloud agent 使用
• Hook 腳本已比照生產環境腳本標準做過安全審查
• 已建立至少一個 Pre-Commit Quality Gate Hook 並驗證觸發時機正確
• Hook 失敗時有清楚的錯誤訊息與集中式 Logging
• 已改用官方 hooks 物件格式（事件名為 key、值為陣列），未再使用舊版的頂層 event 欄位
• 已用 matcher 縮小 preToolUse／postToolUse 的觸發範圍，避免每次讀檔都跑完整檢查
• 已確認攔阻型 Hook 使用 command 型（fail-closed）而非 http 型（fail-open），且 timeout 未設得過短
• 已評估是否需要 subagentStop（Subagent 輸出遮蔽）與 preCompact（壓縮前逐字稿歸檔）兩條稽核路徑
• 若合規要求「不可被使用者停用」，已改以 Policy Hooks 佈署，並確認 POSIX 檔案由 root 擁有且非 group／world 可寫
• cloud agent 用的 Hook 已提供 bash 或 command 欄位（非僅 powershell），且稽核輸出改走 http 而非寫本機檔

14. MCP 整合

14.1 MCP 是什麼

Model Context Protocol（MCP）是 Agent 與外部工具／資料／系統的連接層，讓 Copilot 能存取本身不具備的外部能力（官方已實作）。MCP 由三個核心概念組成：

14.2 Copilot Agent 如何使用 MCP

Agent 在判斷需要外部資訊或需要執行外部動作時，會呼叫已設定的 MCP Server 提供的 Tool，取得結果後繼續推理——這與 Skill（本地封裝的指令與資源）、Plugin（打包分發單位）是不同層級的機制。

sequenceDiagram
    participant U as 使用者
    participant A as Copilot Agent
    participant M as MCP Server（如 Database MCP）
    participant D as 外部系統（如 PostgreSQL）

    U->>A: 「幫我查詢訂單資料表最近一週的異常訂單」
    A->>A: 判斷需要即時外部資料，本地無法回答
    A->>M: 呼叫已設定的 MCP Tool（例如 query_readonly）
    M->>D: 執行唯讀查詢
    D-->>M: 回傳查詢結果
    M-->>A: 回傳結構化資料（MCP Resource/Tool Result）
    A->>A: 將查詢結果整合進推理過程
    A-->>U: 回覆分析結果（附上查到的異常訂單清單）

補充（2026-08-27 查證新增）：MCP 的使用範圍不只限於 Copilot cloud agent／VS Code Agent Mode——Copilot Code Review 自 2026-07-29 起也正式 GA 支援 Agent Skills 與 MCP Server，代表企業在 Pull Request 的自動化程式碼審查情境中，同樣可以讓 Copilot 透過 MCP 查詢外部系統（例如查詢 Jira 確認某個變更是否對應到合法的 Ticket），並非只有互動式對話情境才能使用 MCP。

14.3 MCP 與 Skill／Plugin 的差異

14.4 各 Client 的設定位置

格式為 JSON，頂層 servers 物件，欄位含 type、url、command、args。GitHub MCP Registry 為 Public Preview（官方原文：“The GitHub MCP Registry is in public preview and may change."）。

14.5 .vscode/mcp.json 範例

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/enterprise_db"]
    }
  }
}

⚠️ github Server 的 URL 為官方 GitHub MCP 端點示意；postgres Server 使用的套件為社群常見的 MCP Server 實作示意，非 awesome-copilot 收錄項目，安裝前需依第 21 章安全評估流程審查。

14.6 Web Application 開發常用 MCP 清單

⚠️ 上表除 GitHub MCP 外，其餘均非 awesome-copilot 官方收錄或 GitHub 官方提供，是本手冊列出的「企業可能需要」的示意清單，安裝任何一個前都必須依第 21 章 Checklist 完整審查來源、權限範圍與網路存取行為。

14.7 MCP Server 信任邊界與網域控管

VS Code 官方文件把 MCP Server 列為四大信任邊界之一，需要使用者明確同意後才能運作（2026-08-28 複查，官方已實作）。企業導入 MCP 時必須同時管到這四層：

上述信任均可透過 Command Palette 撤銷。企業在發生事件（例如某套件被揭露為惡意）時，應將「撤銷信任」列入標準應變步驟，而不是只發一封信叫大家「不要用」。

⚠️ 實務提醒（建議架構）：第 14.4 節描述的是「設定檔放哪裡」，本節描述的是「設定了之後還需要誰點頭」。兩者必須同時寫進企業 SOP，否則會出現「設定都發下去了，但每位開發者還是自己按一次信任」的治理破口。

14.8 MCP 的企業層強制治理：Allowlist 與 Denylist

本節為第四版新增。第 14.7 節談的是使用者端的信任提示——但信任提示的本質是「請使用者自己判斷」，在企業規模下這不是可靠的控制。若要做到「這台 MCP Server 在本企業內根本無法被啟動」，必須使用第 20.5 節 managed-settings.json 的 allowedMcpServers 與 deniedMcpServers（官方已實作，2026-08-31 查證）。

14.8.1 兩個鍵的合成語意（最容易誤解的地方）

Deny 恆優先於 Allow：同時符合兩張清單的 Server 一律被封鎖。唯一例外是第一方 Copilot Server（例如內建的 GitHub MCP Server），官方明訂其豁免於 deny 規則、無法被封鎖。

14.8.2 三種比對子（每筆項目只能擇一）

⚠️ serverName 是最弱的比對子，不要用它做安全控制。 官方直接寫明：因為 Server 名稱是使用者自己取的，若你要強制某台 Server 的身分，請改用 serverUrl 或 serverCommand。實務上這代表：用 serverName: "github" 做允許清單，等於任何人只要把自己的惡意 Server 取名叫 github 就能通過——這是典型的偽造漏洞。

14.8.3 URL 正規化：官方內建的繞過防護（官方已實作）

在比對 serverUrl 之前，Client 會先對 pattern 與實際 URL 同時做正規化，這一段直接對應 OWASP 的 URL 混淆／解析器差異類攻擊：

• 通訊協定與主機名轉為小寫
• 國際化或 Unicode 主機名轉為 Punycode（防止同形異義字攻擊）
• 移除預設埠（HTTP 的 :80、HTTPS 的 :443）
• 解碼主機名中的百分號編碼位元組——例如 %65vil 會還原成 evil
• 移除 URL fragment 與 DNS 名稱結尾的點號
• 禁止 authority 區段的萬用字元跨越 / 邊界比對到路徑

最後一項尤其重要：它防止 https://*.example.com 這種 pattern 被 https://evil.com/.example.com/... 之類的構造騙過。

14.8.4 企業導入建議（建議架構）

此鍵可用第 20.5 節的 overridable 機制做企業團隊分層：企業層以 { "overridable": [...] } 包住比對子物件，各團隊檔案再以一般語法定義自己的允許與封鎖清單。這讓「研發團隊可用 Playwright MCP、財會團隊不可」得以在同一份治理架構下實現。

⚠️ 與第 14.7 節的分工必須寫清楚：allowedMcpServers／deniedMcpServers 是硬邊界（Server 根本起不來）；第 14.7 節的信任提示是軟邊界（提醒使用者做判斷）。企業 SOP 應明確寫成兩層：硬邊界由 IT 部署、開發者無感；軟邊界仍需教育訓練，因為允許清單內的 Server 一樣可能在某次更新後行為改變。

Scenario

某團隊為了讓 Copilot 能查詢生產資料庫，直接把生產環境的 DB 帳密寫進 .vscode/mcp.json 並提交到 Repository。這是嚴重的安全事故：MCP 設定檔若含有 Secret，一旦提交到版控就等於外洩。正確做法是透過環境變數或企業密鑰管理系統注入認證資訊，且資料庫帳號應僅具唯讀權限、限定於非生產環境。

AI Prompt 範例

角色：你是負責 MCP 導入的 Platform Engineer。

任務：請幫我們的企業 Vue 3 + Spring Boot 專案設計一份
.vscode/mcp.json，包含 GitHub MCP（官方提供）與一個唯讀的
PostgreSQL Database MCP（僅限測試環境資料庫）。

限制：
1. 資料庫連線字串與帳密一律用環境變數注入，不可寫死在 JSON 中
2. 請說明如何確認該 PostgreSQL MCP Server 套件的來源可信
   （依第 21 章 Checklist）
3. 請額外說明：若之後要在 Copilot Code Review 情境也用到這個
   MCP，是否需要額外設定（依 14.2 補充說明的 2026-07-29 GA 現況）

本章 Checklist

• MCP 設定檔中不含任何硬編碼 Secret（一律用環境變數注入）
• 已將「MCP Server 信任提示」與「撤銷信任」列入企業 SOP 與應變步驟（14.7）
• 資料庫類 MCP 一律使用最小權限（唯讀、非生產環境）帳號
• 已用 14.6 清單分清楚哪些 MCP 是官方提供、哪些需要企業自行審查
• 已理解 MCP／Skill／Plugin 三者的本質差異（14.3）
• 已在 managed-settings.json 部署 allowedMcpServers／deniedMcpServers 硬邊界，未僅倚賴使用者信任提示（14.8）
• 允許清單一律以 serverCommand 或 serverUrl 比對，未使用可被使用者偽造的 serverName（14.8.2）
• 已知悉 allow 取交集、deny 取聯集，且第一方 Copilot Server 豁免於 deny（14.8.1）

15. Web Application 開發實戰

⚠️ 本章案例為建議架構，示範如何用第 6-14 章已驗證的機制組合出完整開發流程，情境本身為教學示範用途之原創設計。

15.1 技術堆疊

• 前端：Vue 3、TypeScript、Tailwind CSS、PrimeVue、Pinia、i18n
• 後端：Java 25、Spring Boot 4.x、REST API、Clean Architecture、Hexagonal Architecture、Maven
• 資料庫：PostgreSQL、Oracle、DB2
• 測試：JUnit 5、Playwright、JMeter
• Infra：Podman、Kubernetes、Jenkins、GitHub Actions

15.2 開發流程

graph TB
    R["Requirements"] --> SA["system-architect<br/>(Agent)"]
    SA --> FA["frontend-architect (Agent)"]
    SA --> BA["backend-architect (Agent)"]
    FA --> IMP["Implementation<br/>(web-application-development Skill)"]
    BA --> IMP
    BA --> DBA["database-agent"]
    DBA --> IMP
    IMP --> TA["test-agent"]
    TA --> SEC["security-agent"]
    SEC --> CRA["code-review-agent"]
    CRA --> DA["devops-agent"]
    DA --> Deploy["Deployment<br/>(Podman / K8s / Jenkins / GH Actions)"]

15.3 各階段對應的客製化資源

Scenario

某企業導入本流程後，新功能開發從「需求 → 上線」平均時間縮短，但真正的價值不在於程式碼生成速度，而在於：每個 Agent 都有明確職責邊界，Code Review 與 Security Review 成為流程中固定的關卡而非事後補救，減少了「AI 生成程式碼但沒人真正審查」的風險。

AI Prompt 範例

角色：你是 backend-architect Agent。

情境：需要新增一個「訂單查詢」REST API，供前端訂單列表頁使用。

Context：
- 遵循 .github/instructions/java.instructions.md 的規範
- 遵循 .github/skills/web-application-development/SKILL.md 的實作步驟
- 資料庫為 PostgreSQL，訂單資料表為 orders，已有 OrderEntity

Objective：實作 GET /api/orders 端點，支援分頁與依狀態篩選。

Constraints：
- Controller 只做參數驗證與轉發，不寫商業邏輯
- 回應格式須為 ApiResponse<PagedResult<OrderDto>>
- 需補上對應的 JUnit 5 測試

Steps：
1. 設計 DTO 與分頁參數物件
2. 實作 Service 層查詢邏輯
3. 實作 Controller
4. 撰寫測試

Validation：mvn test 需全數通過

Output Format：列出新增/修改的檔案清單，並附上關鍵程式碼片段

本章 Checklist

• 已對照 15.3 表格，確認每個開發階段都有對應的客製化資源
• Security Review 與 Code Review 已成為流程固定關卡，而非選擇性步驟
• 已在沙盒專案完整跑過一次本流程，驗證 Agent 間 Handoff 正常

16. 逆向工程實戰

⚠️ 本章案例為建議架構，情境為教學示範用途之原創設計。

16.1 情境輸入

Legacy Web Application
Legacy Java
Legacy JSP
Legacy Servlet
Legacy SQL
Stored Procedure
Batch
Configuration
Logs

16.2 分析流程（由 reverse-engineering-agent 依 reverse-engineering Skill 執行）

graph TB
    S1["1. Repository Discovery"] --> S2["2. Code Inventory"]
    S2 --> S3["3. Dependency Analysis"]
    S3 --> S4["4. Architecture Discovery"]
    S4 --> S5["5. Database Analysis"]
    S5 --> S6["6. API Analysis"]
    S6 --> S7["7. Security Analysis"]
    S7 --> S8["8. Batch Analysis"]
    S8 --> S9["9. Business Rule Extraction"]
    S9 --> S10["10. Architecture Diagram"]
    S10 --> S11["11. Technical Debt Analysis"]
    S11 --> S12["12. Modernization Recommendation"]

16.3 最終產出

Reverse Engineering Report
Architecture Document
Dependency Map
API Catalog
Database Catalog
Business Rule Catalog
Risk Register
Modernization Roadmap

產出內容示意（以 business-rule-catalog.md 的其中兩條為例，而非只列檔名，讓讀者了解實際產出長什麼樣子）：

# Business Rule Catalog

## BR-014：訂單逾時自動取消

- **來源程式碼**：`OrderBatchServlet.java` 第 88-112 行
- **規則描述**：訂單建立後若 30 分鐘內未完成付款，批次作業會將訂單狀態改為 `CANCELLED`
  並釋放已鎖定的庫存。
- **信心等級**：高（邏輯清楚，且有對應的 Log 訊息 `"Auto-cancel order due to timeout"` 佐證）
- **建議處理**：現代化時建議改為可設定的逾時時間（目前硬編碼為 `1800000` 毫秒）

## BR-015：VIP 會員折扣疊加規則

- **來源程式碼**：`PricingCalculator.java` 第 210-245 行，搭配 `MEMBER_LEVEL` 資料表
- **規則描述**：程式碼顯示 VIP 會員折扣與促銷折扣「不可疊加」，但 `PricingCalculator`
  第 240 行有一段被註解掉的邏輯疑似曾支援疊加，且無對應的商業文件可佐證目前規則是否為刻意設計。
- **信心等級**：⚠️ **需人工確認**——無法從程式碼判斷「不可疊加」是原始需求，還是歷史 Bug 修復後未清理的殘留邏輯
- **建議處理**：現代化前必須先向業務單位確認正確規則，不可直接沿用現有程式碼行為

這種「來源程式碼＋規則描述＋信心等級＋建議處理」的四欄結構，可套用到全部 8 份產出文件，讓每一條分析結果都能追溯回原始程式碼位置，也讓「需人工確認」的項目清楚標示、不會被淹沒在報告中。

16.4 重要限制（重申）

依第 8.8 節 Skill 定義：reverse-engineering-agent 只分析、不修改任何原始碼；若無法確認某段程式碼的商業意圖，必須在報告中明確標示「需人工確認」，不可臆測。

Scenario

某企業有一套 15 年歷史的 JSP + Servlet 訂單系統，過去每次新人要維護都要花數週理解程式邏輯。導入本流程後，第一次執行產出的 Business Rule Catalog 雖然不完美（約 15% 條目標示為「需人工確認」），但已足夠讓新人在 2-3 天內建立整體認知，大幅降低 Onboarding 成本。教訓：逆向工程 Agent 的產出是「加速理解的起點」，不是「100% 正確的最終文件」，務必保留人工確認機制。

AI Prompt 範例

角色：你是資深 Software Architect（reverse-engineering-agent）。

任務：分析此 Repository（Legacy JSP + Servlet + Oracle Stored Procedure 訂單系統）。

不可修改任何原始碼。

請依序執行：
1. Repository Discovery：技術堆疊、建置工具
2. Code Inventory：模組/類別數量統計
3. Dependency Analysis
4. Architecture Discovery（若無明確分層，需明確指出）
5. Database Analysis（含 Stored Procedure 邏輯摘要）
6. API Analysis（所有 Servlet/JSP 進入點）
7. Security Analysis
8. Batch Analysis
9. Business Rule Extraction（無法確認商業意圖者，標示「需人工確認」）
10. Architecture Diagram（Mermaid）
11. Technical Debt Analysis
12. Modernization Recommendation

輸出至 docs/reverse-engineering/ 底下對應檔案。

本章 Checklist

• 已確認 reverse-engineering-agent 的工具授權為唯讀
• 產出報告中「需人工確認」條目已排入後續人工複核排程
• 8 項最終產出文件已全數產出且存放於統一目錄

17. Framework Migration 實戰

⚠️ 本章案例為建議架構，情境為教學示範用途之原創設計。

17.1 案例：Spring Boot 3.x → Spring Boot 4.x

graph TB
    A["Current System Assessment"] --> B["Dependency Analysis"]
    B --> C["Breaking Change Detection"]
    C --> D["Configuration Analysis"]
    D --> E["Source Code Analysis"]
    E --> F["Security Analysis"]
    F --> G["Test Analysis"]
    G --> H["Migration Plan"]
    H --> GATE{"人工核准？"}
    GATE -->|"否"| H
    GATE -->|"是"| I["Automated Changes"]
    I --> J["Build"]
    J --> K["Test"]
    K --> L["Regression Test"]
    L --> M["Code Review"]
    M --> N["Migration Report"]

17.2 各階段使用的客製化資源

⚠️ 釐清「Security Analysis」的歸屬：17.1 流程圖中的 Security Analysis 節點屬於升級前的評估階段，聚焦「這次版本升級本身會不會引入安全性變更」（例如 Jakarta namespace 遷移、預設安全設定變更），由 migration-agent 搭配 framework-migration Skill 執行，不是由 security-agent 負責。security-agent 的角色是在變更完成之後，於 Code Review 階段對實際程式碼異動做獨立的安全複查（兩者是「升級相容性檢查」與「異動後安全審查」兩個不同性質的檢查，並非重複執行同一件事）。

17.3 六大機制如何共同完成 Migration

• Instructions：定義升級後的新規範（例如 Jakarta namespace 命名規則）寫入 java.instructions.md
• Skills：framework-migration Skill 封裝分析流程，確保每次分析步驟一致
• Agents：migration-agent 執行變更，security-agent／code-review-agent 把關
• Hooks：preToolUse／postToolUse Hook 在變更前後自動跑測試與安全掃描
• Plugins：可將上述資源打包為 spring-boot-migration-plugin，供多個專案共用同一套升級能力
• MCP：若需要查詢外部相依套件的 CVE 資料庫，透過對應 MCP Server 取得即時資訊

Scenario

某企業原本打算讓單一 Agent 一次完成整個 Spring Boot 3→4 升級，結果因變更範圍過大、難以定位問題而回滾整個升級。改用 17.1 的分階段流程（每個 Gate 都要求可獨立驗證與回滾）後，即使升級中途發現問題，也只需回滾單一階段而非整個專案。

AI Prompt 範例

角色：你是 migration-agent，正在執行 Spring Boot 3.x → 4.x 升級評估。

任務：分析本 Repository 的依賴清單與程式碼，產出符合 17.2 表格
定義的評估階段產出物（Dependency Analysis／Breaking Change
Detection／Configuration Analysis／Source Code Analysis／
Security Analysis／Test Analysis），最終彙整為 Migration Plan。

限制：
1. Security Analysis 階段請聚焦「升級本身帶來的安全性變更」
   （例如 Jakarta namespace、預設安全設定），
   不要跟 code-review 階段的異動後安全複查混為一談（依 17.2 說明）
2. Migration Plan 完成後，明確標示「等待人工核准」，
   不可自行進入 Automated Changes 階段
3. 每個 Breaking Change 都要附上官方 Migration Guide 的對應章節出處，
   不可僅憑推測列出

本章 Checklist

• Migration Plan 已設置人工核准關卡，不可跳過
• 每個升級階段都可獨立驗證、獨立回滾
• Breaking Change Detection 已對照官方 Migration Guide 逐條核對，而非僅憑 AI 推測

18. AI-Assisted SDLC

18.1 全生命週期圖

graph LR
    A["Requirement"] --> B["Analysis"]
    B --> C["Architecture"]
    C --> D["Design"]
    D --> E["Coding"]
    E --> F["Testing"]
    F --> G["Security"]
    G --> H["Code Review"]
    H --> I["CI/CD"]
    I --> J["Deployment"]
    J --> K["Monitoring"]
    K --> L["Feedback"]
    L -.->|"回饋到下一輪"| A

18.2 awesome-copilot 在每個階段的介入方式

Scenario

某企業導入 AI Coding Agent 初期，只把 Copilot 用在 Coding 與 Code Review 兩個階段，Requirement／Architecture 仍完全靠人工會議與 Word 文件溝通，導致 Agent 產出的程式碼經常與架構決策脫節（例如 Agent 不知道某個模組已決議要拆成獨立服務）。導入 18.2 的全生命週期介入方式後，system-architect 在 Architecture／Design 階段就先產出可被下游 Agent 讀取的設計文件（存放於 docs/architecture/，比照第 10.3 節 Shared Artifacts 慣例），Coding 階段的 Agent 才能延續一致的架構決策，而不是各自猜測。

本章 Checklist

• 已對照 18.2 表格，確認每個 SDLC 階段都有明確的 Copilot 介入方式
• Monitoring／Feedback 階段已納入流程，而非只做到 Deployment 就結束

19. Spec-Driven Development 整合

19.1 整合流程

graph LR
    A["Specification"] --> B["Requirements"]
    B --> C["Design"]
    C --> D["Implementation Plan"]
    D --> E["Agent"]
    E --> F["Skill"]
    F --> G["Implementation"]
    G --> H["Test"]
    H --> I["Verification"]

19.2 避免 AI Agent 擴權的防護措施

Scenario

某團隊發現 Coding Agent 在實作「訂單查詢」功能時，「順便」重構了完全不相關的付款模組。追查後發現該 Agent 的 Prompt 過於開放（「請改善這個系統」），缺乏明確的 Scope 邊界。修正：改用 19.1 的 Spec-Driven 流程，每個任務都先有明確的 Implementation Plan 並經人工核准，Agent 只能在核准範圍內執行。

本章 Checklist

• 每個實作任務都有對應的 Specification／Implementation Plan
• Agent 的工具授權已依角色收斂到最小必要範圍
• 已建立「不可修改清單」機制，防止 Agent 修改不相關程式

20. 企業級 AI Coding Governance

20.1 Governance 模型

20.2 安全風險類別

20.3 Governance Workflow

graph LR
    A["Community Resource<br/>(awesome-copilot 等)"] --> B["Security Review"]
    B --> C["Architecture Review"]
    C --> D["License Review"]
    D --> E["Sandbox Test"]
    E --> F["Approved Catalog"]
    F --> G["Team Usage"]
    G --> H["Periodic Review"]
    H -.->|"發現問題"| B

20.4 已知威脅情資（2026，Source-confirmed）

20.2 列出的風險類別並非紙上談兵——以下是 2026 年已被資安研究機構與媒體證實的真實案例，企業撰寫 Governance 政策時可直接引用作為風險佐證：

⚠️ 企業啟示：上述情資直接對應 20.2 的 Prompt Injection、Malicious Skill、MCP Supply Chain 三類風險並非理論假設，而是已發生的真實攻擊模式。20.1 的 Governance 模型與第 21 章的安全評估 Checklist 不是可有可無的官僚流程，而是對應這些已知威脅的具體防禦措施；企業在說服管理層投入 Governance 資源時，可直接引用本節情資作為風險量化依據。

20.5 企業級集中管控：managed-settings.json

前面幾節的治理措施多半落在 Repository 層級，但第 6.6 節已指出治理上最大的破口是：開發者可以自行安裝 GitHub Copilot app 或使用 Copilot CLI，繞過 IDE 與 Repository 層級的所有限制。要堵住這個破口，必須使用企業管理者層級的 managed-settings.json（官方已實作）。

定位：客製化資源的最上層 Scope

呼應第 6.3 節的 Scope 表，managed-settings.json 是位於最上層、由企業 IT 部署、開發者無法自行覆寫的設定層：

graph TB
    E["Enterprise: managed-settings.json<br/>由企業 IT 部署，開發者不可覆寫"] --> O["Organization: GitHub.com 組織設定"]
    O --> R["Repository: .github/copilot/settings.json"]
    R --> P["Personal: ~/.copilot/settings.json"]
    E -.->|"跨所有 harness 生效"| H["VS Code / Copilot CLI<br/>Copilot app / cloud agent"]

（實線＝由上而下的設定層級關係；虛線＝跨 harness 的生效範圍，這正是它與 Repository 層級設定的關鍵差異。）

設定優先序：四層來源與「最嚴格方向」合成（第四版新增，官方已實作）

當多個設定來源同時存在時，排在前面的優先於排在後面的：

1. MDM-managed settings（行動裝置管理／端點管理工具下發）
2. Server-managed settings（企業伺服器端下發）
3. File-based settings（檔案佈署）
4. User-level settings（使用者自己的設定）

但官方明訂兩個例外：sandbox 與 permissions.deny／permissions.ask／permissions.allow 這幾個鍵，跨不同下發方式時是以「最嚴格方向」合成，而不是單純由高優先序覆蓋。實務含意是：一旦任何一層加了 deny 規則，其他層都無法把它放寬回來——這正是合規稽核想要的行為。

十大支援鍵一覽（第四版全面補齊，官方已實作）

第三版僅描述了 Plugin 相關的兩個能力；官方 managed-settings.json 的實際治理面遠大於此：

permissions 的選擇器語法（官方已實作）

deny／ask／allow 三者的優先序是 deny > ask > allow。只要任一有效來源定義了任何權限規則、或宣告了 allow 清單，未被匹配到的操作就預設為需要核准。規則使用以下選擇器：

disableBypassPermissionsMode：關掉「YOLO 模式」（第四版新增）

設為 "disable" 後，使用者無法開啟全開權限模式，各 Surface 的實際效果為：

• Copilot CLI：--yolo、--allow-all，以及 --allow-all-tools、--allow-all-paths、--allow-all-urls 等所有命令列選項在啟動時即被抑制、無法授予提升權限；/yolo 與 /allow-all 兩個 slash command 也被封鎖
• VS Code：全域自動核准設定 chat.tools.global.autoApprove 被關閉且無法重新開啟
• GitHub Copilot app：Session 設定中「Tool Permissions」的「Allow all」被封鎖

⚠️ 這是企業導入 AI Coding Agent 最該優先設定的一個鍵（建議架構）。實務上絕大多數「Agent 誤刪檔案／誤推 branch／外洩機敏內容」事故，起因都是使用者為求方便自行開啟了全開模式。此鍵是唯一能從企業層一次關閉所有 Surface 全開模式的手段。

企業團隊分層：overridable 覆寫機制（第四版新增，官方已實作）

Server-managed 佈署下，企業可依企業團隊（enterprise team）成員身分對不同群組套用不同治理值。要讓某個鍵可被團隊層調整，需在 managed-settings.json 中以 { "overridable": <VALUE> } 語法標記；被標記的鍵在團隊有設值時採團隊值，未設值時退回企業預設。

• 支援 overridable 的鍵：model、permissions.disableBypassPermissionsMode、permissions.deny、permissions.ask、permissions.allow、allowedMcpServers、deniedMcpServers
• 未標記為 overridable 的鍵，仍是企業層決定、團隊不可修改
• enabledPlugins 與 extraKnownMarketplaces 是「加法式」：企業 managed-settings.json 設下基準線，團隊檔案可在其上再追加更多 Plugin 與 Marketplace

這正是「研發團隊可用 Playwright MCP，但財會系統團隊不可」這類差異化治理的官方實作路徑。

兩項 Plugin 核心管控能力

autoUpdate 的治理含意（2026-08-26 官方新增）：設為 true 會要求 Client 定期重新整理該 Marketplace 並更新來自該來源的已安裝 Plugin；設為 false 則要求自動更新保持關閉；省略則沿用 Client 既有預設或使用者設定。由於 managed settings 具優先權，使用者無法覆寫已定義的 autoUpdate 值。此設定只作用於該 Marketplace，且 strictKnownMarketplaces 的限制仍會在重新整理與更新操作之前先行套用。

支援的 source 型別：

• extraKnownMarketplaces 支援 "github"（需 repo，格式 OWNER/REPO；選用 ref 與 path）、"git"（需 url；選用 ref、path）、"directory"（需 path）
• strictKnownMarketplaces 支援範圍更廣："github"、"git"、"url"（需 url，選用 headers）、"npm"（需 package）、"file"（需 path）、"directory"（需 path）、"hostPattern"（regex 比對 Marketplace 主機）、"pathPattern"（regex 比對 Marketplace 路徑）

設定範例（第四版依官方 Example configuration 校正）

{
  "model": "auto",
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "deny": [
      "Shell(rm -rf *)",
      "Read(~/.ssh/**)",
      "Edit(//etc/**)",
      "Domain(*.unapproved.example)"
    ],
    "ask": [
      "Shell(git push *)",
      "Edit(/src/**)",
      "Domain(api.github.com)"
    ],
    "allow": [
      "Shell(npm test *)",
      "Read(/src/**)",
      "Domain(registry.npmjs.org)"
    ]
  },
  "enabledPlugins": {
    "enterprise-web-plugin@acme-plugins": true
  },
  "extraKnownMarketplaces": {
    "acme-plugins": {
      "source": {
        "source": "github",
        "repo": "acme-corp/enterprise-plugins"
      },
      "autoUpdate": true
    }
  },
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/enterprise-plugins"
    }
  ],
  "sandbox": {
    "enabled": true,
    "allowBypass": false,
    "sandboxMcpServers": true,
    "sandboxLspServers": true
  }
}

上列鍵名、巢狀結構與值的型別皆依 docs.github.com 的 Enterprise managed settings 參考頁面（2026-08-31 查證）校正。第三版曾使用的 knownMarketplaces 陣列與 enabledPlugins 陣列寫法不是官方格式，請勿沿用。檔案的實際部署路徑與 MDM／群組原則下發方式，請以 docs.github.com 上「Configuring enterprise-managed settings」頁面的當下版本為準；企業部署前務必先在少量機器上驗證設定確實生效。

三層 Plugin 治理策略

⚠️ 此小節為建議架構，並非 GitHub 官方規定的部署模式。

與其他治理手段的分工

⚠️ 企業實務結論：managed-settings.json 是目前唯一能同時管到 VS Code、Copilot CLI、Copilot app 與 cloud agent 四種 harness 的治理槓桿。若企業已允許使用 Copilot app 卻沒有部署 managed-settings.json，等於第 20.1 的 Governance 模型只在 IDE 上生效，實際覆蓋率遠低於帳面。

20.6 Agent Sandboxing：OS 層級的最後一道防線

⚠️ 本節為第三版新增。前面所有治理手段（managed-settings.json、CODEOWNERS、tools 最小權限、Hooks）都屬於應用層控制；Agent Sandboxing 是唯一在 OS 層級強制執行的邊界，也是唯一能在「Agent 已被 prompt injection 攻陷」之後仍然有效的機制。

為什麼需要 OS 層級隔離

VS Code 官方文件列出四個理由，每一個都對應企業實際遇過的問題：

涵蓋範圍與不涵蓋範圍

⚠️ 這是本節最重要的一個誤解點：開了 sandbox 不等於「Agent 不能亂改檔案」。檔案編輯工具走的是另一套權限模型。Sandbox 防的是「終端機指令做了你沒預期的事」。

檔案系統隔離規則

網路隔離與設定

所有對外連線預設封鎖。 相關設定如下：

⚠️ 官方明確警示：放行網域時務必評估該網域本身的能力。例如允許 api.github.com，就等於允許 Agent 建立 PR 或修改 Repository 設定——網域允許清單本質上是能力允許清單，不是單純的連線白名單。

各作業系統的實作與前置需求

⚠️ 企業導入建議（建議架構）：多數台灣企業開發環境以 Windows 為主，這代表 Agent Sandboxing 在原生 Windows 上目前不可用。務實的替代方案有三：（1）開發者改在 WSL2 中開啟 workspace；（2）統一使用 dev container；（3）在 Windows 上維持較嚴格的終端機指令核准政策，不啟用高自主模式（Autopilot）。企業標準文件應直接寫明「哪一種作業系統採用哪一種隔離方案」，而不是含糊帶過。

與其他控制層的關係

graph TB
    L1["第 1 層：套用前審閱<br/>Diff 檢視 + Checkpoint"]
    L2["第 2 層：行動前核准<br/>工作階段 / 工作區 / 使用者層級"]
    L3["第 3 層：限制自主程度<br/>權限等級，上限為 Autopilot"]
    L4["第 4 層：OS 層強制邊界<br/>Agent Sandboxing"]
    L5["第 5 層：信任邊界<br/>工作區 / 發行者 / MCP Server / 網域"]

    L1 --> L2 --> L3 --> L4 --> L5

    L4 -.->|"唯一在模型被攻陷後仍有效"| NOTE["Prompt Injection 之後的殘存防護"]

圖說：實線為 VS Code 官方文件列出的五層信任與安全控制；虛線為本手冊補充的說明關係（建議架構）。

企業層強制：managed-settings.json 的 sandbox 鍵（第四版新增，官方已實作）

上面描述的 chat.agent.sandbox.* 都是 VS Code 個人設定——使用者隨時可以自己關掉。若企業需要的是「使用者不能關」的沙箱，就必須使用第 20.5 節 managed-settings.json 的 sandbox 鍵（適用於 Copilot CLI）。

官方明訂其語意是「施加限制（restrictions）而非設定預設值（defaults）」，規則如下：

• 強制開啟型設定：管理值為 true 代表強制啟用；false 或省略則不變動使用者設定
• 能力型設定：管理值為 false 代表禁止該能力；true 或省略則不變動使用者設定
• 管理層的讀寫與唯讀路徑清單會「限縮」使用者的授權，而管理層的**拒絕路徑是「追加」**到使用者的拒絕清單

userPolicy 三個子區塊：

⚠️ 兩個實務提醒（建議架構）：

1. allowDevToolAccess: false 很容易弄壞建置。它會阻斷包管理快取與 registry 憑證，造成包還原、驗證式 registry 操作或使用共享快取的建置失敗，除非你明確授予必要路徑。請先在 Pilot 團隊驗證。
2. sandbox 與 permissions 同屬「最嚴格方向合成」的例外鍵（見第 20.5 節優先序），一旦任一層加上限制，其他層無法把它放寬。這代表你可以安心地在企業層設下基礎防線，而不用擔心某個團隊檔案把它解除。

20.7 權限模型：四種核准層級與 Agent 網路過濾

本節為第四版新增。前三版把「治理」集中在檔案與設定層（managed-settings.json、allowed-tools），但使用者在 Chat 介面上當場選擇的權限層級才是最貼近真實風險的那一層。本節補上這塊。

20.7.1 四種權限層級（官方已實作）

VS Code 的 Chat 檢視提供 Permissions Picker，讓使用者為當前工作階段選擇權限層級：

兩項重要限制（官方已實作）：

1. Assisted Permissions 與 Autopilot 只在 Agent Host 上可用（見第 6.7 節 AHP／chat.agentHost.enabled）。未啟用 Agent Host 的環境不會看到這兩個選項。
2. Assisted 不等於安全。LLM 判官本身也是模型，同樣可能被 Prompt Injection 誤導。官方把它定位為「減少中斷」而非「取代人工把關」。

⚠️ 企業治理結論（建議架構）：Bypass Approvals 與 Autopilot 應被視為與 --allow-all-tools 同級的高風險開關。企業政策建議寫成：

• 禁止在能觸及正式環境憑證、Production 資料庫或內網服務的機器上使用這兩種層級
• 若要使用，必須同時開啟第 20.6 節的 Sandbox（網路封鎖 + 檔案系統限制），形成「自動核准 + 強制隔離」的組合
• 在 CI／Cloud Agent 這類本來就隔離的環境中，這兩種層級才是合理選擇

20.7.2 Agent 網路過濾與瀏覽器工具政策（官方已實作）

當 Agent 具備瀏覽器與網路能力後，「Agent 能連到哪裡」本身就成為必須治理的邊界。官方提供兩項企業政策層（可透過 Copilot enterprise settings 檔或既有 MDM 派送）的控制：

與 Sandbox 的關係（建議架構）：這兩者處理的是不同層次的問題，不可互相取代——

• ChatAgentNetworkFilter 管的是Agent 工具自身（例如瀏覽器工具、抓網頁）要連到哪裡
• 第 20.6 節的 sandbox.userPolicy.network 管的是Agent 執行的終端機指令（curl、npm install、自訂腳本）能不能對外連線

一個常見的治理漏洞是：只設了 ChatAgentNetworkFilter，卻沒開 Sandbox，結果 Agent 用 curl 就繞過了網域限制。兩者要一起設。

20.7.3 企業 Plugin 政策設定鍵（官方已實作）

除了第 20.5 節 Copilot CLI 的 managed-settings.json，VS Code 側另有三個**政策支援（policy-backed）**的設定鍵，可透過 Copilot enterprise settings 檔或既有 MDM 方案派送：

與 CLI 的對照（第四版重要提醒）：這三個鍵與第 20.5 節 Copilot CLI managed-settings.json 的 enabledPlugins／extraKnownMarketplaces／strictKnownMarketplaces 語意對應但命名不同、檔案位置也不同。企業導入時必須兩邊都設，否則會出現「IDE 已封鎖、CLI 仍可安裝」（或反之）的治理缺口。這是實務上最常見的落差之一，建議直接納入第 21 章的審查清單逐項核對。

Scenario

某企業的 Security Team 一開始只審查「程式碼」，沒有把 Agent／Skill／Plugin 納入審查範圍，直到一次事件中發現某個社群 Skill 的 allowed-tools 授權了 Terminal 執行權限且腳本會對外連線，才驚覺客製化資源本身就是攻擊面之一。修正：把 20.1 的 Governance 模型正式納入企業 AI 治理政策，客製化資源比照第三方套件依賴（如 npm package）的審查標準處理。

本章 Checklist

• 已建立 Approved Agents／Skills／Plugins／MCP 清單機制
• 客製化資源的安裝與修改已納入 Audit Log
• 20.2 十類安全風險已納入企業 AI 治理政策文件
• 已用 20.4 的 2026 年真實威脅情資向管理層說明 Governance 投資的必要性
• 已部署 managed-settings.json，確認治理範圍涵蓋 Copilot app 與 Copilot CLI，而非只有 IDE（20.5）
• 已依 20.5 三層策略決定目前所處的 Plugin 治理階段（觀察期／收斂期／封閉期）
• 已依 20.6 決定各作業系統的隔離方案（macOS 原生沙箱／Linux 需裝 bubblewrap+socat／Windows 改用 WSL2 或 dev container）
• 已知悉 Agent Sandboxing 不涵蓋內建檔案編輯工具，未將其誤當成全面防護
• 已設定 permissions.disableBypassPermissionsMode: "disable"，關閉全部 Surface 的 YOLO／全開模式（20.5）
• 已知悉 permissions.allow 是交集、permissions.deny 是聯集，並依此規劃分層規則
• 已決定哪些鍵標記為 overridable，以支援企業團隊差異化治理（20.5）
• 已以 managed-settings.json 的 sandbox.enabled 與 sandbox.allowBypass 建立使用者無法停用的 CLI 沙箱基礎線（20.6）
• allowDevToolAccess: false 若已啟用，已在 Pilot 團隊驗證不會弄壞建置與包還原
• 已明訂 Bypass Approvals／Autopilot 的使用邊界，並要求同時開啟 Sandbox（20.7.1）
• 已同時設定 ChatAgentNetworkFilter 與 sandbox.userPolicy.network，避免以終端機指令繞過網域限制（20.7.2）
• 已同時在 VS Code 政策鍵與 CLI managed-settings.json 兩側設定 Plugin 治理，確認無單邊缺口（20.7.3）

21. 社群資源安全評估 Checklist

21.1 Awesome Copilot Resource Security Checklist

在安裝任何 awesome-copilot（或其他社群來源）的 Agent／Skill／Plugin／Hook／MCP 前，逐項檢查：

• Repository source：確認來源 Repository 是否可信（是否為知名組織、star 數、issue 回應速度）
• Maintainer：確認貢獻者/維護者身份與過往紀錄
• Last update：確認最後更新時間，過舊或已停止維護需特別謹慎
• License：確認授權條款是否符合企業使用規範
• Dependencies：確認依賴的第三方套件是否有已知漏洞
• Scripts：逐行閱讀任何內含的 Shell／Python 等腳本
• Shell commands：確認 Hook／Plugin 是否執行 Shell 指令，指令內容是否合理
• MCP servers：確認綁定的 MCP Server 來源與權限範圍
• Network access：確認是否對外發送網路請求，目標端點是否可信
• File access：確認存取的檔案/目錄範圍是否合理，是否有存取範圍外的檔案
• Environment variables：確認是否讀取超出必要範圍的環境變數
• Secrets：確認沒有硬編碼的密碼／API Key／Token
• Tool permissions：確認 tools／allowed-tools 是否符合最小權限原則
• Prompt injection：確認資源內容是否有可疑的隱藏指令或誤導性描述
• Obfuscated code：確認是否有刻意混淆的程式碼
• External download：確認執行時是否會下載額外的外部內容
• Supply-chain risk：確認整條依賴鏈是否有已知風險節點