VS Code 中的代理外掛程式 (預覽)

代理外掛程式 (Agent plugins) 是代理自訂功能的預先封裝套件，您可以從 Visual Studio Code 的外掛程式市集中探索並安裝它們。單一外掛程式可以提供斜線指令 (slash commands)、代理技能、自訂代理、鉤子 (hooks) 以及 MCP 伺服器 的任意組合。

外掛程式會與您本機定義的自訂設定並行運作。安裝外掛程式後，其指令、技能、代理、鉤子和 MCP 伺服器都會出現在聊天介面中。

外掛程式提供的功能

代理外掛程式可以綑綁下列一或多種自訂類型：

• 斜線指令 (Slash commands)：您可以在聊天中使用 / 呼叫的額外指令
• 技能 (Skills)：包含指令、指令碼和資源的代理技能，可隨需載入
• 代理 (Agents)：具有專門角色設定和工具設定的自訂代理
• 鉤子 (Hooks)：在代理生命週期點執行 Shell 指令的鉤子
• MCP 伺服器：用於外部工具整合的 MCP 伺服器

例如，一個測試外掛程式可能包含一個帶有指令碼的 test-runner 技能、一個帶有唯讀工具的 test-reviewer 代理，以及一個用於測試報告儀表板的 MCP 伺服器。外掛程式的目錄結構如下所示：

my-testing-plugin/
  plugin.json              # Plugin metadata and configuration
  skills/
    test-runner/
      SKILL.md             # Testing skill instructions
      run-tests.sh         # Supporting script
  agents/
    test-reviewer.agent.md # Code review agent
  hooks/
    hooks.json             # Hook configuration
  scripts/
    validate-tests.sh      # Hook script
  .mcp.json                # MCP server definitions

安裝後，外掛程式提供的自訂功能會與您本機定義的功能一併出現。例如，來自外掛程式的技能會顯示在設定技能 (Configure Skills) 選單中，而來自外掛程式的 MCP 伺服器則會顯示在 MCP 伺服器清單中。

外掛程式中繼資料 (plugin.json)

每個外掛程式都需要在其根目錄中提供一個 plugin.json 資訊清單檔案。此檔案定義了外掛程式的識別資訊，並告知 VS Code 在何處尋找其元件。

必要欄位

選用欄位

關於完整欄位參考，請參閱 GitHub Copilot CLI 外掛程式參考。

plugin.json 範例

{
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0",
  "author": {
    "name": "Jane Doe"
  },
  "skills": "skills/",
  "agents": "agents/",
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

外掛程式格式

VS Code 會透過檢查格式專用的資訊清單路徑來自動偵測外掛程式格式。若未發現其他格式標記，則預設使用 Copilot 格式。

外掛程式環境變數

某些外掛程式格式提供了一個根權杖 (root token)，您可以在鉤子指令和 MCP 伺服器設定中使用它來參照外掛程式目錄內的檔案。VS Code 會在執行階段展開此權杖，並將其設定為鉤子或伺服器處理序中的環境變數。

外掛程式中的鉤子 (Hooks)

外掛程式可以包含在代理生命週期點執行 Shell 指令的鉤子。外掛程式鉤子會與您的工作區和使用者層級鉤子並行運作。當外掛程式啟用時，其鉤子除了會觸發之外，也會與針對同一事件設定的其他鉤子一起執行。

鉤子檔案位置

鉤子檔案位置取決於外掛程式格式

VS Code 會自動偵測外掛程式格式並自動發現鉤子檔案。

my-plugin/
  hooks/
    hooks.json           # Hook configuration (Claude format)
  scripts/
    format.sh            # Hook script referenced by hooks.json

鉤子設定格式

外掛程式鉤子使用與工作區鉤子相同的基礎格式。VS Code 會解析 Claude Code 的鉤子設定，包括比對器 (matcher) 語法。目前，VS Code 會忽略比對器值，因此鉤子會在每個匹配事件上執行。

平面格式 (Flat format) (與工作區鉤子相同)

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
      }
    ]
  }
}

比對器格式 (Matcher format) (Claude 相容性語法)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

VS Code 會解析 matcher 欄位以與 Claude Code 相容，但目前會忽略比對器值。如果您需要在 VS Code 中過濾鉤子行為，請在鉤子指令碼內檢查事件輸入。

在鉤子指令中參照外掛程式路徑

對於 Claude 格式的外掛程式，請在鉤子指令中使用 ${CLAUDE_PLUGIN_ROOT} 權杖來參照外掛程式目錄內的指令碼與檔案。VS Code 會在執行階段將此權杖展開為外掛程式的絕對路徑，並為鉤子處理序設定一個 CLAUDE_PLUGIN_ROOT 環境變數。在您的指令碼中，請以 $CLAUDE_PLUGIN_ROOT (或 Windows 上的 %CLAUDE_PLUGIN_ROOT%) 存取此變數。

這點非常重要，因為外掛程式安裝的位置位於工作區之外，因此您無法使用相對路徑。

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-tool.sh"
      }
    ]
  }
}

支援的鉤子事件

外掛程式鉤子支援與工作區鉤子相同的生命週期事件：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、SubagentStart、SubagentStop 和 Stop。詳細資訊請參閱鉤子生命週期事件。

外掛程式鉤子如何與其他鉤子互動

外掛程式鉤子會與工作區層級和使用者層級的鉤子並行執行。當多個鉤子鎖定同一個事件時，它們都會執行。對於 PreToolUse 鉤子，將採用所有鉤子中最嚴格的權限決策：deny 會覆寫 ask，而 ask 會覆寫 allow。

停用外掛程式也會停用其鉤子。您可以從「擴充功能」檢視中全域啟用或停用外掛程式，也可以針對特定工作區進行設定。

外掛程式中的 MCP 伺服器

外掛程式可以綑綁 MCP 伺服器，為代理提供額外的工具和資料來源。外掛程式 MCP 伺服器會在啟用外掛程式時自動啟動，並在停用外掛程式時停止。

MCP 設定檔

請將 MCP 伺服器定義放置在外掛程式根目錄下的 .mcp.json 中。VS Code 在載入外掛程式時會自動發現此檔案。

my-plugin/
  .mcp.json              # MCP server definitions
  servers/
    db-server             # Server executable
  config.json             # Server configuration

MCP 設定格式

外掛程式 MCP 伺服器定義在頂層的 mcpServers 物件中。每個伺服器項目都會指定指令、引數和選用的環境變數：

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

在伺服器設定中參照外掛程式路徑

對於 Claude 格式的外掛程式，請在 MCP 伺服器欄位中使用 ${CLAUDE_PLUGIN_ROOT} 權杖來參照外掛程式目錄內的可執行檔與檔案。VS Code 會在下列欄位中展開此權杖：

• command：可執行檔路徑
• args：命令列引數
• cwd：工作目錄
• env：環境變數值
• envFile：環境檔案路徑
• url：用於基於 HTTP 的 MCP 伺服器
• headers：HTTP 標頭值

VS Code 也會將 CLAUDE_PLUGIN_ROOT 環境變數注入伺服器處理序，以便伺服器程式碼能在執行階段存取外掛程式路徑。

外掛程式 MCP 伺服器如何與其他伺服器互動

外掛程式 MCP 伺服器會與工作區和使用者層級的 MCP 伺服器並行出現。您可以透過相同的工具來管理它們：

• 在「聊天」檢視中選擇設定工具 (Configure Tools)，即可查看來自所有 MCP 伺服器（包含外掛程式伺服器）的工具。
• 從指令選擇區執行 MCP: List Servers，即可查看外掛程式伺服器與其他伺服器。

外掛程式 MCP 伺服器在您安裝外掛程式時會被隱式信任。與工作區 MCP 伺服器不同，它們在啟動時不會顯示個別的信任提示。

停用外掛程式會停止其 MCP 伺服器。已停止伺服器所提供的工具將不再於聊天中可用。

探索並安裝外掛程式

VS Code 在「擴充功能」側邊欄中提供了一個專用檢視，供您瀏覽和管理代理外掛程式。

瀏覽可用外掛程式

1. 開啟「擴充功能」檢視 (⇧⌘X (Windows, Linux Ctrl+Shift+X)) 並在搜尋欄位中輸入 @agentPlugins。

   或者，選擇「擴充功能」側邊欄中的更多動作 (More Actions) (三個點) 圖示，並選擇檢視 (Views) > 代理外掛程式 (Agent Plugins)。

2. 從您設定的市集中瀏覽可用外掛程式清單。

   

3. 選擇安裝 (Install) 即可將外掛程式安裝到您的使用者設定檔中。

   當您第一次從新的市集安裝外掛程式時，VS Code 會顯示信任提示。請在確認前審查市集來源。

從來源安裝外掛程式

您可以直接從 Git 儲存庫 URL 安裝外掛程式，無需先新增完整的市集。

• 從指令選擇區執行 Chat: Install Plugin From Source。
• 或者，選擇「代理自訂」編輯器中「外掛程式」頁面上的 + 按鈕。

輸入 Git 儲存庫 URL (例如 https://github.com/rwoll/markdown-review)，VS Code 將會複製並安裝該外掛程式。

由 GitHub Copilot CLI 安裝的外掛程式

VS Code 會自動偵測您使用 GitHub Copilot CLI 安裝的外掛程式，以便您在 VS Code 中也能使用它們。來自 ~/.copilot/installed-plugins/ 的外掛程式會顯示在「代理外掛程式 - 已安裝」檢視中，與您從市集或來源安裝的外掛程式並列。

CLI 會將外掛程式儲存在 ~/.copilot/installed-plugins/<marketplace>/<plugin>/ 下。直接從 Git URL 安裝的外掛程式（而非從市集）會位於 _direct 儲存區，例如 ~/.copilot/installed-plugins/_direct/github--moda-linter--copilot-plugin/。

查看已安裝外掛程式

「擴充功能」檢視中的「代理外掛程式 - 已安裝」檢視會顯示您已安裝的外掛程式。在此檢視中，您可以啟用、停用或解除安裝外掛程式。

您也可以透過選擇「聊天」檢視中的齒輪圖示 > 外掛程式 (Plugins) 來管理已安裝的外掛程式。

啟用或停用外掛程式

您可以全域或針對特定工作區啟用或停用外掛程式：

• 使用「擴充功能」檢視中「代理外掛程式 - 已安裝」區段的外掛程式快顯功能表。
• 使用代理自訂編輯器來切換外掛程式的啟用狀態。

啟用/停用狀態會與外掛程式設定分開儲存，因此不會影響共用的工作區設定。

當外掛程式停用時，其技能、代理、鉤子、MCP 伺服器和斜線指令將不再可用。例如，已停用外掛程式的技能不會出現在聊天：設定技能 (Chat: Configure Skills) 中。已停用的外掛程式在「代理自訂編輯器」和「擴充功能」檢視中會顯示為暗色調。

解除安裝外掛程式

若要移除外掛程式，請在「代理外掛程式 - 已安裝」檢視中按一下右鍵並選擇解除安裝 (Uninstall)。從外部來源（如 npm、PyPI 或外部 Git 儲存庫）安裝的外掛程式將會從磁碟中移除。嵌入在市集儲存庫中的外掛程式將保留在磁碟上，但不再作用。

設定外掛程式市集

預設情況下，VS Code 會從 copilot-plugins 和 awesome-copilot 探索外掛程式。您可以使用 chat.plugins.marketplaces 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定新增額外的市集。

市集是包含外掛程式定義的 Git 儲存庫。您可以用幾種格式來參照它們：

• 縮寫 (Shorthand)：用於公開 GitHub 儲存庫的 owner/repo。例如 anthropics/claude-code。
• HTTPS git 遠端：以 .git 結尾的完整 URL。例如 https://github.com/anthropics/claude-code.git。
• SCP 風格 git 遠端：SSH 風格的參照。例如 git@github.com:anthropics/claude-code.git。
• 檔案 URI：指向已複製到磁碟之市集儲存庫的 file:/// 路徑。

同時也支援私人儲存庫。如果公開查詢失敗，VS Code 會退而求其次，直接嘗試複製該儲存庫。

市集外掛程式也可以參照 npm 或 PyPI 套件等外部套件來源。關於完整的市集外掛程式結構描述，請參閱 Claude Code 外掛程式市集文件。

// settings.json
"chat.plugins.marketplaces": [
    "anthropics/claude-code"
]

使用本機外掛程式

如果您手動複製或下載了外掛程式，可以使用 chat.pluginLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來註冊它。此設定會將本機外掛程式目錄路徑映射至啟用或停用狀態。

// settings.json
"chat.pluginLocations": {
    "/path/to/my-plugin": true,
    "/path/to/another-plugin": false
}

將值設定為 true 以啟用外掛程式，或設定為 false 以保留其註冊但保持停用。

更新外掛程式

當您從指令選擇區執行 Extensions: Check for Extension Updates 時，VS Code 會檢查外掛程式更新；若已啟用 extensions.autoUpdate 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ，則會每 24 小時自動檢查一次。

更新作業會從已複製的市集儲存庫提取變更，並檢查外部來源外掛程式的新版本。

從 npm 或 PyPI 取得的外掛程式不會自動更新。相反地，它們會在「擴充功能」檢視中顯示更新 (Update) 按鈕。選擇該按鈕會在執行安裝指令前提示您確認。如果在背景檢查期間發現更新，在您明確選擇更新之前，不會採取任何動作。

工作區外掛程式推薦

專案可以透過在工作區設定 (.claude/settings.json 或 .github/copilot/settings.json) 中設定外掛程式設定，為團隊成員推薦外掛程式。

當第一次傳送聊天訊息時，VS Code 會顯示通知。您可以透過開啟「擴充功能」檢視並以 @agentPlugins @recommended 篩選來查看推薦的外掛程式。

在設定檔案中指定下列欄位以設定工作區外掛程式推薦：

• extraKnownMarketplaces：為專案註冊額外的市集。當您在「擴充功能」檢視中搜尋 @agentPlugins 時，這些市集便會出現。

• enabledPlugins：列出應預設啟用的外掛程式。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/plugin-marketplace"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true
  }
}

跨工具相容性

外掛程式格式在 VS Code、GitHub Copilot CLI 和 Claude Code 之間共用。單一外掛程式儲存庫可以在這三種工具中運作。

VS Code 會透過在多個位置尋找 plugin.json 來自動偵測外掛程式格式，檢查順序如下：

1. .plugin/plugin.json
2. plugin.json (位於外掛程式根目錄)
3. .github/plugin/plugin.json
4. .claude-plugin/plugin.json

如果您為多種工具開發外掛程式，您可以將 plugin.json 放在根目錄，並在格式專用的目錄中使用符號連結或複本。請保持所有複本中的 name 欄位相同，以避免衝突。

各工具間應注意的關鍵差異

• 鉤子檔案位置：Claude 格式的外掛程式預期鉤子位於 hooks/hooks.json，而 Copilot 格式的外掛程式使用位於根目錄的 hooks.json。VS Code 會自動偵測格式。
• 外掛程式根權杖：Claude 格式的外掛程式使用 ${CLAUDE_PLUGIN_ROOT} 來參照外掛程式目錄內的檔案。此權杖在 Copilot 格式的外掛程式中不可用。
• 技能命名：所有工具都要求 SKILL.md 中的名稱為單純的 Kebab-case。命名空間前綴（例如 myorg/skillname）會導致靜默載入失敗。

關於工具特定的詳細資訊，請參閱 GitHub Copilot CLI 外掛程式參考 和 Claude Code 外掛程式市集文件。

疑難排解

外掛程式安裝後未出現

• 確認已啟用代理外掛程式：檢查 chat.plugins.enabled 在 VS Code 中開啟 在 VS Code Insiders 中開啟 此設定由組織層級管理。請聯絡您的管理員進行變更。組織 已設定為 true。
• 驗證 plugin.json 中的外掛程式 name 欄位是否僅使用小寫字母、數字和連字號。斜線、冒號或其他特殊字元會導致外掛程式靜默載入失敗。
• 檢查 plugin.json 是否位於識別的位置（請參閱 跨工具相容性）。

來自外掛程式的技能未載入

• 開啟 SKILL.md 檔案並檢查 YAML 前言 (frontmatter) 中的 name 欄位。名稱必須是純 Kebab-case，不得包含命名空間前綴（例如 test-runner，而非 myorg/test-runner）。無效名稱會導致該技能被靜默跳過。
• 確保技能目錄名稱與 SKILL.md 前言中的 name 欄位一致。

外掛程式版本未更新

• 在推送變更之前，請更新 plugin.json 中的 version 欄位（以及 marketplace.json 中的外掛程式項目，若適用）。
• 從指令選擇區執行 Extensions: Check for Extension Updates 以觸發更新檢查。

安裝失敗並顯示 'destination path already exists' (目的路徑已存在)

當先前的安裝遺留了快取資料時可能會發生此情況。請刪除快取的「外掛程式目錄」並重試：

• macOS: ~/Library/Application Support/Code/agentPlugins/github.com/{org}/{repo}
• Linux: ~/.config/Code/agentPlugins/github.com/{org}/{repo}
• Windows: %APPDATA%\Code\agentPlugins\github.com\{org}\{repo}

相關資源

• 尋找並安裝 GitHub Copilot CLI 的外掛程式
• GitHub Copilot CLI 外掛程式參考
• 使用代理技能
• 新增和管理 MCP 伺服器
• 使用鉤子進行生命週期自動化
• 建立自訂代理